x/observability/ops Primer
x/observability/ops Primer
Section titled “x/observability/ops 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 protected admin surfaces: auth-gated operations endpoints, queue and receipt admin hooks, diagnostics routes that require authentication, or health HTTP management orchestration.
x/observability/ops is a subordinate package within the x/observability family. Start broader observability work in x/observability before opening this package directly.
Start here when
Section titled “Start here when”- you are adding or modifying a protected admin HTTP endpoint that requires authentication
- you are wiring queue admin hooks or receipt management endpoints
- you are building explicit auth-gated diagnostic routes (
ops.go) - you are orchestrating health HTTP management via
x/observability/ops/healthhttp
Do not start here when
Section titled “Do not start here when”- the work is broader observability infrastructure such as Prometheus exporters, OTel wiring, or record buffering — start from x/observability Primer
- the change is about debug-only development routes — that belongs in
x/observability/devtools - the work introduces core bootstrap ownership or stable root entrypoints
- the change adds tenant bootstrap policy or per-tenant admin policy — coordinate with
x/tenant
First files to read in the current repository
Section titled “First files to read in the current repository”x/observability/ops/module.yamlx/observability/ops/ops.gox/observability/ops/healthhttp/
Concrete ownership examples
Section titled “Concrete ownership examples”Keep it in x/observability/ops when the work is about | Move out when the work becomes |
|---|---|
| Auth-gated admin routes: queue inspection, receipt status, runtime diagnostics | business admin dashboards or domain-specific management UIs |
healthhttp: orchestrating liveness and readiness HTTP endpoints with health primitives | stable health root types or health check registration |
| Queue and receipt admin hooks for operational inspection | application-level business queue management or domain workflows |
| Explicit auth middleware wrapping for all admin routes | authentication token issuance — that belongs in security/jwt |
Why this primer exists
Section titled “Why this primer exists”Admin surfaces carry security risk: an unprotected endpoint leaks internal state. x/observability/ops enforces that all admin routes are explicitly auth-gated, fail closed on authentication errors, and registered through visible wiring rather than automatic discovery. The subordinate relationship with x/observability prevents ops endpoints from competing with the family entrypoint and ensures their security posture is reviewed in context.