Local Workflow

The complete offline debugging flow: capture events, process them into incidents and bundles, inspect, resolve, and clean up — no cloud account needed.

Overview

DebugBundle's local workflow gives you the full debugging experience wherever the SDK can write files and the CLI can process them:

Capture → Process → Inspect → Resolve

No cloud account, no signup, and no network requests to DebugBundle servers. Everything runs on disk.

This can be a development machine or a self-managed server. For server-local use, keep .debugbundle/ on persistent storage and run debugbundle process on that server or on a mounted/synced copy of the same directory.

1. Setup

If you haven't already:

debugbundle setup

This creates the .debugbundle/ scaffold. See Setup & Configuration for details.

2. Capture Events

Events land in .debugbundle/local/events/ through three paths:

SDK Capture (Automatic)

When your SDK's projectToken is 'local' or projectMode is 'local-only', events write to disk automatically:

import DebugBundle from '@debugbundle/sdk-node';

DebugBundle.init({
  projectToken: 'local',
  service: 'my-api',
});

// Exceptions, logs, and HTTP context now capture to local files

Log Ingestion (One-Shot)

Ingest an existing log file:

debugbundle ingest ./logs/error.log --format php-error

Supported formats:

Format	Description
`debugbundle-ndjson`	Native DebugBundle NDJSON format
`php-error`	PHP error log format
`apache-error`	Apache error log format

Log Watch (Continuous)

Tail-watch a log file and ingest new entries as they appear:

debugbundle watch --log ./logs/error.log --format apache-error

Watch mode polls the log file for new content and processes new events through the full pipeline (ingest → process → bundle).

To stream watched events to the cloud simultaneously:

debugbundle watch --log ./logs/error.log --format php-error --cloud

3. Process Events

Process raw events into incidents, bundles, and reproduction artifacts:

debugbundle process

Processing does the following for each batch of events:

Normalize — Standardize event format, extract structured fields
Classify — Determine event type (exception, log, HTTP, metric)
Fingerprint — Generate a stable fingerprint for incident grouping
Aggregate — Group events into incidents by fingerprint
Build bundles — Generate debug bundles with full context
Build reproductions — Create reproduction artifacts (curl, httpie, JSON spec)

Output:

Processed 12 events into 3 incidents.
- api: 2 incidents
- worker: 1 incident

Processing State

Processing is incremental and idempotent. The processor tracks the last processed event file and only processes new files on subsequent runs. Re-running process on already-processed events is safe.

Trace correlation joins services only inside the same project and environment. If an older cache reports local_incident_scope_mismatch, preserve .debugbundle/ and explicitly rebuild the local incident/artifact state from retained events:

debugbundle process --preset minimal

Choose balanced or investigative instead if that was the intended capture preset. This rebuild does not change cloud data or delete retained event files. Ordinary reads and incremental processing leave a mixed cache untouched.

4. List Incidents

debugbundle incidents

Output:

inc_a1b2c3 | high     | open     | TypeError: Cannot read property 'id' of undefined
inc_d4e5f6 | medium   | open     | POST /api/charge → 500 (timeout)
inc_g7h8i9 | high     | regressed | Checkout worker timeout

Filtering

# By source
debugbundle incidents --source local
debugbundle incidents --source cloud

# By status and severity
debugbundle incidents --status active --severity high
debugbundle incidents --status all

# By environment and service
debugbundle incidents --environment production --service api

# Pagination
debugbundle incidents --limit 20 --cursor <cursor>

JSON Output

debugbundle incidents --json

Returns a JSON object with incidents, cursor, and total fields.

5. Inspect an Incident

debugbundle inspect inc_a1b2c3

Output:

Incident: inc_a1b2c3
Source: local
Title: TypeError: Cannot read property 'id' of undefined
Severity: high
Status: open
Environment: development
Occurrences: 5

JSON Output

debugbundle inspect inc_a1b2c3 --json

Returns the full incident object including event history, fingerprint details, and matched fields.

6. Retrieve the Bundle

debugbundle bundle inc_a1b2c3

Returns the full debug bundle as JSON — the complete context snapshot for the incident:

{
  "schema_version": "1.0.0",
  "bundle_type": "failure",
  "incident": { "..." },
  "events": [ "..." ],
  "context": {
    "request": { "..." },
    "response": { "..." },
    "probe_data": { "..." },
    "breadcrumbs": [ "..." ]
  },
  "reproduction": {
    "curl": "curl -X POST ...",
    "httpie": "http POST ...",
    "json_spec": { "..." }
  }
}

7. Retrieve Reproduction Artifacts

debugbundle reproduce inc_a1b2c3

Returns ready-to-run reproduction commands:

{
  "curl": "curl -X POST http://localhost:3000/api/charge -H 'Content-Type: application/json' -d '{\"amount\":100}'",
  "httpie": "http POST http://localhost:3000/api/charge amount:=100",
  "json_spec": {
    "method": "POST",
    "url": "/api/charge",
    "headers": { "content-type": "application/json" },
    "body": { "amount": 100 }
  }
}

8. View Event Logs

debugbundle logs inc_a1b2c3

Output:

2025-01-15T10:30:00Z | error   | exception | evt_001
2025-01-15T10:30:00Z | warning | log       | evt_002
2025-01-15T10:29:58Z | info    | http      | evt_003

Filtering

debugbundle logs inc_a1b2c3 --level error --limit 50

9. Resolve and Reopen

Mark an incident as resolved:

debugbundle resolve inc_a1b2c3

Reopen if it recurs:

debugbundle reopen inc_a1b2c3

10. Run Analysis

Run improvement analysis on local incidents:

debugbundle analyze --type improvement --local --json

Analysis types:

Type	Purpose
`improvement`	Suggests code changes to prevent the incident
`failure`	Root cause analysis for failures
`performance`	Performance regression analysis

11. Clean Up

Remove local events:

debugbundle clean --events

Remove local bundles:

debugbundle clean --bundles

Remove everything:

debugbundle clean --all

Remove data older than N days:

debugbundle clean --all --older-than 30d

Complete Example

A full local workflow session:

# 1. Initialize
debugbundle setup

# 2. Start your app with the SDK
#    (events capture to .debugbundle/local/events/)

# 3. Process captured events
debugbundle process

# 4. Check what happened
debugbundle incidents

# 5. Investigate
debugbundle inspect inc_a1b2c3
debugbundle bundle inc_a1b2c3

# 6. Get reproduction command
debugbundle reproduce inc_a1b2c3

# 7. Fix and resolve
debugbundle resolve inc_a1b2c3

# 8. Verify health
debugbundle doctor

Next Steps

CLI Overview — Full command index and authentication
Setup & Configuration — Profile, connection, and scaffold details
Node.js SDK — Capture events from your backend

Local Workflow

On this page