Agno provides convenience functions on your database instance to query traces and spans. These functions work with any supported database (SQLite, PostgreSQL, etc.).
Trace Functions
db.get_trace()
Get a single trace by identifier.
# Get by trace_id
trace = db.get_trace(trace_id="abc123...")
# Get by run_id (returns most recent match)
trace = db.get_trace(run_id=response.run_id)
| Parameter | Type | Description |
|---|
trace_id | Optional[str] | Unique trace identifier |
run_id | Optional[str] | Filter by run ID |
Trace or None
See the reference for Trace for more information.
db.get_traces()
Get multiple traces with filtering and pagination.
# Get recent traces
traces, total_count = db.get_traces(limit=20)
# Filter by agent
traces, count = db.get_traces(agent_id=agent.id)
# Filter by time range
from datetime import datetime, timedelta, timezone
now = datetime.now(timezone.utc)
traces, count = db.get_traces(
start_time=now - timedelta(hours=1),
end_time=now,
limit=100
)
| Parameter | Type | Default | Description |
|---|
run_id | Optional[str] | None | Filter by run ID |
session_id | Optional[str] | None | Filter by session ID |
user_id | Optional[str] | None | Filter by user ID |
agent_id | Optional[str] | None | Filter by agent ID |
team_id | Optional[str] | None | Filter by team ID |
workflow_id | Optional[str] | None | Filter by workflow ID |
status | Optional[str] | None | Filter by status (OK, ERROR, UNSET) |
start_time | Optional[datetime] | None | Filter traces after this time |
end_time | Optional[datetime] | None | Filter traces before this time |
limit | Optional[int] | 20 | Max traces to return |
page | Optional[int] | 1 | Page number for pagination |
tuple[List[Trace], int] - (traces, total_count)
Span Functions
db.get_span()
Get a single span by ID.
span = db.get_span(span_id="xyz789...")
if span:
print(f"{span.name}: {span.duration_ms}ms")
| Parameter | Type | Description |
|---|
span_id | str | Unique span identifier |
Span or None
See the reference for Span for more information.
db.get_spans()
Get multiple spans for a trace or parent.
# Get all spans in a trace
spans = db.get_spans(trace_id=trace.trace_id)
# Get child spans of a specific parent
children = db.get_spans(parent_span_id=root_span.span_id)
| Parameter | Type | Description |
|---|
trace_id | Optional[str] | Filter by trace ID |
parent_span_id | Optional[str] | Filter by parent span ID |
List[Span]
Unlike get_traces(), get_spans() returns a list without a count.
Example: Analyzing a Run
from agno.db.sqlite import SqliteDb
db = SqliteDb(db_file="tmp/traces.db")
# Get trace for a run
trace = db.get_trace(run_id=response.run_id)
if trace:
print(f"Trace: {trace.name} ({trace.duration_ms}ms)")
# Get all spans
spans = db.get_spans(trace_id=trace.trace_id)
# Print execution tree
for span in sorted(spans, key=lambda s: s.start_time):
indent = " " if span.parent_span_id else ""
print(f"{indent}- {span.name} ({span.duration_ms}ms)")
See Also
