ci.trace - Cirron Documentation

ci.trace() returns the current session’s scope tree without leaving the Python process. It is the on-demand companion to the continuous output= sinks: a notebook user can call it after a training cell to see the tree inline; a script can call it mid-run to inspect what has happened so far. The data source is a process-wide in-memory buffer that the flush thread populates each tick. ci.trace() performs a best-effort synchronous drain into the buffer before reading, so spans closed between the last tick and the call are visible immediately.

Signature

def trace(
    format: Literal["tree", "dict", "json", "df"] = "tree",
    name: str | None = None,
    last: int | None = None,
) -> _TraceTreeRepr | dict | str | pandas.DataFrame | None

Parameters

Name	Type	Default	Purpose
`format`	`str`	`"tree"`	Output format. One of `"tree"`, `"dict"`, `"json"`, `"df"`.
`name`	`str?`	`None`	Keep only spans whose `name` matches and their descendants.
`last`	`int?`	`None`	Keep only the N most recently closed spans (ranked by `end_ns`).

Formats

Format	Returns	Notes
`"tree"`	`None` (prints) or `_TraceTreeRepr`	In a Jupyter kernel returns a notebook-renderable wrapper; otherwise prints to stdout.
`"dict"`	`{"roots": [...], "span_count": int}`	Nested dict form: each node has `name`, `index`, `wall_us`, `attrs`, `marks`, `children`.
`"json"`	`str`	Same shape as `"dict"`, serialized with `json.dumps`.
`"df"`	`pandas.DataFrame`	Flat: one row per span. Columns: `id`, `parent_id`, `name`, `index`, `wall_us`, `cpu_ns`, `gpu_ns`, `memory_peak_bytes`, `mark_count`, `depth`. Requires `cirron-sdk[pandas]`.

format="df" raises CirronDependencyError when pandas is not installed, with a pip install hint.

Examples

Print the tree in a script

import cirron as ci

ci.profile(output="none")     # purely in-memory; no spool writes
for epoch in ci.epochs(range(3)):
    for batch in ci.batches(loader):
        loss = train_step(batch)
        ci.mark("loss", loss.item())

ci.trace()
# epoch[0] - 142us {epoch_loss=0.5234}
#   batch[0] - 12us {loss=0.6124}
#   batch[1] - 11us {loss=0.5410}
#   ...

Render in a Jupyter cell

ci.trace()       # last expression renders inline; nothing prints to stdout

The Jupyter detection probes IPython.get_ipython() and only treats the ZMQ kernel as a notebook. A plain ipython REPL still prints.

Custom analysis with a DataFrame

df = ci.trace(format="df")
df[df["name"] == "forward"]["wall_us"].quantile([0.5, 0.95, 0.99])

df.groupby("name")["wall_us"].agg(["count", "mean", "max"])

Filter to a single scope name

epochs = ci.trace(format="dict", name="epoch")
# Returns only the epoch subtrees and their children.

Recent spans only

ci.trace(format="dict", last=5)
# The 5 most recently closed spans, ranked by end_ns.

Behavior with no profiler attached

ci.trace() works without a prior ci.profile() call. In that mode it drains the in-memory buffer directly and never writes a spool file as a side effect, so it is safe on read-only filesystems and in notebook inspection contexts.

import cirron as ci

with ci.scope("standalone"):
    ci.mark("x", 1)

ci.trace()    # no profiler, no spool writes, just the tree

When a profiler is active, the synchronous drain routes through ci.flush() so the user’s configured output= sinks still fire (an output="spool" run continues to land batches on disk).

Buffer bounds

The in-memory buffer is bounded:

Spans: keeps the most recent trace_buffer_max_spans (default 100_000).
Marks per span: keeps every kind="summary" mark and the most recent 1024 kind="point" marks. This bound matters for long-lived open spans like cirron.session whose span_id never appears in the span eviction list.

Tune via Cirron:

from cirron import Cirron
c = Cirron(trace_buffer_max_spans=10_000)
c.profile()

output= sinks

Continuous spool / log / stdout streaming as scopes close.

Lifecycle

flush, health, shutdown.

​Signature

​Parameters

​Formats

​Examples

​Print the tree in a script

​Render in a Jupyter cell

​Custom analysis with a DataFrame

​Filter to a single scope name

​Recent spans only

​Behavior with no profiler attached

​Buffer bounds

​Related