Skip to main content
Every time your agent runs, Veritrix records the entire execution as a trace — a complete, ordered record of every decision, tool call, and handoff from the moment the agent starts to the moment it finishes. Within that trace, each discrete unit of work is captured as a span. Together, traces and spans give you an exact replay of what your agent did, how long each step took, how many tokens it consumed, and whether anything went wrong.

​
What Is a Trace?

A trace represents one end-to-end agent run. It starts when your agent receives its first input and ends when it returns a final response or errors out. If your agent delegates work to sub-agents, their execution is nested inside the same trace — so you always have a single, unified view of the entire chain. Every trace carries the following metadata:

​
What Is a Span?

A span is a single unit of work inside a trace. One LLM call is a span. One tool invocation is a span. One handoff to a sub-agent is a span. Spans are the atoms Veritrix uses to build the full picture of your agent’s behaviour. Each span records what happened, how long it took, and whether it succeeded or failed. When spans are nested — for example, a tool call that happens inside an LLM planning step — Veritrix preserves the parent-child relationship so you can navigate the exact execution path in the dashboard.

​
Span Types

Veritrix recognises four built-in span types, each mapped to a distinct category of agent work:

​
Span Payload

Every span carries a structured payload. Here is a representative example from a planning step:
The fields you will see on every span are:
input_tokens and output_tokens are only present on llm.call and llm.retry spans. tool.exec and agent.handoff spans omit these fields.

​
Getting Started

To start capturing traces and spans, install the SDK and initialise it with your agent name:
After calling trace.init, Veritrix automatically instruments your agent. Every LLM call, tool execution, and handoff is recorded without any additional code changes.
Pass a descriptive name to trace.init — it becomes the root label in the Veritrix dashboard and appears on shareable trace links, so your team can immediately identify which agent a trace belongs to.
1

Open the Traces view

In the left sidebar, click Traces. You will see a paginated list of recent runs sorted by start time, with at-a-glance columns for duration, span count, total tokens, and cost.
2

Select a trace

Click any row to open the trace detail view. The top panel shows trace-level metadata — trace_id, total duration, token counts, and cost. The bottom panel renders the full span waterfall.
3

Inspect individual spans

Click any span in the waterfall to expand its payload. You will see the raw input and output, token counts, duration, status, and — for failed spans — the error message that triggered the failure.
4

Filter by span type or status

Use the filter bar above the waterfall to narrow spans by type (llm.call, tool.exec, etc.) or by status (ok / fail). This is particularly useful in long traces with hundreds of spans.
5

Share the trace

Every trace has a permalink. Click Copy link in the top-right corner to share the full trace with a teammate, attach it to a bug report, or include it in a compliance review.

Agents & Handoffs

Learn how multi-agent chains are represented as nested spans inside a single trace.

Root-Cause Summaries

See how Veritrix turns failed traces into plain-language explanations of what went wrong.