From 8474b72bf4584f156856cb48673cd732d3ce24e2 Mon Sep 17 00:00:00 2001 From: Niek Otten Date: Thu, 23 Jul 2026 14:37:50 +0200 Subject: [PATCH] docs: demo note + backlog tick for distributed tracing (refs #123) refs #123 --- BACKLOG.md | 2 +- docs/demo-script.md | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/BACKLOG.md b/BACKLOG.md index b87a48b..627a2ef 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -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 ✅ diff --git a/docs/demo-script.md b/docs/demo-script.md index c4b7492..02aa957 100644 --- a/docs/demo-script.md +++ b/docs/demo-script.md @@ -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 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