# Telemetry

Telemetry is **off by default for external users**. It is enabled automatically for known internal Parity contexts and can also be controlled explicitly.

## Opt in / opt out

Telemetry is **off by default** for external users. It is only enabled automatically when running in a known Parity/internal context (see detection signals below), or via explicit opt-in.

- `BULLETIN_DEPLOY_TELEMETRY=1`: explicit opt-in — also overrides `DO_NOT_TRACK`
- `BULLETIN_DEPLOY_TELEMETRY=0` or `BULLETIN_DEPLOY_TELEMETRY=off`: force off
- `DO_NOT_TRACK=1`: telemetry is disabled (standard EFF Do Not Track convention); overridden only by an explicit `BULLETIN_DEPLOY_TELEMETRY=1`

Precedence (highest to lowest): explicit opt-out → explicit opt-in → DO_NOT_TRACK → internal context detection → default off.

Internal detection signals are OR'd together:

1. `GITHUB_REPOSITORY` matches a known internal org
2. `RUNNER_NAME` starts with `parity-`
3. `git remote get-url origin` points at a known internal org

## What is tracked

- deploy duration and success/failure
- storage phase timing
- DotNS phase timing
- pool account selection
- source metadata such as repo, branch, and CI vs local
- tool version

## Ambient Sentry mode

If another app embeds `bulletin-deploy` and already owns Sentry initialization, set these before importing or invoking the library:

```sh
BULLETIN_DEPLOY_USE_AMBIENT_SENTRY=1
BULLETIN_DEPLOY_HOST_APP=<your-app-name>
BULLETIN_DEPLOY_HOST_APP_VERSION=<your-app-version>
```

`BULLETIN_DEPLOY_HOST_APP_VERSION` is optional but recommended — it populates `deploy.host_app_version` on every span, enabling version-correlated triage in your Sentry dashboard.

That makes `bulletin-deploy` reuse the existing Sentry client instead of calling its own `Sentry.init()`.

Requirements:

- the host app must initialize Sentry first
- Sentry SDK compatibility still matters
- quotas and issue grouping remain owned by the host project

## Tagging test traffic

Use `--tag` or `DEPLOY_TAG` to separate test and benchmark traffic from real deploys.

Examples:

```bash
bulletin-deploy --tag ci-smoke ./build my-app.dot
DEPLOY_TAG=load-test bulletin-deploy ./build my-app.dot
```

Use any label that distinguishes a class of deploy — for example, separating CI smoke runs, nightly runs, and load tests from real user traffic so they can be filtered apart in telemetry.