Lifecycle - Cirron Documentation

Three small helpers that manage the profiler’s runtime. You rarely call any of them directly (atexit invokes shutdown for you on process exit), but they’re useful for tests, manual checkpoints, and health-check endpoints. All three are available both as module-level functions (ci.flush(), ci.health(), ci.shutdown()) and as methods on a Profiler handle.

`flush`

Synchronously drain the scope stack and mark buffer to the local spool.

def flush() -> None

Useful when you want trace data on disk at a known point: typically at a test assertion or before handing off to another tool.

import cirron as ci

ci.profile()
do_work()
ci.flush()            # ./.cirron/spool/ now contains everything so far
inspect_spool()

flush blocks the calling thread until the drain is complete. It does not close the root scope; ci.profile() stays live and continues to accept scopes and marks.

`health`

Snapshot of SDK internals. Never raises; safe to call from an HTTP health check.

def health() -> dict[str, Any]

Returned dict:

Key	Type	What it means
`enabled`	`bool`	`False` if `ci.profile(enabled=False)` was called
`frameworks_installed`	`list[str]`	Which framework hooks are active
`transport`	`str`	`"event_stream"`, `"http"`, or `"file_only"`
`scope_depth`	`int`	Current innermost-scope depth on this thread
`mark_drop_count`	`int`	Marks dropped because the ring buffer was full
`spool_drop_count`	`int`	Spool batch files dropped when the cap was hit
`spool_bytes`	`int`	Current spool disk usage, temp files included
`flush_latency_ns`	`int`	Most recent flush thread wake-to-done duration

Drop counts that climb during a run are a signal to either raise the buffer cap (Cirron(spool_max_bytes=...)) or reduce the rate of ci.mark calls. spool_bytes reports what the cap is enforced against, which counts both sealed *.json batches and unsealed *.json.tmp writes. spool_drop_count covers evicted batch files only: sweeping an orphaned temp file never bumps it, because a temp file is garbage no reader could have consumed rather than data you lost.

`shutdown`

Close the root scope, flush synchronously, stop the flush thread, and clear the default singleton. Idempotent; calling it twice is a no-op.

def shutdown() -> None

Normally invoked by the atexit handler registered during ci.profile(). Call it yourself when:

You’re in a test that wants a clean state between cases.
You’re hot-reloading a module that calls ci.profile().
You want to deterministically release the flush thread and its file handles before a fork().

import cirron as ci

def test_profiler():
    p = ci.profile()
    ...
    ci.shutdown()    # reset so the next test starts clean

Signal handlers

ci.profile() also registers SIGTERM and SIGINT handlers that call shutdown() before the default handler runs, so traces are never lost on a kill or Ctrl-C.

ci.profile

The entry point that starts the lifecycle these manage.

ci.trace

In-process read-back of the scope tree.

Profiler type

The handle exposing the same methods on an instance.

​flush

​health

​shutdown

​Signal handlers

​See also

​Related