trace0

A low-overhead tracing profiler for Python, written in Rust.

trace0 hooks PEP 669 sys.monitoring, packs each event into 8 bytes in a thread-local buffer, and hands whole batches to a background thread over lock-free SPSC rings. It emits Perfetto-compatible traces — open them at https://ui.perfetto.dev.

How much does it cost?

Across 14 benchmarks from pyperformance, the suite CPython itself is judged on, run unmodified on an M4 Mac:

Median slowdown 1.19×, ranging 1.00× to 1.48×.

slowdown
telco, fannkuch, nbody, scimark 1.00–1.04× arithmetic in tight loops
json_dumps, pyflate, chaos, float, go, spectral_norm 1.12–1.25×
raytrace, hexiom, deltablue, richards 1.36–1.48× call-heavy

The spread is the story: a tracer charges per call, so what a program pays depends entirely on how many calls it makes per unit of work, not on how long it runs. Reproduce with scripts/benchmark.py suite.

Against the alternatives, on a call-dense workload — transpiling SQL with sqlglot, 10.8M events per second of work. Reproduce with scripts/benchmark.py alternatives:

wall time vs vanilla
vanilla 0.97 s —
trace0 (protobuf) 1.16 s 1.20×
trace0 (json) 1.35 s 1.40×
cProfile 2.36 s 2.45×
profile 19.11 s 19.8×

trace0 adds about a seventh of cProfile's overhead and keeps every event, where cProfile only keeps per-function aggregates. That protobuf trace was 197 MB — a full timeline is not free, it is just cheaper in time than in disk. The same run as JSON is an order of magnitude larger.

For the callback in isolation, scripts/benchmark.py overhead reports the difference against the same workload untraced: ~4 ns per event at 8 threads, ~13 ns on a single thread. An event is one PY_START or PY_RETURN, so a function call is two.

Try it

No install — uvx fetches the wheel, traces your script, and leaves nothing behind:

uvx trace0 run --output trace.pb your_script.py

Drop trace.pb onto https://ui.perfetto.dev and you have a flame chart.

The traced script runs inside the tracer's environment, so name what it imports with --with, and the interpreter with --python:

uvx --with httpx --python 3.13t trace0 run --output trace.pb your_script.py

Free-threaded builds (3.13t, 3.14t) are a first-class target — every thread is traced, not just the calling one.

-m runs a library module, exactly as python -m does; everything after the module name belongs to it:

uvx --with uvicorn trace0 run --output trace.pb -m uvicorn app:app --port 8000

A server traced from launch spends most of its trace importing. To trace only the part you care about, wrap it with the Tracer API below instead.

Install

Install it for the Tracer API, which also puts the same CLI on your project's path. Requires Python 3.13+.

uv add trace0

from trace0 import Tracer

with Tracer("trace.pb"):
    your_workload()

Output is Perfetto protobuf by default. --format json, or Tracer(..., format="json"), writes Chrome Trace Event instead — larger and slower to write, but human-readable and diffable.

Child processes

Children are traced too, whether they arrive by fork or by exec, so multiprocessing, subprocess and worker-based servers all show up. They write into the same file as they run, so there is nothing to merge afterwards:

trace0 run --output trace.pb -m uvicorn app:app --workers 4

leaves one trace.pb holding every worker, on a track of its own. Each process buffers whole packets and commits them under a lock, so two processes writing at once never splice into each other, and each namespaces its packet sequences by pid so Perfetto keeps them apart.

JSON traces use the Chrome JSON Array Format for the same reason — entries follow one another with a trailing comma and no closing bracket. That is what lets several processes append to one array, and it means a process killed mid-run still leaves everything up to its last whole entry.

To trace only the process you launched, pass --no-trace-subprocesses, or Tracer(..., trace_subprocesses=False).

Being stopped

A run ended by SIGTERM, SIGHUP or SIGQUIT still writes what it recorded. The default action for those is to end the process outright — nothing unwinds and no atexit runs — so trace0 takes them over while tracing, finishes the run, then lets the signal do what it was going to do, exit status and all.

Signals the program handles itself are left alone: if it installs its own handler, that handler runs and tracing continues. SIGINT is untouched, because Python already turns it into an exception that unwinds. SIGKILL cannot be caught, so a run ended that way still loses whatever the exporter had not yet drained.

Status

Early. The tracer works end to end and is covered by tests, but the API is not yet stable and wheels are not yet built for every platform.

Developing

The benchmarks behind every number above live in one script:

uv run scripts/benchmark.py --help

prek runs the CI checks before a commit lands — formatting and clippy on commit, both test suites on push:

uv tool install prek && prek install --hook-type pre-commit --hook-type pre-push

Layout

Rust lives under crates/, Python under python/.

crate role
trace0-core clock, event model, event queue, exporter contract
trace0-json Chrome Trace Event output
trace0-proto Perfetto protobuf output
trace0-py the sys.monitoring callbacks and the _core extension

Only trace0-py links against CPython, and it is the one crate with no tests: a cdylib built with extension-module leaves the interpreter's symbols undefined, so it cannot link outside maturin. Everything worth testing lives in the other three, which cargo test runs directly.

License

MIT

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for soofgolan from gravatar.com soofgolan

Credits

Author: Soof Golan

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.13

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

trace0-0.1.11.tar.gz (46.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

trace0-0.1.11-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (655.3 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.17+ x86-64

trace0-0.1.11-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (638.5 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.17+ ARM64

trace0-0.1.11-cp314-cp314t-macosx_11_0_arm64.whl (583.5 kB view details)

Uploaded CPython 3.14tmacOS 11.0+ ARM64

trace0-0.1.11-cp314-cp314t-macosx_10_12_x86_64.whl (600.0 kB view details)

Uploaded CPython 3.14tmacOS 10.12+ x86-64

trace0-0.1.11-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (654.3 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

trace0-0.1.11-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (639.0 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ ARM64

trace0-0.1.11-cp314-cp314-macosx_11_0_arm64.whl (585.2 kB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

trace0-0.1.11-cp314-cp314-macosx_10_12_x86_64.whl (600.9 kB view details)

Uploaded CPython 3.14macOS 10.12+ x86-64

trace0-0.1.11-cp313-cp313t-macosx_11_0_arm64.whl (584.8 kB view details)

Uploaded CPython 3.13tmacOS 11.0+ ARM64

trace0-0.1.11-cp313-cp313t-macosx_10_12_x86_64.whl (598.7 kB view details)

Uploaded CPython 3.13tmacOS 10.12+ x86-64

trace0-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (655.0 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

trace0-0.1.11-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (639.9 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64

trace0-0.1.11-cp313-cp313-macosx_11_0_arm64.whl (586.8 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

trace0-0.1.11-cp313-cp313-macosx_10_12_x86_64.whl (601.2 kB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

File details

Details for the file trace0-0.1.11.tar.gz.

File metadata

  • Download URL: trace0-0.1.11.tar.gz
  • Upload date:
  • Size: 46.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for trace0-0.1.11.tar.gz
Algorithm Hash digest
SHA256 3e65c52881107bd35dbe08c000245fa0005eec40311039f6ec8d5d966977ecc1
MD5 00811adcff5191d82999a535733c24f4
BLAKE2b-256 c9d9e282c26903481c549a5384efab51282beb8af7865bc39ee60835dfe10670

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11.tar.gz:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8616a22d5ecaf4533da3c89e934cf0d0f059d105922b5d2731844d90cf5ac2ce
MD5 43816745987e436083c89c0bc2ffa3f7
BLAKE2b-256 7fc8fc08706b1e88aa7d8b0ccc1dc6bd24c479f140738d5a8bd15cffd665769e

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 963fd2510fe28e93bb83d6304232f112d30f84d53759a9cdb4fbc60122448a91
MD5 07aa8eca6c1687eb4519e2f81efc2c5b
BLAKE2b-256 8db034b4d8bf6c56ab90b4744ae2101794fc7436ad34cad3b0b37a68162acc04

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5a3c3b58ed250ea7b0f0fdc7aacfba974b7869c3d80741be11ab12c8dd9aca5f
MD5 cdb649b47bfef8781b237389a3d52ad8
BLAKE2b-256 5fb4a8046011cd9de0f2d7804a3ccc51575704b30c72ba032e27b87c647be740

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314t-macosx_11_0_arm64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314t-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314t-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 17958e21e0208e690d8763fc61fa021a284a0afefeca0bd13f71883891e6e95f
MD5 505845904a68160d190099c438576ed8
BLAKE2b-256 b3d58b8a9a5986b5171db181e1ea25b6667a4f68c3c58c28fd29c095422c1984

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314t-macosx_10_12_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 78d49707ceee71ad5a4da4f2378b4ad9c16885322b04e6b73deb4ffbbc4c0843
MD5 3f1ddb4df450994e7545d9520789ce07
BLAKE2b-256 d8b365bd33630680f1e5281d3315427f2c316d8aa64a09bdf0fdb32f3105022c

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d9c252654306dddfcd81d4548af2d44b9dd5654d602fca30fda66a51719c83f2
MD5 ba986c0a025e7cf6ab10fca4f253779b
BLAKE2b-256 c8bbffc79c7ff619d0c2f0e82120e3101a6e7420831fa17fe82a7438c1366852

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0832c61af11e9ff07889bc66dbed4bc779cb2fe9eeffcaffadad409b8890ebdd
MD5 c5a2c9f32e2173291a51733d1cee20e4
BLAKE2b-256 70bffd2cb0da7cdb215c60afaa5d0c5e423b187a3f89ffa4cacec103dfa6583f

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp314-cp314-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp314-cp314-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 47e6bcf1e3c28451e3ff95d72a11d0cb74815ae9bb0db4c41cb3c90e0c9f7e6b
MD5 aa623ff3da76dca135ae8b06ea8672be
BLAKE2b-256 d0f05ddff31256e3a4660e2914893a8edbd76e326a1074647c75904d5a158ebf

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp314-cp314-macosx_10_12_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp313-cp313t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 243c9c2e714c8fe1e6f0e63d7dbcc360321fb7a53f1054e01bd99257eff2ec78
MD5 d7ed8ed03971a5e6c24ff109dfa3cacb
BLAKE2b-256 6cd03be0ddd7d2d397c2d351c1b2fd5205dcbdb2e774a7867fa0b0f0d3501e55

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp313-cp313t-macosx_11_0_arm64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp313-cp313t-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp313-cp313t-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 74304fec0b7ee2962479b57606dfbb904c05b0539eb28ec878ac6d7af27cf700
MD5 f8d9130305fee36e4d7cd9e9daeea09a
BLAKE2b-256 ff5ff9eb10b859e8580cfd4bc34498fb30aa5cca91686effe60c2a51ec7ea3e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp313-cp313t-macosx_10_12_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6f5d762480c8361dbb2e6faa5ce686d1b552405f458530a8490af60e8b1ac2ec
MD5 ec45aaedd4e089a9ffe4f2c5b8c2baf9
BLAKE2b-256 5670647cfed9349683bdb0ca0f9efc41cfa09a5d5341464ca7ed0c59299fedff

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e02f2b487cffe9625d54349d39ce3804542c73ee3bc4ba61fbeed1daaa060aa1
MD5 0c4e8ec9e4cd560630c879928437f498
BLAKE2b-256 d460c85e6d0a0566b35e953bbd0b0de786095071036181f670da62ec5c33d510

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 30e4f8ad980c9ac936f5e8d8be3826928e3bbdaebda1e2f7c182006eebe7c7fd
MD5 d9f79f396fdfef08828fc885df26820b
BLAKE2b-256 435bd0bc6a477bd1b6bdf7d105a2a6a1e88cf10bf456fca3720d26e9d9585e43

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file trace0-0.1.11-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for trace0-0.1.11-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 43844791f59bfbacdd77a55d0f3060677fe283bcee761a5a6d706d891a17ae66
MD5 dcdf733a8562e0239f0a61f5b8c1e0a4
BLAKE2b-256 cecd467efa148b343871dac110cf2a5eff874a9ee1788324a8e72e6d1708215d

See more details on using hashes here.

Provenance

The following attestation bundles were made for trace0-0.1.11-cp313-cp313-macosx_10_12_x86_64.whl:

Publisher: release.yml on soof-golan/trace0

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page