Colby McHenry
a1dfa72cac
A new user can now reach the viewer from the README alone: a "Read your graph in the browser" section with a screenshot re-shot from the real build, a step 5 in Get Started, a CLI Reference row, and the same content as a docs-site guide. - README: new section (what the three columns are, the options, the privacy posture), Contents entry, Get Started step 5, CLI row. Screenshot at assets/codegraph-ui-symbol-view.png, version-tagged ?v=1. - CHANGELOG: an [Unreleased] New Features entry in the user-facing voice. - codegraph help ui: mentions the `web` alias, says what the screen shows, and states that nothing is sent anywhere. - TELEMETRY.md: the viewer has no telemetry of its own and makes no outbound connections; the only thing recorded is the command name in the daily rollup, which every off-switch already suppresses. - site/: guides/viewer.md + sidebar entry, a `ui` section in the CLI reference, and a link from Next Steps.
123 lines
6.5 KiB
Markdown
123 lines
6.5 KiB
Markdown
# Telemetry
|
|
|
|
CodeGraph collects a small set of **anonymous usage statistics** — which commands and
|
|
tools get used, which languages get indexed, which agents drive usage — so we can tell
|
|
which of the 20+ languages and 8 agent integrations deserve the most work. This page is
|
|
the complete list of what is collected. If a field isn't on this page, it isn't collected;
|
|
the ingest endpoint enforces this list as an allowlist and is itself
|
|
[public, auditable code](telemetry-worker/) in this repository.
|
|
|
|
## Turning it off
|
|
|
|
Any of these works, permanently:
|
|
|
|
```bash
|
|
codegraph telemetry off # stores your choice (and deletes any unsent data)
|
|
```
|
|
|
|
```bash
|
|
export CODEGRAPH_TELEMETRY=0 # per-shell / per-CI override
|
|
export DO_NOT_TRACK=1 # the cross-tool standard — always honored
|
|
```
|
|
|
|
`codegraph telemetry status` shows the current state, what decided it, and your machine ID.
|
|
The interactive installer (`codegraph install`) asks up front with a visible default-on
|
|
toggle and never re-asks. If you never saw the installer (e.g. `npx` straight into `init`),
|
|
a one-line notice is printed to stderr before the first time anything is sent.
|
|
|
|
Off means off: when disabled, CodeGraph records nothing, opens no connection to the
|
|
telemetry endpoint, and sends no "opted out" ping.
|
|
|
|
Separately from telemetry, the MCP server checks GitHub for a newer release in the
|
|
background (at most once a day) so it can tell you an update exists — it fetches a
|
|
version number and sends nothing about you or your machine. `DO_NOT_TRACK=1` disables
|
|
this check too; to turn off only the update check, use `CODEGRAPH_NO_UPDATE_CHECK=1`.
|
|
|
|
## What is collected
|
|
|
|
Every payload carries this envelope:
|
|
|
|
| field | example | notes |
|
|
|---|---|---|
|
|
| `machine_id` | `b3a8c1…` | random UUID minted on first send — derived from nothing |
|
|
| `codegraph_version` | `0.9.9` | |
|
|
| `os` / `arch` | `darwin` / `arm64` | platform identifiers only |
|
|
| `node_major` | `22` | major version only |
|
|
| `ci` | `false` | whether the `CI` env var was set |
|
|
| `schema_version` | `2` | bumped when this page changes (v2 dropped the `index` event's `sqlite_backend` field) |
|
|
|
|
And one of four events:
|
|
|
|
- **`install`** — when `codegraph install` configures agents: which agents
|
|
(`["claude","cursor",…]`), global vs project-local, and whether it was a fresh install,
|
|
an upgrade, or a re-run.
|
|
- **`index`** — when a full index completes: the **language names** present (e.g.
|
|
`["typescript","go"]`), the file count as a **coarse bucket** (`<100`, `100-1k`,
|
|
`1k-10k`, `10k+`), and the duration as a bucket (`<10s`, `10-60s`, `1-5m`, `5m+`).
|
|
- **`usage_rollup`** — one line per day per tool: the tool or CLI command **name** (e.g.
|
|
`codegraph_explore`, `init`), how many times it ran, how many errored, and — for MCP
|
|
tools — the connecting agent's name and version from the MCP handshake (e.g.
|
|
`Claude Code 2.1`). The Claude Code prompt hook also counts its **gate decision**
|
|
(fired fully, fired as a hint, or did nothing — fixed counter names like
|
|
`prompt-hook-gate-medium-segment`); the prompt itself is never read, stored, or sent.
|
|
- **`uninstall`** — when `codegraph uninstall`/`uninit` runs: which agents were removed.
|
|
|
|
Usage is **aggregated locally into daily totals** before anything is sent — there is no
|
|
per-call event stream, and nothing is sent in real time.
|
|
|
|
### The browser viewer sends nothing
|
|
|
|
`codegraph ui` (the local viewer) has no telemetry of its own. The server it starts
|
|
makes no outbound connections at all, and the page in your browser talks only to that
|
|
server on `127.0.0.1`: nothing about the symbols you open, the searches you type, or the
|
|
path you walk leaves your machine, and none of it is recorded anywhere. The only thing
|
|
telemetry ever learns about the viewer is what it learns about every command: that a
|
|
command named `ui` was run, once, on a day, in the daily `usage_rollup` above. The
|
|
command never triggers a send of its own, and `codegraph telemetry off`,
|
|
`CODEGRAPH_TELEMETRY=0`, or `DO_NOT_TRACK=1` switches off even that count, as it does
|
|
everything else on this page.
|
|
|
|
## What is never collected
|
|
|
|
- **No source code.** No file paths, file names, directory names, repository names or
|
|
URLs, symbol names, search queries, or anything else derived from the contents of an
|
|
indexed project.
|
|
- **No IP addresses.** The ingest endpoint never reads, logs, or stores the client IP —
|
|
and there is no analytics vendor downstream that could. No geolocation.
|
|
- **No fingerprinting.** The machine ID is a random UUID stored in
|
|
`~/.codegraph/telemetry.json` — delete that file (or run `codegraph telemetry off`,
|
|
then `on`) and the old ID is gone forever, with no way to reconnect it.
|
|
- **No personal data.** No usernames, hostnames, emails, or environment variables.
|
|
|
|
## How it travels
|
|
|
|
Events POST to `telemetry.getcodegraph.com` — a first-party endpoint whose complete
|
|
source lives in [`telemetry-worker/`](telemetry-worker/) in this repository. It validates
|
|
every event and property against the allowlist above (anything else is dropped), never
|
|
reads the client IP, and rate-limits per machine ID. Sends are fire-and-forget with a
|
|
short timeout: offline or air-gapped machines buffer a bounded local file (256 KB cap)
|
|
and never retry-loop, log errors, or slow a command down. Telemetry never adds latency to
|
|
MCP tool calls — recording is an in-memory counter.
|
|
|
|
## Where it is stored
|
|
|
|
Accepted events are written to **our own database on Cloudflare** (D1) and go nowhere
|
|
else. **No third-party analytics vendor receives any of this data**, because the ingest
|
|
endpoint makes no outbound requests at all — its source is the entire path your events
|
|
take, and there is nothing after it. This is a stronger guarantee than a promise not to
|
|
share: there is no second party to share with.
|
|
|
|
What is kept is checkable rather than asserted. The storage schema —
|
|
[`telemetry-worker/migrations/0001_init.sql`](telemetry-worker/migrations/0001_init.sql),
|
|
checked in beside the endpoint that writes it — is the complete list of what a row can
|
|
hold, with a comment on every column.
|
|
|
|
Individual events are **deleted after 90 days**. What outlives them is anonymous daily
|
|
totals: counts per day of things like operating system, version, and language, plus which
|
|
days each machine ID was active so returning-user numbers survive. No event details, and
|
|
still nothing that identifies a person or a codebase.
|
|
|
|
The engineering contract behind all of this — including the rule that schema changes must
|
|
update this page, the client, and the public endpoint in one PR — is in
|
|
[`docs/design/telemetry.md`](docs/design/telemetry.md).
|