feat(portal-shell): wire spa-side opentelemetry tracing #72

Merged

julien merged 1 commits from feat/portal-shell/observability-foundations into main 2026-05-09 23:23:21 +02:00

Conversation 0 Commits 1 Files Changed 7

+255 -36

julien commented 2026-05-09 23:21:42 +02:00

Owner

Copy Link

Copy Source

Summary

Phase 2 of ADR-0012 — closes the loop SPA → BFF → DB. After this PR, a single user action (initial 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 through Prisma, and (eventually) Redis / downstream-API hops.

What lands

Browser-side OTel libs (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

No @opentelemetry/context-zone: the workspace is zoneless per ADR-0004; the default StackContextManager covers the auto-instrumented paths. Custom spans across await will need explicit context.with(...) plumbing — fine, encountered as code lands.

Code:

• apps/portal-shell/src/observability/tracing.ts — WebTracerProvider bootstrap. Documents the load-order constraint inline (same pattern as the BFF: must be the very first import of main.ts, otherwise auto-instrumentations miss everything imported above).
• apps/portal-shell/src/main.ts now imports the tracing module as line 1.

CORS plumbing for end-to-end trace 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 / tracestate headers. The full security-grade CORS (per-environment allowlists, helmet, cookie-session, CSRF) belongs to the future phase-2 security ADR — this PR adds the strict minimum for the SPA→BFF trace context to survive cross-origin pre-flight.
• OTel Collector (infra/local/otel-collector.yaml) gains a cors block on its OTLP/HTTP receiver so the browser's own OTLP POST clears its pre-flight.

ADR-0012 §Confirmation rewritten: a new "Wired in the SPA foundation PR (phase 2)" block enumerates what landed here; the carry-over "Wired as features land" list drops the SPA-side SDK item and adds a follow-up note about the security-grade CORS.

Verification

pnpm exec nx run-many -t lint test build           # 8 projects green
pnpm audit                                          # 0 vulns
./infra/local/dev.sh up observability               # bring up Collector + Jaeger
./infra/local/dev.sh                                # (separately, BFF stack — your choice)
pnpm nx serve portal-bff                           # localhost:3000
pnpm nx serve portal-shell                         # localhost:4200

Open http://localhost:4200 → a document_load trace appears in http://localhost:16686 with service.name=portal-shell. From DevTools, run fetch('http://localhost:3000/api/health').then(r => r.json()) → a fetch span appears with a child BFF span on the same trace.

Test plan

• CI green on this PR.
• After local up, document_load span visible in Jaeger UI for the SPA.
• Cross-origin fetch from SPA carries traceparent (visible in Network tab) and produces a single end-to-end trace SPA → BFF in Jaeger.
• DevTools console shows no CORS warnings about traceparent, tracestate, or the localhost:4318/v1/traces POST.

## Summary Phase 2 of ADR-0012 — closes the loop SPA → BFF → DB. After this PR, a single user action (initial 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 through Prisma, and (eventually) Redis / downstream-API hops. ## What lands **Browser-side OTel libs** (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 No `@opentelemetry/context-zone`: the workspace is zoneless per ADR-0004; the default `StackContextManager` covers the auto-instrumented paths. Custom spans across `await` will need explicit `context.with(...)` plumbing — fine, encountered as code lands. **Code**: - [`apps/portal-shell/src/observability/tracing.ts`](apps/portal-shell/src/observability/tracing.ts) — `WebTracerProvider` bootstrap. Documents the load-order constraint inline (same pattern as the BFF: must be the very first import of `main.ts`, otherwise auto-instrumentations miss everything imported above). - `apps/portal-shell/src/main.ts` now imports the tracing module as line 1. **CORS plumbing** for end-to-end trace 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` / `tracestate` headers. The full security-grade CORS (per-environment allowlists, helmet, cookie-session, CSRF) belongs to the future phase-2 security ADR — this PR adds the strict minimum for the SPA→BFF trace context to survive cross-origin pre-flight. - OTel Collector (`infra/local/otel-collector.yaml`) gains a `cors` block on its OTLP/HTTP receiver so the browser's own OTLP POST clears its pre-flight. **ADR-0012 §Confirmation** rewritten: a new "Wired in the SPA foundation PR (phase 2)" block enumerates what landed here; the carry-over "Wired as features land" list drops the SPA-side SDK item and adds a follow-up note about the security-grade CORS. ## Verification ```bash pnpm exec nx run-many -t lint test build # 8 projects green pnpm audit # 0 vulns ./infra/local/dev.sh up observability # bring up Collector + Jaeger ./infra/local/dev.sh # (separately, BFF stack — your choice) pnpm nx serve portal-bff # localhost:3000 pnpm nx serve portal-shell # localhost:4200 ``` Open http://localhost:4200 → a `document_load` trace appears in http://localhost:16686 with `service.name=portal-shell`. From DevTools, run `fetch('http://localhost:3000/api/health').then(r => r.json())` → a fetch span appears with a child BFF span on the same trace. ## Test plan - [ ] CI green on this PR. - [ ] After local up, `document_load` span visible in Jaeger UI for the SPA. - [ ] Cross-origin fetch from SPA carries `traceparent` (visible in Network tab) and produces a single end-to-end trace SPA → BFF in Jaeger. - [ ] DevTools console shows no CORS warnings about `traceparent`, `tracestate`, or the `localhost:4318/v1/traces` POST.

julien added 1 commit 2026-05-09 23:21:42 +02:00

feat(portal-shell): wire spa-side opentelemetry tracing ... 13a12e6591

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 merged commit 8f2cd4e068 into main 2026-05-09 23:23:21 +02:00

julien deleted branch feat/portal-shell/observability-foundations 2026-05-09 23:23:27 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

adastra-bot (AdAstra Bot) julien (Julien Gautier)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: julien/apf_portal#72