statelens 0.1.0

A Time Machine for Python Programs — record, inspect, and replay program execution.

StateLens

A Time Machine for Python Programs.

StateLens records how a Python program's execution evolves over time — every function call, every line executed, every variable mutation, every exception, every allocation — so you can replay that history after the program has already finished running, instead of only staring at a final stack trace.

Where a debugger shows you the present moment and a stack trace shows you the point of failure, StateLens shows you the whole story:

• What changed? — every variable mutation, tracked automatically.
• When did it change? — a precise, ordered timeline of every event.
• Why did it change? — the full call stack and arguments at that moment.
• Which function caused it? — a reconstructed call tree with timing.
• What was the state before the crash? — not just the traceback, the entire program state leading up to it.
• How did memory evolve? — periodic memory samples across execution.
• How did execution flow? — a visual execution graph of the whole run.

Install

pip install statelens

Requires Python 3.11+.

Quick start

Record a script's execution:

statelens run app.py

This produces session.json — a complete recording of the program's execution. Now generate an interactive HTML report:

statelens report session.json --open

Or step through the recording one event at a time in your terminal:

statelens replay session.json

Check that your environment is set up correctly:

statelens doctor

Using the Python API directly

from statelens import record_script, save_session
from statelens.storage import JSONSessionStorage

result = record_script("app.py")
save_session(result, JSONSessionStorage("session.json"))

print(f"Recorded {result.metadata.total_events} events")
print(f"Program {'succeeded' if result.succeeded else 'raised an exception'}")

Or trace code you're already running in-process:

from statelens import Tracer, TraceConfig

tracer = Tracer(config=TraceConfig(trace_memory=True))
with tracer.trace():
    my_function()

for event in tracer.events:
    print(event.event_type, event.location)

Replaying a session programmatically

from statelens import load_session, ReplaySession
from statelens.storage import JSONSessionStorage

events, metadata = load_session(JSONSessionStorage("session.json"))
replay = ReplaySession(events)

while not replay.at_end:
    state = replay.state_at_current_position()
    print(state.current_location, state.variables_in_scope())
    replay.step_forward()

The HTML report

statelens report generates a single, self-contained, dependency-free HTML file with:

• An interactive, filterable execution timeline
• A collapsible function call tree with per-call timing
• A variable inspector showing every value a variable held over time
• A memory usage graph
• An execution flow graph sized by time spent per function
• An exception viewer with full tracebacks
• A step-by-step replay view with a scrubber
• Full-text search across functions, variables, and exceptions
• Dark mode and a responsive layout for any screen size

Because everything is inlined into one HTML file, reports can be opened locally, emailed, or archived as CI artifacts with zero setup.

Storage backends

StateLens ships two storage backends behind one interface:

• JSON (default) — human-readable, diffable, great for small-to-medium sessions and version control.
• SQLite — better suited to large sessions (heavy line tracing, long-running programs); pass a .db/.sqlite/.sqlite3 path to --output or SQLiteSessionStorage to use it.

statelens run app.py --output session.db

Plugins

StateLens has an extensible plugin architecture with four extension points: Exporter, Visualization, ReportSection, and EventProcessor. See docs/plugins.md and CONTRIBUTING.md for details on writing your own.

Two exporters ship built in: csv (flat event export) and chrome-trace (open your session directly in chrome://tracing or Perfetto UI).

CLI reference

statelens run SCRIPT [ARGS...]     Record a script's execution
statelens report SESSION           Generate an interactive HTML report
statelens replay SESSION           Step through a session in the terminal
statelens doctor                   Diagnose your environment

Run statelens COMMAND --help for full options on any subcommand.

Documentation

• Tutorial
• API reference
• Examples
• Contributing
• Changelog

Development

git clone https://github.com/statelens/statelens
cd statelens
pip install -e ".[dev]"
pytest
ruff check .
mypy src/statelens

License

MIT — see LICENSE.