mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
fb7b94b60e
* feat(telemetry): add node exception reporter * feat(telemetry): report node cli exceptions * feat(telemetry): add daemon exception reporter * feat(telemetry): report daemon exceptions * docs(telemetry): document error reports * fix(telemetry): pass redaction snapshots from node call sites * test(telemetry): verify prepared node exception payload * fix(telemetry): close daemon exception lifecycle gaps * test(telemetry): verify prepared daemon exception payload * test(telemetry): close error collection acceptance gaps * test(telemetry): close posthog exception acceptance gaps
80 lines
3.3 KiB
Text
80 lines
3.3 KiB
Text
---
|
|
title: Telemetry
|
|
description: Understand what usage telemetry ktx collects and how to opt out.
|
|
---
|
|
|
|
**ktx** collects aggregated usage telemetry so maintainers can see
|
|
which commands work, where setup fails, and which parts of the data-agent
|
|
workflow need improvement. Telemetry is opt-out: it turns on the first time you
|
|
run **ktx** in any way — an interactive command, a script, or an
|
|
agent-launched MCP server — and prints a one-time notice (to the terminal when
|
|
there is one, otherwise to standard error). It stays disabled in CI and whenever
|
|
an opt-out is set.
|
|
|
|
## Opt out
|
|
|
|
Use any of these mechanisms to disable telemetry:
|
|
|
|
| Mechanism | Effect |
|
|
|-----------|--------|
|
|
| `export KTX_TELEMETRY_DISABLED=1` | Disables telemetry for the shell and child processes |
|
|
| `export DO_NOT_TRACK=1` | Standard do-not-track environment variable |
|
|
| `CI=1` | Automatic in CI |
|
|
| Edit `~/.ktx/telemetry.json` and set `"enabled": false` | Persistent for the machine, including the MCP server |
|
|
|
|
## What we collect
|
|
|
|
High-level signals: which commands run, how long they take, whether they
|
|
succeed or fail, and basic environment metadata (CLI version, Node version, OS
|
|
platform). When an operation fails, we also include diagnostic detail about the
|
|
error so we can debug it. For project-level analysis, **ktx** sends a salted
|
|
hash of the project directory to group events.
|
|
|
|
When an agent reaches **ktx** through MCP, we also record the connecting client
|
|
tool's self-reported name and version (for example Claude Desktop, Cursor, or
|
|
Cline) so we can see which agents people use **ktx** with. That describes the
|
|
tool, never you or your data.
|
|
|
|
## What we never collect
|
|
|
|
We build telemetry around counts and coarse signals, not the contents of your
|
|
data or configuration. We don't deliberately collect your `ktx.yaml`, query
|
|
results, passwords, API keys, or access tokens.
|
|
|
|
The one place environment-specific text can appear is failure diagnostics: when
|
|
an operation errors, the detail we record is the error as your tools reported
|
|
it, which can include identifiers from your setup. If you'd rather send nothing
|
|
at all, turn telemetry off using any of the options above.
|
|
|
|
## Error reports
|
|
|
|
When telemetry is enabled, **ktx** sends PostHog Error Tracking `$exception`
|
|
events for CLI and daemon exceptions. Error reports help group crashes and
|
|
handled failures into PostHog issues.
|
|
|
|
Error reports can include:
|
|
|
|
- Stack frames, including function names, local file paths, line numbers, and
|
|
SDK-provided source context.
|
|
- Error class names and raw error messages.
|
|
- Cause chains when the runtime exposes them.
|
|
- `source`, `handled`, and `fatal` diagnostic fields.
|
|
- Runtime version, OS, architecture, and CI fields.
|
|
- The hashed `projectId` when **ktx** knows the project.
|
|
|
|
Error reports never intentionally include:
|
|
|
|
- Secrets, credentials, API keys, tokens, cookies, signed URLs, or auth headers.
|
|
- Database URLs, connection strings, DSNs, raw argv, or raw environment values.
|
|
- SQL text, schema names, table names, or column names as explicit payload
|
|
properties.
|
|
- Customer row data.
|
|
- User prompt text or raw MCP arguments.
|
|
|
|
The same opt-out controls listed above disable error reports.
|
|
|
|
## Storage and retention
|
|
|
|
Telemetry is sent to PostHog, a third-party product-analytics service used by
|
|
the **ktx** maintainers. Raw event data is retained for 90 days. Aggregated
|
|
counts may be retained indefinitely.
|