Capture Policy

The capture policy controls how your SDKs behave — what types of events they capture, at what verbosity level, and how breadcrumbs and probes are handled. Each project has one capture policy that applies to all SDKs connecting to it. The same policy also controls which selected 4xx responses open incidents immediately. Unpromoted 4xx responses, including generic 404 traffic, stay as request telemetry/context when captured and do not open incidents by repetition.

Capture rules sit on top of the policy for known noisy patterns. After an incident appears, you can create a project-level rule to demote, sample, or drop future matching events without changing the broader preset.

For the end-to-end triage loop, see Managing Noise.

Presets

Presets provide sensible defaults for common scenarios. Choose a preset, then optionally override individual controls.

Default Preset by Tier

Controls

Capture Logs

Controls which log levels are captured and sent as events.

Capture Request Events

Controls which HTTP request/response pairs are captured.

Capture Breadcrumbs

Controls how frontend breadcrumbs (clicks, route changes, console logs) are handled.

Capture Probe Events

Controls how probe-collected data is handled.

Client Error Incidents

Controls which HTTP 4xx responses are promoted into immediate incident-opening request failures.

5xx responses remain immediate incidents automatically and are not configured here.

Promoted client errors behave like any other request-failure incident: they can trigger alerts, webhooks, GitHub dispatch automation, bundle generation, retention, and usage accounting.

For routes that should never return 404, use a path-scoped rule instead of promoting all 404 responses. Path rules combine a 4xx status, a path pattern, and optional HTTP methods:

{
  "immediate_client_error_path_rules": [
    { "status_code": 404, "path_pattern": "/checkout/*", "methods": ["GET", "POST"] }
  ]
}

The path must start with / and may use a terminal * wildcard. A rule like /checkout/* promotes /checkout/order-missing, but leaves scanner traffic such as /robots.txt or /wp-config.php_old2024 as non-incident telemetry.

Capture Rules

Capture rules are manual, project-level decisions for known noise. They are useful for cases like blocked third-party analytics scripts, repeated browser resource-load failures, or a noisy route that should be sampled after you have confirmed the pattern.

Rules use structured matchers. The incident detail page and debugbundle capture-rule suggest can suggest narrow rules from an existing bundle, so most teams should start from an incident rather than writing matchers by hand.

Browser Noise Examples

Demote generic opaque browser Window error noise after confirming it is not a real application exception:

{
  "event_types": ["frontend_exception"],
  "runtime": ["browser"],
  "services": ["checkout-web"],
  "environments": ["production"],
  "browser_event_kind": "window_error",
  "browser_event_opaque": true,
  "message_equals": "Window error"
}

Drop repeated third-party resource-load errors from a known analytics host:

{
  "event_types": ["frontend_exception"],
  "browser_event_kind": "resource_error",
  "first_party": false,
  "resource_url": { "host": "analytics.example.com" }
}

Demote bot-scoped generic unhandled rejections without hiding the same message from human users:

{
  "event_types": ["frontend_exception"],
  "runtime": ["browser"],
  "services": ["checkout-web"],
  "environments": ["production"],
  "client_kind": "bot",
  "bot_family": "Googlebot",
  "message_equals": "Unhandled promise rejection"
}

Use server-side capture rules first for operational noise because they are visible, auditable, and enforced by ingestion/worker backstops. Use SDK-local filters for app-owned capture choices such as network breadcrumb filtering, final redaction, or tenant-specific suppression. The JS SDKs expose a synchronous beforeSend(event) => event | null hook for that local policy; return null only when the event should never leave the runtime.

Current local SDK enforcement:

Ingestion and worker processing enforce active rules again as a backstop, so rules still apply even when an SDK has not implemented local filtering.

Managing the Policy

API

# Get current policy
curl https://api.debugbundle.com/v1/projects/proj_01HXYZ.../capture-policy \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

# Update policy
curl -X PATCH https://api.debugbundle.com/v1/projects/proj_01HXYZ.../capture-policy \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "preset": "investigative" }'

# List capture rules
curl https://api.debugbundle.com/v1/projects/proj_01HXYZ.../capture-rules \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

# Suggest rules from an incident bundle
curl -X POST https://api.debugbundle.com/v1/incidents/inc_01HXYZ.../capture-rule-suggestion \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

CLI

# View current policy
debugbundle capture-policy get --project proj_01HXYZ...

# Switch to investigative mode
debugbundle capture-policy set --project proj_01HXYZ... --preset investigative

# Promote the recommended interactive-app client errors immediately
debugbundle capture-policy set \
  --project proj_01HXYZ... \
  --client-error-incidents recommended

# Promote only 404s under a real application path
debugbundle capture-policy set \
  --project proj_01HXYZ... \
  --client-error-path-rule '404=/checkout/*@GET,POST'

# Suggest and create capture rules from a known noisy incident
debugbundle capture-rule suggest inc_01HXYZ...
debugbundle capture-rule create-from-suggestion inc_01HXYZ... --suggestion-id primary_resource_host_demote

Override Behavior

Setting a preset changes the resolved defaults. Existing advanced overrides stay in place unless you clear or replace them, so you can update only the fields you mean to change:

# Start with balanced preset, but capture all request events
curl -X PATCH https://api.debugbundle.com/v1/projects/proj_01HXYZ.../capture-policy \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "balanced",
    "capture_request_events": "all"
  }'

Result: the preset becomes balanced, the saved request-event override becomes all, and any other existing advanced overrides keep their previous saved state.

To clear an override and revert to the preset default, set the field to null:

{ "capture_request_events": null }

The same null vs [] distinction matters for client error incidents:

{ "immediate_client_error_statuses": null }

means "use the preset default", while:

{ "immediate_client_error_statuses": [] }

means "explicitly promote no additional 4xx statuses".

Path-scoped client error rules follow the same override model:

{ "immediate_client_error_path_rules": null }

means "use the preset default", while:

{ "immediate_client_error_path_rules": [] }

means "explicitly promote no path-scoped 4xx rules".

SDK Behavior

SDKs fetch the capture policy and active capture rules from the server during initialization and periodically refresh it. When the policy changes, shipped Browser, Node.js, Python, PHP, Java, Go, Ruby, Android, iOS, and React Native SDKs adjust their capture behavior without requiring a restart or redeploy, including the selected client error incident statuses. Path-scoped client error rules are delivered in the same config response and are enforced locally by SDKs that support request capture before ingestion applies the same policy as a backstop.

In local-only mode, SDKs use built-in defaults (equivalent to the balanced preset).

Next Steps

• Projects API — Capture policy API endpoints
• Project Setup — Project configuration overview
• Universal SDK Interface — SDK capture behavior