Record the boundary. Replay the Python.

Why rerunning can change the answer

Python code may call an API, read a file or database, ask the clock for a time, draw a random value, or run alongside another thread. A later run can encounter different results or ordering. Even if the source code is unchanged, the state behind an unexpected outcome may no longer be present.

Logs and distributed traces help locate many failures, but they generally contain only the fields and events instrumented in advance. Retrace addresses a different question: what did this supported Python execution do, given the outside-world results it received at the time?

The record-to-replay path

Python command
    → supported external boundary calls are recorded
    → .retrace artifact retains results and ordering
    → same Python code runs again against recorded results
    → debugger inspects frames, variables and control flow

1. Record before the question arrives. Launch a supported Python command with Retrace enabled. The recorder observes configured boundaries, executes those calls during the original run, and writes their results and relevant ordering to a .retrace artifact.
2. Retain the recording and its context. Keep the artifact, source, Python version and required environment available. A completed run cannot be reconstructed retroactively if it was not recorded.
3. Replay the Python code. The replay path runs the code again. At recorded boundaries, it returns captured results instead of contacting the live outside world. A mismatch or unsupported boundary can cause replay to fail or diverge; it should not be treated as proof of a successful reconstruction.
4. Investigate in a debugger. In the documented VS Code workflow, engineers can stop at breakpoints, inspect stack frames and variables, and step through the recorded run, including backwards stepping. The debugger follows the replay rather than triggering a fresh live execution.

This walkthrough reflects the public architecture description and the pytest quickstart. The implementation records configured boundary crossings, not every machine instruction or the internal state of remote services.

A concrete example: a failed test

The Python CI walkthrough records a checkout test that fails after a calculation uses values in the wrong order. Its .retrace artifact retains the execution needed for the supported replay. A fresh pytest run can produce new time, UUID or random values; the replay uses the values captured in the failing run. The engineer can then inspect the Python state around the calculation rather than guessing from the final assertion alone.

Where the boundary is

Retrace’s public documentation describes configured handling for network, filesystem, time, randomness, subprocess and other nondeterministic operations. Coverage is specific to the runtime, libraries and operations actually supported. The compatibility notes list tested areas and current caveats, including experimental threading support. A library appearing there is not a guarantee that every API or production configuration works.

Replay can show Python state and control flow that followed a recorded external result. It cannot expose an LLM’s hidden reasoning, recover opaque state inside a remote API, reconstruct an unrecorded incident, or automatically provide complete value-level provenance. Provenance—tracing precisely where every value came from—is a separate capability and should be evaluated independently.

The recording may contain sensitive application data. Decide what to record, where the artifact is retained, who can access it and when it is deleted before applying the workflow to real customer data. Pilot data-handling questions are addressed separately.

For two illustrative applications of this model, see how a previously recorded run could help investigate an unexpected Python agent action or historical calculation. Each workflow needs its own boundary and compatibility check.

To try the current workflow, start with the documented Python quickstart, or bring a specific investigation to Retrace.