opentelemetry

OpenTelemetry

Core Principles

1. Three pillars, one setup — Configure traces, metrics, and logs through a single AddOpenTelemetry() call. Use UseOtlpExporter() for cross-cutting export to any OTLP-compatible backend.
2. Use IMeterFactory for metrics — Never create Meter instances with new. The factory manages lifetime through DI and prevents leaks.
3. Null-safe activities — StartActivity() returns null when no listener is attached. Always use ?. when setting tags or events.
4. Environment variables over code — Use OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME so deployments control telemetry routing without code changes.
5. Low-cardinality metric tags — Keep metric tag combinations under ~1000 per instrument. Use span attributes or logs for high-cardinality data like user IDs or request IDs.

Patterns

Full Setup with All Three Signals

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource
        .AddService(
            serviceName: builder.Environment.ApplicationName,
            serviceVersion: "1.0.0"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddEntityFrameworkCoreInstrumentation()
        .AddSource("MyApp.Orders"))
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddRuntimeInstrumentation()
        .AddMeter("MyApp.Orders"))
    .WithLogging()             // no per-signal exporter here —
    .UseOtlpExporter();        // UseOtlpExporter covers all three signals

// UseOtlpExporter replaces per-signal AddOtlpExporter calls. Never combine
// the two — mixing them throws NotSupportedException (see Anti-patterns).

The OTLP endpoint defaults to http://localhost:4317 (gRPC). Override via:

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
OTEL_SERVICE_NAME=MyApp.Api