Trace & Events

Two views over the same run. Events is what happened. Trace is that laid against time.

Trace

A flame graph of the run's spans — engine calls, tool calls, capsule commands — nested by what spawned what, sized by how long they took.

It answers the question no log answers quickly: where did the time go?

The shape of a run is legible at a glance.

Three flame graphs: a healthy loop of short calls, one enormous engine call, and a staircase of repeating spans

A tight sequence of short calls is a healthy loop. One enormous bar with nothing under it is an agent thinking with no tools. A staircase of near-identical spans is a loop that is not converging.

Events

The full stream, in order, classified by namespace:


`build:`	Resolving and preparing the agent
`kernel:`	The runtime's meter around engine calls, tools, the loop
`cognet:`	The brain narrating itself
`capsule:`	The sandbox — commands, processes, policy
entries	The conversation: stimuli in, output and actions out

The three worth knowing by name:

axon:agent:message — what it actually said. capsule:stdin / capsule:stdout — what it ran, and what came back.

A capsule command and its output in the event stream

capsule:denied — what policy stopped.

A denied capsule action in the event stream

That last one saves the most time. An agent that "ignored" an instruction to edit a file very often tried and was refused — which looks like a reasoning failure in the transcript and a one-line config fix here.

Entry types are documented under Entries.

Working them together

Trace to Events to Engine — find the span, read what happened, see what the model was given

Trace — find the span where it went wrong.
Events — read what happened around it.
Engine — open that call and read what the model was given.

Most investigations end at step two. The ones that do not are context problems, and step three is where those become visible.

Back to Debugging in Code, or on to Managing Agents.