Core Concepts
The three primitives, event types, fingerprinting, incident lifecycle, and bundle types.
DebugBundle is built on three primitives: bundles, incidents, and profiles. Hosted improvements add an opportunity layer on top of those primitives, but the mental model still starts here.
Debug Bundles
A debug bundle is a deterministic, versioned JSON document that packages debugging or hardening context into one portable artifact. It is the core artifact of the system.
Bundle Types
| Type | When created | Purpose |
|---|---|---|
failure | An unhandled exception, fatal error, or critical failure signal fires | Standard debugging: understand what broke and why |
improvement | Deterministic hosted rules detect a recurring hardening or optimization opportunity | Prioritize recurring latency, warning, request-failure, regression, or recurrence patterns before they become larger problems |
Hosted automated improvement bundles are available on Solo, Team, and self-host projects. They are generated from deterministic request/log rules, not by an LLM. Incident-derived signals such as recurring incidents and post-deploy regressions are still recorded as improvement opportunities, but they point to the related incident bundles instead of generating duplicate hosted improvement artifacts.
What's Inside
Every bundle contains a summary (title, severity, occurrence count, service, environment) and a set of context blocks. Each context block is independently versioned (version: 1) so blocks can evolve without breaking the bundle schema.
Context blocks: error, request, response, logs, frontend, environment, deploy, runtime, git, dependencies, probe_data, device.
Determinism Guarantee
Given the same normalized events, the bundle generator produces byte-identical output. No random IDs or wall-clock timestamps are injected during generation. This means bundles can be diffed, cached, and verified.
Incidents
An incident is a fingerprint-grouped container of events. When the system sees a new incident_signal event, it computes a fingerprint and either creates a new incident or groups it with an existing one.
Incident Lifecycle
Open
Active incident receiving new occurrences.
Resolved
Manually closed by CLI, API, MCP, or the web app.
Regressed
Reopened after a new event matches a previously resolved fingerprint.
Open — Active incident receiving new occurrences.
Resolved — Manually resolved via CLI (debugbundle resolve), API (POST /v1/incidents/{id}/resolve or POST /v1/incidents/resolve), or MCP (resolve_incident / resolve_incidents).
Regressed — A resolved incident that received a new matching event. Automatically transitions back and can trigger alerts and webhooks.
Spike Detection
The system maintains rolling frequency counters for each incident across four windows: 1 minute, 5 minutes, 1 hour, and 24 hours. A spike is detected when the 5-minute/1-hour ratio reaches ≥ 3.0, indicating a sudden increase in occurrence rate.
Occurrence Retention
Not every occurrence is retained in full detail. The system keeps:
- First occurrence
- Latest occurrence
- First occurrence after each deploy
- Highest-severity occurrence
Other occurrences are demoted to summary-only metadata to bound storage.
Profiles
A project profile (profile.json) is the configuration file for a DebugBundle project. It lives in .debugbundle/profile.json and is created by debugbundle setup.
The profile contains:
- Project identification (name, token, environment)
- Service metadata
- Capture policy overrides
- Local processing settings
- Agent skill references
Profiles are validated by the CLI and SDK on startup. Staleness warnings are emitted if the profile hasn't been updated after significant project changes.
Event Types
Every piece of data entering DebugBundle is an event. Events are classified into three immutable classes during normalization:
| Event class | Examples | Creates incident? | Billed (free tier)? |
|---|---|---|---|
incident_signal | Unhandled exceptions, fatal errors, critical log entries | Yes | Yes |
context_signal | Logs, breadcrumbs, request/response context, probe data | No — attaches to incidents | No |
operational_signal | Health checks, SDK lifecycle events, config fetches | No | No |
Classification is immutable — once assigned during normalization, it never changes. This simplifies billing, grouping, and retention logic.
Fingerprinting
Fingerprinting determines which events belong to the same incident. The algorithm examines:
- Error class and message (with variable parts normalized)
- Stack trace frames (file, function, line)
- Service name
- Environment
Two errors with the same fingerprint are grouped into the same incident. This means fixing one occurrence fixes all grouped occurrences.
Reproduction Artifacts
When an incident has HTTP request context, the reproduction engine generates executable artifacts:
| Artifact | Format | Example |
|---|---|---|
curl | Shell command | curl -X POST https://api.example.com/v1/endpoint -H 'Content-Type: application/json' -d '{...}' |
httpie | Shell command | http POST https://api.example.com/v1/endpoint Content-Type:application/json key=value |
json_spec | Structured JSON | Machine-readable spec with method, URL, headers, body |
Each artifact includes a confidence level indicating how completely the request could be reconstructed from available context.
Next Steps
- Quickstart — Capture your first incident
- How It Works — The full 4-stage lifecycle
- Improvement Bundles — Hosted deterministic improvement opportunities
- SDKs Overview — Configure capture for your language and framework
- CLI Local Workflow — Process, inspect, and resolve incidents locally