Operate
Product Telemetry
Anonymous product telemetry — on by default, opt out anytime, no PII, no third-party trackers.
chmonitor includes an anonymous, privacy-first telemetry system. It is on by default and you can turn it off at any time — with a single environment variable. It collects lightweight, aggregate product analytics (five events, three dimensions, no PII) to help the project understand how the dashboard is used at a high level.
This is separate from Self-Tracking, which writes dashboard usage events to your own ClickHouse instance, and from Product Analytics, an opt-in, off-by-default PostHog integration used for the hosted SaaS product's conversion funnel.
Opt out — on by default
Telemetry runs unless you explicitly turn it off. Any one of these disables it:
| Variable | Where it applies | Value to disable |
|---|---|---|
CHM_TELEMETRY | Server runtime (Worker binding / process.env) | off (also 0, false, no) |
VITE_TELEMETRY_ENABLED | Client build-time (inlined by Vite) | off |
DO_NOT_TRACK | Server runtime — the cross-tool opt-out standard | 1 (any truthy value) |
CHM_TELEMETRY_ENDPOINT | Server runtime — collection endpoint | "" (empty = hard kill-switch, no network call) |
DO_NOT_TRACK is a hard override: when set, telemetry is off regardless of
CHM_TELEMETRY. Leaving everything unset keeps telemetry on.
CHM_TELEMETRY=offApplies to Cloudflare Worker, Docker, and Kubernetes deployments. 0, false,
and no are also accepted.
DO_NOT_TRACK=1The cross-tool opt-out standard. A hard
override — telemetry is off regardless of CHM_TELEMETRY.
VITE_TELEMETRY_ENABLED=offOr, to remove the endpoint entirely:
VITE_TELEMETRY_ENDPOINT=""Inlined at pnpm run build / vite build.
Collection endpoint
Data is sent to the shared telemetry service, project chmonitor, at
https://telemetry.anyr.workers.dev/chmonitor by default. The instance ping and the
product events both go to this one URL. Point it elsewhere by setting
CHM_TELEMETRY_ENDPOINT (server) or VITE_TELEMETRY_ENDPOINT (client build); a
custom endpoint must accept the same JSON event shape (see
Transport and storage). Setting it to an empty string
disables the network call entirely.
The aggregate numbers are public: https://telemetry.anyr.workers.dev/chmonitor.
What is collected
Events
| Event | When it fires |
|---|---|
app_loaded | Dashboard page first loads |
cluster_connected | A ClickHouse connection is established |
health_viewed | Health page is opened |
queries_viewed | Queries page is opened |
ai_query_sent | A natural language query is sent to the AI agent |
Dimensions (sent as props on events)
| Dimension | Values | Example |
|---|---|---|
deploy_target | docker, helm, cf, dev, unknown | docker |
ch_version | MAJOR.MINOR only | 24.8 |
ch_flavor | oss, altinity, cloud, unknown | oss |
Every event also carries the chmonitor version and, on the instance ping, the
browser's os family (windows, macos, linux, android, ios,
unknown). The service derives the country from the request, so the client
does not send one.
The license key (CHM_LICENSE_KEY) is never sent. A license key is an
identifier, so it stays out of public telemetry. See
Commercial license.
What is NOT collected
- Query text, SQL statements, or fingerprints
- Hostnames, IP addresses, or connection strings
- User identifiers, email addresses, or session tokens
- Table names, database names, or schema information
- Any free-text or user-generated content
A defensive redaction layer (redact.ts) runs before every event is emitted. It
drops any prop whose key name implies sensitive content (host, ip, url,
query, sql, email, token, license_key, …) and any string value that matches an email,
IPv4/IPv6 address, or URL pattern. When in doubt, it drops.
The ClickHouse version is always truncated to MAJOR.MINOR (e.g. 24.8) — never
the full four-part string — to avoid matching the IPv4 redaction pattern.
Transport and storage
Instance ping (maybePingInstance) runs once per day when due. It POSTs one
ping event to the collection endpoint:
{
"event": "ping",
"id": "<hashed install id>",
"version": "0.3.1",
"os": "linux",
"props": { "deploy_target": "docker", "ch_version": "24.8", "ch_flavor": "oss" }
}It is a hard no-op when telemetry is disabled, when the endpoint is an empty string, or in non-browser contexts (SSR/prerender).
The shared telemetry service hashes id
again with a server-side secret and never stores it raw. It does not store IP
addresses or user agents.
Retention
The service keeps raw events for 90 days and daily aggregates (active installs, event counts, top dimensions) long term.
Event tracking (track()) is typed and redacted, then delivered by the event
sink to the same endpoint, one event per POST, with the same hashed id as the
ping so events and pings count as one install. The sink installs once per app
load and is a hard no-op when telemetry is disabled or no endpoint resolves.
CLI telemetry (a separate stream)
The standalone chm / chmonitor CLI (Linux /
macOS release binaries; other platforms via cargo install) and its
install.sh installer emit their own anonymous telemetry — tracked as a
separate stream from the dashboard telemetry above, with its
separate id space (the CLI's own persisted id). Same privacy posture: anonymous, opt-out, no PII.
It is best-effort and non-blocking: the CLI fires the ping on a background thread with a sub-second timeout and never delays a command's exit by more than ~300ms, and never fails a command if the network is down.
Opt out (any one disables it)
The CLI honours the same switches as the dashboard:
CHM_TELEMETRY=off # also 0 / false / no
DO_NOT_TRACK=1 # cross-tool standard, hard override
CHM_TELEMETRY_ENDPOINT="" # hard kill-switch — no network callThe install.sh install ping additionally skips automatically when CI=true.
What the CLI collects
| Field | Values | Notes |
|---|---|---|
id | 64-char opaque hex | Random id persisted at $XDG_CONFIG_HOME/chmonitor/cli-id (default ~/.config/chmonitor/cli-id). Counts distinct installs only; maps to no identity. |
event | cli_install, cli_run, cli_diagnose | Install ping vs. a command run vs. a doctor --ch-host scan. |
props.command | hosts, chart, table, tui, update, auth, config, link, chat, agent, doctor, install, … | Subcommand name (chm and chmonitor report the same names). |
version | semver (e.g. 0.1.0) | The chm version. |
os | linux, macos, windows, unknown | Shipped prebuilts are Linux/macOS only; windows appears for source builds. |
arch | x86_64, aarch64, unknown |
It sends nothing else — no ClickHouse host, query text, command arguments, file paths, usernames, IPs, or license key. The install-script ping uses an ephemeral random id (one-shot installs do not persist identity).
The public stats page, https://telemetry.anyr.workers.dev/chmonitor, shows installs over time, event counts, and the version and OS splits for the dashboard and the CLI together.
Activation metric
The project tracks a single derived metric called "activation":
activation =
cluster_connectedAND (health_viewedORqueries_viewed)
A session is considered activated when a cluster is connected and the user viewed
either the Health or Queries page in that session. This definition lives in
activation.ts and is the same across the client, any analytics query over the
telemetry store, and this documentation.
Privacy stance
Privacy by design
- One-switch opt-out —
CHM_TELEMETRY=offorDO_NOT_TRACK=1disables it completely, anytime. - Self-hosted data stays put — chmonitor is fully self-hostable; your ClickHouse data never leaves your network regardless of telemetry settings.
- No third-party trackers in this system — telemetry uses only the project's own shared telemetry service, never a third-party analytics SDK. (chmonitor separately offers an opt-in, off-by-default Product Analytics integration that sends funnel events to PostHog — only if you explicitly configure a key.)
- No PII by design — the event schema and redaction layer are written to make PII collection structurally impossible, not just policy-forbidden.
- Anonymous — only a hashed random install id is sent; it cannot be tied to an identity, and the service never stores request IPs. The license key (
CHM_LICENSE_KEY) is never sent. - Hard kill-switch — setting the endpoint env to an empty string stops all network calls regardless of any other setting.
Related
Self-Tracking
Writes dashboard usage events (page visits, query executions) to your own ClickHouse instance. A different system, entirely within your infrastructure.
Product Analytics
Opt-in, off-by-default PostHog funnel analytics for the hosted SaaS product.
Environment Variables
Full reference for all configuration variables.
Self-Tracking
chmonitor writes its own usage events to a ClickHouse table — configure the target table, required grants, and how to suppress writes.
Agent Conversation Storage
Conversation history persistence has moved — find backend setup, env vars, and store selection on the dedicated AI agent pages.