Incidents
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, qualifying log_event, preset-specific immediate request_event failures (minimal: 5xx; balanced: 5xx plus 408/423/424/425/429; investigative: balanced plus 409), plus any project-selected 4xx statuses from immediate_client_error_statuses | Create/update incidents directly. |
| Context Signal | request_event outside the preset's immediate failure set, frontend_breadcrumb, deploy_metadata, probe_event, lower-level log_event | Enrich existing incidents with additional data. Repeated contextual request failures can open request-anomaly incidents without changing the stored event class. |
| Operational Signal | error_suppressed | Tracked but may not create new incidents. |
Incident Lifecycle
Created
A new incident is created when an incident signal does not match an existing fingerprint.
Open
Matching events continue to update occurrence counts, context, bundles, and alerts.
Resolved
A team member or agent explicitly marks the incident resolved.
Reopened
A new matching event after resolution reopens the incident as a 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 resolve inc_01H...
debugbundle resolve inc_01H... inc_01J...
# API
curl -X POST https://api.debugbundle.com/v1/incidents/inc_01H.../resolve \
-H "Authorization: Bearer dbundle_mem_a1b2c3d4..."
curl -X POST https://api.debugbundle.com/v1/incidents/resolve \
-H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{"incident_ids":["inc_01H...","inc_01J..."]}'
# MCP
resolve_incident(incidentId: "inc_01H...")
resolve_incidents(incidentIds: ["inc_01H...", "inc_01J..."])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 and opaque browser-native resource_error captures. |
high | Significant, needs attention. | backend_exception, non-opaque frontend_exception, immediate request-failure incident signals. |
critical | Severe, immediate action required. | Manually escalated. |
Severity is automatically inferred from event type and signal confidence at grouping
time. Opaque browser-native window_error captures infer low because browsers did
not expose enough application detail to justify paging-level severity by default.
Severity 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
debugbundle incidents --source cloud
debugbundle incidents --source localNext Steps
- Reproduction — Reproduction artifacts
- Bundles — Debug bundle structure
- API Incidents — Incident API endpoints
Context and log metadata
Incident detail includes Context for one-call evidence with explicit pending or failed artifacts, and Logs for bounded event metadata. Filter logs by level, choose 1–100 records per page and follow cursors. Raw sensitive log messages are not introduced by this view; bounded redacted bundle context remains in the bundle tab.