Metadata-Version: 2.4
Name: incident-replay
Version: 0.1.0
Summary: Deterministic backend incident replay system for Django applications.
Author-email: System Architect <architect@example.com>
License: MIT
Keywords: django,debugging,incident,replay,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Django
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: Django>=3.2
Requires-Dist: requests>=2.25
Requires-Dist: httpx>=0.20
Requires-Dist: ulid-py>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: psycopg2-binary; extra == "dev"
Requires-Dist: redis; extra == "dev"

# 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

```bash
pip install incident-replay
```

Add to your Django project settings:

```python
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

```bash
incident-replay list
```

### 3. Replay locally!

You must set your `DJANGO_SETTINGS_MODULE` to run the replay engine.

```bash
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.*
