docs: add ADR-0012 for observability (Pino + OpenTelemetry, W3C Trace Context, stdout + collector)
Pin the observability foundation. Two signals are in scope: structured logs and distributed traces. Logs: pino + nestjs-pino, JSON line-delimited on stdout, with a fixed envelope (level, time, service, version, env, trace_id, span_id, session_id, user_id_hash, audience, msg, ...). Pino redact strips a reviewable allowlist of sensitive paths (Authorization/Cookie headers, *.password, *.access_token, *.refresh_token, ...). user_id_hash uses a per-environment salt (LOG_USER_ID_SALT) so the same userId is not correlatable across environments. Tracing: OpenTelemetry SDK for Node + auto-instrumentations (HTTP, Express, NestJS, pg, ioredis, Prisma). The SPA also runs OTel-Web with an HTTP interceptor propagating traceparent on outbound calls; the same trace_id is the correlation identifier from the user click to the DB query. No separate X-Correlation-ID. Request-scoped context lives in nestjs-cls; the Pino formatter and the future audit-log writer pull from CLS - no per-call threading. Sampling is 100% at the application; tail sampling is performed at the local OpenTelemetry Collector (deferred to the phase-3 infrastructure ADR, where the on-prem backend - Grafana stack, ELK, or other - will be chosen). Output: stdout for logs, OTLP/HTTP for traces, both consumed by the local collector. The application stays vendor-neutral. Audit logs are explicitly out of scope of this ADR - they share the trace_id but use a separate writer and a separate sink (next ADR). decisions/README.md index updated. CLAUDE.md gains an explicit 'Observability' summary pointing to ADR-0012.
This commit is contained in:
@@ -55,3 +55,4 @@ ADRs are listed in numerical order. To slice by topic, filter on the `Tags` colu
|
||||
| [0009](0009-auth-flow-oidc-pkce-msal-node.md) | Authentication flow — OIDC Authorization Code + PKCE via MSAL Node, BFF session pattern | accepted | `security`, `backend` | 2026-04-29 |
|
||||
| [0010](0010-session-management-redis.md) | Session management — opaque session IDs in cookies, payload in self-hosted Redis with AES-GCM at rest | accepted | `security`, `backend`, `infrastructure` | 2026-04-29 |
|
||||
| [0011](0011-mfa-enforcement-entra-conditional-access.md) | MFA enforcement — Entra ID Conditional Access baseline, BFF claim sanity-check, step-up hooks designed-in | accepted | `security` | 2026-04-29 |
|
||||
| [0012](0012-observability-pino-opentelemetry.md) | Observability — Pino structured logs + OpenTelemetry tracing, W3C Trace Context propagation, stdout + collector | accepted | `observability`, `backend`, `frontend` | 2026-04-29 |
|
||||
|
||||
Reference in New Issue
Block a user