feat(obs): distributed traces across the .NET services (S-16b, closes #123) (#126)

## What & why

S-16b, second of the S-16 split, on top of the #125 backplane. The five .NET services now emit OpenTelemetry traces so a request is **one connected trace** across them.

- Each host wires `AddOpenTelemetry().WithTracing(...)` with `AddAspNetCoreInstrumentation` (incoming) + `AddHttpClientInstrumentation` (outgoing) + `AddOtlpExporter` to **Tempo**.
- Because every cross-service call already goes through a typed `HttpClient` (§8 boundaries), the W3C `traceparent` propagates with no manual code — bff → domain → acl → openzaak and bff → projection-api stitch into a single trace.
- Service name + OTLP endpoint come from `OTEL_*` env set per app service in compose. `/health` is filtered out so liveness polls don't flood the traces.

No new ADR — ADR-0023 already records the stack + the two documented gaps (browser-side tracing is out of scope, so the trace begins at the BFF; the async Flowable-poll boundary is a separate trace).

Closes #123

## Definition of Done

- [x] Failing test committed first (`verify-tracing` fails with no instrumentation).
- [x] Implementation makes it pass — **validated locally end to end**: a real connected trace spanning `bff` + `projection-api` was found in Tempo (BFF→projection→db + Tempo subset, no OpenZaak/egress).
- [x] Conventional Commits referencing the issue (`refs #123`).
- [ ] CI green — awaiting Gitea Actions (verify-tracing added to verify-stack after verify-bff).
- [x] `docker compose up` health unaffected — services boot healthy even when Tempo is unreachable (exporter no-ops; verified).
- [x] Docs — demo-script + BACKLOG.
- [x] ADR — none needed (covered by ADR-0023).

## Notes for reviewers

- **Per-service wiring, no shared lib:** the block is duplicated across the five hosts by design — services don't share code across boundaries here (§8), same as the duplicated typed clients.
- **Packages:** OpenTelemetry.Extensions.Hosting / Instrumentation.AspNetCore / Instrumentation.Http / Exporter.OpenTelemetryProtocol, all 1.17.0, pinned per-csproj (no central props file).
- **The check** generates anonymous BFF→projection traffic (no auth, no OpenZaak), then queries Tempo (TraceQL search → fetch trace → assert both service.names present) from a python:3-slim container in-network — same idiom as run-projection-check.sh.
- **Next:** #124 (S-16c) adds `/metrics` + Prometheus scrape targets + golden-signal Grafana dashboards.

Reviewed-on: #126

services/acl/Acl.Api/Acl.Api.csproj

@@ -5,6 +5,13 @@
     <ProjectReference Include="..\Acl.Infrastructure\Acl.Infrastructure.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.17.0" />
+  </ItemGroup>
+
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
     <Nullable>enable</Nullable>

services/acl/Acl.Api/Program.cs

@@ -1,8 +1,21 @@
 using Acl.Application;
 using Acl.Infrastructure;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
 
 var builder = WebApplication.CreateBuilder(args);
 
+// OpenTelemetry tracing (S-16b, ADR-0023): auto-instrument incoming ASP.NET Core requests and
+// outgoing HttpClient calls (the ACL → OpenZaak hop), exported over OTLP to Tempo. Service name +
+// OTLP endpoint come from OTEL_* env (compose); the exporter no-ops when Tempo is unreachable.
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService(
+        builder.Configuration["OTEL_SERVICE_NAME"] ?? builder.Environment.ApplicationName))
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation(o => o.Filter = ctx => ctx.Request.Path != "/health")
+        .AddHttpClientInstrumentation()
+        .AddOtlpExporter());
+
 builder.Services.AddSingleton<IClock, SystemClock>();
 builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
     .GetSection("Acl:Defaults").Get<AclDefaults>()

services/bff/Bff.Api/Bff.Api.csproj

@@ -10,6 +10,10 @@
     <!-- OIDC/JWT validation of Keycloak-issued tokens (ADR-0010) and OpenAPI generation. -->
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.8" />
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.8" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.17.0" />
   </ItemGroup>
 
 </Project>

services/bff/Bff.Api/Program.cs

@@ -3,9 +3,23 @@ using System.Text.Json;
 using System.Text.Json.Serialization;
 using Bff.Api;
 using Microsoft.AspNetCore.Authentication.JwtBearer;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
 
 var builder = WebApplication.CreateBuilder(args);
 
+// OpenTelemetry tracing (S-16b, ADR-0023): auto-instrument incoming ASP.NET Core requests and
+// outgoing HttpClient calls (BFF → Domain, BFF → projection-api), exported over OTLP to Tempo, so a
+// portal request is one connected trace across the services. Service name + OTLP endpoint come from
+// OTEL_* env (compose); the exporter no-ops when Tempo is unreachable. /health is filtered out.
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService(
+        builder.Configuration["OTEL_SERVICE_NAME"] ?? builder.Environment.ApplicationName))
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation(o => o.Filter = ctx => ctx.Request.Path != "/health")
+        .AddHttpClientInstrumentation()
+        .AddOtlpExporter());
+
 var keycloakAuthority = builder.Configuration["Keycloak:Authority"]
     ?? throw new InvalidOperationException("Missing configuration 'Keycloak:Authority'");
 // Behandelaars authenticate against a *different* Keycloak realm (medewerker) than citizens (digid),

services/domain/Big.Api/Big.Api.csproj

@@ -6,6 +6,10 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.17.0" />
     <PackageReference Include="Quartz.Extensions.Hosting" Version="3.18.2" />
   </ItemGroup>
 

services/domain/Big.Api/Program.cs

@@ -1,10 +1,25 @@
 using Big.Application;
 using Big.Domain;
 using Big.Infrastructure;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
 using Quartz;
 
 var builder = WebApplication.CreateBuilder(args);
 
+// OpenTelemetry tracing (S-16b, ADR-0023): auto-instrument incoming ASP.NET Core requests and
+// outgoing HttpClient calls, exported over OTLP to Tempo, so a request is one connected trace across
+// the services. Service name + OTLP endpoint come from OTEL_* env (compose); the exporter no-ops
+// harmlessly when Tempo is unreachable (e.g. a service run standalone). /health is filtered out so
+// liveness polls don't flood the traces.
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService(
+        builder.Configuration["OTEL_SERVICE_NAME"] ?? builder.Environment.ApplicationName))
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation(o => o.Filter = ctx => ctx.Request.Path != "/health")
+        .AddHttpClientInstrumentation()
+        .AddOtlpExporter());
+
 // Options bound from configuration (compose sets Flowable__* and Acl__* env vars).
 builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
     .GetSection("Flowable").Get<FlowableOptions>()

services/event-subscriber/EventSubscriber.Api/EventSubscriber.Api.csproj

@@ -5,6 +5,13 @@
     <ProjectReference Include="..\..\projection-api\Projection.ReadModel\Projection.ReadModel.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.17.0" />
+  </ItemGroup>
+
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
     <Nullable>enable</Nullable>

services/event-subscriber/EventSubscriber.Api/Program.cs

@@ -1,9 +1,22 @@
 using System.Text.Json;
 using EventSubscriber.Application;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
 using Projection.ReadModel;
 
 var builder = WebApplication.CreateBuilder(args);
 
+// OpenTelemetry tracing (S-16b, ADR-0023): auto-instrument the incoming NRC notification callback and
+// the outgoing ACL enrichment call, exported over OTLP to Tempo. Service name + OTLP endpoint come
+// from OTEL_* env (compose); the exporter no-ops when Tempo is unreachable.
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService(
+        builder.Configuration["OTEL_SERVICE_NAME"] ?? builder.Environment.ApplicationName))
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation(o => o.Filter = ctx => ctx.Request.Path != "/health")
+        .AddHttpClientInstrumentation()
+        .AddOtlpExporter());
+
 var connectionString = builder.Configuration.GetConnectionString("Projection")
     ?? throw new InvalidOperationException("Missing connection string 'ConnectionStrings:Projection'");
 // The exact Authorization header value Open Notificaties sends on each abonnement callback.

services/projection-api/ProjectionApi.Api/Program.cs

@@ -1,8 +1,21 @@
 using Microsoft.EntityFrameworkCore;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
 using Projection.ReadModel;
 
 var builder = WebApplication.CreateBuilder(args);
 
+// OpenTelemetry tracing (S-16b, ADR-0023): auto-instrument incoming ASP.NET Core requests, exported
+// over OTLP to Tempo, so a BFF → projection-api read is one connected trace. Service name + OTLP
+// endpoint come from OTEL_* env (compose); the exporter no-ops when Tempo is unreachable.
+builder.Services.AddOpenTelemetry()
+    .ConfigureResource(r => r.AddService(
+        builder.Configuration["OTEL_SERVICE_NAME"] ?? builder.Environment.ApplicationName))
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation(o => o.Filter = ctx => ctx.Request.Path != "/health")
+        .AddHttpClientInstrumentation()
+        .AddOtlpExporter());
+
 var connectionString = builder.Configuration.GetConnectionString("Projection")
     ?? throw new InvalidOperationException("Missing connection string 'ConnectionStrings:Projection'");
 

services/projection-api/ProjectionApi.Api/ProjectionApi.Api.csproj

@@ -4,6 +4,13 @@
     <ProjectReference Include="..\Projection.ReadModel\Projection.ReadModel.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.17.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.17.0" />
+  </ItemGroup>
+
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
     <Nullable>enable</Nullable>