incident-replay

incident-replay is a deterministic backend incident capture and replay system for Django applications. It automatically captures the minimal database, cache, environment, and external API state surrounding failing production requests, generating a portable incident snapshot.

You can then deterministically replay these incidents locally on your machine with a single CLI command!

Features (v0.1.0 MVP)

• Failing Request Capture: Intercepts HTTP 500s or Python unhandled exceptions via standard Django Middleware.
• Minimal Data Extraction Engine: Traces all SQL executed during a bad request, calculates foreign key dependencies automatically via Django models, and saves ONLY the rows accessed (no full database dumps needed!).
• Portable Snapshots: Generates INC-<ULID>/ snapshots containing serialized JSON artifacts request.json, query_trace.json, metadata.json, and db_snapshot.json.
• Deterministic CLI Replay: Spin up incidents directly in your local environment. Replay engine initializes an ephemeral SQLite schema automatically, loads the minimal DB snapshot, mocks out UUID generation and Time (WIP), and deterministically crashes with the exact same stack-trace.

Installation

pip install incident-replay

Add to your Django project settings:

INSTALLED_APPS = [
    # ...
    # Any specific apps...
]

MIDDLEWARE = [
    'incident_replay.capture.middleware.IncidentReplayMiddleware',
    # ... your other middleware
]

# Local directory where snapshots are placed (S3 integrations planned)
INCIDENT_REPLAY_STORAGE_DIR = "/tmp/incident_snapshots" 

Usage

1. Wait for an Incident

When your application throws an internal server error (or if a manual trigger header X-Incident-Trigger: true is sent), incident-replay captures it to your storage backend.

2. List Incidents

incident-replay list

3. Replay locally!

You must set your DJANGO_SETTINGS_MODULE to run the replay engine.

DJANGO_SETTINGS_MODULE=myproject.settings incident-replay run INC-01JEXAMPLEID1234

You will see the identical stack trace error out on your terminal.

Core Principles

1. Developer First: Focus on exactly what broke during a single request execution timeline.
2. Minimal Data Universe: Extracts rows that matter. No PII leaking across massive table dumps.
3. Low Overhead: Uses passive DB cursor tracing <5% overhead on the critical path. Snapshot serialization only occurs off the critical path or synchronously on failures only.

Phase 2 roadmap includes Redis capture, httpx interception, and background Celery integrations.