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_ListsEveryCatalogConstant reads the constants from the source, so it fails when a new constant is missing from QueryNames().
  • database_query_cancellations_total is seeded at both cancellation_reason values.
  • A deferred-timer query name books no outcome, so its database_query_errors_total and database_query_cancellations_total series stay at 0 permanently. Its errors / queries ratio is not a failure signal. docs/dev/database-query-patterns.md and docs/dev/observability.md now say this.
  • The internal/storage names are not seeded in this MR. The docs say that they still appear on first use, and that upload_sessions_commit_tx has 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.

🤖 Generated with Claude Code

Related to #1595 (closed)

Edited by Pawel Rozlach

Merge request reports

Loading
Loading