Trace
Trace attributes, methods, and how to query stored traces from the database.
A Trace represents one complete agent execution from start to finish. Each trace has a unique trace_id that groups all related spans together.
Trace Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
trace_id | str | Required | Unique trace identifier |
name | str | Required | Trace name (typically the root span name, e.g., Agent.run) |
status | str | Required | Overall status: OK, ERROR, or UNSET |
duration_ms | int | Required | Total execution time in milliseconds |
start_time | datetime | Required | When the trace started |
end_time | datetime | Required | When the trace completed |
total_spans | int | Required | Total number of spans in this trace |
error_count | int | Required | Number of spans that errored |
run_id | Optional[str] | Required | Associated agent/team/workflow run ID (None when not set) |
session_id | Optional[str] | Required | Associated session ID (None when not set) |
user_id | Optional[str] | Required | Associated user ID (None when not set) |
agent_id | Optional[str] | Required | Associated agent ID (None when not set) |
team_id | Optional[str] | Required | Associated team ID (None when not set) |
workflow_id | Optional[str] | Required | Associated workflow ID (None when not set) |
created_at | datetime | Required | When the trace record was created |
Methods
The following method snippets assume an existing trace object or its serialized data. Import the type with from agno.tracing.schemas import Trace.
to_dict()
Convert the trace to a dictionary.
trace_dict = trace.to_dict()Returns: dict
from_dict()
Create a trace from a dictionary.
trace = Trace.from_dict(data)Parameters:
data(dict): Dictionary containing trace data
Returns: Trace
Usage
First follow the tracing setup, including its OpenTelemetry and instrumentation dependencies, to record a run in tmp/traces.db. Run this query from the same working directory after spans have been exported. Creating SqliteDb alone does not enable instrumentation or populate traces. For a separate query environment, install uv pip install -U agno sqlalchemy opentelemetry-sdk.
from agno.db.sqlite import SqliteDb
db = SqliteDb(db_file="tmp/traces.db")
# Read a stored trace from the populated database
traces, _ = db.get_traces(limit=1)
trace = traces[0] if traces else None
if trace:
print(f"Trace ID: {trace.trace_id}")
print(f"Name: {trace.name}")
print(f"Duration: {trace.duration_ms}ms")
print(f"Status: {trace.status}")
print(f"Total Spans: {trace.total_spans}")
print(f"Errors: {trace.error_count}")See Also
- Span Reference - Individual operations within a trace
- DB Functions - Query functions for traces and spans