> ## Documentation Index
> Fetch the complete documentation index at: https://delivery.vexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry ladder

> What your side chooses to send back, at which rung, on whose authority.

**You pick the rung; nothing above it leaves, and nothing above it is kept.** Every rung is the same mechanism — a bundle of plain, inspectable files pushed to your station's write path on the channel host you already pull from. No streams, no second endpoint, no new firewall rule; the tool prints the payload path and stops before sending, so your security team can open it first.

| Tier                 | What your side sends back                                                                                                                                         | Cadence           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **T0 — silent**      | nothing. Entries can even arrive by sneakernet.                                                                                                                   | —                 |
| **T1 — receipts**    | signed install and validation verdicts: which pin, which entry, sync and health words, the PreSync verifier's verdict, the image digests actually running         | per release       |
| **T2 — health**      | aggregate counters: pod phase counts, restart counts, deployment ready ratios, CronJob last-success ages, node readiness. **No identities, no content, no logs.** | daily (or weekly) |
| **T3 — usage**       | activation and volume aggregates, pseudonymous: activated-user counts, meeting and minute volumes, tokens per model                                               | daily or weekly   |
| **T4 — diagnostics** | scrubbed log and trace bundles. **Never automatic** — exported by your admin, read by you, handed over per incident                                               | on demand         |

<Warning>
  **Content is on no rung.** Transcripts and meeting bodies never leave, structurally: [`report.v1`](https://github.com/Vexa-ai/vexa-delivery/blob/main/spec/report.v1.schema.json) sets `additionalProperties: false` on every object but one, so there is no field a transcript could go in. The exception is `usage.tokens_by_model`, an open-keyed map — and its keys are constrained to model-name shape while its **values must be integers**, so it cannot hold a string either. A payload carrying content fails validation on your side, before it is sent.
</Warning>

Your `contract.yaml` declares the rung, and three independent things hold it:

1. **The packager cannot collect above it** — [`collectors.collect()`](https://github.com/Vexa-ai/vexa-delivery/blob/main/kit/validate/collectors.py) resolves your tier to a list of collector functions *before calling any of them*; at T2 the usage collector is never referenced.
2. **The schema refuses a payload above its own declared tier**, so even a bug in (1) cannot produce one.
3. **Our ingest refuses a bundle exceeding your declared scope** — a T3-shaped bundle against a T2 contract is refused (`S10`) and nothing is kept. That is the half you cannot check yourself, which is why it is there.

## Declaring your rung

```yaml theme={null}
report_scope:
  schema: report.v1
  tier: 2                          # 0-4. Your declaration; nothing else may set it.
  cadence: daily                   # per-release · daily · weekly · on-demand
  trigger: explicit-command-only   # or `scheduled`
  destination: channel.vexa.ai
  allowed_sections: [contract_document, profile, values, ...]
  require_redaction_verified: true
```

`tier` is deliberately not settable from a values file. A `report_scope` with no `tier` is tier 1; **no `report_scope` at all is a refusal at both ends.** `explicit-command-only` means nothing in the delivered software originates a report — it happens when an operator types `--submit`. Setting `scheduled` is what authorises the in-cluster CronJob: **the station chart renders no CronJob unless `receiptSender.trigger` is `scheduled`**, and that value is set to mirror your contract. The chart reads its values, not the contract document — so the two must be set together, and the contract is the authority the value is copied from.

## Sending, per rung

T1 fires from a PostSync hook Job when a sync completes. T2/T3 go by that CronJob, or by hand — the sender's RBAC is `get`/`list` on pods, deployments, cronjobs and jobs plus `get` on one named ConfigMap, and `get` on the one named Argo Application it follows, in the argocd namespace. That last one is what gives the receipt its pin and sync status; it defaults on (`receiptSender.readArgoApplication`) and a station that will not grant cross-namespace read sets it `false` and submits with those fields absent rather than invented. No secrets, no exec, no logs, no write.

```bash theme={null}
python3 kit/validate/vexa_validate.py --report --namespace vexa-prod \
  --contract ./contract.yaml --station <your-station> \
  --submit --submit-dry-run          # prints the payload path; sends nothing
```

**T4 does not send.** It writes a scrubbed bundle to your disk and stops — no `--submit` path, and no `tier: 4` value in `report.v1`. Secret and ConfigMap values, container env values and credential-shaped annotations are removed; object names, images, conditions and event messages are kept.

```bash theme={null}
python3 kit/validate/vexa_validate.py --export-diagnostics --namespace vexa-prod --out ./diag
```

A counter that could not be collected is reported **absent, with a reason** — never defaulted to zero. **T3 ships today as an interface with no implementation and says so:** every counter null, one `absent` row explaining why.

The more your side chooses to send back, the faster your deployment improves: support entitlement at T1, degradation visible before you file a ticket at T2, fleet benchmarks and tuned defaults at T3.

Next: [The station gate](station-gate) · [Security model](security)