Metadata-Version: 2.4
Name: trace0
Version: 0.1.0
Summary: A low-overhead tracing profiler for Python, built on sys.monitoring, emitting Perfetto traces.
Author-email: Soof Golan <hi@soofgolan.com>
Requires-Python: >=3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/soof-golan/trace0
Project-URL: Repository, https://github.com/soof-golan/trace0

# trace0

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

`trace0` hooks [PEP 669](https://peps.python.org/pep-0669/) `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](https://ui.perfetto.dev)-compatible traces — open them at
<https://ui.perfetto.dev>.

Roughly **13 ns per traced function call** at 4 threads on an M-series Mac.

## Install

```bash
pip install trace0
```

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

## Use

As a context manager:

```python
from trace0 import Tracer

with Tracer("trace.pb", "protobuf"):
    your_workload()
```

Or from the command line:

```bash
trace0 run --output trace.pb --format protobuf your_script.py
```

Formats are `json` (Chrome Trace Event, human-readable and diffable) and
`protobuf` (Perfetto, smaller and faster to write).

## 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.

## Layout

| crate | role |
| --- | --- |
| `trace0-core` | clock, event model, event queue, exporter contract |
| `trace0-json` | Chrome Trace Event output |
| `trace0-proto` | Perfetto protobuf output |

## License

MIT

