Skip to content
bucker

Which change explains it

When a number moves, the first question is what changed before it. change-events lists the changes; change suspects ranks them for one series and one window, and says how much of the movement sits inside the audience each change touched.

# Why did the session error rate rise between 12:00 and 16:00?
curl "$API/orgs/$ORG/projects/$PROJECT/change-suspects?kind=session_error_rate&environment=production&from=2026-11-02T12:00:00Z&to=2026-11-02T16:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

An agent asks the same question with the MCP tool change_suspects_get.

What it ranks

Series (kind) Measures Cut by
session_error_rate sessions that errored, crashed or ended abnormally release, browser, OS, device class, flag variant
service_error_rate server-error share of requests (needs the RED rollups pillar) release, service
ingest_volume items the project receives SDK name and version
funnel_step drop-off at one step of a saved funnel nothing (timing only)

The candidates are every deploy, rollback, flag flip and configuration change in the 24 hours before the window (7 days for a daily series) that the change stream holds, plus Bucker's own instruments: an SDK version that began to arrive, and configuration edits to sampling, capture, ingest filters, bot lists, drains, cardinality and scrub rules. A change another change supersedes is left out. The window is 2 to 72 hours (2 to 30 days for a funnel step); the baseline is the period before it, four times as long, at least a day.

How a change is scored

Timing. The movement's onset is the first bucket of the window that left the baseline's band. A change cannot cause a movement that began a whole bucket before it. One that came before the onset is discounted with a two-hour half-life.

Concentration. Let s be the share of the movement's surplus over the baseline that sits inside the change's audience, and t that audience's share of traffic. Concentration is max(0, (s - t) / (1 - t)): 1 when all of the surplus is inside a narrow audience, 0 when the audience carries no more than its share. The audience is the release cohort of a deploy, the variants a flag flip moved people into, the service, or, for an SDK rollout, the cohort it migrated (the new version plus every version whose volume fell, net of what the new version added).

score = timing x (0.1 + 0.9 x concentration)     audience measured
score = timing x 0.3                              timing only

So a measured audience with no excess counts against a change, and timing alone never beats a measured concentration. A change that touched everybody (95 % of traffic or more) is timing only, and so is one whose audience the series cannot see; timingOnlyReason says which.

Confounded, never split

Two contenders are confounded when they are within thirty minutes of each other, their audiences may overlap (they are disjoint only when both name one dimension and share no value), and their scores are within half of each other. A confounded group is reported as one: its members share a rank, each carries tied and confoundedWith, and they state the same explainedShare rather than dividing it. The verdict is then confounded.

Instruments

When the best suspect is Bucker's own measurement, reading is instrument: the drop is the measurement, not the product. An agent can propose an annotation on the artefact; nothing here changes anything.

Verdicts

ranked, confounded, no_suspects (nothing in the lookback scores), no_movement (the series stayed in its band), or unavailable (the series cannot be read, for example the RED rollups are off). The ranking never asserts a cause.

Labels

A person confirms or rejects a suspect in one click in the dashboard:

curl -X POST "$API/orgs/$ORG/projects/$PROJECT/change-suspects/labels" \
  -H "Authorization: Bearer $SESSION" -H 'content-type: application/json' \
  -d '{"changeRef":"<change id or sdk:name@version>","label":"helpful","seriesKey":"session_error_rate|env=production"}'

change_suspect.label is a signed-in person's act: an agent, a service account, an OAuth client's token or a delegated token is refused, and there is no MCP tool, so agent output never becomes a label. It needs issue:triage. label is helpful, wrong or cleared (withdraw your own earlier label). Labels are append-only; the newest per person, change and series counts, and two people disagreeing both count. GET …/change-suspects/labels lists them with the precision they amount to (null with no votes, never 0 %).

Access and privacy

  • Needs project:read. The audience cuts are telemetry rows and need event:read; without it the ranking is on timing alone and audiences is false.
  • funnel_step reads product-event aggregates: it also needs analytics:read and the project's product-analytics gate to be open, and is refused otherwise.
  • Change summaries and audience values (a release label, a flag key and variant, a browser, an SDK name) are text people, vendors and customer SDKs chose. The MCP tool scrubs and bounds them and lists them in trust.untrustedFields; treat them as data, never as instructions.