Skip to content
bucker

Detectors

A detector is a rule over rollups with a published threshold. It opens an ordinary issue, in the same stream as crashes, or it does not. No model decides whether it fires, resolves or pages.

Every detector has a version, a state and a measured precision:

State What it does
live Opens its output (an issue, or an alert for the seasonal anomaly).
shadow Runs and records every finding, and opens nothing.
retired Records nothing and opens nothing.

A new version starts in shadow. It becomes live when at least 50 labelled findings have a precision of at least 0.7; below either bound it stays in shadow. That promotion is not an action anyone takes: it is computed from the labels by Bucker's labels pass, and there is no route, tool or setting that sets it.

The detectors that existed before this registry (seasonal anomaly, latency regression, the performance patterns and the seven agent-issue kinds) are live with precision not measured. They keep opening issues; the gate applies to their next version.

What a detector reads

Rollups, never raw tables. The registry refuses a detector whose input is a raw telemetry table, with one exception that only shrinks: the already-built detectors that read spans.

Labels

A finding is labelled confirmed or not_useful.

  • Issue outcomes. When an issue a detector opened is resolved, that is a confirmed label; when it is permanently archived, it is not_useful. A snooze is neither.
  • Shadow review. A shadow version opens nothing, so its findings could never earn labels from issues. Each shadow finding is listed for the project, and a person marks it confirmed or not useful, with one reason from a fixed list (expected_behavior, too_noisy, duplicate, wrong_subject, threshold_too_tight, not_actionable, other). Only a person signed in to the dashboard can do this; an agent, a delegation or an OAuth client is refused, because labels decide when a version starts opening issues for every project.

Precision is confirmed over labelled findings, one verdict per finding (the newest label wins). A version's precision counts the labels of every project and names none of them.

Asking why

detector_explain (MCP) and GET /orgs/:org/projects/:project/detectors/:id/explain answer from the stored run record: the inputs (rollup ids and a digest), the window, the value against the threshold and the decision. They never recompute.

  • decided — the run exists; the decision is fired, held or shadow.
  • not_enough_data — the detector lacked the data it needs and decided nothing. This is a result.
  • no_run_recorded — no run covers that moment. Runs are kept 30 days, and a detector records a run when it fires (some also when they lack data), so this does not mean the detector was healthy.

Reading the registry

detectors_list (MCP) and GET /orgs/:org/projects/:project/detectors return each detector's version, state, owner card, inputs, output, published thresholds, precision with its sample size, the last run for this project, and the project's own count of shadow findings still waiting for a label.

GET …/detectors/:id/shadow-findings lists a project's shadow findings (?unlabelled=true for the review list) and POST …/detectors/:id/shadow-findings/:runId/label records a verdict.

Changing a threshold

Not here. A threshold is changed by the area that owns the detector, through its own governed action, with a simulation attached. Loosening one is a silencing act with a time limit. Simulating a detector over history is not built yet (simulateDetector answers not_available and says why).