Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cirron.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
KeyTypeWhat it means
enabledboolFalse if ci.profile(enabled=False) was called
frameworks_installedlist[str]Which framework hooks are active
transportstr"event_stream", "http", or "file_only"
scope_depthintCurrent innermost-scope depth on this thread
mark_drop_countintMarks dropped because the ring buffer was full
spool_drop_countintSpool batch files dropped when the cap was hit
spool_bytesintCurrent spool disk usage
flush_latency_nsintMost 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.

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

​
See also

ci.trace is the read-back companion to flush: it returns the current session’s scope tree as text, dict, JSON, or a DataFrame without leaving the process. It is also exposed as Profiler.trace() and Cirron.trace().

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.