Capture rules
Capture rules let a project make its SDKs collect less, without a redeploy, and make sure nothing can make them collect more except a person. They are one signed document per project, served to every SDK, applied on top of what the code configured, and changed through one governed door.
code configuration ───────────────► what the SDK collects
▲
signed document (this page) ─────┘ can only remove, mask, lower or stop; never add, raise or restore
The document
bucker.capture-rules/1. Every list holds at most 200 entries of at most 200 characters, with no
control characters. Everything in it is a name or a pattern the SDK compares against; nothing is code.
| Section | Fields | Written by |
|---|---|---|
sampling |
spans, logs, product.events, product.pageviews, product.autocapture (a keep-rate ceiling, 0 to 1), sampleBy (trace, session, user) |
capture_rules_update |
drop |
eventNames, loggers, spanOps, breadcrumbKinds |
capture_rules_update |
mask |
propertyKeys, headerKeys, selectors |
capture_rules_update |
propagation |
removeTargets (hosts the SDK stops attaching trace headers to) |
capture_rules_update |
runtime |
denyEntries (APM-04's runtime deny list), exceptionCapture (Exception Replay) |
capture_rules_update (deny entries); the Exception Replay family (the entry) |
identity |
denylist |
PA-04's identity rules |
replay |
DX-02's replay rules | the replay rules family |
windows |
scheduled capture windows | the capture-window family |
A document is shadow (stored and previewed, never served) or live (served). A new document lands as
a shadow draft, and going live is its own act, so a person reading the draft sees what will be served
before an SDK does.
Tighten-only is a property of the comparison
compareDocuments(before, after) is the one function that decides whether after collects less than
before, and every door that writes the document asks it. Over what an SDK actually collects (a shadow
draft collects like the empty document):
- a lower or newly set ceiling, a larger set, a newly chosen
sampleByis a tightening; - a higher ceiling, a removed entry, a ceiling dropped to "no ceiling", a changed
sampleByor a live document withdrawn is a widening.
A widening is only ever a person's act (capture_rule.widen, org:admin). The first document of a
project tightens against the empty document: the code's own configuration is the first ceiling, and
the SDK enforces it again when it applies a served document.
What an agent can do
capture_rules_update (MCP) and PUT /orgs/:org/projects/:project/capture-rules (REST) take the
desired state of the sections to change, the version the caller read, the digest of a counted
preview and a reason. The act is derived from what the diff does, never from an argument:
| What the change does | Act | Class | Decision |
|---|---|---|---|
| a draft saved, never served | capture_rule.create |
ELEVATED | ALLOW |
| masks added that nothing reads | capture_masking.narrow |
ELEVATED | ALLOW |
| ... when a dependent reads a masked field, or a removed propagation host sent spans | capture_sampling.narrow |
SENSITIVE | ASK |
| drops or propagation hosts added that name nothing stored in 7 days | capture_rule.update |
ELEVATED | ALLOW |
| ... naming data the project stored in the last 7 days | capture_rule.update |
SENSITIVE, silencing-class, 90-day TTL | ASK |
| a sampling ceiling set or lowered | capture_sampling.narrow |
SENSITIVE, 90-day TTL | ASK |
| runtime deny entries added | capture_denylist.narrow |
SENSITIVE | ASK |
| anything that collects more | capture_rule.widen |
human-only | refused to an agent, a service account and an OAuth client |
The SENSITIVE branches may be answered ALLOW by an organization's own policy, up to 10% of a signal's items on any day. A change that drops more than that, or whose share could not be measured, is CRITICAL, which no ALLOW row reaches. An unmeasured share is treated as wide, never as zero.
When the 90-day TTL ends, the sweeper does not undo anything by itself: it asks an org:admin to keep
the rule or restore the previous document.
The counted preview
Before anything is applied the change is previewed over the last 7 days of the project's own data, a day at a time, and each figure says how it was measured:
- a name matched against stored rows (a logger, a span op) is
exact; - a ceiling applied to a day's count is an
estimate; - a signal nothing counted (product events outside the core-event rollup) is
unmeasured.
The preview also lists the dependents that read a masked field (alert rules, saved views, board widgets) and counts spans that went to a propagation host the change removes. A change that would drop spans or logs of a trace that holds an error is refused with no digest: an SDK never samples an error away, and a plan that takes the evidence an investigation needs is not offered to an approver.
Previews are their own tool (capture_rules_list with include: ["preview"]) and route
(POST .../capture-rules/preview), never a flag on the write. Giving a reason also records the
engine's planned operation, which the act requires within 30 minutes (requirePreview).
After the apply
The apply is one compare-and-swap on the document's version: a human edit through any other door
between the approval and the retry closes the request TARGET_CHANGED and spends nothing. The
verification signal is event_volume over 60 minutes against the preview. The stored inverse of every
narrowing is capture_rule.widen, which is human-only, so operation_revert is refused to an agent
and to every other principal: a person restores a version through the widen door.
Widening, by a person
POST /orgs/:org/projects/:project/capture-rules/widen takes either new changes or a
restoreVersion, a reason, and optionally the revision the screen showed. It needs an OWNER
(org:admin) on their own dashboard session, writes the new version and its audit row
(capture_rule.widen, flagged loosened: true) in one transaction and alerts the organization's
owners afterwards. It refuses a change that does not widen and points at the governed door. It also
refuses a change that widens in one place and narrows in another (MIXED_WIDEN_AND_NARROW): anything
that collects less goes through capture_rules_update, with its preview, ask and TTL, so a restore that
would also narrow takes two steps. Withdrawing a live document (state: "shadow") is a widening, and
from then on SDKs are served nothing until the document goes live again.
How an SDK gets it
GET /api/:projectId/sdk-config?sentry_key=... is authenticated by the DSN key the SDK already ships.
The project comes from the key: a key resolved against another project's id is refused, and nothing in
the path, query or a body can name another project's document.
The response is the newest version, signed, when that version is live:
{ "v": 1, "alg": "ES256", "keyId": "...", "payload": "<the exact string that was signed>", "signature": "<base64url r||s>" }
payload is a string. The server signs those bytes and a verifier checks the signature over the string
it received and only then parses it, so no language ever has to reproduce another's JSON number
formatting. The payload names schema, projectId, version, keyId, issuedAt and the document
without its lifecycle.
- 204 when the newest version is not live (no document, a draft, or a withdrawn document), or the deployment has no signing key. An unsigned document is never served, and the door never reaches past a newer shadow version to an older live one: what is served is what every change is classified against.
ETagis a digest of the payload (stable across reads, independent of the signature);If-None-Matchanswers 304.Cache-Control: public, max-age=300.- The public half of the signing key is published at
/.well-known/bucker-sdk-config.jsonas JWKs. The signing key isREMOTE_DOCUMENT_SIGNING_KEY, one per region, a PKCS#8 PEM P-256 private key created and rotated by a person. It is a secret and is never logged or written.
What the SDK does with it
@bucker/sdk-core/remote-config (remoteCaptureRules()) and bucker_sdk.remote_config.install():
- fetch, verify against the embedded public key, and cache for an hour (the cached copy is verified again on every read);
- refuse a document that is unsigned, signed by an unknown key, for another project, of a lower version than the one already applied (a replay), of the wrong shape, or that widens anything (a ceiling above 1). A refusal keeps the code's own configuration;
- apply each section on top of the code: minimise rates, add drop entries, mask keys, header keys and selectors, remove propagation targets;
- report the applied version on every envelope header as
config_version.
It is inert by default: nothing is fetched until the integration is installed, and with no embedded
public key (EMBEDDED_PUBLIC_KEYS is empty until the regional key exists) nothing is ever applied.
Errors in this path never reach the application.
Tenancy and trust
- Every statement that reads or writes a document opens with the project, resolved inside the caller's organization. Another organization's project is "not found" on every route and tool, and nothing of it is counted, listed, previewed or written.
- The serving cache is keyed by organization, project, version and key id.
- Every entry of the document and every dependent's name that an MCP tool returns passes the
agent-tier gate and is listed in
trust.untrustedFieldswith an F-16 class (plan_echo). capture_rules_updateis held (SG-059): it needscapture:write, which is outside the live MCP ceiling.