docs: plan the CLI telemetry implementation#511
Conversation
Add the spec, plan and ADRs for CLI telemetry and its backend service. Signed-off-by: Alexey Orlenko <alex@aqrln.net>
@prisma-next/extension-upgrade-skill
@prisma-next/upgrade-skill
@prisma-next/mongo-runtime
@prisma-next/family-mongo
@prisma-next/sql-runtime
@prisma-next/family-sql
@prisma-next/extension-arktype-json
@prisma-next/extension-cipherstash
@prisma-next/middleware-cache
@prisma-next/mongo
@prisma-next/extension-paradedb
@prisma-next/extension-pgvector
@prisma-next/extension-postgis
@prisma-next/postgres
@prisma-next/sql-orm-client
@prisma-next/sqlite
@prisma-next/target-mongo
@prisma-next/adapter-mongo
@prisma-next/driver-mongo
@prisma-next/contract
@prisma-next/utils
@prisma-next/config
@prisma-next/errors
@prisma-next/framework-components
@prisma-next/operations
@prisma-next/ts-render
@prisma-next/contract-authoring
@prisma-next/ids
@prisma-next/psl-parser
@prisma-next/psl-printer
@prisma-next/cli
@prisma-next/emitter
@prisma-next/migration-tools
prisma-next
@prisma-next/vite-plugin-contract-emit
@prisma-next/mongo-codec
@prisma-next/mongo-contract
@prisma-next/mongo-value
@prisma-next/mongo-contract-psl
@prisma-next/mongo-contract-ts
@prisma-next/mongo-emitter
@prisma-next/mongo-schema-ir
@prisma-next/mongo-query-ast
@prisma-next/mongo-orm
@prisma-next/mongo-query-builder
@prisma-next/mongo-lowering
@prisma-next/mongo-wire
@prisma-next/sql-contract
@prisma-next/sql-errors
@prisma-next/sql-operations
@prisma-next/sql-schema-ir
@prisma-next/sql-contract-psl
@prisma-next/sql-contract-ts
@prisma-next/sql-contract-emitter
@prisma-next/sql-lane-query-builder
@prisma-next/sql-relational-core
@prisma-next/sql-builder
@prisma-next/target-postgres
@prisma-next/target-sqlite
@prisma-next/adapter-postgres
@prisma-next/adapter-sqlite
@prisma-next/driver-postgres
@prisma-next/driver-sqlite
commit: |
📝 WalkthroughWalkthroughTwo new ADR documents define the CLI telemetry architecture: ADR 216 specifies the installation ID as a v4 UUID persisted per-user for MAU deduplication, and ADR 217 documents the subprocess design using ChangesCLI Telemetry Architecture
Estimated Code Review Effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture` docs/adrs/ADR 216 - CLI telemetry installation ID is a
stored random UUID not a system fingerprint.md:
- Around line 33-34: Replace the absolute phrasing "unambiguously *not* personal
data" and the DPIA claim with a risk-qualified statement that acknowledges
uncertainty and defers to legal review; for example, reword to say the stored
random UUID "is intended to avoid identifying a person and is less likely to
constitute personal data than device fingerprints (e.g., hashed MAC addresses),
but this should be confirmed by legal counsel" and add a note referencing a
formal legal review/DPIA for final determination.
- Line 5: The ADR currently links to a transient project artifact
(`projects/cli-telemetry/spec.md`) in multiple places; update those references
in "ADR 216 - CLI telemetry installation ID is a stored random UUID not a system
fingerprint" so they point to a durable documentation location (for example a
docs/ path or a package README) instead. Replace every occurrence of
`projects/cli-telemetry/spec.md` (appears ~3 times) with the canonical durable
docs URL or the stable spec document you want to preserve long-term, and ensure
the new links use the same relative linking style and text so cross-references
(in the ADR title and body) remain readable.
In `@docs/architecture` docs/adrs/ADR 217 - CLI telemetry runs in a detached
subprocess spawned at command start.md:
- Line 5: The ADR (file "ADR 217 - CLI telemetry runs in a detached subprocess
spawned at command start") currently links to a transient project spec at
"projects/cli-telemetry/spec.md" in multiple places; update those references
(occurrences of "projects/cli-telemetry/spec.md" mentioned around Lines 5, 29,
74, 108) to point to a stable documentation target (e.g., a durable "docs/..."
ADR or package README) or remove the link if no durable target exists, ensuring
the ADR text and any cross-reference labels (e.g., the phrase "CLI Telemetry
project" and the inline link) remain coherent after the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 8c2c1cbf-c7f7-4b39-9f99-8dbe3e734e81
⛔ Files ignored due to path filters (2)
projects/cli-telemetry/plan.mdis excluded by!projects/**projects/cli-telemetry/spec.mdis excluded by!projects/**
📒 Files selected for processing (3)
docs/architecture docs/ADR-INDEX.mddocs/architecture docs/adrs/ADR 216 - CLI telemetry installation ID is a stored random UUID not a system fingerprint.mddocs/architecture docs/adrs/ADR 217 - CLI telemetry runs in a detached subprocess spawned at command start.md
|
|
||
| ## Status | ||
|
|
||
| Proposed. Recorded during the design of the CLI Telemetry project (see `projects/cli-telemetry/spec.md`). Promote to Accepted once that project's Phase 1 lands. This ADR scopes only the CLI usage telemetry installation identifier; it does not concern the existing runtime telemetry surface in [ADR 024 — Telemetry Schema](./ADR%20024%20-%20Telemetry%20Schema.md), which is an internal query-execution observability SPI with no client-stored identifier. |
There was a problem hiding this comment.
Replace transient projects/ references with durable docs links.
This ADR links to projects/cli-telemetry/spec.md (also on Line 20, Line 68, and Line 98). Durable architecture docs should not depend on transient project artifacts; these links will stale and break over time.
As per coding guidelines: “Documentation must not link to transient project artifacts under projects/ directory; link to durable docs/ or package READMEs instead.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture` docs/adrs/ADR 216 - CLI telemetry installation ID is a
stored random UUID not a system fingerprint.md at line 5, The ADR currently
links to a transient project artifact (`projects/cli-telemetry/spec.md`) in
multiple places; update those references in "ADR 216 - CLI telemetry
installation ID is a stored random UUID not a system fingerprint" so they point
to a durable documentation location (for example a docs/ path or a package
README) instead. Replace every occurrence of `projects/cli-telemetry/spec.md`
(appears ~3 times) with the canonical durable docs URL or the stable spec
document you want to preserve long-term, and ensure the new links use the same
relative linking style and text so cross-references (in the ADR title and body)
remain readable.
| 2. **Regulatory ambiguity.** GDPR jurisprudence has classified hashed MAC addresses as personal data in some EU jurisdictions, because they identify a device that can in practice be associated with a single individual. A stored random UUID is unambiguously *not* personal data — it identifies an installation event, not a person. | ||
|
|
There was a problem hiding this comment.
Avoid absolute legal claims about personal-data status.
“Unambiguously not personal data” (and the related DPIA statement on Line 76) is too definitive for an ADR unless explicitly legal-approved language. Please rephrase to a risk-based statement and point to legal review as the authority.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture` docs/adrs/ADR 216 - CLI telemetry installation ID is a
stored random UUID not a system fingerprint.md around lines 33 - 34, Replace the
absolute phrasing "unambiguously *not* personal data" and the DPIA claim with a
risk-qualified statement that acknowledges uncertainty and defers to legal
review; for example, reword to say the stored random UUID "is intended to avoid
identifying a person and is less likely to constitute personal data than device
fingerprints (e.g., hashed MAC addresses), but this should be confirmed by legal
counsel" and add a note referencing a formal legal review/DPIA for final
determination.
|
|
||
| ## Status | ||
|
|
||
| Proposed. Recorded during the design of the CLI Telemetry project (see `projects/cli-telemetry/spec.md`). Promote to Accepted once that project's Phase 1 lands. This ADR is the engineering-architecture companion to [ADR 216 — CLI telemetry installation ID is a stored random UUID](./ADR%20216%20-%20CLI%20telemetry%20installation%20ID%20is%20a%20stored%20random%20UUID%20not%20a%20system%20fingerprint.md). It does not cover crash/error reporting, which is Phase 2 of the same project and is expected to require a different isolation contract (synchronous-flush-before-exit rather than fire-and-forget). |
There was a problem hiding this comment.
Use stable documentation targets instead of projects/ spec links.
This ADR references projects/cli-telemetry/spec.md multiple times (also Line 29, Line 74, and Line 108). For durable architecture docs, switch these to stable docs/ references (or remove direct links if no durable target exists yet).
As per coding guidelines: “Documentation must not link to transient project artifacts under projects/ directory; link to durable docs/ or package READMEs instead.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture` docs/adrs/ADR 217 - CLI telemetry runs in a detached
subprocess spawned at command start.md at line 5, The ADR (file "ADR 217 - CLI
telemetry runs in a detached subprocess spawned at command start") currently
links to a transient project spec at "projects/cli-telemetry/spec.md" in
multiple places; update those references (occurrences of
"projects/cli-telemetry/spec.md" mentioned around Lines 5, 29, 74, 108) to point
to a stable documentation target (e.g., a durable "docs/..." ADR or package
README) or remove the link if no durable target exists, ensuring the ADR text
and any cross-reference labels (e.g., the phrase "CLI Telemetry project" and the
inline link) remain coherent after the change.
| - [ ] Scaffold the telemetry client subpackage inside `packages/1-framework/3-tooling/` (suggested name: `cli-telemetry`). Set `architecture.config.json` entry for `framework / tooling / shared`. Wire as a dependency of the CLI package. (unblocks: TC-1 through TC-14) | ||
| - [ ] Implement opt-out resolution: read `PRISMA_NEXT_DISABLE_TELEMETRY`, `DO_NOT_TRACK`, and the `telemetry: false`-shaped option from the already-loaded `prisma-next.config.ts`. Any one true ⇒ opted out. Pure function over the trio; unit-testable. (satisfies: TC-2, TC-3, TC-4) | ||
| - [ ] Implement UUID file lifecycle: read existing file at `$XDG_CONFIG_HOME/prisma-next/installation-id` (Unix, defaulting `$XDG_CONFIG_HOME` to `$HOME/.config` per XDG spec) or platform-equivalent under `%APPDATA%` on Windows; generate v4 UUID + write file on first telemetry-enabled invocation only; never delete the file in response to opt-out. Use a single cross-platform helper (e.g. `env-paths`) for the path resolution. (satisfies: TC-1, TC-5) | ||
| - [ ] Implement first-run banner: print proposed wording (see spec FR4) to stderr, gated by "file did not exist before this run". Suppressed on subsequent runs by file presence. (satisfies: TC-7) |
There was a problem hiding this comment.
Should it be just a banner or interactive question (if we are in interactive terminal)?
SevInf
left a comment
There was a problem hiding this comment.
Left one non-blocking question on the spec, otherwise LGTM
Add the spec, plan and ADRs for CLI telemetry and its backend service.
Summary by CodeRabbit