Product Telemetry

Open as Markdown

chmonitor includes an opt-in, anonymous telemetry system. It is off by default — no data leaves your instance unless you explicitly enable it.

This is separate from Self-Tracking, which writes dashboard usage events to your own ClickHouse instance. Telemetry is lightweight product analytics (five events, three dimensions, no PII) intended to help the project understand how the dashboard is used at a high level.

Off by default

Telemetry is disabled unless you set one of the following environment variables:

Variable	Where it applies	Value to enable
`CHM_TELEMETRY`	Server runtime (Worker binding / `process.env`)	`on`
`VITE_TELEMETRY_ENABLED`	Client build-time (inlined by Vite)	`true`

CHM_TELEMETRY=on is the canonical form. true, 1, and yes are also accepted. Any other value — including unset — keeps telemetry off.

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 (attached to every event)

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`

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, …) 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.

How to enable

Server-side (Cloudflare Worker, Docker, Kubernetes):

CHM_TELEMETRY=on

Client build-time (inlined at bun run build / vite build):

VITE_TELEMETRY_ENABLED=true

Both variables are independent. You can enable server-side telemetry without a client rebuild or vice versa.

How to disable

Telemetry is off by default — you do not need to do anything to disable it. To confirm it is off, ensure neither CHM_TELEMETRY nor VITE_TELEMETRY_ENABLED is set (or set them to any value other than the accepted ones above).

Current transport status

Two separate systems exist, each with its own no-op guarantee:

Instance ping (maybePingInstance) is wired to the app and runs once per day when due. It is a hard no-op unless both conditions hold simultaneously:

Telemetry is explicitly enabled (CHM_TELEMETRY=on / VITE_TELEMETRY_ENABLED=true).
A collection endpoint is explicitly configured (CHM_TELEMETRY_ENDPOINT / VITE_TELEMETRY_ENDPOINT).

Neither variable is set by default. Because both are required, enabling just the flag makes zero network calls — the code short-circuits before any fetch() is invoked.

Event tracking (track()) has no default transport sink. Events are typed and redacted internally, but with no sink registered they are silently dropped. A self-hosted sink (writing to your own ClickHouse) will be added in a later release. Enabling telemetry today produces no network traffic from event tracking.

Activation metric

The project tracks a single derived metric called “activation”:

activation = cluster_connected AND (health_viewed OR queries_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

Opt-in only — telemetry is off unless you set the env var.
Self-hosted — chmonitor is fully self-hostable; your ClickHouse data never leaves your network regardless of telemetry settings.
No third-party trackers — there are no analytics SDKs, beacon scripts, or third-party pixels in the application.
No PII by design — the event schema and redaction layer are written to make PII collection structurally impossible, not just policy-forbidden.
Inert by default — both the telemetry flag and a collection endpoint must be explicitly set for any network call to occur. Enabling just the flag (without an endpoint) still makes zero network calls.

Self-Tracking — writes dashboard usage events (page visits, query executions) to your own ClickHouse instance. A different system, entirely within your infrastructure.
Environment Variables — full reference for all configuration variables.