docs(telemetry): #1906 cannot drain these spools, and four comments said it would

[LukasWodka]

Part of backend#2217. Split out deliberately so the correction isn't buried inside the delivery work, which is blocked on a credential decision (see below).

Correction (was: "comment-only, no behaviour change"). That framing was wrong and @saqlainsyed007 / Bugbot caught it. scripts/lib/telemetry.sh is bootstrap-fetched and hash-pinned, so editing a comment changes its digest — and install.sh verifies the fetched file against scripts/manifest.sha256, aborting before the privileged install on a mismatch. For a hash-pinned bootstrap file the digest is part of the contract. scripts/manifest.sha256 is regenerated in 789e4e1 (exactly one line moves: 38b2a2e9… → d773c8a1…). The prose below is unchanged; this note stays rather than being edited away, because the wrong claim is the instructive part.

What was wrong

scripts/lib/telemetry.sh said in four places that #1906's forwarder would read or drain the spool files this module writes. It cannot, and the reason is structural rather than a matter of sequencing:

#1906 is an OpenTelemetry Collector running as a pod inside the customer's Kubernetes cluster, reading container stdout through a filelog receiver. Neither spool is container stdout and neither is reachable from a pod — $HOST_DATA_DIR/telemetry/pending.jsonl and the $TMPDIR fallback are files on the operator's own machine. Worse, the pre-log failures the fallback exists for (validate_config, early_data_dir_guard) happen when there is often no cluster to run a Collector in at all.

This is why the host transport went unowned. backend#1907 was closed on the understanding that the remaining transport belonged to #1905 plus #1906. It didn't, and these comments are what made that reading look right. This file is the first place the next person looks, so it now points at backend#2217 and says why #1906 is the wrong answer — so the same wrong conclusion isn't re-derived a third time.

Also recorded: the trim's disagreement with D7 is deliberate

The spool's tail -n trim is drop-oldest, which is deliberately not what RFC-BACKEND-1872 D7's overflow row says since rfcs#36. D7 was amended to drop-newest because exporterhelper sheds at the entrance and offers nothing else — a constraint on the Collector's queue, not a preference. This spool is our own code and can do what D7 originally wanted, so it does: the newest records describe the failure in progress.

Without that note the next reader has a standing invitation to "fix" the disagreement in the wrong direction. The same note is in the Go spool on cli#542.

Test plan

• bash -n scripts/lib/telemetry.sh — OK
• shellcheck -S warning -x scripts/lib/telemetry.sh — clean (CI severity, not -S error)
• scripts/tests/telemetry.bats — 44/44 pass
• scripts/tests/telemetry-vocabulary-agreement.sh — green, all six agreement checks

No mutation table: this diff contains no logic, so there is nothing to mutate. Asserting otherwise would be the vacuous-guard pattern this epic keeps finding.

The PowerShell twin needed no matching change — install-k8s.ps1 contains no telemetry at all (grep -ci telemetry → 0), so there is no twin drift. That absence is arguably its own gap: a Windows install currently reports nothing. Not filed, since it's outside this ticket.

What is NOT in this PR, and why

The actual POST. backend#2217 assumes the installer can authenticate, and it cannot today. The ingest endpoint requires Authorization: Token … or Bearer … (IsAuthenticatedEdge), and the installer holds TRACEBLOC_CLIENT_ID/TRACEBLOC_CLIENT_PASSWORD — a provisioning pair, not a bearer token. It also never reads the CLI's ~/.tracebloc/config.json (zero hits across scripts/), so there is no existing path to a token.

Options and a recommendation are on backend#2217. That is a design decision, not an implementation detail, so it isn't being made in a PR.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and checksum only; no executable telemetry or delivery logic changes.

Overview
Comment-only correction in telemetry.sh: host JSONL spools are not drained by #1906 (in-cluster Collector on container stdout). Ownership is now backend#2217, because those files live on the operator machine and often exist before any cluster.

Also documents that _telemetry_trim_spool's drop-oldest tail -n is intentional vs RFC D7's drop-newest Collector queue. Updates manifest.sha256 for the file. No runtime change.

^{Reviewed by Cursor Bugbot for commit 789e4e1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ec4c0c1. Configure here.}

[saqlainsyed007]

The correction itself is right and worth landing — #1906 is an in-cluster OTel Collector reading container stdout, so it genuinely cannot reach $HOST_DATA_DIR/telemetry/pending.jsonl or the $TMPDIR fallback on the operator's machine, and pointing the next reader at #2217 (plus the deliberate drop-oldest-vs-D7 note) is the right fix for a comment that mislabelled ownership twice already.

But this isn't behaviour-free, and the open Bugbot finding at telemetry.sh:141 is exactly why — it's a real High, and it's what's reddening CI:

scripts/manifest.sha256 is stale.telemetry.sh is a bootstrap-fetched script pinned in the manifest, so even a comment-only edit changes its digest — the drift check shows it moving 38b2a2e9… → d773c8a1…. All three failures are this one cause:

• Source-of-truth drift (make drift): [ERROR] scripts/manifest.sha256 is out of date. Run scripts/gen-manifest.sh and commit.
• bats / Unit tests: not ok 418 a clean tree passes --check in gen-manifest.bats.

And it's not just CI cosmetics: at runtime install.sh verifies the fetched telemetry.sh against the pinned hash and would abort before the privileged install on the mismatch. So the "comment-only, no behaviour change" framing doesn't hold for a hash-pinned bootstrap file — the digest is part of the contract.

Fix: run scripts/gen-manifest.sh and commit the updated scripts/manifest.sha256 (the drift log spells out the same command). That greens all three checks and closes the Bugbot thread. Nothing else needed — the prose is good; re-request me once the manifest is regenerated and I'll approve.

[LukasWodka]

@saqlainsyed007 — fixed in 789e4e1. Bugbot's thread auto-resolved on the push.

You caught something better than a red check: my "comment-only, no behaviour change" claim was false, and falsely in the direction that matters. telemetry.sh is bootstrap-fetched and hash-pinned, so install.sh verifies it against scripts/manifest.sha256 and aborts before the privileged install on a mismatch — meaning this would have broken every fresh install while every local check I ran stayed green. For a hash-pinned bootstrap file the digest is part of the contract, and I treated it as metadata.

Ran scripts/gen-manifest.sh. Exactly one line moves — 38b2a2e9… → d773c8a1…, the digests you quoted — and that single-line diff is itself the check that this is the manifest catching a real edit rather than unrelated drift riding along on my commit.

I have corrected the PR description rather than deleting the wrong sentence, and left the correction visible as a note. A PR body that quietly stops being wrong teaches nobody; this file's whole subject is comments that mislabelled ownership twice, so silently editing away my own mislabel would have been the same defect one level up.

Verified: gen-manifest.sh --check up to date · make drift green on all 6 guards · gen-manifest.bats 20/20 · telemetry.bats 44/44. Re-requested you.

[saqlainsyed007]

The manifest fix is exactly right — 789e4e1c regenerates scripts/manifest.sha256 for the new telemetry.sh digest, and the commit title ("a comment edit IS a behaviour change" for a hash-pinned bootstrap file) captures precisely why. That closes the Bugbot :141 thread and the root cause of all three red checks. CI is re-running (Prereqs / Unit / bats pending) — I'll approve as soon as it's green; nothing else outstanding.

[LukasWodka]

@saqlainsyed007 — CI is green: 42 passed, 0 failed, 0 pending (4 skipped). Source-of-truth drift, Unit tests and bats — the three that were red — all pass now, and the Bugbot :141 thread auto-resolved on the push.

Worth restating the bit your review made me correct, since it's the durable lesson: I shipped this as "comment-only, no behaviour change" and that was false for a hash-pinned bootstrap file. install.sh verifies the fetched telemetry.sh against manifest.sha256 and aborts before the privileged install, so it would have broken every fresh install while every local check I ran stayed green. The PR description carries that correction visibly rather than having quietly stopped being wrong.

[LukasWodka]

@saqlainsyed007 — this one is stuck on a formality rather than anything outstanding, so flagging it precisely.

Your CHANGES_REQUESTED is still the governing review decision, which is what keeps the PR BLOCKED. You then commented that the manifest fix is "exactly right" with "nothing else outstanding" and that you'd approve once green — and it has been green for a while now: 42 passed, 0 failed, 0 pending, 0 unresolved threads, Bugbot's :141 thread auto-resolved.

The thing that needs you specifically: only you can clear your own change-request. An approval from another reviewer does not dismiss it, and you had dropped off the requested-reviewer list, so nothing was prompting you to look again. I have re-requested you.

Nothing to re-review unless you want to — the only change since your comment is 789e4e1c, the manifest regeneration you asked for.

[saqlainsyed007]

Approving — and thanks for splitting this out so the correction isn't buried in the delivery work.

I verified the thing my earlier note was actually about: scripts/lib/telemetry.sh is bootstrap-fetched and hash-pinned, so editing even a comment changes its digest, and install.sh aborts before the privileged install on a manifest.sha256 mismatch. I recomputed the digest of telemetry.sh at this head and it matches the regenerated manifest line exactly:

d773c8a11fa80d6880b5a104e2159de1dc9aaa35234ad6a764e4e1c49f601aec scripts/lib/telemetry.sh

So the hash gate is satisfied — this won't brick the installer. The prose correction itself is right and important: #1906 is an in-cluster OTel Collector reading container stdout via filelog, and neither $HOST_DATA_DIR/telemetry/pending.jsonl nor the $TMPDIR fallback is container stdout or reachable from a pod — and the pre-log failures the fallback exists for happen when there may be no cluster at all. Pointing the next reader at backend#2217 (and saying why #1906 is the wrong answer) is what stops the unowned-transport conclusion being re-derived a third time. Recording that the drop-oldest trim's disagreement with D7 is deliberate — D7 went drop-newest only because exporterhelper sheds at the entrance — is a good guard against someone "fixing" it the wrong way. LGTM.