TaskHub.Shared

TaskHub.Observability.OpenTelemetry - Technical Manual

The TaskHub.Shared.Observability.OpenTelemetry module is the central nervous system for monitoring and diagnostics in TaskHub. It provides a standardized, pre-configured setup for the three pillars of observability: Traces, Metrics, and Logs.

🏛 Deep Architecture

1. The Bootstrap Chain

When you call AddAppOpenTelemetry, the system initializes a comprehensive pipeline:

• Resource Management: Every service is automatically assigned a service.name, service.version, and deployment.environment based on its assembly metadata and configuration.
• Automatic Instrumentation: It registers specialized processors that intercept calls from standard .NET libraries:
  • AspNetCoreInstrumentation: Captures incoming HTTP requests.
  • HttpClientInstrumentation: Captures outgoing HTTP calls to other services.
  • EntityFrameworkCoreInstrumentation: Captures SQL queries and database operations.
  • SqlClientInstrumentation: Low-level SQL tracking for non-EF providers.
  • RedisInstrumentation: Tracks performance of distributed cache operations.
• Exporter Management: It creates a multi-sink export chain, allowing data to be sent simultaneously to OTLP collectors (Tempo/Loki), Zipkin, or exposed via Prometheus.

2. Trace Propagation

The module ensures that TraceId and SpanId are correctly propagated across the entire microservice ecosystem using the W3C traceparent header. This allows a single user request to be visualized as a continuous flow from the API Gateway down to the database.

---

🛠 API Reference

AddAppOpenTelemetry(Action<OpenTelemetryOptions> configure)

| Parameter | Description | | :— | :— | | ServiceName | Unique identifier for the service (e.g., TaskHub.Identity). | | OtlpEndpoint | The URL of the OpenTelemetry Collector (e.g., http://tempo:4317). | | SamplingRatio | Value between 0.0 and 1.0. 1.0 means capture everything. |

---

🚀 Real-World Configuration & Usage

1. Global Setup (Program.cs)

builder.Services.AddAppOpenTelemetry(options => 
{
    options.ServiceName = "TaskHub.UserService";
    options.OtlpEndpoint = "http://otel-collector:4317";
    options.SamplingRatio = 1.0; // Sample all requests in development
});

2. Manual Instrumentation (Custom Spans)

public class MyBusinessLogic
{
    private static readonly ActivitySource MyActivitySource = new("TaskHub.CustomLogic");

    public async Task ProcessDataAsync()
    {
        // Start a manual span
        using var activity = MyActivitySource.StartActivity("DataCrunching");
        
        activity?.SetTag("item.count", 100);
        activity?.SetTag("logic.version", "2.1");

        try 
        {
            // ... work ...
            activity?.SetStatus(ActivityStatusCode.Ok);
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            activity?.AddException(ex);
            throw;
        }
    }
}

---

⚙️ Configuration Schema (appsettings.json)

"OpenTelemetry": {
  "OtlpEndpoint": "http://otel-collector:4317",
  "SamplingRatio": 0.5,
  "Exporters": {
    "IsOtlpEnabled": true,
    "IsPrometheusEnabled": true,
    "IsZipkinEnabled": false
  },
  "Instrumentation": {
    "IsSqlEnabled": true,
    "IsRedisEnabled": true,
    "IsHttpEnabled": true
  }
}

---

👁 Telemetry Data Reference

Standard Tags (Attributes)

Every trace in TaskHub includes these by default:

• service.name: The source service.
• host.name: The machine or pod name.
• http.method: e.g., GET, POST.
• http.status_code: e.g., 200, 404.
• db.system: e.g., postgresql.

Custom TaskHub Tags

• command.name: Present in spans created by the CommandsBus.
• result.code: The TaskHub standard result code.
• user.id: If the user is authenticated, their ID is tagged.

---

✅ Best Practices & Anti-Patterns

🟢 Best Practices

• High-Cardinality Tags: Use tags for IDs (UserId, OrderId) to allow precise filtering.
• Span Filtering: Use the SamplingRatio to reduce volume in high-traffic production environments.
• Context Passing: Always pass CancellationToken as it often carries internal tracing context in .NET.

🔴 Anti-Patterns

• Too Many Manual Spans: Avoid creating spans for every single method; focus on logical boundaries (I/O, complex logic).
• Large Payloads in Tags: Do not put large JSON objects or sensitive data (PII) in Activity Tags.

This site is open source. Improve this page.