chore(metrics): create datastore query series at startup (#1595 stack: 2/4)
What this delivers
This MR is part 2 of 4 of the split of !3348 (merged).
A new instance now exports the named-query series of every internal/datastore catalog name at 0 before any query runs.
Fix.
metrics.InitQuery creates the children of the four query families for one name with WithLabelValues, and records no observation.
datastore.QueryNames() lists every constant in internal/datastore/query_names.go.
registerServiceMetrics calls metrics.InitQuery for every name in that list.
Specific behavior:
TestQueryNames_ListsEveryCatalogConstantreads the constants from the source, so it fails when a new constant is missing fromQueryNames().database_query_cancellations_totalis seeded at bothcancellation_reasonvalues.- A deferred-timer query name books no outcome, so its
database_query_errors_totalanddatabase_query_cancellations_totalseries stay at0permanently. Itserrors / queriesratio is not a failure signal.docs/dev/database-query-patterns.mdanddocs/dev/observability.mdnow say this. - The
internal/storagenames are not seeded in this MR. The docs say that they still appear on first use, and thatupload_sessions_commit_txhas no outcome series. Part 3 seeds them and removes these sentences.
The stack
| Part | MR | Scope |
|---|---|---|
| 1 | !3353 (merged) | HTTP server series |
| 2 | This MR | Datastore query series |
| 3 | !3355 (merged) | Storage query series |
| 4 | !3348 (merged) | Job series |
Depends on !3353 (merged), which adds the shared test helpers that this MR uses.
Merge the parts in order.
When all four parts merge, the tree is the same as the !3348 (merged) head before the split, 9f5b5285608815c320547be1552405c410687eb9.
Spec coverage
Source: the issue card acceptance list. No spec governs startup series creation; S03-B and S27 govern only the label values.
| # | Criterion | Tests |
|---|---|---|
| AC-1 | The owning package exposes an Init helper next to its registration | TestInitQuery_CreatesTheNameChildrenWithoutAnObservation, TestWiring_SeedsHTTPAndQuerySeriesWithNoTraffic |
| AC-2 | Histogram children are created without an observation | TestInitQuery_CreatesTheNameChildrenWithoutAnObservation |
| AC-3 | Query names come from the catalog; a test fails when a constant is missing from the exported list | TestQueryNames_ListsEveryCatalogConstant, TestWiring_SeedsHTTPAndQuerySeriesWithNoTraffic |
| AC-7 | The query series are on /-/metrics of a fresh instance with no traffic |
TestWiring_MetricsEndpointServesSeededSeriesWithNoTraffic |
| AC-8 | AuditCardinality passes with the seeded series present |
TestWiring_CardinalityAuditPasses, TestIntegration_SeedsMountedRoutesAtStartup |
The issue card lists no error case and no security consideration.
E2E scenario catalog
No scenario is added or affected.
The row e2e.management.observability.metric-families-registered asserts a subset of families, and a new series breaks nothing.
Size
The diff is 736 added and 23 removed lines in 9 files, measured against part 1.
| File group | Files | Added | Removed |
|---|---|---|---|
internal/datastore/query_names.go, the QueryNames() list |
1 | 601 | 0 |
Go tests (*_test.go) |
4 | 105 | 11 |
| Other production Go | 2 | 16 | 1 |
docs/dev/ |
2 | 14 | 11 |
The 601 lines in query_names.go are one function that returns one constant per line, with no logic.
Without that list, the diff is 135 added lines, so a further split does not make the review smaller.
No customer-visible surface changes, so docs/user/ is not affected.
Related to #1595 (closed)