Rewrite the living observability docs off the legacy request id
This is the final G7 step of the trace-graph migration. The PRAMAAN-minted request id is fully retired in code (functions / app / admin RIPs merged). This Story brings the live teaching surface in pramaan-docs in line with that reality.
What this Story is
A documentation-only rewrite. It removes the retired correlation-id model from PRAMAAN's living observability docs and replaces it with the trace-context model that pramaan-docs ADR-124 made canonical: trace_id is the one technical request identity, traceparent is the propagation carrier, run_id stays the agent business-run key, and the bar is one connected server-side trace graph.
Why it matters
AGENTS.md sends every bug investigation to docs/runbooks/debugging.md first. If the playbook still tells engineers to query a retired field, the doctrine actively misleads. Living docs must describe the system that exists, not the one that was decommissioned.
Accepted ADRs are immutable history and keep their original text. The grep-zero gate applies only to living docs (runbooks, rules, primers), never to docs/decisions/adrs/.
What changed
Rewritten in place (no path renamed, so all inbound citations and image assets stay valid):
| File | Change |
|---|---|
docs/runbooks/debugging.md | Symptom→log-source playbook now threads by trace_id; queries, CLI loops, headers, log-shape table, and the user-facing support-reference contract moved to trace_id / traceparent. Incident worked examples preserved. |
docs/rules/constitution.md | Rule 21 shared-context fields moved to trace_id / span_id; states there is no separate PRAMAAN request id. |
docs/primers/observability-debugging-xray.md | Collapsed the two-ID courier model to one identity; trace_id is now both receipt number and barcode. Glossary, request-path diagram, playbooks, forced-sample smoke, and quick reference updated. |
docs/primers/technical/observability/correlation-propagation.md | Whole-page rewrite from the X-Request-ID OBS-3 model to W3C traceparent propagation, including async-hop carriage and the baggage allowlist. Filename kept (cited path). |
docs/primers/technical/observability/{index,structured-logging,tracing,metrics-and-alarms}.md + bridge-utilities/observability.md | Log/trace context fields, examples, and annotation/metadata split aligned to trace_id / span_id and ADR-124 §D11. |
docs/primers/handbook/main.tex | Stale Logs Insights query filter moved to trace_id. |
docs/primers/technical/observability/glossary.md | New AC-required doc: defines trace_id, span_id, traceparent/tracestate, span, span link, parent/child edge, the connected graph, the baggage allowlist, and the egress stripper. |
Acceptance criteria
- grep-zero cid in living docs —
grep -rnIE 'correlation_id|correlationId|\bcid\b'overdocs/runbooks/ docs/rules/ docs/primers/returns zero. ✅ - accepted ADRs keep historical text —
docs/decisions/adrs/untouched; cid persists there by design. ✅ - no cited path renamed — every rewritten file kept its path; the
correlation-reference-404.pngscreenshot asset is intact. ✅
Not in scope
No code, no runtime, no ADR edits. The defined living-docs surface is runbooks / rules / primers. Residual cid mentions in docs/checklists/, docs/doctrine/, and the time-stamped docs/investigations/ and docs/session-logs/ evidence records are outside this Story's stated scope and are flagged in the PR body for a follow-up decision (evidence logs are append-only per AGENTS.md). The compiled handbook PDF is a derived artifact of main.tex (now clean); a rebuild can follow.