docs: split observability.md into Reference + How-to + Explanation#56
Merged
Conversation
F-min pulled from the docs-landing-and-comparison follow-ons. Two tutorials under a new docs/tutorials/ directory (Your first outbox app, Add a Kafka relay) plus a three-way split of docs/usage/observability.md into Reference (kept at URL, trimmed to event catalog + PromQL playbook), How-to (setup-prometheus-opentelemetry.md, adapter wiring), and Explanation (concepts/instrumentation-seams.md, the recorder-vs- middleware layering rationale). Spec covers structural calls (tutorials slot under Getting started, observability.md URL stays for SEO, tutorial code is executed end- to-end with literal captured output). Plan walks an executor through eight tasks; structural pieces are deterministic, tutorials require real code execution. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Splits out the adapter setup recipes (now usage/setup-prometheus-opentelemetry.md) and the layering rationale (now concepts/instrumentation-seams.md). Kept page stays at the URL for SEO continuity; new content adds an event-catalog table and absorbs the operator PromQL playbook from the former Prometheus-adapter section. Top-of-page see-also pair links to the new how-to and the new explanation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…explanation Two tutorial stubs land in docs/tutorials/ so the nav resolves; content is filled by the following per-tutorial commits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Scope reduction for this PR: the observability split (Tasks 4-7)
ships now; the two tutorials (Tasks 2-3) defer to a follow-on PR.
Reason: the spec's "tutorial code executed end-to-end with literal
captured output" discipline warrants a dedicated session, not a
rushed attempt at the tail of this one.
Removed from working tree: docs/tutorials/{first-outbox-app,
add-kafka-relay}.md (which were stubs added in the prior nav-reshape
commit) and the two Tutorial nav entries under Getting started.
Spec gets a "Scope reduction" callout at the top; plan T2 + T3 are
marked DEFERRED with a back-reference to the spec note.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
lesnik512
added a commit
that referenced
this pull request
Jun 12, 2026
…-split chore: archive shipped planning pair from #56
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
F-min — partial. Scope reduced from the spec: ships the observability split + supporting nav + planning artifacts. The two tutorials (Tutorial 1: Your first outbox app; Tutorial 2: Add a Kafka relay) are explicitly deferred to a follow-on PR — the spec's discipline that tutorial code must be executed end-to-end against a clean environment with literal terminal output captured warrants a dedicated session, not a rushed tail-end attempt.
The structural pieces stand on their own and are the meat of F-min in any case.
Summary
docs/concepts/instrumentation-seams.md— Explanation page for "why two instrumentation seams" (recorder vs native middleware). Extracted from the formerobservability.md § Layeringsection and expanded with the four-bullet "what each seam physically cannot observe" deep-dive.docs/usage/setup-prometheus-opentelemetry.md— How-to page for the practical wiring. Direct port of the former Prometheus / OpenTelemetry / native-middleware / both-seams-together setup sections fromobservability.md, with cross-section references retargeted.docs/usage/observability.mdtrimmed to Reference shape — the recorder seam API surface, the new event catalog table, the operator PromQL playbook, and the test broker note. Kept at the same URL for SEO continuity (327 → ~100 lines).mkdocs.yml— adds the two new nav entries (Concepts § Instrumentation seams, Guides § Setup Prometheus and OpenTelemetry).observability.mdpoints readers at the new How-to and the new Explanation.The spec and plan both include a "Scope reduction (2026-06-12)" note explaining the deferral; plan Tasks 2 and 3 are explicitly marked DEFERRED.
Test plan
just docs-build(mkdocs build --strict) passes clean — all cross-links resolve, no orphaned pagesjust lintpasses (eof-fixer, ruff format, ruff check, ty check)just docs-serveand confirm sidebar shows the new Concepts § Instrumentation seams and the new Guides § Setup Prometheus and OpenTelemetry; Reference § Observability is now Reference-shaped (event catalog table + PromQL playbook + recorder seam API + test-broker note)concepts/instrumentation-seams.mdand confirm it answers "why two seams?" without bleeding into setup recipesusage/setup-prometheus-opentelemetry.mdand confirm the four examples (Prometheus / OTel / native middleware / both-seams-together) port cleanlyOut of scope (deferred to follow-on PR per spec § Scope reduction)
Both kept in the spec § Design (intact) and the plan T2 + T3 (marked DEFERRED with backrefs).
🤖 Generated with Claude Code