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
confirmedlabel; when it is permanently archived, it isnot_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 isfired,heldorshadow.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).