Phase 2 of ADR-0012 — closes the loop SPA → BFF → DB. With this
PR a single user action (page load, click, form submit) produces
one trace whose root span is owned by the SPA and whose child
spans cover the BFF request, Postgres queries, and (eventually)
Redis / downstream-API hops.
Runtime libs added (production deps):
- @opentelemetry/sdk-trace-web browser tracer + provider
- @opentelemetry/exporter-trace-otlp-http OTLP/HTTP+JSON exporter
- @opentelemetry/instrumentation auto-instrumentation runtime
- @opentelemetry/instrumentation-fetch fetch + W3C traceparent propagation
- @opentelemetry/instrumentation-document-load initial-paint timings
- @opentelemetry/instrumentation-user-interaction click / keypress / submit
Code:
- apps/portal-shell/src/observability/tracing.ts — WebTracerProvider
bootstrap. Documents the load-order constraint inline (must be
the very first import of main.ts, same pattern as the BFF). No
context-zone package because the workspace is zoneless (per
ADR-0004); the default StackContextManager covers the
auto-instrumentation cases.
- main.ts now imports the tracing module as line 1.
CORS plumbing for end-to-end propagation:
- BFF (apps/portal-bff/src/main.ts) calls enableCors with a
minimal dev allowlist (http://localhost:4200) and explicit
permission for the W3C traceparent and tracestate headers. The
full security-grade CORS belongs to phase-2 security ADR; this
is the strict minimum for the SPA→BFF link to keep the trace
context across origins.
- OTel Collector (infra/local/otel-collector.yaml) gains a cors
block on its OTLP/HTTP receiver so the browser's OTLP POST
clears its own pre-flight.
ADR-0012 §Confirmation: a new "Wired in the SPA foundation PR
(phase 2)" block enumerates what landed here; the carry-over
"Wired as features land" list is updated to drop the SPA-side
SDK item that used to live there and to add a CORS-grade
follow-up note.
Verified locally:
- pnpm exec nx run-many -t lint test build → 8 projects green.
- pnpm audit clean.
- After ./infra/local/dev.sh up observability and nx serve
portal-shell, opening http://localhost:4200 produces a
document_load trace in Jaeger with the SPA service.name; a
manual fetch from DevTools to /api/health on the BFF produces
a child span on the same trace.
Julien Gautier