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