Loading
docs(jobs): record River's accepted database surface
Summary
- Problem: S27's
#### Database connectionsection claimed that the shared connection pool gives River "one set of metrics". River's own statements are in neither query-name catalog, so none of thedatabase_query_*families counts them. The same section cited alabkit/v2@v2.3.1QueryTracerwiring that the tree does not run. No page stated which signals do cover River's database use, or what they cannot show. - Impact: Before this change, a reader of the spec or of the observability page had no statement of which signals cover River's database use. An operator who diagnoses a saturated connection pool had no signal that separates River's share of pool time or of database time from request load.
- Change: S27 now records the accepted surface (the connection-pool metrics, the OpenTelemetry spans the shared pool's instrumentation emits, and
jobs_in_flight{backend="river"}), names what that surface cannot show, and points to #1722 for per-query counters.docs/dev/observability.mdgains a### River's database surfacesubsection under the metrics table, which names thedatabase_connection_pool_*families, the reason none of thedatabase_query_*families counts River's statements, and the same follow-up pointer. The edits stay inside sections that already exist, and S27 keepsStatus: Approved. - Downsides: The change records the gap and does not remove it. Per-query counters for River's own statements wait on a LabKit option that chains a caller's
pgx.QueryTracer, and that work is #1722.
Checklist
- Ran it: n/a — the change is two Markdown documents. It adds no route and no runtime behavior, so there is nothing to run and no client to run it with.
- Interfaces and data: n/a — no API, configuration, schema, or wire or storage format changes. The two documents are developer-facing: S27, the spec for this surface, moves with the change, and
docs/dev/observability.mdrecords how to read the metrics. No customer-visible surface changes, sodocs/user/**needs no update. - Failure: n/a — documentation only. Nothing in this change can fail at runtime.
- Rollout: n/a — no schema and no configuration change, so a mixed-version deploy has nothing to act on.
- Hot path: n/a — no request path is touched.
- Database: n/a — no migration and no query change.
- Security: n/a — no input, route, permission, or audited action is added or changed.
- ADRs: ADR-006 (Technology Stack) governs the choice of River and its monitoring and observability requirement. ADR-003 (System Requirements) makes background job processing a required capability. The change holds both: it changes no code and records the surface the tree runs. No other ADR constrains the two files (checked
docs/adr/). - E2E: No scenario row is added or changed, and none is affected. The change is two documents: no route, no metric emission, and no client-visible behavior. No row asserts anything about a documentation page, so no row describes a journey this change touches.
- Simplicity: The issue names both documents, and each one needed the correction: S27 carried the stale claim, and the observability page had no River row. An edit to one file leaves the other one wrong.
Acceptance coverage
Coverage table, verbatim from the test author's return; its rows are the card's acceptance items (the header says so):
| # | Card acceptance item |
Coverage in this unit |
|---|---|---|
| 1 | S27 #### Database connection and docs/dev/observability.md record that pool stats, OTel spans and jobs_in_flight{backend="river"} are the River database surface, and name what they cannot show. |
No Go test can carry it (verified above: nothing reads either file). It is a review-level row over the two documents. Deterministic gates that do run on the change: lint:doc-size (bash scripts/ci/check-doc-size.sh --base <base>) and lint:new-markdown (bash scripts/ci/check-new-markdown.sh --base <base>), both in .gitlab-ci.yml. Owned by the implementation author. |
| 2 | The docs point to #1722 for River query counters; current state only, with no promise of a date. | Review-level row, same as row 1. Grep-checkable evidence: 1722 has no match today in docs/specs/S27-background-jobs-foundation.md or in docs/dev/observability.md, so the row closes on the string appearing in both files with no date-bearing wording. |
| 3 | The LabKit feature request is filed and linked from #1721 (closed) and #1722. | Operator action, outside the smurfit unit — no row here can close it. The card's Notes say so, the body marks it (operator action, outside the smurfit unit), and the draft text is in the body under ### LabKit feature request (draft). It stays open for the operator. |
| 4 | S27 stays Status: Approved. |
Read-checkable: S27 line 3 is **Status:** Approved today (verified). No script or CI job validates the status field (grep over scripts/ for Status:.*Approved / \*\*Status:\*\*: no matches), so this is a review check, not a mechanical gate. |
Diff at a165df1679c481d40f4d0f33208435eca471cd6c: 2 files, 13 lines added and 19 removed — docs/dev/observability.md 7 added, docs/specs/S27-background-jobs-foundation.md 6 added and 19 removed.
Closes #1721 (closed) Acceptance item 3 is met outside this MR: the request is already open as gitlab-org/labkit#154, with Artifact Registry's use case added, and #1721 (closed) and #1722 link to it.
This is a bot message
Edited by Pawel Rozlach