Documentation Index
Fetch the complete documentation index at: https://agno-v2-shaloo-ai-support-link.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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
