Skip to content

docs: fix broken anchors + stale RUNBOOK metric names#305

Merged
trilamsr merged 1 commit into
mainfrom
docs/anchor-fixes
Jun 1, 2026
Merged

docs: fix broken anchors + stale RUNBOOK metric names#305
trilamsr merged 1 commit into
mainfrom
docs/anchor-fixes

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Sweep of broken doc anchors and stale tracecore_* self-telemetry metric names that drifted after the v0.2.0 OCB pivot.

Three independent root causes:

  1. Anchor typos — 8 cross-links to RFC-0013 used #migration--rollout (double dash) and one used #3-customer-stable-contracts (truncated). Replaced with the canonical slugs #migration-rollout and #3-customer-stable-telemetry-contracts.
  2. Stale RUNBOOK metric vocabularymodule/receiver/ncclfrreceiver/RUNBOOK.md still referenced v0.1.x names (tracecore_receiver_errors_total, tracecore_exporter_calls_total, tracecore_receiver_degraded_seconds_total). The v0.2.0 OCB binary emits otelcol_receiver_ncclfr_* and otelcol_exporter_<name>_* per the in-tree namespace alignment table in docs/migration/v0.1-to-v0.2.md. Also flipped result="fail"result="error" to match the migration table's worked example.
  3. Orphan attribute rowtracecore.container.lines_per_s in docs/ATTRIBUTES.md carried a "recipe TBD" emitter, but the containerstdout receiver was deleted at v0.2.0 (RFC-0013 PR-K.2 / §7) and no replacement emitter exists. Dropped the row.

Files touched

  • docs/getting-started.md#3-customer-stable-contracts#3-customer-stable-telemetry-contracts
  • docs/ATTRIBUTES.md — drop tracecore.container.lines_per_s row
  • docs/integrations/{k8sobjects-events,filelog-container,journald-kernel}.md — anchor fix
  • docs/migration/v0.1-to-v0.2.md — anchor fix (2 occurrences)
  • docs/migration/v0.2-to-v0.3.md — anchor fix
  • docs/notes/ci.md — anchor fix
  • docs/reproducibility.md — anchor fix
  • module/receiver/ncclfrreceiver/RUNBOOK.md — 4 metric-name rewrites + migration-doc citation

Why

Anchor fragments silently 404 in GitHub-rendered docs (no broken-link CI gate for fragment-only mismatches). Stale RUNBOOK metric names point operators at series that no longer exist on the :8888/metrics endpoint, blocking incident response. The orphan ATTRIBUTES row implied a recipe was in flight when in fact the upstream emitter was deleted two minors ago.

Test plan

  • git grep '#migration--rollout' docs/ returns 0 in-scope hits (the one remaining occurrence is an intra-doc link in docs/rfcs/0009-pyspy-receiver-scope.md, outside this PR's scope).
  • grep -n 'Customer-stable telemetry contracts' docs/rfcs/0013-distro-first-pivot.md confirms heading exists at L97.
  • RUNBOOK metric names cross-checked against docs/migration/v0.1-to-v0.2.md lines 113-121 (in-tree namespace alignment table) and lines 137-138 (worked PromQL migration recipe — result="error").
  • Pre-push hooks: golangci-lint, go vet, go mod verify, doc-check (554 markdown links resolved on-disk), alert-check, chart-appversion-check, no-autoupdate-check — all green.
docs: fix 9 broken cross-doc anchors (RFC-0013 §migration and §3 slug), rewrite stale v0.1.x `tracecore_*` self-telemetry metric names in `module/receiver/ncclfrreceiver/RUNBOOK.md` to the v0.2.0 `otelcol_receiver_ncclfr_*` / `otelcol_exporter_<name>_*` vocabulary, and drop the orphan `tracecore.container.lines_per_s` row from `docs/ATTRIBUTES.md` (no emitter — `containerstdout` deleted at v0.2.0 per RFC-0013 §7).

- Replace #migration--rollout -> #migration-rollout in 8 doc cross-links
  (k8sobjects-events, filelog-container, journald-kernel, ci.md,
  reproducibility, v0.1-to-v0.2 x2, v0.2-to-v0.3).
- getting-started.md: #3-customer-stable-contracts ->
  #3-customer-stable-telemetry-contracts (full RFC-0013 heading slug).
- ncclfrreceiver/RUNBOOK.md: rewrite v0.1.x tracecore_* metric names to
  v0.2.0 otelcol_receiver_ncclfr_* / otelcol_exporter_<name>_*
  vocabulary per the in-tree-namespace-alignment table in
  docs/migration/v0.1-to-v0.2.md; cite the migration doc inline.
- ATTRIBUTES.md: drop tracecore.container.lines_per_s row -- the
  containerstdout receiver was deleted at v0.2.0 (RFC-0013 PR-K.2)
  and the attribute has no current emitter.

Signed-off-by: Tri Lam <tri@maydow.com>
@trilamsr trilamsr enabled auto-merge (squash) June 1, 2026 06:25
@trilamsr trilamsr merged commit 82d6dde into main Jun 1, 2026
11 checks passed
@trilamsr trilamsr deleted the docs/anchor-fixes branch June 1, 2026 06:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant