Anonymous usage telemetry

What CocoIndex's anonymous usage tracking collects, what it doesn't, and how to opt out.

CocoIndex sends a small number of anonymous events to help us understand how the library is used across platforms and runtimes. Tracking is strictly anonymous, release-only, and opt-out.

What we collect

On release builds, CocoIndex POSTs a JSON event to our telemetry endpoint (the Scarf gateway) at four points in the library’s lifecycle:

• init — once per process, when CocoIndex is imported.
• app_create — when a cocoindex.App is constructed.
• app_update — each time app.update() is called.
• app_drop — each time app.drop() is called.

Each event body contains three fields, plus a fourth only if you set an application tag:

• event — the event name above.
• platform — CPU architecture and operating system, for example aarch64-macos.
• lang — the language and its version, for example python3.11.
• application — an application tag, sent only if you set one with the COCOINDEX_APPLICATION_FOR_TRACKING environment variable (see Tagging your application).

{ "event": "app_update", "platform": "aarch64-macos", "lang": "python3.11" }

With COCOINDEX_APPLICATION_FOR_TRACKING=my-app set, the same event is:

{ "event": "app_update", "platform": "aarch64-macos", "lang": "python3.11", "application": "my-app" }

The package identity and version travel in the request URL, for example https://cocoindex.gateway.scarf.sh/python-1.0.0a1.

What we don’t collect

CocoIndex telemetry never sends:

• Your data, flow definitions, or function code.
• Source/target connector configuration, credentials, URLs, or database names.
• cocoindex.App names, component names, file paths, or other identifiers from your code. The only identifier ever sent is the application tag, and only if you set it yourself.
• Stats about row counts, processing times, or memory usage.
• A persistent machine or user identifier. Requests carry no identifier unless you set an application tag; the gateway only sees whatever an HTTP request normally carries (IP address, which Scarf uses for coarse geolocation and then discards).

When telemetry is active

Telemetry runs only in release builds of the native extension (the wheels published to PyPI). Local development installs via maturin develop produce a debug build and never send any events — the check is compile-time, so the code path doesn’t exist in debug binaries.

CocoIndex dispatches each event on a background task with a 5-second timeout, so delivery is non-blocking. It logs failures at INFO level without affecting your app.

Opting out

Set the COCOINDEX_DISABLE_USAGE_TRACKING environment variable to any non-empty value other than 0 before starting your program:

export COCOINDEX_DISABLE_USAGE_TRACKING=1

When this variable is set, CocoIndex skips all telemetry initialization — no events are ever constructed or dispatched.

Tagging your application

If you build a tool or service on CocoIndex, you can label its events so they can be told apart in aggregate usage counts. Set the COCOINDEX_APPLICATION_FOR_TRACKING environment variable before CocoIndex is imported:

export COCOINDEX_APPLICATION_FOR_TRACKING=my-app

CocoIndex reads the variable once, when telemetry starts at import, and adds its value as the application field of every event that process sends. The value is sent exactly as you set it, so don’t put anything in it you wouldn’t want shared. Leaving the variable unset or empty sends no tag. The tag doesn’t override opt-out: with COCOINDEX_DISABLE_USAGE_TRACKING set, nothing is sent.

Why we collect this

Knowing which platforms and Python versions are in active use helps us prioritize wheel builds, platform support, and compatibility testing. If you have feedback about what we track, please open an issue or reach out in our Discord.