Concept
The handful of ideas behind Trodo observability: runs, spans, the trace tree, identity, conversations, and the metrics rolled up from them.
Trodo models your agent with two things: runs and spans. Almost everything else (cost, latency, conversations, issues) is built on top of them. Here's the whole model on one page.
The trace tree
One agent execution is a run. Every step inside it (an LLM call, a tool call, a retrieval) is a span. Spans nest under the run and under each other, forming a tree, the trace:
The dashboard renders this as a waterfall: what ran, in what order, how long each step took, and where it failed.
Runs
A run is a single execution of your agent, start to finish. One wrapAgent call produces one run. You set its name, input, and output; everything else is derived from the spans inside it. Each run has a unique run ID you can use to filter traces, attach feedback, or correlate across services.
Spans
A span is one step inside a run. Its kind decides which fields the dashboard shows and which totals it feeds:
| Kind | For | Feeds the run's |
|---|---|---|
llm | Model calls | tokens, cost |
tool | Functions the agent invokes | tool count |
retrieval | Vector search, RAG lookup | — |
agent | A nested sub-step | — |
function | Any other instrumented step | — |
Auto-instrumentation creates llm / tool / retrieval spans for supported frameworks; you add your own with the span helpers.
What's rolled up
You set a few things on the run by hand. Trodo derives the rest by summing the spans, so the numbers always match the trace that explains them:
Tokens
Input and output, summed from every llm span in the run.
Cost
Computed from each span's provider, model, and tokens. See Pricing.
Latency
Total wall-clock time of the run, with per-span durations on the waterfall.
Counts
Span count, tool count, and error count. See Status & errors.
Identity and conversations
Two optional IDs turn a stream of runs into something you can analyze per user and per session.
- Distinct ID is the end user behind a run. Pass it and every run is filterable, attributable in the user timeline, and groupable into cohorts. See Identification.
- Conversation ID ties several runs into one multi-turn session. Pass the same ID across turns and Trodo stacks them:
Run · turn 1
"Where did sales drop last week?"
Run · turn 2
"Break it down by region."
Run · turn 3
"Export the top five."
Same conversationId, one session. Each turn is still its own run, with its own trace. See Conversations.
Next
- Get Started to capture your first run
- Instrumentation Guide for every way to capture runs and spans