budget/.plans/otel-integration.md

OTel Integration — Budget

Wire up OpenTelemetry in Budget.Api so logs and traces flow through the OTel Collector to Seq. Depends on the infrastructure plan (docker/.plans/otel-seq-infrastructure.md) being applied first.

Packages to add (Budget.Api.csproj)

Verify latest stable versions on NuGet before adding — do not guess.

OpenTelemetry.Extensions.Hosting
OpenTelemetry.Instrumentation.AspNetCore
OpenTelemetry.Instrumentation.Http
OpenTelemetry.Instrumentation.EntityFrameworkCore
OpenTelemetry.Exporter.OpenTelemetryProtocol

Phase 1 — Wire up OTel in Program.cs

Add after var builder = WebApplication.CreateBuilder(args);:

builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource
        .AddService(serviceName: "budget", serviceVersion: "1.0.0"))
    .WithLogging()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddEntityFrameworkCoreInstrumentation()
        .AddOtlpExporter());

The AddOtlpExporter() call with no arguments reads the endpoint from environment variables (OTEL_EXPORTER_OTLP_ENDPOINT), keeping config out of code.

Phase 2 — docker-compose environment variables

Add to the budget service in docker/docker-compose.yaml:

      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
      - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
      - OTEL_SERVICE_NAME=budget

otel-collector resolves via the telemetry network added in the infrastructure plan.

Phase 3 — Verification

1. Build and push a new Budget image
2. docker compose up -d budget
3. Make a few API calls (create a transaction, fetch accounts)
4. In Seq, search @ServiceName = 'budget' — you should see structured log events including the OIDC discovery retry loop logs already present in Program.cs
5. Confirm DB spans appear for EF Core queries

Notes

• Budget already has structured logging calls in the OIDC startup retry loop (startupLogger.LogInformation, LogWarning). These will automatically become structured events in Seq with no code changes.
• The ErrorHandlingMiddleware and KnownUserMiddleware are good candidates to add structured properties (e.g. userId, endpoint) to log calls, making Seq searches more useful.
• AddHttpClientInstrumentation() will trace outgoing calls to the Auth server (OIDC discovery, token introspection), which is useful for diagnosing auth latency.