CodeTracer Recorders (Monorepo)

This repository now hosts two related projects:

• codetracer-pure-python-recorder — the existing pure-Python prototype that records CodeTracer traces using sys.settrace.
• codetracer-python-recorder — a new, Rust-backed Python extension module (PyO3) intended to provide a faster and more featureful recorder.

Warning

Both projects are early-stage prototypes. Contributions and discussion are welcome!

codetracer-pure-python-recorder

Install from PyPI:

pip install codetracer-pure-python-recorder

CLI usage:

codetracer-record <path to python file>
# produces several trace json files in the current directory
# or in the folder of `$CODETRACER_DB_TRACE_PATH` if such an env var is defined

During development you can also run it directly:

python src/trace.py <path to python file>
# produces several trace json files in the current directory
# or in the folder of `$CODETRACER_DB_TRACE_PATH` if such an env var is defined

codetracer-python-recorder (Rust-backed)

A separate Python module implemented in Rust with PyO3 and built via maturin lives under: crates/codetracer-python-recorder/

Basic workflow:

• Build/dev install the Rust module:
  • maturin develop -m crates/codetracer-python-recorder/Cargo.toml
• Use in Python:
  • from codetracer_python_recorder import hello
  • hello()

Testing & Coverage

• Run the full split test suite (Rust nextest + Python pytest): just test
• Run only Rust integration/unit tests: just cargo-test
• Run only Python tests (including the pure-Python recorder to guard regressions): just py-test
• Collect coverage artefacts locally (LCOV + Cobertura/JSON): just coverage

The CI workflow mirrors these commands. Pull requests get an automated comment with the latest Rust/Python coverage tables and downloadable artefacts (lcov.info, coverage.xml, coverage.json).

Future directions

The current Python support is an unfinished prototype. We can finish it. In the future, it may be expanded to function in a way to similar to the more complete implementations, e.g. Noir.

Currently it's very similar to our Ruby tracer

Current approach: sys.settrace API

Currently we're using the sys.settrace API: https://docs.python.org/3/library/sys.html#sys.settrace . This is very flexible and can function with probably multiple Python versions out of the box. However, this is limited:

• it's not optimal
• it can't track more detailed info/state, needed for some CodeTracer features(or for more optimal replays).

For other languages, we've used a more deeply integrated approach: patching the interpreter or VM itself (e.g. Noir).

Patching the VM

This can be a good approach for Python as well: it can let us record more precisely subvalues, assignments and subexpressions and to let some CodeTracer features work in a deeper/better way.

One usually needs to add additional logic to places where new opcodes/lines are being ran, and to call entries/exits. Additionally tracking assignments can be a great addition, but it really depends on the interpreter internals.

Filtering

It would be useful to have a way to record in detail only certain periods of the program, or certain functions or modules: we plan on expanding the trace format and CodeTracer' support, so that this is possible. It would let one be able to record interesting parts of even long-running or more heavy programs.

Contributing

We'd be very happy if the community finds this useful, and if anyone wants to:

• Use and test the Python support or CodeTracer.
• Provide feedback and discuss alternative implementation ideas: in the issue tracker, or in our discord.
• Contribute code to enhance the Python support of CodeTracer.
• Provide sponsorship, so we can hire dedicated full-time maintainers for this project.

Legal info

LICENSE: MIT

Copyright (c) 2025 Metacraft Labs Ltd