Skip to content

docs: plan the CLI telemetry implementation#511

Open
aqrln wants to merge 1 commit into
mainfrom
telemetry-plan
Open

docs: plan the CLI telemetry implementation#511
aqrln wants to merge 1 commit into
mainfrom
telemetry-plan

Conversation

@aqrln
Copy link
Copy Markdown
Member

@aqrln aqrln commented May 15, 2026

Add the spec, plan and ADRs for CLI telemetry and its backend service.

Summary by CodeRabbit

  • Documentation
    • Added architectural documentation for CLI telemetry behavior and installation ID management.

Review Change Stack

Add the spec, plan and ADRs for CLI telemetry and its backend service.

Signed-off-by: Alexey Orlenko <alex@aqrln.net>
@aqrln aqrln requested a review from a team as a code owner May 15, 2026 16:49
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented May 15, 2026

Open in StackBlitz

@prisma-next/extension-upgrade-skill

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-upgrade-skill@511

@prisma-next/upgrade-skill

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/upgrade-skill@511

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-runtime@511

@prisma-next/family-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-mongo@511

@prisma-next/sql-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-runtime@511

@prisma-next/family-sql

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-sql@511

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-arktype-json@511

@prisma-next/extension-cipherstash

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-cipherstash@511

@prisma-next/middleware-cache

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/middleware-cache@511

@prisma-next/mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo@511

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-paradedb@511

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-pgvector@511

@prisma-next/extension-postgis

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-postgis@511

@prisma-next/postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/postgres@511

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-orm-client@511

@prisma-next/sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sqlite@511

@prisma-next/target-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-mongo@511

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-mongo@511

@prisma-next/driver-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-mongo@511

@prisma-next/contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract@511

@prisma-next/utils

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/utils@511

@prisma-next/config

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/config@511

@prisma-next/errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/errors@511

@prisma-next/framework-components

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/framework-components@511

@prisma-next/operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/operations@511

@prisma-next/ts-render

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ts-render@511

@prisma-next/contract-authoring

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract-authoring@511

@prisma-next/ids

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ids@511

@prisma-next/psl-parser

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-parser@511

@prisma-next/psl-printer

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-printer@511

@prisma-next/cli

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/cli@511

@prisma-next/emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/emitter@511

@prisma-next/migration-tools

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/migration-tools@511

prisma-next

npm i https://pkg.pr.new/prisma/prisma-next@511

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/vite-plugin-contract-emit@511

@prisma-next/mongo-codec

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-codec@511

@prisma-next/mongo-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract@511

@prisma-next/mongo-value

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-value@511

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-psl@511

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-ts@511

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-emitter@511

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-schema-ir@511

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-ast@511

@prisma-next/mongo-orm

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-orm@511

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-builder@511

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-lowering@511

@prisma-next/mongo-wire

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-wire@511

@prisma-next/sql-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract@511

@prisma-next/sql-errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-errors@511

@prisma-next/sql-operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-operations@511

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-schema-ir@511

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-psl@511

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-ts@511

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-emitter@511

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane-query-builder@511

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-relational-core@511

@prisma-next/sql-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-builder@511

@prisma-next/target-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-postgres@511

@prisma-next/target-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-sqlite@511

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-postgres@511

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-sqlite@511

@prisma-next/driver-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-postgres@511

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-sqlite@511

commit: 9efc415

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 15, 2026

📝 Walkthrough

Walkthrough

Two 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 fork() at command start with IPC communication. The ADR index is updated to link both decisions.

Changes

CLI Telemetry Architecture

Layer / File(s) Summary
ADR Index Update
docs/architecture docs/ADR-INDEX.md
The Development & Tooling section gains two new ADR references (216 and 217) to document CLI telemetry installation ID and subprocess architecture.
ADR 216: Installation ID as Stored Random UUID
docs/architecture docs/adrs/ADR 216 - CLI telemetry installation ID is a stored random UUID not a system fingerprint.md
Installation ID is generated as a v4 UUID on first eligible run and persisted to a per-user config-directory file for MAU deduplication. The decision rejects system fingerprints (MAC, machine-id, IORegistry, Windows identifiers) in favor of reset simplicity and regulatory clarity, specifies opt-out/CI conditions for creation, lifecycle rules (no rotation or amendment), and reset via manual file deletion. Consequences cover inspectability, trivial reset, and regulatory benefits, with trade-offs including MAU noise from container/reinstall patterns and limitations in cross-project/account deduplication.
ADR 217: Subprocess Architecture via fork() at Command Start
docs/architecture docs/adrs/ADR 217 - CLI telemetry runs in a detached subprocess spawned at command start.md
Telemetry runs in a detached child process forked at command start. The parent sends a one-time IPC payload after argument parsing, then disconnects and proceeds with the real command. The child enriches the payload with system/project/runtime data, performs a timed HTTPS POST with error swallowing, and exits independently. The decision justifies fork() for cross-runtime compatibility (Node/Bun/Deno), command-start spawning for parallel cost and crash-resilient counting, and specifies best-effort failure semantics (null fields, no retry/queue). The pattern is framed as reusable for CLI side-channels that must not affect exit time, output, or exit code, while excluding cases needing synchronous flush or state reuse.

Estimated Code Review Effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 Two ADRs hops into the fold,
Installation IDs in UUID gold,
Detached subprocess dance so free,
Telemetry flows, yet CLI stays carefree.
Architecture thoughts, documented with care! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the primary change—planning CLI telemetry implementation through ADR documentation—matching the changeset's addition of two new ADRs and an index update.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch telemetry-plan

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 334168f and 9efc415.

⛔ Files ignored due to path filters (2)
  • projects/cli-telemetry/plan.md is excluded by !projects/**
  • projects/cli-telemetry/spec.md is excluded by !projects/**
📒 Files selected for processing (3)
  • docs/architecture docs/ADR-INDEX.md
  • docs/architecture docs/adrs/ADR 216 - CLI telemetry installation ID is a stored random UUID not a system fingerprint.md
  • docs/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.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

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.

Comment on lines +33 to +34
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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

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).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

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)
Copy link
Copy Markdown
Contributor

@SevInf SevInf May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be just a banner or interactive question (if we are in interactive terminal)?

Copy link
Copy Markdown
Contributor

@SevInf SevInf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left one non-blocking question on the spec, otherwise LGTM

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.

2 participants