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
| Variable | Effect |
|---|---|
COCO_TRACING_V2=true | Collects runs with CocoTracer automatically, without passing a callback. |
COCO_PROJECT | Names 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.
Related Resources
Custom graphs
Build your own workflow with StateGraph, typed state and reducers, edges, and the control flow types Send and Command.
Architecture
The framework's design goals, its four layers, the agent loop, state channels and supersteps, checkpointing, local tracing, where Coco's check attaches, and the decisions behind it.