Probes

Request additional diagnostic data from SDKs without code changes or redeployment.

Debug probes let you dynamically request richer diagnostic data from running applications without changing code or redeploying. When a probe is active, matching SDK instances collect extra context and include it in subsequent events.

When to Use Probes

An incident exists but the bundle lacks sufficient diagnostic data.
You need heap snapshots, extended stack traces, or local variable dumps.
You want to capture richer data temporarily without a code change.
You need data from a specific service/environment combination.

How Probes Work

API, CLI, or MCP

Activate

Create a probe with a label pattern, service filter, environment filter, and TTL.

Store

DebugBundle stores the activation and returns the current directive state.

Distribute

SDKs receive probe directives through config polling and ingestion responses.

Collect

Matching SDK instances attach probe data to subsequent events.

Bundle

Probe data appears in context.probe_data when related incidents are bundled.

Activate — You create a probe via API, CLI, or MCP with a label pattern, service filter, and TTL.
Distribute — Backend SDKs poll GET /v1/sdk/config with ETags; browser and mobile SDKs use a bounded startup/lifecycle config check plus probe_directives piggybacked on successful POST /v1/events responses.
Collect — Matching SDK instances emit standalone probe_event records for active remote probes and continue buffering always-on probe data locally for error flushes.
Enrich — Enriched data arrives with subsequent events and is included in the context.probe_data section of bundles.
Expire — The probe automatically deactivates after its TTL expires.

If a project downgrades to Free, saved remote probe activations remain visible in the management surfaces so owners can see what will resume after upgrading again. They do not continue shipping while the lower tier is active.

Probe Configuration

Parameter	Description	Default
`label_pattern`	Glob pattern matching incident labels (e.g., `auth.*`, `payment.checkout`)	— (required)
`service`	Scope to a specific service name	All services
`environment`	Scope to a specific environment	All environments
`ttl_seconds`	Passive remote activation lifetime, max 3600 seconds	— (required)
`trigger_ttl_seconds`	Trigger token validity window	Same as `ttl_seconds`

Label Pattern Matching

Pattern	Matches
`*`	All incidents
`auth.*`	`auth.login`, `auth.token.expired`, etc.
`payment.checkout`	Exactly `payment.checkout`

Probe Data in Bundles

Probe-collected data appears in the context.probe_data section of the bundle:

{
  "context": {
    "probe_data": {
      "version": 1,
      "items": [
        {
          "label": "auth.token.expired",
          "data": {
            "heap_snapshot": "...",
            "local_variables": { "userId": "usr_01H...", "tokenAge": 86401 },
            "extended_stack": "..."
          },
          "timestamp": "2026-03-24T11:05:00Z",
          "activation_id": "prb_01H9KL..."
        }
      ]
    }
  }
}

Limits

Constraint	Limit
Max concurrent remote activations per project	5
Passive probe activation TTL	1 hour max
Probe directive refresh interval	Backend default 60 seconds; browser zero-polling; mobile bounded lifecycle refresh
Trigger token validity	Configurable up to 24 hours

Trigger Token

When you activate a probe, the API returns a trigger_token. This token is shown exactly once at creation time — store it immediately.

The trigger token lets SDKs activate matching probes for a specific request or session without waiting for passive directive refresh. SDKs validate dbundle_probe_... tokens locally with the trigger_token_key from GET /v1/sdk/config, check expiry, and silently ignore invalid tokens.

Managing Probes

Interface	Reference
Web app	Project Probes tab
API	Probes API
CLI	CLI Cloud Workflow
MCP	MCP Workflows

Next Steps

Probes API — Activate, list, and deactivate probes
Bundles — How probe data enriches bundles
Universal SDK Interface — SDK probe support