How It Works

DebugBundle operates in four stages. Each stage is a clean boundary with well-defined inputs and outputs.

Stage 1: Capture

SDKs intercept errors and context at runtime. No manual instrumentation required — the SDK hooks into your language's native error handling and optionally into your logging framework.

What gets captured:

Capture policy controls what gets shipped. The server-side capture policy (fetched by the SDK on init) defines three presets:

SDKs also apply local volume controls: storm suppression (repeated exceptions/logs are deduplicated with error_suppressed checkpoints), per-event sample rates, and log-level filtering.

Stage 2: Ship

The SDK batches captured events, applies redaction, and sends them to their destination.

Transport modes:

In connected staging and production, backend SDK delivery does not depend on container-local disk. Ephemeral containers and pods are fine as long as they can reach the ingestion API and have enough graceful shutdown time to flush buffered events. In local-only mode, and in connected development, events are written to local disk. For server-side local-only production, install the CLI where the files live and use persistent storage if you need events and bundles to survive replacement.

Browser SDK shipping: Browser events are sent through a relay handler (POST /debugbundle/browser) hosted on your backend. Same-origin relay paths avoid CORS setup; split frontend/backend deployments can use explicit browser relay mode with relay preflight handling and allowedOrigins. The relay validates, sanitizes, and either writes to local events (local mode) or spools for forwarding (connected mode). This keeps project tokens off the client. If you rely on the relay spool for durability in containers or pods, place the spool directory on persistent storage.

Log-based capture: An alternative input path. debugbundle ingest and debugbundle watch parse existing log files (via packages/log-parser) into the same event format. Supports debugbundle-ndjson (canonical structured format) and first-party adapters for PHP error logs and Apache error logs.

Stage 3: Process

Raw events are transformed into debug bundles through a deterministic pipeline.

In connected mode, the ingestion API validates events, persists raw payloads to S3, and enqueues processing jobs. The worker then runs the pipeline:

In local-only mode, debugbundle process runs the same pipeline locally using the same pure-function packages.

Pipeline steps

Normalize — Raw events are parsed into a canonical internal form.

Classify — Each event is assigned an immutable event_class:

Group — incident_signal events are fingerprinted and grouped into incidents. The system maintains rolling frequency counters (1m / 5m / 1h / 24h) and detects:

• Spikes — 5m/1h ratio ≥ 3.0
• Regressions — new occurrence on a resolved incident

Bundle — The bundle engine assembles a deterministic debug bundle from the qualifying failure or improvement opportunity context. Failure bundles center on grouped incidents; hosted improvement bundles center on deterministic request/log opportunity records. Incident-derived improvement opportunities are still recorded, but they point agents at the related incident bundles instead of generating duplicate hosted improvement artifacts. Given the same normalized inputs, generation remains byte-identical.

Reproduce — The reproduction engine generates executable artifacts (curl commands, HTTPie commands, JSON spec) from request context, with a confidence level.

Notify — Matching webhook endpoints receive signed payloads (bundle.created, bundle.updated, bundle.reopened, bundle.resolved, improvement_bundle.created). Alert rules evaluate incident conditions and deliver to configured channels (email, Slack, Discord, webhook). Solo and Team projects can also evaluate GitHub automation rules for incident lifecycle events and hosted improvement bundle creation, then send repository_dispatch events to the project's assigned repository.

Act — Repository-owned workflows fetch the full bundle and reproduction artifacts, then decide whether to open an issue, invoke an agent, create a PR, or do nothing.

Improvement Opportunities

Solo, Team, and self-host projects also run a hosted deterministic improvement lane after core ingestion and grouping. This lane evaluates recurring patterns such as:

• warning hotspots
• slow requests
• repeated request failures
• recurring incidents
• post-deploy regressions

When a bundle-producing request or log rule qualifies, DebugBundle stores an improvement opportunity, builds a hosted bundle_type: "improvement" artifact, and exposes it through the same retrieval surfaces as failure bundles. Incident-derived rules still create improvement opportunities, but those opportunities link back to the related incident bundles instead of producing a second hosted artifact.

Stage 4: Retrieve

The debug bundle and all related data are available through three equal interfaces:

All three interfaces call the same domain services — no capability is exclusive to any single interface.

In connected mode, retrieval fetches from the cloud API. The CLI and MCP default to a merged local+cloud view, with --source local|cloud for explicit filtering.

In local-only mode, retrieval reads directly from .debugbundle/local/state.json and .debugbundle/bundles/local/. No cloud account or authentication required.

Architecture Diagram

Next Steps

• Quickstart — Set up DebugBundle and capture your first error
• Installation — All installation methods
• Core Concepts — Bundles, incidents, profiles, and event types
• Improvement Bundles — Hosted deterministic improvement opportunities