docs: fix broken anchors + stale RUNBOOK metric names#305
Merged
Conversation
- 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
#migration--rollout(double dash) and one used#3-customer-stable-contracts(truncated). Replaced with the canonical slugs#migration-rolloutand#3-customer-stable-telemetry-contracts.module/receiver/ncclfrreceiver/RUNBOOK.mdstill referenced v0.1.x names (tracecore_receiver_errors_total,tracecore_exporter_calls_total,tracecore_receiver_degraded_seconds_total). The v0.2.0 OCB binary emitsotelcol_receiver_ncclfr_*andotelcol_exporter_<name>_*per the in-tree namespace alignment table indocs/migration/v0.1-to-v0.2.md. Also flippedresult="fail"→result="error"to match the migration table's worked example.tracecore.container.lines_per_sindocs/ATTRIBUTES.mdcarried a "recipe TBD" emitter, but thecontainerstdoutreceiver 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-contractsdocs/ATTRIBUTES.md— droptracecore.container.lines_per_srowdocs/integrations/{k8sobjects-events,filelog-container,journald-kernel}.md— anchor fixdocs/migration/v0.1-to-v0.2.md— anchor fix (2 occurrences)docs/migration/v0.2-to-v0.3.md— anchor fixdocs/notes/ci.md— anchor fixdocs/reproducibility.md— anchor fixmodule/receiver/ncclfrreceiver/RUNBOOK.md— 4 metric-name rewrites + migration-doc citationWhy
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/metricsendpoint, 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 indocs/rfcs/0009-pyspy-receiver-scope.md, outside this PR's scope).grep -n 'Customer-stable telemetry contracts' docs/rfcs/0013-distro-first-pivot.mdconfirms heading exists at L97.docs/migration/v0.1-to-v0.2.mdlines 113-121 (in-tree namespace alignment table) and lines 137-138 (worked PromQL migration recipe —result="error").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.