Skip to content
bucker

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 sampleBy is a tightening;
  • a higher ceiling, a removed entry, a ceiling dropped to "no ceiling", a changed sampleBy or 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.
  • ETag is a digest of the payload (stable across reads, independent of the signature); If-None-Match answers 304. Cache-Control: public, max-age=300.
  • The public half of the signing key is published at /.well-known/bucker-sdk-config.json as JWKs. The signing key is REMOTE_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():

  1. fetch, verify against the embedded public key, and cache for an hour (the cached copy is verified again on every read);
  2. 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;
  3. apply each section on top of the code: minimise rates, add drop entries, mask keys, header keys and selectors, remove propagation targets;
  4. 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.untrustedFields with an F-16 class (plan_echo).
  • capture_rules_update is held (SG-059): it needs capture:write, which is outside the live MCP ceiling.