Bundles

A debug bundle is a captured snapshot of a debugging-relevant failure or improvement signal. It is the core artifact in DebugBundle — portable, self-describing, agent-readable, and designed for both human and AI consumption.

Bundle Types

Type	Description
`failure`	Captures an error, exception, or degraded behavior.
`improvement`	Captures a recurring hardening or optimization opportunity from deterministic request, log, deploy, or incident patterns.

Improvement bundles are a first-class hosted artifact for Solo+, not just a footnote on the failure-bundle flow. See Improvement Bundles for the product-specific model, triggers, quota behavior, and settings surface.

What's in a Bundle

A bundle aggregates data from multiple events into a single coherent debugging artifact:

Section	Contents
Metadata	ID, version, timestamps, generator
SDK info	SDK name and version
Project	Project ID, slug, and environment
Service	Service name, runtime, framework, version, and region
Signal	Signal type, severity, fingerprint, and occurrences
Summary	Title, description, likely cause, and confidence
Impact	Affected users or requests and business criticality
Context: Error	Error name, message, stack, and top frames
Context: Request	Method, path, headers, and body
Context: Response	Status, duration, headers, and body
Context: Logs	Timestamped log entries
Context: Frontend	Route changes, clicks, network, console, and DOM context
Context: Environment	OS, host, and container details
Context: Deploy	Commit, version, branch, and regression window
Context: Runtime	Process state, memory, and framework details
Context: Git	Commit, branch, repo, and dirty state
Context: Dependencies	Service health checks
Context: Probe Data	Dynamically collected diagnostic data
Context: Device	Browser, OS, screen, and viewport
Reproduction	cURL, HTTPie, JSON spec, and confidence
Verification	Test results and verification commands

All context blocks are optional — bundles work with partial data. Missing blocks are simply absent, not null-padded.

Bundle Generation

Failure bundles are generated asynchronously by the worker after events are grouped into incidents. Improvement bundles are generated asynchronously when deterministic opportunity rules cross threshold and dedupe gates.

Common generation triggers:

failure occurrence thresholds and meaningful context changes
recurring warning/log patterns
repeated slow requests
repeated request failures
recurring incident reopen/regression behavior
post-deploy regressions

Determinism

Given the same normalized events, the bundle generator produces byte-identical output. No random IDs or wall-clock timestamps are used in generation — deterministic reproducibility is a core invariant.

Versioning

Envelope versioning: bundle_version: 1 (integer). Bumps only when the overall contract changes significantly.

Context block versioning: Each context block contains its own version: 1. This allows individual blocks to evolve independently without forcing a whole-bundle version change.

Compatibility rules:

Unknown context blocks must be ignored safely by consumers.
Missing context blocks are allowed.
Additive fields are preferred over breaking changes.
A new optional context block does not require a new bundle_version.

Signal Types

The signal.signal_type field describes what kind of signal triggered the bundle:

Signal Type	Description
`exception`	An unhandled or handled exception.
`fatal_error`	A fatal/crash-level error.
`request_failure`	An HTTP request that returned an error status.
`frontend_exception`	A browser-side JavaScript exception.
`warning`	A warning-level signal.
`deprecation`	A deprecation notice.
`performance_issue`	A detected performance regression.
`retry_loop`	A detected retry loop pattern.
`slow_query`	A slow database query.

Improvement bundles commonly use warning, performance_issue, request_failure, and retry_loop style signals depending on the qualifying rule.

Severity Levels

Severity	Meaning	Automatic Assignment
`low`	Minor issue, informational.	Default for most event types.
`medium`	Moderate impact, should be reviewed.	`error_suppressed` events and opaque browser-native `resource_error` captures.
`high`	Significant impact, needs attention.	`backend_exception`, non-opaque `frontend_exception`, immediate request-failure incident signals.
`critical`	Severe impact, immediate action required.	Manually escalated.

Opaque browser-native window_error captures infer low by default because the browser did not provide enough application detail to classify them as high-confidence failures.

Summary Section

The summary is derived at bundle generation time from existing context — it is not stored separately. Key derivations:

Field	Derived From
`severity`	`signal.severity`
`error_type`	`context.error.name`
`error_message`	`context.error.message`
`first_application_frame`	Stack parsing — top application frame from `context.error.stack`
`likely_cause`	Analysis engine output
`confidence`	Analysis confidence score (0–1)

Reproduction Section

When sufficient request context is available, bundles include reproduction artifacts:

Artifact	Description
`curl`	Ready-to-run cURL command.
`httpie`	Ready-to-run HTTPie command.
`json_spec`	Structured JSON with method, URL, headers, query, and body.

Each reproduction includes a confidence score and feasibility assessment:

Scenario	Feasibility
Standard HTTP bugs	High
Frontend interaction + failing request	Medium-high
Background jobs	Medium
External outage timing	Low-medium
Race conditions	Low

See Bundle Schema for the complete JSON structure.

Next Steps

Bundle Schema — Complete JSON schema reference
Improvement Bundles — Hosted deterministic improvement opportunities
Incidents — How incidents are created from events
Probes — Enrich bundles with probe data

Bundles

On this page