docs: demo note + backlog tick for distributed tracing (refs #123)

refs #123
2026-07-23 14:37:50 +02:00
parent 271c54197e
commit 8474b72bf4
2 changed files with 28 additions and 1 deletions
@@ -260,7 +260,7 @@ Split (issue #11 closed) into two independently-demoable slices per §13 — the
 Split into independently deployable sub-slices (CLAUDE.md §13):

 - **S-16a** (#122) · Observability backplane — Grafana Tempo + Prometheus + Grafana in compose, datasources auto-provisioned (ADR-0023). No collector; config baked into built images.
- **S-16b** (#123) · Distributed traces across the five .NET services (OTLP → Tempo; nginx `traceparent` passthrough). Depends on S-16a.
+- **S-16b** (#123) · Distributed traces across the five .NET services (OTLP → Tempo; traceparent propagates via the typed HttpClients). Depends on S-16a. ✅
 - **S-16c** (#124) · Prometheus metrics + golden-signal Grafana dashboards. Depends on S-16a.

 ### S-17 · Quartz.NET scheduler — herregistratie reminder sweep ✅
@@ -5,6 +5,33 @@ copy-pasteable walkthrough against a local `make up` stack.

 ---

+## S-16b — distributed traces across the .NET services (#123, ADR-0023)
+
+**Outcome:** the five .NET services (BFF, Domain, ACL, projection-api, event-subscriber) now emit
+OpenTelemetry traces — ASP.NET Core + `HttpClient` auto-instrumentation, exported over OTLP to Tempo.
+Because every cross-service call goes through a typed `HttpClient`, the W3C `traceparent` propagates for
+free, so a request is **one connected trace** across the services (bff → domain → acl → openzaak;
+bff → projection-api). `/health` is filtered out. No browser-side instrumentation yet, so the trace
+begins at the BFF; the async Flowable-poll boundary is a separate trace (ADR-0023).
+
+```bash
+# 1. Automated (a CI verify-stack step): generate BFF traffic and assert Tempo holds one trace
+#    spanning multiple services.
+make verify-tracing              # → OK — trace <id> spans ['bff', 'projection-api']
+
+# 2. By hand: drive the stack, then explore traces in Grafana.
+make up
+curl -s localhost:8080/openbaar/register >/dev/null   # BFF → projection-api
+open http://localhost:3000       # Grafana → Explore → Tempo → Search → service.name = bff → open a trace
+```
+
+**The path:** each host wires `AddOpenTelemetry().WithTracing(AddAspNetCoreInstrumentation +
+AddHttpClientInstrumentation + AddOtlpExporter)`; `OTEL_SERVICE_NAME` / `OTEL_EXPORTER_OTLP_ENDPOINT`
+come from compose; spans export to **tempo:4317** and render in Grafana against the provisioned Tempo
+datasource.
+
+---
+
 ## S-16a — observability backplane: Tempo + Prometheus + Grafana (#122, ADR-0023)

 **Outcome:** the compose stack now includes a Grafana-native observability backplane — **Tempo** (OTLP