# Anonymous usage telemetry

> **CocoIndex v1, Rust SDK (experimental).** This page documents the CocoIndex **v1** Rust SDK (the `cocoindex` crate). The Rust SDK is experimental: any release may change or remove its API, and it is not yet published on crates.io. The Python SDK pages are at https://cocoindex.io/docs/.
>
> Source: https://cocoindex.io/docs/rust/about/telemetry/ · Rust docs index: https://cocoindex.io/docs/rust/llms.txt · Rust SDK tour: https://github.com/cocoindex-io/cocoindex/blob/main/rust/sdk/SHOWCASE.md · Rust examples: https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust

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](https://about.scarf.sh/) 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](#tagging-your-application)).

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

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

```json
{ "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:

```bash
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:

```bash
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](https://github.com/cocoindex-io/cocoindex/issues)
or reach out in our [Discord](https://discord.com/invite/zpA9S2DR7s).