bundle.tracy¶

Tracy profiler integration for TheBundle. Provides nanosecond-resolution, real-time profiling of Python code via a pybind11 C++ extension wrapping Tracy v0.13.1.

When the _tracy_ext native extension is built and a Tracy viewer/capture is connected, all instrumented calls are live-profiled across all threads. When the extension is absent, every call is a silent no-op — zero overhead, no code changes needed.

Quick start¶

Build¶

# Build the Python extension + tracy-capture + tracy-csvexport
bundle tracy build

# Build individual components
bundle tracy build extension       # Python pybind11 extension only
bundle tracy build capture         # tracy-capture CLI tool
bundle tracy build csvexport       # tracy-csvexport CLI tool
bundle tracy build profiler        # Tracy viewer GUI (needs GLFW, freetype, capstone)

Usage¶

Manual zones¶

from bundle import tracy

# Context manager
with tracy.zone("load"):
    data = load()

# Decorator (sync or async)
@tracy.zone("process")
async def process(data): ...

Auto-instrument all Python calls¶

import bundle.tracy as tracy

tracy.start()              # install sys.setprofile hook
run_workload()
tracy.stop()               # remove hook, flush pending data

# Filter to bundle code only (skip stdlib/third-party)
tracy.start(bundle_only=True)

Live metrics and annotations¶

tracy.plot("queue_size", len(q))              # numeric plot in viewer
tracy.message("batch complete", color=0x00FF00)  # timeline annotation
tracy.frame_mark()                             # frame boundary marker
tracy.set_thread_name("worker-1")             # name the current thread

Public API¶

Function / Class	Description
`zone(name, color=0)`	Context manager and decorator for manual profiling zones
`start(bundle_only=False)`	Install Tracy as the global Python profiler via `sys.setprofile`
`stop()`	Remove the profiler hook and flush pending data
`frame_mark(name=None)`	Emit a frame boundary marker
`plot(name, value)`	Record a live numeric value as a plot
`message(text, color=0)`	Add a text annotation on the timeline
`set_thread_name(name)`	Name the calling thread in the viewer
`is_connected()`	True when a Tracy viewer is actively connected
`ENABLED`	Boolean — True when the native extension is loaded

Full profiling pipeline¶

The recommended way to run profiling is through the test CLI:

# Profile with Tracy (real-time viewing)
bundle testing python pytest --tracy

# Profile + generate PDF report
bundle testing python pytest --tracy --report

# Custom output directory
bundle testing python pytest --tracy --report --perf-output ./my-perf-dir

This runs the full pipeline automatically:

Starts tracy-capture in the background
Runs the test suite as a subprocess with PERF_MODE=true (Tracy hook active, logs silenced)
Waits for tracy-capture to finish writing when the subprocess exits
Exports the .tracy file to CSV via tracy-csvexport
Generates a PDF report with per-zone charts and cross-version comparison (when --report is used)

Prerequisites: bundle tracy build (builds and installs tracy-capture and tracy-csvexport).

Architecture¶

bundle.tracy/
  __init__.py          # Python API: zone, start/stop, plot, message, etc.
  _fallback.py         # No-op stubs when native extension is unavailable
  cli.py               # `bundle tracy build` CLI commands
  pyproject.toml       # [tool.pybind11] declarative extension config
  setup.py             # Pybind.setup() entry point
  pybind_plugin.py     # PybindPluginSpec for platform-specific flags
  binding/
    _tracy_ext.cpp     # pybind11 C++ extension wrapping Tracy's C API
  vendor/
    tracy/             # Tracy v0.13.1 git submodule

The extension is built via bundle.pybind — the declarative config lives in the tracy-local pyproject.toml and platform-specific flags (TRACY_ENABLE, linker libs) are injected by TracyPlatformPlugin. The extension is not built during pip install thebundle to avoid requiring a C++20 compiler and the Tracy submodule; instead it is built on-demand via bundle tracy build extension.

Dependencies¶

Tracy v0.13.1 (vendored as git submodule)
pybind11 (build-time)
C++20 compiler (MSVC on Windows, GCC/Clang on Linux/macOS)
bundle.pybind.services.cmake (for building native tools via CLI)