CodeTrace

CodeTrace is a browser-based Python runtime trace explorer. It shows the real path a Python command takes while running: imports, calls, executed lines, returns, output, and exceptions.

The npm package is @codetrace/cli. The command name is ctrace.

Demo

Watch the CodeTrace demo on Bilibili

Watch the CodeTrace demo on YouTube

Install

npm install -g @codetrace/cli

Check the installation:

ctrace doctor

Start

Start the browser service:

ctrace serve

Open:

http://127.0.0.1:3038

ctrace serve starts the web UI. It defaults to 127.0.0.1:3038.

Use another host or port when needed:

ctrace serve -h 0.0.0.0 -p 3038

Add A Repo

In the browser UI, click + in the Projects panel, choose a repo directory, then click Index.

Trace In The Browser

Enter a command in the Runtime Trace input and click Trace Run:

python app.py
/path/to/venv/bin/python app.py
/path/to/venv/bin/some-python-cli --help

The graph streams while the command runs. Click a source node to open the editable source viewer at the matching line.

Trace From A Terminal

Keep ctrace serve running first. Then run:

cd /path/to/repo
ctrace run python app.py

From another directory, specify the repo:

ctrace run -r /path/to/repo python app.py

ctrace run does not start the browser service. It runs the command and sends trace events to the running CodeTrace UI.

Common Commands

ctrace serve
ctrace serve -h 0.0.0.0 -p 3038
ctrace run python app.py
ctrace run -r /path/to/repo python app.py
ctrace doctor

Requirements

• Node.js 20 or newer.
• Python 3.8+ for traced Python programs.
• System python3 for static repo indexing.

Timing

CodeTrace is for understanding runtime workflow, not raw performance. Python tracing hooks add overhead, so measured runtime inside CodeTrace can be much slower than a normal run.