Skip to content
bucker

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 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

# telemetry/registry/registry_manifest.yaml
name: web-telemetry
semconv_version: 1.4.0        # the registry version Bucker stamps on envelopes
# 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".

$ 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.