TaskHub.Shared

OpenTelemetry (OTEL)

OpenTelemetry is an open-source observability framework for cloud-native software. It provides a vendor-neutral set of APIs and SDKs to collect and export traces, metrics, and logs.

In TaskHub, OTEL is the shared spine that ties together logs (Loki), metrics (Prometheus), and traces (Tempo) into a single observable system.

🎯 Why OTEL Here

• One protocol, three signals — OTLP carries traces, metrics, and logs to the same collector. No bespoke transports.
• Vendor-neutral — swap Tempo for Jaeger, Loki for Elastic, Prometheus for Mimir without touching service code.
• Automatic instrumentation — ASP.NET Core, HttpClient, EF Core, and Redis are traced out of the box.
• Custom spans where they matter — the Command Pipeline emits [PRE]/[HNDLR]/[POST] spans; the Response system tags every Result onto the active activity.

🧭 The Three Signals

Signal	What it answers	TaskHub backend
Traces	“Where did this request spend its time, and who did it call?”	Grafana Tempo
Metrics	“How fast / how many / how big — over time?”	Prometheus
Logs	“What happened, in human-readable detail?”	Grafana Loki

All three are stitched together by TraceId and SpanId, so a slow trace in Tempo links directly to its log lines in Loki.

📦 Module

TaskHub.Observability.OpenTelemetry provides:

• AddAppOpenTelemetry() — single-call registration that wires up tracing, metrics, and resource attributes.
• OpenTelemetryOptions — configuration record (endpoint, sampling, instrumentations, ignored paths).
• Pre-configured instrumentations for ASP.NET Core, HttpClient, EF Core, Npgsql, and Redis.

See OpenTelemetry usage for setup and OpenTelemetry architecture for internals.

⚙️ Minimal Configuration

"OpenTelemetry": {
  "ServiceVersion": "1.0",
  "Protocol": "grpc",
  "TracingEndpoint": "http://otel-collector:4317",
  "Environment": "Production",
  "RecordException": true,
  "IsHttpTracesEnabled": true,
  "IsAspNetTracesEnabled": true,
  "IsEFCoreTracesEnabled": true,
  "Ignore": [ "/health", "/metrics", "/swagger" ],
  "Sources": [ "ReaderRepository", "WriterRepository" ],
  "Sampling": { "IsEnabled": true, "Type": "AlwaysOn" }
}

Sources is the list of custom ActivitySource names your service emits — list every one, or spans won’t be exported.

🧪 Sampling Strategies

Type	Behavior	When to use
AlwaysOn	Every trace exported.	Dev, staging, low-traffic services.
AlwaysOff	Nothing exported.	Trace-only-on-demand setups.
TraceIdRatio	Random fraction (e.g. 0.1 = 10%).	High-traffic production.
ParentBased	Inherit decision from upstream service.	Chained microservices.

✅ Best Practices

• Don’t trace health checks — list /health, /ready, /metrics in Ignore. Otherwise sampler exhaustion drowns useful traces.
• Name custom sources — new ActivitySource("OrderRepository") not new ActivitySource("repo"). Names show up in Tempo’s service map.
• Tag with stable keys — job.id, user.id, result.code. These become searchable in Tempo. Avoid high-cardinality tags like full URLs or timestamps.
• Mark errors explicitly — activity?.SetStatus(ActivityStatusCode.Error) ensures Tempo flags the span red. The Response system does this automatically when a Result fails.

🔗 See Also

• OpenTelemetry usage — registration and code samples.
• OpenTelemetry architecture — exporter chain, resource attributes, propagators.
• Logging — how Serilog enriches log records with the active TraceId.
• Metrics — Prometheus metrics that complement traces.

This site is open source. Improve this page.