docs(metrics): bring the S03-B database table up to the shipped families (#1718 stack: 1/2)

Summary

Problem. The S03-B ### Database table lists four families. internal/metrics registers thirteen, and docs/dev/observability.md already documents all thirteen. The spec is the source of truth for the database surface, and it describes a smaller surface than the service publishes. Nothing read the spec, so the drift stayed silent.

Impact. A reader of the spec sees a database surface with nine families missing. The name budget row says "up to ~200" where the code bounds the label at 700. An operator who writes an alert, a developer who adds a family, and a reviewer who checks the budget all work from that text.

Change. The ### Database table gains the nine missing families, each with the labels internal/metrics/database.go declares. A short paragraph after the table points to docs/dev/observability.md for how to read each family. The instrumenter prose names InstrumentQueryErr and InitQuery, and "the two vectors" becomes "the four vectors". The prose names database_queries_total as the counter that duplicates the histogram's _count series. The pool prose covers the family set the collector emits and the snapshot the provider yields. The name budget row states the code's 700 and points at #908 (closed) for the catalog's growth policy, and a cancellation_reason row joins the table. cancellation_reason also joins the closed-set enumerations, and the pool counters' zero value is stated.

Downsides. The MR changes only the spec text. No test reads the spec, so a family registered later without a row still passes CI. Issue #1784 (closed) decides how to guard the spec against that drift.

Checklist

  • Ran it: n/a. The change is a specification document only, and it has no runtime behavior. There is nothing to drive against a running service with a client.
  • Interfaces and data: n/a. The change touches no API, configuration, schema, wire format, or storage format. It edits the S03-B specification and the cardinality budget table that document the metrics surface. No customer-visible surface changes, so docs/user/** is unaffected.
  • Failure: n/a. The change adds no code and no failure path.
  • Rollout: n/a. The change ships no schema and no configuration, so the previous release runs unchanged against it.
  • Hot path: n/a. The change touches no request path and adds no Go code.
  • Database: n/a. The change adds no migration and changes no query.
  • Security: n/a. The change adds no input, route, permission, or audited action, and it changes no authentication or authorization.
  • ADRs: None of the ADRs synced into this repository governs the change. It corrects a specification's table and prose. ADR 006 (technology stack) and ADR 012 (usage data collection) mention metrics as platform tooling, and neither constrains this table or its budgets.
  • E2E: n/a. No scenario row is added or changed, because the change asserts nothing that a client or an operator observes. It is a specification document only.
  • Simplicity: The change corrects the spec text and adds nothing else. The guard against later drift is left to #1784 (closed).

Acceptance coverage

Source of the rows: the card's acceptance items, which restate the issue body's ## Acceptance criteria. No test covers these rows in this MR; each is met by the diff.

# Criterion (card acceptance) Evidence
A-1 Every gitlab_artifact_registry_database_* family that internal/metrics registers on origin/main has a row in the S03-B ### Database table, with the same labels. The diff adds the nine missing rows to the ### Database table.
A-2 The instrumenter prose names InstrumentQueryErr and InitQuery. The diff adds both to the instrumenter prose.
A-3 The name budget in the expected-distinct-values table agrees with internal/metrics/cardinality.go, or points to #908 (closed). The name row states 700, the code's budget, and points to #908 (closed).
A-4 The spec stays Status: Approved. The branch does not change the spec's **Status:** line. docs/specs/README.md makes the spec index authoritative for status.

Files: docs/specs/S03-b-metrics.md +32/−39.

Merge order

This MR merges first. !3527 (closed) is stacked on this MR. !3527 (closed) adds a CI job that runs the S03-B spec tests when the spec changes, and this MR no longer adds those tests.

Closes #1718 (closed)

This is a bot message 🤖 — /smurfit

Edited by Pawel Rozlach

Merge request reports

Loading
Loading