Probes

Probes deliver bounded checkpoints that application code already records with the SDK's probe method. Instrument and deploy the label and safe data first. Remote activation can then ship future matching observations independently, subject to capture policy, tier, expiry, sampling and delivery limits.

Use probes when an incident needs a specific technical observation, such as the stage of a media decode, an observed session state, a job dependency result or a cache hit/miss. New checkpoints require an application change and deployment. Activation does not inject code or collect arbitrary local variables or heap dumps.

How Probes Work

1. Activate — You create a probe via API, CLI, or MCP with a label pattern, service filter, and TTL.
2. 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.
3. Collect — When instrumented code executes a matching probe, the SDK may emit a standalone probe_event when policy permits, while retaining its documented always-on buffering and error-flush behaviour.
4. Enrich — Enriched data arrives with subsequent events and is included in the context.probe_data section of bundles.
5. 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

Label Pattern Matching

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.session.checkpoint",
          "data": {
            "stage": "refresh",
            "has_session": false,
            "result": "session_missing",
            "attempt": 1
          },
          "timestamp": "2026-03-24T11:05:00Z",
          "activation_id": "11111111-1111-4111-8111-111111111111"
        }
      ]
    }
  }
}

Bounded checkpoint recipes

Choose fixed labels, allowlisted technical states, booleans, counts or coarse buckets. Record observations the application actually checked. Keep names, customer or job identifiers, tokens, cookies, cache keys, media URLs, form values and raw payloads out of checkpoint data.

A successful HTTP status or a completed attempt alone does not establish semantic recovery. The application must check the required state explicitly.

Built-in evidence and probe instrumentation

Built-in collectors populate ordinary error, runtime or device evidence according to the installed SDK and its settings. Probe activation delivers the data supplied by instrumented checkpoints. Check the exact installed SDK and wrapper versions before relying on a collector.

When probe data is empty

An empty section means this bundle contains no matching retained checkpoint observation for its selected sample/window. It does not prove that every SDK received an activation, that no matching label exists, or that the checkpoint ran. Verify the deployed instrumentation/version, label and service/environment scope, expiry, capture policy, sampling and delivery receipts before drawing a conclusion. Activation cannot recover measurements that were never retained.

Limits

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

Next Steps

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