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.