Python API: Trace viewer

A local page that shows your runs, with no account. Generated from the docstrings and type hints of criogenai 0.1.7. See also: Python API overview, the same module in TypeScript.

The local trace viewer: every run on a page, on your own computer.

python -m criogenai.trace                # http://127.0.0.1:4318

from criogenai import Agent, Telemetry
agent = Agent("openai:gpt-5-mini", telemetry=Telemetry.local())

Each run's model calls, tool calls and steps on a time axis, with durations, tokens, cost (from your prices) and failures. Prompts and outputs appear only with Telemetry.local(capture_content=True); nothing leaves the computer either way. It listens on 127.0.0.1 unless given a token.

Command-line options of python -m criogenai.trace: --port (default 4318), --host (default 127.0.0.1), --db FILE, --memory (keep runs in memory only), --keep-runs N, --keep-days N, --prices FILE (a JSON file shaped like serve's prices) and --token-env NAME (the environment variable holding the token, needed off 127.0.0.1).

from criogenai import trace

trace.serve(...)

These are used as trace.<name>.

Contents#

serve#

def serve(
    port: int = 4318,
    *,
    host: str = '127.0.0.1',
    db: Optional[str] = None,
    keep_runs: Optional[int] = None,
    keep_days: Optional[int] = None,
    prices: Optional[Mapping[str, Mapping[str, float]]] = None,
    token: Optional[str] = None,
) -> TraceViewer

Starts the trace viewer in the background and returns once it listens.

It receives traces at /v1/traces (OTLP/HTTP JSON, what Telemetry.local <criogenai.Telemetry.local> sends) and shows the runs at its address.

Parameters

• port (int, default 4318): The port to listen on. Default 4318; 0 picks a free one (read it from viewer.url).
• host (str, default '127.0.0.1'): The address to listen on. Default "127.0.0.1" (this computer only); any other address needs token.
• db (Optional[str], default None): Where runs are kept: a SQLite file, or ":memory:" to keep them in memory only. Default ~/.criogen/traces.db.
• keep_runs (Optional[int], default None): The newest runs kept. Default 10,000.
• keep_days (Optional[int], default None): Days a run is kept. Default 14.
• prices (Optional[Mapping[str, Mapping[str, float]]], default None): USD per million tokens, for the cost column, by "provider:model" or model name, e.g. {"openai:gpt-5-mini": {"input": 0.25, "output": 2.0}}. Without prices, cost is not shown.
• token (Optional[str], default None): Required as Authorization: Bearer <token> by the receiver and the API; needed to listen on an address other than this computer's.

Returns: The running TraceViewer.

Raises

• ValidationError: Another address without a token, a port in use, or unreadable settings (invalid_value).

Example

from criogenai import Agent, FakeModel, Telemetry, trace

async with trace.serve(0, db=":memory:") as viewer:
    telemetry = Telemetry.local(url=viewer.url)
    agent = Agent(FakeModel(["Hi!"]), telemetry=telemetry)
    await agent.run("Hello")
    await telemetry.flush()
    print("open", viewer.url)

TraceViewer#

class TraceViewer:
    def __init__(self, native: Any)

A trace viewer serving in the background; made by serve.

Stop it with stop, or use it with async with.

Parameters

• native (Any): The running server. Internal: use serve.

TraceViewer.url#

url: str

The page's address, e.g. http://127.0.0.1:4318.

TraceViewer.stop#

async def stop() -> None

Stops serving.

main#

def main(argv: Optional[list] = None) -> int

The command line, python -m criogenai.trace: serves until Ctrl+C.

Parameters

• argv (Optional[list], default None): The arguments (default sys.argv[1:]); see the module description for the options.

Returns: The exit code: 0, or 2 when --token-env names a variable that is not set.