Updated plan to fix issues

2026-05-04 17:42:44 -05:00
parent 8d4d7c7ce3
commit efde0f952b
6 changed files with 158 additions and 5 deletions
@@ -0,0 +1,74 @@
+# 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);`:
+
+```csharp
+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`:
+
+```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.