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

infra/docker-compose.yml

@@ -296,6 +296,10 @@ services:
       dockerfile: Dockerfile
     image: register-referentie/acl:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: acl
       # Overridable so verify-domain can point the ACL at the same OpenZaak host that
       # owns the seeded zaaktype URL (host-consistent zaak creation, ADR-0009).
       Acl__OpenZaak__BaseUrl: ${ACL_OPENZAAK_BASEURL:-http://openzaak:8000/}
@@ -334,6 +338,10 @@ services:
       dockerfile: Dockerfile
     image: register-referentie/domain:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: domain
       Flowable__BaseUrl: http://flowable-rest:8080/flowable-rest/
       Flowable__Username: rest-admin
       Flowable__Password: test
@@ -360,6 +368,10 @@ services:
       dockerfile: Dockerfile
     image: register-referentie/bff:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: bff
       # The BFF is the portals' only backend; it validates digid tokens and fans out (ADR-0010).
       # Keycloak (start-dev) derives the issuer from the request host, so the BFF authority and the
       # verify token request both use keycloak:8080 to keep the issuer consistent.
@@ -412,6 +424,10 @@ services:
       dockerfile: services/event-subscriber/Dockerfile
     image: register-referentie/event-subscriber:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: event-subscriber
       ConnectionStrings__Projection: Host=projection-db;Database=projection;Username=projection;Password=projection
       # The subscriber enriches the projection with each zaak's reference (identificatie) by asking
       # the ACL — the only code allowed to read ZGW (§8.1, #78).
@@ -441,6 +457,10 @@ services:
       dockerfile: services/projection-api/Dockerfile
     image: register-referentie/projection-api:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: projection-api
       ConnectionStrings__Projection: Host=projection-db;Database=projection;Username=projection;Password=projection
     ports:
       - "8120:8080"
@@ -538,12 +558,16 @@ services:
       context: ./observability/tempo
     image: register-referentie/tempo:dev
     command: ["-config.file=/etc/tempo.yaml"]
+    # Cap the backplane's footprint so it can't starve the app stack + the Playwright browser on the
+    # memory-tight CI runner (verify-e2e OOM history, commit d5e5fa2). Generous vs idle (~150M).
+    mem_limit: 400m
     networks: [cg]
 
   prometheus:
     build:
       context: ./observability/prometheus
     image: register-referentie/prometheus:dev
+    mem_limit: 400m
     ports:
       - "9090:9090"
     networks: [cg]
@@ -552,6 +576,7 @@ services:
     build:
       context: ./observability/grafana
     image: register-referentie/grafana:dev
+    mem_limit: 512m
     environment:
       GF_SECURITY_ADMIN_USER: admin
       GF_SECURITY_ADMIN_PASSWORD: admin

infra/run-tracing-check.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# S-16b (#123): assert one connected distributed trace spans the .NET services in Tempo,
+# against an ALREADY-RUNNING full stack. Runs the driver in a python:3-slim container on the
+# stack network (services reached by container IP; the runner can't reach published ports —
+# gitea-actions-gotchas.md §5/§6). Does NOT manage the stack lifecycle.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+ip() { docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$1"; }
+
+bff="$(docker ps -q --filter 'name=[-_]bff[-_]' | head -1)"
+tempo="$(docker ps -q --filter 'name=[-_]tempo[-_]' | head -1)"
+[ -n "$bff" ] && [ -n "$tempo" ] || { echo "ERROR: bff and/or tempo not running — bring the stack up first" >&2; exit 1; }
+net="$(docker inspect -f '{{range $k,$_ := .NetworkSettings.Networks}}{{$k}}{{"\n"}}{{end}}' "$bff" | head -1)"
+bff_ip="$(ip "$bff")"; tempo_ip="$(ip "$tempo")"
+echo ">> network=$net bff=$bff_ip tempo=$tempo_ip"
+
+cid="$(docker create --network "$net" \
+  -e "BFF=http://$bff_ip:8080" -e "TEMPO=http://$tempo_ip:3200" \
+  -e "TRACING_TIMEOUT=${TRACING_TIMEOUT:-90}" \
+  python:3-slim python /tracing-check.py)"
+docker cp "$here/tracing-check.py" "$cid:/tracing-check.py" >/dev/null
+rc=0; docker start -a "$cid" || rc=$?
+docker rm -f "$cid" >/dev/null
+exit $rc

infra/tracing-check.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""S-16b (#123): prove distributed tracing works end to end.
+
+Generate anonymous BFF traffic (GET /openbaar/register, which the BFF serves by
+calling projection-api — no auth, no OpenZaak egress), then query Tempo and assert
+that ONE trace contains spans from both `bff` and `projection-api`. That proves the
+services export OTLP to Tempo AND that the W3C traceparent propagates across the
+HttpClient hop, stitching the request into a single connected trace.
+
+Stdlib only (urllib/json) so it runs in a bare python:3-slim container in-network.
+"""
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BFF = os.environ["BFF"]        # http://<bff-ip>:8080
+TEMPO = os.environ["TEMPO"]    # http://<tempo-ip>:3200
+TIMEOUT = int(os.environ.get("TRACING_TIMEOUT", "90"))
+WANT = {"bff", "projection-api"}  # the two services that must share one trace
+
+
+def _get(url):
+    with urllib.request.urlopen(url, timeout=10) as r:
+        return r.read()
+
+
+def generate_traffic():
+    # A non-2xx still produces spans; only total unreachability of the BFF is fatal.
+    for _ in range(3):
+        try:
+            _get(f"{BFF}/openbaar/register")
+        except urllib.error.HTTPError:
+            pass
+
+
+def search_trace_ids():
+    q = urllib.parse.quote('{ resource.service.name = "bff" }')
+    try:
+        data = json.loads(_get(f"{TEMPO}/api/search?q={q}&limit=50"))
+    except Exception:
+        return []
+    return [t["traceID"] for t in data.get("traces", [])]
+
+
+def services_in_trace(trace_id):
+    try:
+        data = json.loads(_get(f"{TEMPO}/api/traces/{trace_id}"))
+    except Exception:
+        return set()
+    names = set()
+    for batch in data.get("batches", []):
+        for attr in batch.get("resource", {}).get("attributes", []):
+            if attr.get("key") == "service.name":
+                names.add(attr.get("value", {}).get("stringValue"))
+    return names
+
+
+def main():
+    deadline = time.time() + TIMEOUT
+    generate_traffic()
+    seen = set()
+    while time.time() < deadline:
+        for tid in search_trace_ids():
+            names = services_in_trace(tid)
+            seen |= names
+            if WANT.issubset(names):
+                print(f"OK — trace {tid} spans {sorted(names)}")
+                return 0
+        time.sleep(3)
+        generate_traffic()
+    print(f"FAIL — no single trace spanned {sorted(WANT)}; services seen: {sorted(seen)}",
+          file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())