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 | None = None,
        workspace_id: str | None = None,
        output_dir: str | None = None,
        snapshots: Literal["stats", "sampled", "full"] | None = None,
        sample_rate: float | None = None,
        flush_interval: float | None = None,
        spool_max_bytes: int | None = None,
        ingest_path: str | None = None,
        load_warn_bytes: int | None = None,
        load_max_bytes: int | None = None,
        output: str | list[str] | None = None,
        trace_buffer_max_spans: int | None = None,
    ): ...

Every parameter defaults to None. The values below are what the layered resolver produces when you pass nothing, not literal parameter defaults, so passing None explicitly is identical to omitting the argument.

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://api.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
`ingest_path`	`str?`	`"/api/traces"`	Path appended to `api_endpoint` for span ingestion
`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, **attrs) -> None

kind is not a named parameter. It is a reserved key inside **attrs, so c.mark("loss", 0.5, kind="summary") works and defaults to "point" when omitted.

`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, search=None, top_k=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, each carrying its own configuration. 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://api.cirron.com")
custom = Cirron(api_endpoint="https://cirron.internal.example",
              output_dir="./.cirron-custom/")

prod.profile()
custom.profile()

What is per-instance is configuration: api_endpoint, api_key, output_dir, output, and the size thresholds. Those drive transport selection and spool location for whichever instance you call.

Instrumentation state is process-wide, not per-instance. The scope stack, the mark buffer, the ci.trace() ring, and the flush-thread supervisor are module-level singletons shared by every instance. A with b.scope(...) opened inside a with a.scope(...) nests on the same stack, and ci.mark() attaches to whichever scope is innermost regardless of which instance opened it. Use separate instances to point at different backends, not to isolate two concurrent trace trees.

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