Coco
Build agents

Tracing

Record runs in memory with CocoTracer, read the latest run, tag runs with a project, and keep payloads out of spans. Nothing leaves the process.

Inspect runs in memory with CocoTracer.

CocoTracer records each run in process memory and never sends anything over the network: no traces, prompts, completions, or metadata.

Prerequisites: The framework and the agent from the Quickstart.


Record a run

Pass a CocoTracer as a callback, then read the root run from latest_run:

from coco_core.tracers.coco import CocoTracer

tracer = CocoTracer(project_name="support-agent-local", tags=["quickstart"])

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Check status of ORD-101"}]},
    config={"configurable": {"thread_id": "trace-thread"}, "callbacks": [tracer]},
)

# Inspect the root Run recorded in memory
latest_run = tracer.latest_run
print("Run ID:", latest_run.id)
print("Run Type:", latest_run.run_type)
print("Start / End:", latest_run.start_time, "->", latest_run.end_time)

It prints the run's ID, its type, chain for an agent, and its start and end times.

The tracer records model, chain, tool and retriever runs, and adds up token usage across model calls. latest_run keeps the last finished root run with its inputs, outputs, events, tags and metadata.

Good to know: tracer.get_run_url() raises CocoTracer keeps runs in memory; there is no run URL. by design.

Turn on tracing for every run

VariableEffect
COCO_TRACING_V2=trueCollects runs with CocoTracer automatically, without passing a callback.
COCO_PROJECTNames the project runs carry. Defaults to default.

To scope tracing to a block of code, use tracing_context from coco_core.tracers._context:

from coco_core.tracers._context import tracing_context

with tracing_context(enabled=True, project_name="support-agent-local", tags=["batch"]):
    agent.invoke({"messages": [{"role": "user", "content": "Check status of ORD-102"}]})

Keep payloads out of spans

To record timing and structure without message or state contents, set a TracePolicy. See Trace payload privacy.


On this page