Developer guide / telemetry

Telemetry and privacy

Control analytics sampling and attribution. Keep application diagnostics separate from analytics.

Draft · The release review is in progress.

Canonical events

The event names retain the oss.runtime prefix. They describe instance creation, run or connect requests, and stream start, end, or error.

Other HTTP routes do not emit copilot_request_created. Error streams must not also emit a successful stream-ended event.

The default anonymous sample rate is 0.05. COPILOTKIT_TELEMETRY_SAMPLE_RATE overrides the configured rate.

Events include the effective sample rate and weight. Timestamps use integer Unix seconds.

A standalone ID travels in X-CopilotKit-Telemetry-Id. It does not bypass sampling.

A valid telemetry_id claim in a legacy license token bypasses sampling. The telemetry_identified field reports this choice.

A configured standalone identity takes precedence over the token. A standalone identity does not bypass sampling.

COPILOTKIT_LICENSE_TOKEN supplies a fallback when the configured token is blank. Invalid claims do not bypass sampling.

The runtime reads the claim without checking the license signature. This analytics behavior does not grant access.

The exporter sends only the extracted identity, never the license token. Analytics opt-out takes precedence over the token.

Explicit opt-out overrides enabled configuration. The environment variables that follow also disable analytics with the value true or 1.

COPILOTKIT_TELEMETRY_DISABLED=true
DO_NOT_TRACK=1

The default sink is https://telemetry.copilotkit.ai/ingest. COPILOTKIT_TELEMETRY_URL selects another sink.

Native exporters use bounded queues and three-second request limits. Export errors must not fail a run.

Shutdown has a bounded flush period. Local exporter statistics expose dropped or failed sends.

Analytics must not contain prompts, responses, memories, tool arguments, UI HTML, API keys, or arbitrary upstream errors.

Agent failures use AGENT_EXECUTION_FAILED. The application-owned onError callback receives the original diagnostic separately.

The host must protect its diagnostic logs. Analytics privacy rules do not sanitize application logs.