x/observability/devtools Primer
x/observability/devtools Primer
Section titled “x/observability/devtools Primer”Experimental — API compatibility is not frozen. Evaluate before adopting in production. Check Release Posture for current maturity status.
Open this page after x/observability Primer when the change is narrowly about development-time debug routes: local profiling endpoints, environment snapshot payloads, development metrics surfacing, or pubsub debug helpers.
x/observability/devtools is a subordinate debug-only package within the x/observability family. Start broader observability work in x/observability before opening this package directly. Devtools must never be mounted in production without an explicit gate.
Start here when
Section titled “Start here when”- you are adding or modifying a debug route (
/_debug/...) for local development inspection - you are implementing a runtime or config snapshot payload for development diagnostics
- you are adding development metrics surfacing at a debug endpoint
- you are building an environment reload helper for local hot-reload workflows
- you are adding pubsub debug helpers for inspecting in-process topic state (
pubsubdebug/)
Do not start here when
Section titled “Do not start here when”- the work is broader observability infrastructure such as Prometheus exporters or OTel wiring — start from x/observability Primer
- the change is about protected admin endpoints in production — that belongs in
x/observability/ops - the work needs stable root entrypoints or core bootstrap changes
- you intend to mount devtools routes in a production binary without an explicit development gate
First files to read in the current repository
Section titled “First files to read in the current repository”x/observability/devtools/module.yamlx/observability/devtools/devtools.gox/observability/devtools/devcollector.gox/observability/devtools/pubsubdebug/
Concrete ownership examples
Section titled “Concrete ownership examples”Keep it in x/observability/devtools when the work is about | Move out when the work becomes |
|---|---|
devtools.go: debug route registration and handler wiring | production admin endpoints — that belongs in x/observability/ops |
devcollector.go: collecting and surfacing runtime snapshots and config state | stable metrics or log root interface changes |
| Environment reload endpoints for local hot-reload workflows | production configuration management or runtime config API |
pubsubdebug: inspecting in-process broker state during local development | production broker monitoring or operational diagnostics |
Why this primer exists
Section titled “Why this primer exists”Debug tooling is valuable in development but dangerous in production. x/observability/devtools is the explicit home for debug-only routes so that they cannot accidentally migrate into x/observability/ops, x/observability, or core. The invariant is opt-in mounting: devtools routes must be registered explicitly in a development-only wiring path, never via package init or automatic discovery.