DebugBundle

How DebugBundle groups events into incidents using fingerprinting and lifecycle management.

An incident represents a unique problem detected in your application. DebugBundle automatically groups related events into incidents using fingerprinting, tracks their lifecycle, and generates debug bundles for investigation.

Event-to-Incident Pipeline

Events → Normalize → Fingerprint → Group → Incident → Bundle

Ingest — SDKs send events to POST /v1/events. Events are persisted to object storage and queued for processing.
Normalize — The worker normalizes event data (strips dynamic values like UUIDs, timestamps, IP addresses, email addresses).
Fingerprint — A deterministic fingerprint is computed from the normalized message, error type, route template, top stack frames, HTTP method, and HTTP status.
Group — Events with the same fingerprint are grouped into a single incident.
Bundle — Debug bundles are generated at occurrence thresholds (1, 3, 10 events).

Fingerprinting

The fingerprint is a SHA-256 hash computed from these fields (when available):

Field	Description
`environment`	Deployment environment (always included).
`normalized_message`	Error message with dynamic values stripped.
`error_type`	Exception class name (e.g., `TypeError`, `NullPointerException`).
`route_template`	URL route template (e.g., `/api/users/:id`).
`top_frames`	Top application stack frames (excluding library/framework frames).
`http_method`	HTTP method (GET, POST, etc.).
`http_status`	HTTP response status code.

The matched_fields array on each incident records which fields contributed to its fingerprint, providing transparency into grouping decisions.

Normalization Patterns

Before fingerprinting, dynamic values are stripped from messages:

Pattern	Replacement
UUIDs	`[UUID]`
Email addresses	`[EMAIL]`
ISO timestamps	`[TIMESTAMP]`
IPv4 addresses	`[IP]`
Hex values	`[HEX]`

This ensures that occurrences of the same underlying error are grouped together regardless of dynamic payload content.

Event Types

Events are classified into three categories:

Event Class	Event Types	Role
Incident Signal	`backend_exception`, `frontend_exception`, `request_event` (4xx/5xx)	Create/update incidents directly.
Context Signal	`log_event`, `frontend_breadcrumb`, `deploy_metadata`, `probe_event`	Enrich existing incidents with additional data.
Operational Signal	`error_suppressed`	Tracked but may not create new incidents.

Incident Lifecycle

┌──────────┐         ┌──────────┐         ┌──────────┐
│  Created  │────────▶│  Open    │────────▶│ Resolved │
└──────────┘         └──────────┘         └──────────┘
                          ▲                     │
                          │    (regression)      │
                          └─────────────────────┘

State	Description
Open	Active incident, events still arriving. Default state.
Resolved	Incident marked resolved by a team member.
Reopened	A resolved incident that received new matching events (regression).

Resolution

Incidents can be resolved via API, CLI, or MCP:

# CLI
debugbundle incidents resolve inc_01H...

# API
curl -X POST https://api.debugbundle.com/v1/incidents/inc_01H.../resolve \
  -H "Authorization: Bearer dbundle_member_a1b2c3d4..."

# MCP
resolve_incident(incident_id: "inc_01H...", resolution_note: "Fixed in v2.3.1")

When an incident is resolved, a bundle.resolved webhook event is fired.

Regression

If new events arrive matching a resolved incident's fingerprint, the incident is automatically reopened and a bundle.reopened webhook event is fired. If the regression correlates with a recent deploy, the regression_after_deploy flag is set and deploy metadata is included in the webhook payload.

Severity

Level	Meaning	Auto-Assigned For
`low`	Minor, informational.	Most event types (default).
`medium`	Moderate impact.	`error_suppressed` events.
`high`	Significant, needs attention.	`backend_exception`, `frontend_exception`.
`critical`	Severe, immediate action required.	Manually escalated.

Severity is automatically inferred from the event type at grouping time. It can be manually escalated but not downgraded.

Sources

Incidents can come from two sources:

Source	Description
Local	Generated by `debugbundle process` on local log files.
Cloud	Generated from events ingested via `POST /v1/events`.

Use --source filters to view incidents from a specific source:

debugbundle incidents list --source cloud
debugbundle incidents list --source local
debugbundle incidents list --source all

Next Steps

Reproduction — Reproduction artifacts
Bundles — Debug bundle structure
API Incidents — Incident API endpoints

Incidents

On this page