Skip to content

TELEMETRY.md

Latest commit

 

History

History
118 lines (90 loc) · 5.36 KB

TELEMETRY.md

File metadata and controls

118 lines (90 loc) · 5.36 KB
Raw

Telemetry

CodeBoarding collects anonymous, aggregate usage telemetry so we can see how the tool is used (which commands run, success rates, rough token/latency cost) and prioritize what to improve. It is on by default and easy to turn off.

We designed it to be privacy-first: no source code, repository names, prompts, model outputs, API keys, IP addresses, or any personal information are ever collected. (Error diagnostics may include file paths from a traceback — see Error diagnostics for the only exception.)

How to opt out

Set either environment variable before running CodeBoarding:

export CODEBOARDING_TELEMETRY=false   # CodeBoarding-specific switch
# or the cross-tool standard:
export DO_NOT_TRACK=1

When telemetry is disabled, the client is never initialized and every event call becomes a no-op — nothing leaves your machine.

What we collect

Identity — one anonymous id

Each event is tagged with a single distinct_id: an anonymous machine fingerprint. It is built from stable hardware identifiers (system UUID, disk serial, CPU model) that are run through SHA-256, so the id is irreversible and cannot be mapped back to your machine, user, or network. The same id is generated by the VS Code extension and the open-source package, which lets us tell that one anonymous user used both — without ever learning who they are.

There is no account, email, login, or IP-based identity. GeoIP is disabled.

distinct_id is the who. Events also carry a run_id (the which run): a per-run correlation id that lets us join one analysis's events across the VS Code extension, the wrapper, and Core. The extension generates one per analysis and threads it through the wrapper into Core (via the CODEBOARDING_RUN_ID env var); for standalone OSS runs it is Core's internal run id. It is an opaque id, never personal data.

Events

Event When Properties
analysis_started An analysis run begins command, version, run_id, depth_level
analysis_completed An analysis run ends (success or failure) command, version, run_id, depth_level, status, duration_ms, model_name, total_tokens, input_tokens, output_tokens
repo_scanned The repository is scanned (once per repo) version, run_id, total_loc, language_count, languages, stack
$exception Any unhandled exception, via PostHog's built-in error tracking command, version, run_id (plus the exception type, message, and stack trace captured automatically by the SDK)

Every event also carries:

  • source — "oss" for the open-source CLI, "vscode" when invoked by the extension, or "core" for other embeddings.
  • distinct_id — the anonymous id described above.

Property meanings:

  • command — the Core entry point that ran (e.g. generate_analysis, generate_analysis_incremental).
  • version — the installed CodeBoarding version.
  • run_id — the per-run correlation id described under Identity.
  • depth_level — the configured diagram depth (an integer).
  • status — success or error.
  • duration_ms — wall-clock duration of the run.
  • model_name — the LLM model used (e.g. gpt-4o), for cost analysis.
  • *_tokens — token counts consumed by the run, for cost analysis.
  • total_loc — total lines of code in the repository.
  • language_count — number of detected languages.
  • languages — per-language breakdown: [{language, loc, percentage}] (top 15).
  • stack — sorted, comma-joined language names (the tech stack), e.g. Python,Shell,TypeScript.

Error diagnostics

On failure, exceptions are forwarded to PostHog's built-in error tracking ($exception event) via telemetry.capture_exception. The SDK captures the exception type, message, and stack trace automatically; we attach command, version, run_id, and source so the crash can be correlated to the run. The stack trace may contain file paths, line numbers, or source snippets from the failing frame. No source code, repository names, prompts, model outputs, or credentials are ever sent.

What we never collect

  • Source code or file contents
  • Repository names or URLs
  • Prompts sent to or responses from LLMs
  • API keys, tokens, or credentials of any kind
  • Names, emails, usernames, or IP addresses

(File paths or source snippets may appear inside a truncated error stack trace, as noted above — that is the only exception.)

Where it goes

Events are sent to PostHog (US cloud). The project key shipped in the code is a write-only ingest key — it can submit events but cannot read any data back.

Where it lives in the code

All telemetry is contained in the telemetry/ package:

If anything here is unclear or you'd like a change, please open an issue.