docs(lifecycle): align the S20-A lifecycle metrics docs with the code

What this delivers

The S20-A lifecycle metrics documentation and comments now match the code, the measured environment selector and the current owners. No behavior changes: three of the four files are Markdown, and the only Go change is comment text in internal/lifecycle/metrics.go.

Cause. The purger's metric surface moved after these documents were written, and the documents did not follow. The package header of internal/lifecycle/metrics.go described three families and left the fourth, purge_counter_emit_drops_total, in a comment above package lifecycle, outside the header. Its cross-reference then claimed expectedDistinctValues carries three counts, where internal/metrics/cardinality.go:292-298 declares four. The four alert rules moved to #1661 on 2026-10-15, so docs/dev/alerting.md still pointed at #354 (closed) (closed) and still described a file to create. The build_info measurement returned application series in both environments, which refuted the claims that no series reach the Mimir tenant. The S20-A spec's Observability table never gained the purge_scope label or the purge-lag histogram, and the four uncounted tombstone tables had no recorded reason.

What the change does.

  • internal/lifecycle/metrics.go: the header lists all four families. The emit-drop counter is the fourth bullet, its stray comment is deleted, and the counts sentence now says "the same four counts", which matches cardinality.go:292-298. The "three signals" wording in observePurge and purgeObservation stays, because those functions record three signals.
  • docs/dev/alerting.md: the paragraph that names the purger rules' owner points at #1661, and the rules land in the existing hand-written mimir-rules/runway/artifact-registry-gke.yml, not in a file to create. Every expression takes the environment="production" selector, the label the measured series carry. The paragraph that claimed no series reach the Mimir tenant now records that they arrive in both environments.
  • docs/dev/observability.md: all four uncounted tables — container_remote_blobs, maven_remote_files, npm_files and npm_remote_files — are recorded as excluded on purpose, with one reason each and the #1694 (closed) link for the npm_files orphan.
  • docs/specs/S20-a-lifecycle-closed-beta.md: the Observability table names the purge_scope label on the outcome counter and gains a row for gitlab_artifact_registry_lifecycle_purge_lag_seconds. The spec is over its word limit, so the added rows are offset by a cut in the sweep row of the ## Error Cases table. Two stale claims that the repositories discovery index is not implemented are corrected to the migration that shipped it.

Coverage

The rows come from the card's acceptance (card lines 22-29), which restates the issue body's ## Acceptance criteria.

Acceptance (card lines 22-29) Edit surface Test owed?
1. internal/lifecycle/metrics.go header lists all four families; line 86 matches cardinality.go Go comments only. Lines 1-55 and 79-97 are the file's doc comment; line 86 sits inside the block comment at 79-97 ("expectedDistinctValues carries the same three counts"), and the :54-55 block the card folds in is a comment above package lifecycle. No statement, label, or family changes. no
2. docs/dev/alerting.md paragraph about #354 (closed) points at a live owner Markdown no
3. Decide the spec and plan corrections and make them or record why not Markdown (spec table rows) + MR-description prose. Card OQ-3 A amends the spec; OQ-2 C records the plan decision in the MR description; no plan file is edited. no
4. A test or shared constant keeps internal/accounting's purge_scope values inside cardinality.go's closed set Already on main — §4 no (already met)
5. Count npm_files and the other uncounted tables, or document them as excluded on purpose Card OQ-6 B chose the documentation path: docs/dev/observability.md :161 and :219-224 only. CountTombstonesByLevel, the HELP string, artifactTombstoneCountTables are untouched. no — §5
6. Settle the selector with the build_info query and record the answer External Mimir measurement (card OQ-7 A: {env="production",environment="production"} 2, {env="staging",environment="staging"} 2), recorded on #1599 (closed) and posted on #1661; the doc selectors in alerting.md then follow it. no
7. alerting.md :257-263 and :287-291 stop claiming the rule file must be created / collection is unverified Markdown no

Acceptance 4's guard already exists on main, at TestTombstoneCollector_PassesTheCardinalityAudit (internal/accounting/metrics_integration_test.go:1011-1049). A reverted mutation showed that it fails when an internal/accounting purge_scope value leaves the closed set in cardinality.go. Acceptance 5 takes the documentation path, which adds no count and no test. No test file is added or updated, and scripts/ci/check-changed-line-coverage.sh counts no statement for a comment-only Go diff.

E2E scenario catalog

This MR changes no row in docs/testing/. No e2e scenario is added or affected. The diff is comment text in one Go file and three Markdown documents, and it changes no runtime behavior. No scenario row asserts comment text or documentation wording.

Size

The diff is four files, 63 added and 60 removed lines, measured at f5ba960978c32f20b7fa82e6c9d3d012ce218da7 with git diff --numstat 82cdd618db0f9437905d75943c3792666c43bd91 f5ba960978c32f20b7fa82e6c9d3d012ce218da7.

File group Files Added Removed
docs/dev/ (alerting, observability) 2 42 42
docs/specs/ (S20-A) 1 6 5
internal/lifecycle/metrics.go (comment text) 1 15 13

Merge order

!3380 (merged) (open) rewrites the same docs/dev/observability.md :161 and :220 tombstone-count sentences and the gauge HELP text, and it edits the S20-A spec outside ### Observability. Whichever merge request merges second rebases, and the spec's doc-size gate measures the second one again after that rebase. The merged-tree check of this branch with !3380 (merged) fails test_datastore on TestQueryNames_ListsEveryCatalogConstant (internal/datastore/queries_test.go:388): ten catalog constants of !3380 (merged) are missing from QueryNames(). !3380 (merged) must list them when it rebases. This branch does not touch internal/datastore/. !3368 (merged) edits the S20-A spec at other ranges, and !2971 (merged) (Draft) edits docs/dev/alerting.md at :323-329. Both are a line-number risk only.

Plan and spec amendments

Spec. The S20-A Observability table is corrected in this MR. :774 names the purge_scope label, and one row is added for gitlab_artifact_registry_lifecycle_purge_lag_seconds. The cut named above pays for the added words, which the doc-size gate requires.

Plan. No S20-A plan line changes. docs/plans/2026-08-11-s20a-lifecycle-closed-beta.md:1088 and :1090 record that Step 16 put "the three families Step 17a creates" on /-/metrics. That text is a true record of what Step 16 shipped against. Step 17a created three families, and the fourth came from 99ebd6be2, which is not a plan step. docs/dev/conventions.md:56 reserves a plan-amendment MR for adding, removing, splitting or reordering steps, and a count correction changes no step. The Step 20b counts (plan :1402, :1418, :1473-:1484, :1511) are Step 20b's own text under docs/dev/conventions.md:52. That correction therefore belongs to !3380 (merged), which is open and was built against the old text. This MR leaves those lines unchanged.

  • #1661 owns the four purger alert rules and their transcription into mimir-rules/runway/artifact-registry-gke.yml. The build_info measurement is recorded there.
  • #1600 (closed): this MR meets the alerting.md:257-263 half of its last acceptance item. It also removes the collection claims in alerting.md:447-450, which is the collection half of that item. The owner-pointer half — the #354 (closed) links at :445 and :450 — stays with #1600 (closed).
  • #1662: the stale #354 (closed) pointers at docs/dev/storage-accounting.md:1577 and docs/runbooks/reconciliation-lockout.md:306 are out of scope here. They go to #1662 as follow-up work, and the hand-off is recorded on that item.
  • #1694 (closed): the npm_files orphan-tombstone defect, filed as a public type::bug issue and linked from docs/dev/observability.md.

Closes #1599 (closed)

This is a bot message 🤖 — /smurfit

Merge request reports

Loading
Loading