bundle.tracy
============

.. py:module:: bundle.tracy

.. autoapi-nested-parse::

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

.. toctree::
   :maxdepth: 1

   /autoapi/bundle/tracy/cli/index
   /autoapi/bundle/tracy/pybind_plugin/index
   /autoapi/bundle/tracy/setup/index


Attributes
----------

.. autoapisummary::

   bundle.tracy.ENABLED


Classes
-------

.. autoapisummary::

   bundle.tracy.zone


Functions
---------

.. autoapisummary::

   bundle.tracy.frame_mark
   bundle.tracy.plot
   bundle.tracy.message
   bundle.tracy.set_thread_name
   bundle.tracy.is_connected
   bundle.tracy.start
   bundle.tracy.stop


Package Contents
----------------

.. py:data:: ENABLED
   :value: True


.. py:class:: 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(): ...


.. py:function:: frame_mark(name: str | None = None) -> None

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


.. py:function:: plot(name: str, value: float) -> None

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


.. py:function:: message(text: str, color: int = 0) -> None

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


.. py:function:: set_thread_name(name: str) -> None

   Name the calling thread in the Tracy viewer.


.. py:function:: is_connected() -> bool

   True when a Tracy viewer is actively connected.


.. py:function:: 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).

   :param 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.


.. py:function:: stop() -> None

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