S03 spec: observability metrics framework and inherited metric set

Context

Spawned by the narrowing of S03 to logging-only on !56 (merged). The metrics framework, the foundational metric set every spec inherits, and the /-/metrics API contract were cut from S03 to keep the narrowing focused. This issue tracks the follow-up spec that picks them up.

Scope

Define:

  • The Prometheus library and namespace (gitlab_artifact_registry_*, BuildName(subsystem, name) discipline).
  • Patterns every metric must follow: naming, label allowlists, exemplar policy.
  • The foundational metric set every spec inherits: HTTP server middleware (S01 chain position #8 (closed)), HTTP client, database, object storage, runtime, readiness gauge.
  • Histogram bucket choices across HTTP, DB, storage, and size families.
  • Cardinality governance (disallowed-label list, expected distinct-value table, lint enforcement).
  • The /-/metrics API contract (OpenMetrics + exemplars on the internal listener).

Source material

The pre-narrowing version of S03 at commit 5592b76, specifically:

  • Lines 91-403: ### Metrics and all subsections (library/namespace, scope/catalog growth, exposition, HTTP server middleware, HTTP client, database, object storage, runtime, readiness, histogram buckets, cardinality governance).
  • Lines 897-910: ### GET /-/metrics API contract.

Author treats those sections as starting material, not a frozen contract. Reviewer feedback on the original sections is in !56 (merged)'s history.

Known consumer

#54: Wire datastore query metrics per S03 catalog currently blocks on the cut metrics catalog. Update its references when this spec ships.

Related

  • Sister follow-ups from the same narrowing: tracing framework, readiness + internal listener.
  • !56 (merged) (the narrowing MR).

Closure criterion

The framework spec ships and replaces the placeholder reference to this issue in:

  • docs/specs/S03-observability.md Summary and Out of Scope.
  • docs/dev/observability.md catalog header.