bundle.tracy

bundle.tracy — Tracy profiler integration for TheBundle.

When the _tracy_ext native extension is built and a Tracy viewer is connected, all calls are live-profiled at nanosecond resolution across all threads. When the extension is absent, every call is a silent no-op.

Usage

Manual zones:

from bundle import tracy

with tracy.zone("load"):
    data = load()

@tracy.zone("process")
async def process(data): ...

Auto-instrument all Python calls:

tracy.start()
run_workload()
tracy.stop()

Live metrics and annotations:

tracy.plot("queue_size", len(q))
tracy.message("batch complete", color=0x00FF00)
tracy.frame_mark()

Submodules

• bundle.tracy.cli
• bundle.tracy.pybind_plugin
• bundle.tracy.setup

Attributes

ENABLED

Classes

zone	Tracy profiling zone — use as a context manager or decorator.

Functions

frame_mark(→ None)	Emit a frame boundary marker. Optionally named for multi-frame workflows.
plot(→ None)	Record a live numeric value visible as a plot in the Tracy viewer.
message(→ None)	Add a text annotation on the Tracy timeline. color is ARGB (0 = default).
set_thread_name(→ None)	Name the calling thread in the Tracy viewer.
is_connected(→ bool)	True when a Tracy viewer is actively connected.
start(→ None)	Install Tracy as the global Python profiler.
stop(→ None)	Remove the Tracy profiler hook and flush all pending data to tracy-capture.

Package Contents

bundle.tracy.ENABLED = True

class bundle.tracy.zone(name: str, color: int = 0)

Tracy profiling zone — use as a context manager or decorator.

As a context manager:

with tracy.zone("my_zone"):
    ...

As a decorator (sync or async):

@tracy.zone("my_func")
def my_func(): ...

@tracy.zone("my_coro")
async def my_coro(): ...

bundle.tracy.frame_mark(name: str | None = None) → None

Emit a frame boundary marker. Optionally named for multi-frame workflows.

bundle.tracy.plot(name: str, value: float) → None

Record a live numeric value visible as a plot in the Tracy viewer.

bundle.tracy.message(text: str, color: int = 0) → None

Add a text annotation on the Tracy timeline. color is ARGB (0 = default).

bundle.tracy.set_thread_name(name: str) → None

Name the calling thread in the Tracy viewer.

bundle.tracy.is_connected() → bool

True when a Tracy viewer is actively connected.

bundle.tracy.start(bundle_only: bool = False) → None

Install Tracy as the global Python profiler.

Every Python function call and return will open/close a Tracy zone, giving a full call-stack timeline across all threads with zero manual annotation. Overhead is ~255 ns/call (Python profiler API) + ~18 ns (Tracy zone).

Parameters:

bundle_only – When True, only profile frames whose source file lives inside the bundle package, skipping stdlib and third-party libraries. Greatly reduces noise in the Tracy viewer.

bundle.tracy.stop() → None

Remove the Tracy profiler hook and flush all pending data to tracy-capture.