Skip to content

docs(002): re-baseline the telemetry spec for review round 2 of cdk-terrain #62 - #6

Open
so0k wants to merge 4 commits into
mainfrom
002-telemetry-rebaseline-2026-09
Open

docs(002): re-baseline the telemetry spec for review round 2 of cdk-terrain #62#6
so0k wants to merge 4 commits into
mainfrom
002-telemetry-rebaseline-2026-09

Conversation

@so0k

@so0k so0k commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Re-baselines specledger/002-remove-hashicorp-telemetry to the state of cdk-terrain PR #62 after its second review round (2026-09-09). The code is the source of truth; every metric name and attribute set below was derived from packages/@cdktn/commons/src/telemetry.ts and its delivery-oracle tests.

What changed

  • spec.md: FR-005 revised (the typed CdktfConfig.sendUsageTelemetry getter was removed; exactly one forgiving reader in commons), FR-012 (the Errors factories count cli.error{type, command} instead of posting), FR-014 (the canonical metric table with per-metric attributes and the once-per-failed-run rule for cli.command.error), FR-003 note for the ^10.73.0 pin. New FR-019 (binary, target and platform attributes from one lazy process-global probe), FR-020 (the restored per-stack and per-binding signal), FR-021 (enumerated and validated attributes, typed per-command allow-list, identity caps, SDK-stamped fields limited), FR-022 (single failure path, synchronous .fail, metric before the one bounded flush; absorbs cdk-terrain #378, fixes #360 and #361). SC-001 evidence re-grounded on the delivery oracle plus the CI E2E; SC-009 (E2E on every build) and SC-010 (LEAK-marker refutation) added. The HCL-output cli.stack.provider gap recorded as an edge case.
  • research/2026-09-09-review-round-2.md (new): decisions R1 to R7, the five privacy findings and their fixes, the adversarial test-review verdicts, and the three internal edge-case tests kept with their WHY.
  • research/2026-09-09-asset-pipeline-telemetry-evaluation.md (new): whether usage data could inform the asset-pipeline scope discussion (cdk-terrain #380). Verdict: very little; the one candidate metric is deferred, nothing is added to the library. research.md gets a pointer.
  • contracts/telemetry-contract.md, data-model.md, quickstart.md, pr-migration-notes.md: synced to the code (payload allow-list, metric catalogue, single flush helper and failure-path contract, removal list, rewritten collected-data and never-sent lists, journeys updated for the CI script).

Known divergences left as written

  • "Single emission point" for cli.command.error is not literal: two synth paths exit the process themselves and count their own failure; the spec says "once per failed run", which is what the code guarantees.
  • FR-004's "7 call sites" is stale; the call-site map in data-model.md carries the current count.
  • The June research decision to add a typed config getter stays in the history; its reversal is recorded in FR-005 and the new note rather than by rewriting the old decision.

so0k added 4 commits September 9, 2026 19:47
Revises FR-005 (the typed CdktfConfig getter is gone; one forgiving reader in
commons), FR-012 (the Errors factories count cli.error instead of posting) and
FR-014 (the canonical metric list with its attribute sets), and adds FR-019
(binary and target attributes), FR-020 (the restored per-stack signal), FR-021
(attribute validation) and FR-022 (the single failure path, absorbing #378).
Adds SC-009 and SC-010, re-grounds SC-001's evidence, and records the HCL-output
provider gap.
…evaluation

Adds the review round 2 note (decisions, privacy findings from the refutation
rounds, test review verdicts, known gaps) and the asset pipeline telemetry
evaluation, with pointers from research.md.
…tes to the code

C1 gains the payload allow-list and the metric catalogue plus C1b for the Errors
factories; C2 records the single commons reader; C5 becomes the one bounded
flush helper and the single failure path; C6 lists what was removed. The data
model carries the base attribute set, the metric table, the SDK-stamped fields
and the current call-site map. Quickstart re-grounds journey 1's evidence,
rewrites the bundle E2E journey around the CI step and adds the failure-path
journey. The migration notes list what is collected and what is never sent.
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