Cirron - Cirron Documentation

Module-level functions (ci.profile(), ci.load(), ci.mark(), …) are sugar over a process-wide default Cirron instance. Instantiate the class directly when you need a self-hosted endpoint, a custom spool directory, multi-workspace routing, or an isolated instance for tests.

from cirron import Cirron

Constructor

class Cirron:
    def __init__(
        self,
        api_key: str | None = None,
        api_endpoint: str = "https://app.cirron.com",
        workspace_id: str | None = None,
        output_dir: str = "./.cirron/",
        snapshots: Literal["stats", "sampled", "full"] = "stats",
        sample_rate: float = 0.01,
        flush_interval: float = 1.0,
        spool_max_bytes: int = 1_000_000_000,
        load_warn_bytes: int = 1_000_000_000,
        load_max_bytes: int = 10_000_000_000,
        output: str | list[str] | None = None,
        trace_buffer_max_spans: int | None = None,
    ): ...

Parameters

Name	Type	Default	Purpose
`api_key`	`str?`	`None` (falls back to env)	Workspace API key; normally read from `CIRRON_API_KEY`
`api_endpoint`	`str`	`"https://app.cirron.com"`	Control-plane base URL; point at a self-hosted install
`workspace_id`	`str?`	`None` (falls back to env)	Target workspace; normally read from `CIRRON_WORKSPACE_ID`
`output_dir`	`str`	`"./.cirron/"`	Local spool + snapshots root
`snapshots`	`str`	`"stats"`	Snapshot mode; see `ci.profile`
`sample_rate`	`float`	`0.01`	Fraction of epochs to sample in `"sampled"` mode
`flush_interval`	`float`	`1.0`	Flush-thread wake interval (seconds)
`spool_max_bytes`	`int`	`1_000_000_000` (1 GB)	Oldest batch files evicted when the spool exceeds this
`load_warn_bytes`	`int`	`1_000_000_000` (1 GB)	`ci.load()` logs a WARNING at or above this size
`load_max_bytes`	`int`	`10_000_000_000` (10 GB)	`ci.load()` raises `CirronDataSizeError` at or above this
`output`	`str` or `list[str]?`	`None` (= `"spool"`)	Default `output=` for `profile()` calls on this instance
`trace_buffer_max_spans`	`int?`	`None` (= `100_000`)	Cap on retained spans in the in-memory `ci.trace()` buffer

Config resolution order: explicit argument → CIRRON_* env var → ~/.cirron/config.toml → default.

Methods

Every method mirrors its module-level counterpart; the module-level function just calls get_default().method(...). Linked pages are the source of truth for each method.

Method	See
`profile`	`ci.profile`
`scope`	`ci.scope`
`mark`	`ci.mark`
`epochs` / `batches`	Loop wrappers
`trace`	`ci.trace`
`load`	`ci.load`
`inference`	`ci.inference`
`wrap`	`ci.wrap`
`env`	`ci.env`
`secret`	`ci.secret`

ci.watch, ci.flush, ci.health, and ci.shutdown are module-level only: they operate on the active profiler singleton rather than on a Cirron instance. Use them as cirron.watch(model) / cirron.flush() etc. even when you’ve built an explicit Cirron instance.

`profile`

c.profile(config=None, frameworks=None, snapshots=None,
          sample_rate=None, flush_interval=None, enabled=True,
          path=None, output=None) -> Profiler

`scope`

with c.scope(name, index=None, **attrs) as s:
    ...

`mark`

c.mark(name, value, *, kind="point", **attrs) -> None

`epochs` / `batches`

for epoch in c.epochs(range(20)):
    for batch in c.batches(loader):
        ...

`trace`

c.trace(format="tree", name=None, last=None) -> Any

Read back the current session’s scope tree. See ci.trace for the full surface.

`load`

c.load(name, *, source="local", match=None, ext=None, columns=None,
       map=None, where=None, as_="pandas", lazy=False,
       batch_size=10_000, confirm_large=False) -> Any

`inference`

@c.inference(config=...)
def predict(request):
    ...

`wrap`

wrapped = c.wrap(estimator)

`env`

value = c.env(key, default=None)

`secret`

value = c.secret(name)

`get_default()`

from cirron import get_default

c = get_default()    # the process-wide singleton module-level ci.* uses

Returns the lazy-initialized default Cirron instance. Rarely needed directly; reach for it only when you want to inspect or mutate the instance that the module-level functions are delegating to.

Multi-instance use

Independent Cirron instances coexist in one process without interfering. Useful for self-hosted-plus-cloud comparisons, for driving two workspaces from one script, or for test harnesses.

from cirron import Cirron

prod = Cirron(api_endpoint="https://app.cirron.com")
custom = Cirron(api_endpoint="https://cirron.internal.example",
              output_dir="./.cirron-custom/")

prod.profile()
custom.profile()

Each instance has its own scope stack, mark buffer, spool directory, and flush thread. Nothing is shared.

Configuration guide

Narrative walk-through of env vars, config.toml, and credential resolution.

Core concepts

Scope tree, marks, transport, overhead.

​Constructor

​Parameters

​Methods

​profile

​scope

​mark

​epochs / batches

​trace

​load

​inference

​wrap

​env

​secret

​get_default()

​Multi-instance use

​Related

Configuration guide

Core concepts

Constructor

Parameters

Methods

`profile`

`scope`

`mark`

`epochs` / `batches`

`trace`

`load`

`inference`

`wrap`

`env`

`secret`

`get_default()`

Multi-instance use

Related