# The telemetry contract

Keep one registry in your repository that declares every signal your application emits, and let Bucker
hold what strays from it, name what a change would break, and check that the first release which carries
it emits what it declares.

The registry is an [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver) registry: a directory
of YAML (default `telemetry/registry`) with a `registry_manifest.yaml` and any number of group files. Bucker
reads Weaver's own grammar and adds what Weaver has no place for under `annotations.bucker`.

## The registry

```yaml
# telemetry/registry/registry_manifest.yaml
name: web-telemetry
semconv_version: 1.4.0        # the registry version Bucker stamps on envelopes
```

```yaml
# telemetry/registry/signals.yaml
groups:
  - id: product_event.checkout.completed
    type: event
    name: checkout.completed
    annotations:
      bucker:
        kind: product_event     # a Weaver `event` is a log event unless it says so
        owner: team-payments    # required
        pii: none               # none | pseudonymous | personal | sensitive; required
        volume: { min: 100, max: 100000 }   # expected per day, optional
    attributes:
      - { id: amount, type: double, requirement_level: required }
      - { id: currency, type: string }
```

Four kinds of signal are declared: product events (`kind: product_event`), spans (`type: span`), log events
(`type: event`) and metrics (`type: metric`, named by `metric_name`). Attribute types are `string`, `int`,
`double`, `boolean` and the arrays of each. An attribute may carry its own `annotations.bucker.pii`; one
that says nothing inherits the signal's, and a registry that states no PII class anywhere fails `check`:
"not stated" is not "none".

To rename an attribute the Weaver way, keep the old one and mark it
`deprecated: { reason: renamed, renamed_to: new_name }`. Bucker reads that as a rename, not a removal.

## The command line

| Command | What it does |
| --- | --- |
| `bucker contract init` | Writes a starter registry that passes `check`. Never overwrites one. |
| `bucker contract check` | Runs `weaver registry check` when Weaver is installed, and always Bucker's own checks: an owner and a PII class on everything, valid types and names, nothing a generated identifier would collide on. Under `--json` Weaver is not run (its output would join the JSON document). |
| `bucker contract diff [--base origin/main] [--strict]` | The registry against a base ref, and what each rename, retype or removal breaks. |
| `bucker contract emit [--lang ts\|py\|all] [--out dir] [--check]` | Typed emitters for TypeScript and Python. `--check` fails when they are stale. |
| `bucker contract publish [--repository owner/name]` | Records the registry as an accepted version (run it in CI after the merge). |

`diff` sends signal names, attribute names and the kind of change to Bucker, never a file, an event or a
value. With `--strict` it exits 1 when a breaking change has a reader, and also when the readers could not
be looked up: "could not check" is not "nothing reads it".

```text
$ bucker contract diff --base origin/main
Registry telemetry/registry against origin/main: 3 change(s), 1 breaking.
!  field removed product_event checkout.completed.amount  breaks funnel_step "Checkout v2" step 3,
                                                          alert_rule "Revenue drop" condition 1,
                                                          export "finance-daily"
   1 consumer(s) found, 1 not checked (free text) for checkout.completed.amount
```

## What a change breaks

Bucker indexes the readers of every field from the specs it already keeps: alert rules (project and
organization-wide), dashboard widgets, saved views and queries, insights and funnel steps, cohorts, SLOs,
flag guardrails, exports and the lineage edges that name a field. A reader that names a field in a typed spec
is listed with where it reads it ("step 3", "condition 1"). A reader written as free text (a search string)
is counted as "not checked", never listed: a green answer is never "nothing reads this".

Insights, funnel steps and cohorts are end-user analytics objects. While a project's analytics gate is closed
(PA-01) they are not read, and the answer names them under `notChecked`.

## Typed emitters

`bucker contract emit` writes `telemetry/generated/bucker-contract.ts` and `bucker_contract.py`: one
attributes type per signal (required attributes without `?`) and one `emit<Name>` function over a sink you
provide in one line. They also export `BUCKER_REGISTRY_VERSION`, the value an SDK stamps on every envelope
(`consent.registryVersion`). Run `bucker contract emit --check` in CI.

## What Bucker does with a recorded version

`bucker contract publish` records the registry as an accepted version and signs a `telemetry_contract`
claim into your organization's receipt log. A version is immutable: the same version with different content
is refused, so bump `semconv_version`. Recording changes no capture setting.

**At ingest (not switched on yet).** Holding is built but not yet enabled. It switches on only once a held
contract event can be released back, so a hold can never quietly end in expiry. Once enabled, an envelope
stamped with a version Bucker has recorded has its product events read against
it. An event the registry does not declare, a property it does not declare, or a property of the wrong type
is **held**, not dropped: it goes to the 14-day quarantine (excluded from every insight), is
answered as `ingestion_filter_quarantined`, and is counted under the hold's reason `contract:<version>`.
Nothing is ever rejected by the contract; moving a field to reject is the ask-first step of ingestion
filters. `$`-prefixed events and properties are the SDKs' and are exempt. A version Bucker has not recorded,
an unstamped envelope and a project whose analytics gate is closed are read against nothing.

**On the first release.** `instrumentation_verification_get` (and `GET .../telemetry-contract/verification`)
checks, per declared signal, that the first release created after the version was accepted emits it. A
release names itself in the answer; name another with `release`.

| Status | Meaning |
| --- | --- |
| `verified` | Seen, attributes as declared, volume inside the band. |
| `partial` | Seen, but a required attribute is missing, a value has the wrong type, an email address sits in a value declared without PII, or the per-day volume is outside the band. |
| `not_observed` | Not seen, and the release has enough traffic of that kind to have shown it. |
| `not_enough_traffic` | Not seen, in a release too quiet (under 20 rows of that kind) to say it is absent. Never a pass. |

The overall answer is the worst of them. Product events are not kept per release, so they are checked by
whether the event has been seen since the release started, and their volume and properties read
`not_checked`. A value is never returned: a PII finding names the attribute and not what it held.

## Proposing a change

An agent proposes a registry change with `tracking_plan_change_propose`: typed changes (`add_attribute`,
`retype_attribute`, `remove_attribute`, `rename_attribute`, `add_signal`), never file text. Bucker edits the
YAML itself, inside the registry directory only, writes what the change breaks into the pull request and
asks a person to approve the exact plan. Only then does it push a `bucker/telemetry-contract-...` branch and
open **one draft pull request**. It never merges and never writes your default branch; an approval given for
one plan on one base commit is not spent on another.

After merging, run `bucker contract emit` (CI: `--check`) so the generated emitters match, then
`bucker contract publish`.
