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

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

from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="tmp/traces.db")

# Get a trace
trace = db.get_trace(run_id=response.run_id)

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