# Telemetry

URL: https://cogitator.app/docs/getting-started/telemetry

> The one anonymous event create-cogitator-app and cogitator init send, what it holds, and how to turn it off.

## What is sent

When `create-cogitator-app` or `cogitator init` scaffolds a project, it sends **one** event to the Umami instance of the Cogitator project (`analytics.el1fe.com`). It tells us which presets, providers and add-ons people start with, and how often and why scaffolding fails, so we know what to improve first.

The event holds exactly these fields and nothing else:

| Field            | Example                        | What it is                                                                                                                   |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `version`        | `0.5.0`                        | Version of the scaffolder                                                                                                    |
| `preset`         | `rag`                          | The preset, `custom` for a stack picked by hand, `example` or `template` for a copied project                                |
| `provider`       | `openai`                       | The LLM provider                                                                                                             |
| `memory`         | `postgres`                     | The memory adapter                                                                                                           |
| `features`       | `rag,evals`                    | The add-ons, comma-separated                                                                                                 |
| `packageManager` | `pnpm`                         | The package manager                                                                                                          |
| `node`           | `24`                           | The major version of Node                                                                                                    |
| `os`             | `darwin`                       | The operating system                                                                                                         |
| `outcome`        | `success`                      | `success`, or `failure` when creating the project or installing its dependencies failed                                      |
| `failedStep`     | `install`                      | Where a failure stopped: `create` (the options, the directory, downloading or writing files) or `install`, `none` on success |
| `errorCode`      | `ERR_PNPM_NO_MATCHING_VERSION` | Why it stopped, as a code (see below), `none` on success                                                                     |

It never contains the project name, a path, the model, an API key, the name of an example or a template repository, an error message, the output of the install, or anything else you typed. The request goes to Umami's `/api/send` endpoint, which does not store IP addresses.

Sending is fire-and-forget with a 1.5 second timeout: a slow or offline network changes nothing about the project or the output. A payload that is not exactly these fields, each a short value of letters, digits and `._,-`, is not sent at all.

## The error code

`errorCode` is only ever a code, never a message or a line of output, which can hold paths and package names:

* the code the package manager failed with: pnpm's `ERR_PNPM_*` (`ERR_PNPM_NO_MATCHING_VERSION`), npm's `E*` (`ETARGET`, `E404`), Yarn's `YN*` (`YN0035`). Bun and Yarn 1 print no codes, so their messages map to `NO_MATCHING_VERSION`, `HTTP_404`, `ELIFECYCLE` (a failed install script) or, for Bun's network errors, the Node code. Install scripts print into the same output, so only known codes are taken from it: any other pnpm or npm code is sent as `ERR_PNPM_OTHER` or `NPM_OTHER`
* a Node network or file system code: `ENOTFOUND`, `ECONNREFUSED`, `EACCES`, `ENOSPC`
* the scaffolder's own: `DIRECTORY_NOT_EMPTY`, `INCOMPATIBLE_SPEC`, `INVALID_ARGS`, `PM_NOT_FOUND`, `HTTP_<status>` for a download, `UNKNOWN_EXAMPLE` and `TEMPLATE_*` for a template that cannot be used
* otherwise the kind of error (`TYPE_ERROR`), the exit code of the install (`EXIT_1`) or `UNKNOWN`

## Turning it off

Any one of these turns it off:

```bash
npx create-cogitator-app my-app --no-telemetry
cogitator init my-bot --no-telemetry
export COGITATOR_TELEMETRY_DISABLED=1
export DO_NOT_TRACK=1
```

It is also off when `CI` is set, on `--dry-run`, and in builds of the scaffolder made without a website id (`COGITATOR_UMAMI_WEBSITE_ID` at build time), which send nothing at all.

The first time it is on, the scaffolder prints one line saying so and how to turn it off. It remembers that in `~/.config/cogitator/telemetry-notice` (`%APPDATA%\cogitator` on Windows, `$XDG_CONFIG_HOME/cogitator` when set).

## The code

The implementation is [`packages/create-cogitator-app/src/kit/telemetry.ts`](https://github.com/cogitator-ai/Cogitator-AI/blob/main/packages/create-cogitator-app/src/kit/telemetry.ts), and `installErrorCode` in [`package-manager.ts`](https://github.com/cogitator-ai/Cogitator-AI/blob/main/packages/create-cogitator-app/src/kit/package-manager.ts) next to it reads the code of a failed install. Their tests check that every way of turning it off makes no request, that the payload holds exactly the fields above, and that the error code is read correctly from real failed installs of npm, pnpm, Yarn 1, Yarn 4 and Bun.