julien/apf_portal
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(development): add observability dev-loop section #73

Merged
julien merged 1 commits from docs/development/observability-dev-loop into main 2026-05-10 02:14:48 +02:00
Conversation 0 Commits 1 Files Changed 2
+101 -20
julien commented 2026-05-10 02:14:00 +02:00
Owner
Copy Link
Copy Source

Summary

ADR-0012 phase 1 + phase 2 are wired (BFF + SPA), so the "Observability dev-loop" placeholder in the roadmap table now has real content to point at. Promote it from §9 future-work list to a full §5 walkthrough sitting between "Daily commands" and "Dependency updates".

What §5 covers

  • Bringing up the observability stack — ./infra/local/dev.sh up observability, with the endpoint table (Jaeger UI, OTLP receiver, BFF stdout, browser DevTools).
  • Reading a trace in Jaeger — service-dropdown filter, span attribute keys to look at (http.method, db.statement, service.name, trace_id), the trace-id-as-pivot pattern.
  • Correlating a trace with the BFF Pino logs via trace_id and request_id (the per-request UUID nestjs-cls provides). Concrete grep example.
  • Reading SPA spans from the browser — DevTools Network filter on localhost:4318/v1/traces + Jaeger UI cross-check.
  • Common gotchas — observability profile not active, CORS pre-flight on /v1/traces, propagateTraceHeaderCorsUrls mismatches, NODE_ENV mis-set, EADDRINUSE on serve restart.
  • What's not in v1 — pointer at the "wired as features land" deltas (CLS keys for session/user/audience, redact list, custom domain spans, prod backend) so a contributor knows what's intentionally not yet there.

Renumbering

The new §5 pushes existing sections down. Final structure: 1. Repo layout / 2. Prerequisites / 3. Initial setup / 4. Daily commands / 5. Observability dev-loop / 6. Dependency updates (Renovate) / 7. Conventional commit cycle / 8. Where to look / 9. Roadmap.

The "Observability dev-loop" line in §9's roadmap table is removed (now implemented).

docs/README.md cross-link updated to mention the new section.

Test plan

  • CI green on this PR (format:check).
  • In a fresh checkout, follow §5's "Bring up the observability stack" verbatim, reach the Jaeger UI, then walk a trace through the grep correlation example with a synthetic request — flag any step that's wrong / missing on this real-world rehearsal.
## Summary ADR-0012 phase 1 + phase 2 are wired (BFF + SPA), so the "Observability dev-loop" placeholder in the roadmap table now has real content to point at. Promote it from §9 future-work list to a full §5 walkthrough sitting between "Daily commands" and "Dependency updates". ## What §5 covers - **Bringing up the observability stack** — `./infra/local/dev.sh up observability`, with the endpoint table (Jaeger UI, OTLP receiver, BFF stdout, browser DevTools). - **Reading a trace in Jaeger** — service-dropdown filter, span attribute keys to look at (`http.method`, `db.statement`, `service.name`, `trace_id`), the trace-id-as-pivot pattern. - **Correlating a trace with the BFF Pino logs** via `trace_id` and `request_id` (the per-request UUID `nestjs-cls` provides). Concrete `grep` example. - **Reading SPA spans from the browser** — DevTools Network filter on `localhost:4318/v1/traces` + Jaeger UI cross-check. - **Common gotchas** — observability profile not active, CORS pre-flight on `/v1/traces`, `propagateTraceHeaderCorsUrls` mismatches, NODE_ENV mis-set, EADDRINUSE on serve restart. - **What's not in v1** — pointer at the "wired as features land" deltas (CLS keys for session/user/audience, redact list, custom domain spans, prod backend) so a contributor knows what's intentionally not yet there. ## Renumbering The new §5 pushes existing sections down. Final structure: 1. Repo layout / 2. Prerequisites / 3. Initial setup / 4. Daily commands / 5. **Observability dev-loop** / 6. Dependency updates (Renovate) / 7. Conventional commit cycle / 8. Where to look / 9. Roadmap. The "Observability dev-loop" line in §9's roadmap table is removed (now implemented). `docs/README.md` cross-link updated to mention the new section. ## Test plan - [ ] CI green on this PR (`format:check`). - [ ] In a fresh checkout, follow §5's "Bring up the observability stack" verbatim, reach the Jaeger UI, then walk a trace through the `grep` correlation example with a synthetic request — flag any step that's wrong / missing on this real-world rehearsal.
julien added 1 commit 2026-05-10 02:14:01 +02:00
docs(development): add observability dev-loop section
CI / commits (pull_request) Successful in 1m14s
Details
CI / check (pull_request) Successful in 1m25s
Details
CI / scan (pull_request) Successful in 1m24s
Details
CI / a11y (pull_request) Successful in 1m19s
Details
CI / perf (pull_request) Successful in 2m58s
Details
6065922520 
ADR-0012 phase 1 + phase 2 are wired (BFF + SPA), so the
"Observability dev-loop" placeholder in the roadmap table now has
real content to point at. Promote it from §9 (was §8) future-work
list to a full §5 walkthrough sitting between "Daily commands"
and "Dependency updates".

What §5 covers:

- Bringing up the observability stack (`./infra/local/dev.sh up
  observability`) with the endpoint table.
- Reading a trace in Jaeger — service-dropdown filter, span
  attribute keys to look at, the trace-id-as-pivot pattern.
- Correlating a trace with the BFF Pino logs via `trace_id` and
  `request_id` (the latter the per-request UUID nestjs-cls
  provides).
- Reading SPA spans from the browser (DevTools Network +
  Jaeger UI cross-check).
- Common gotchas — observability profile not active, CORS
  pre-flight on `/v1/traces`, `propagateTraceHeaderCorsUrls`
  mismatches, NODE_ENV mis-set, EADDRINUSE.
- Pointer at the "wired as features land" deltas (CLS keys for
  session/user/audience, redact list, custom domain spans, prod
  backend) so a contributor knows what's intentionally not yet
  there.

Renumber the rest of the doc accordingly (5→6 / 6→7 / 7→8 / 8→9)
and drop the now-implemented "Observability dev-loop" line from
the §9 roadmap table.

`docs/README.md` cross-link updated to mention the new section.
julien merged commit 288610b9ba into main 2026-05-10 02:14:48 +02:00
julien deleted branch docs/development/observability-dev-loop 2026-05-10 02:14:51 +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
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: julien/apf_portal#73
Delete Branch "docs/development/observability-dev-loop"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?