Trace Execution
trace_executionTrace Python line by line to debug why a program behaved as it did for a specific input: see statement order, changed variable values, branch hits, and lines never executed.
Instructions
Debug WHY, line by line, for the ONE input you actually ran it on: which statements fired, in what order, with what variable values at each step, and which if/elif/while/for/try branch was taken versus never taken. Want just the printed output instead? Use execute_code.
Returns events: ordered {step, line, event, func, locals}, one entry
per traced line/call/return/exception in YOUR code only (library
internals excluded). locals on each entry is only the names that
changed since the previous step in that same call — not a full dump
every line. A return entry also carries return_value; an
exception entry carries exception_type/exception_message.
Also returns branches (hit count per if/elif/while/for/try line),
lines_executed / lines_never_executed (coverage from a static parse),
and truncated/truncated_reason when max_events or an internal
size ceiling stopped RECORDING early (the underlying stdout/exit code
are unaffected either way). truncated_reason is also
"event_detail_over_cap" when one event's OWN detail (e.g. a call with
more than 200 changed locals) was too large to admit — that ONE event is
still present in events, as a bounded stub (locals: {},
detail_dropped: true), so its real step/line/func still count
toward lines_executed/branches exactly like any other event; only
its own detail, never the rest of the trace, was dropped.
TRUST: the trace is produced BY the traced program at its OWN privilege
— a debugging aid, not an attestation of behaviour, exactly as
trustworthy as that program's own stdout. discarded_events /
events_consistent are a best-effort tamper/corruption signal (never a
guarantee) computed independently of the file's own content —
events_consistent requires discarded_events == 0 among its
conditions, since an honest run never produces one.
unenforced may additionally note "only the main thread is traced"
(sys.settrace is per-thread) or, fallback backend only, an OLE
exit_code race.
For a structural Big-O guess with nothing executed, use analyze_complexity.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Source code to trace line by line | |
| stdin | No | Text piped to the program's standard input; empty means no input | |
| no_net | No | Block outbound network access for this run; best-effort on platforms without seccomp | |
| max_cpu | No | Per-call CPU-time ceiling in seconds; 0 means no explicit limit is set | |
| timeout | No | Wall-clock seconds before the run is killed; clamped to a 120s ceiling | |
| language | Yes | Runtime to trace; only 'python3' is supported, any other value is refused | |
| provider | No | Execution backend id; only 'local' (the default) is supported here | |
| max_events | No | Max trace events to record before truncating; the run's own stdout/exit code are unaffected | |
| max_memory_mb | No | Per-call memory ceiling in MiB; 0 means no explicit limit is set | |
| max_output_kb | No | Stdout/stderr capture cap in KiB per stream; 0 uses the 64 KiB default, hard-clamped to 240 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||