Traces

Distributed tracing lets you correlate events across agents and visualize execution flow.

Trace Context

from axonpush import get_or_create_trace

trace = get_or_create_trace()
trace_id = trace.trace_id          # e.g., "tr_a1b2c3d4e5f6g7h8"
span_id = trace.next_span_id()     # e.g., "sp_a1b2c3d4e5f6g7h8_0001"

Use an explicit trace ID:

trace = get_or_create_trace(trace_id="tr_my_custom_trace")

Multi-Step Tracing

from axonpush import AxonPush, EventType, get_or_create_trace

with AxonPush(api_key="ak_...", tenant_id="1", base_url="https://api.axonpush.xyz") as client:
    trace = get_or_create_trace()

    client.events.publish(
        identifier="research.start",
        payload={"goal": "Find papers"},
        channel_id=1,
        agent_id="researcher",
        trace_id=trace.trace_id,
        span_id=trace.next_span_id(),
        event_type=EventType.AGENT_START,
    )

    client.events.publish(
        identifier="web_search",
        payload={"query": "transformer papers 2025"},
        channel_id=1,
        agent_id="researcher",
        trace_id=trace.trace_id,
        span_id=trace.next_span_id(),
        event_type=EventType.AGENT_TOOL_CALL_START,
    )

Listing Traces

traces = client.traces.list(page=1, limit=20)
for t in traces:
    print(t.trace_id, t.event_count, t.duration_ms)

Trace Summary

summary = client.traces.get_summary("tr_abc123")
print(summary.event_count)      # 12
print(summary.duration_ms)      # 340
print(summary.error_count)      # 0
print(summary.agents)           # ["researcher", "writer"]

TraceSummary Fields

Field	Type	Description
trace_id	str	Trace identifier
event_count	int	Total events in trace
agents	list[str]	Unique agent IDs
event_types	list[str]	Unique event types
start_time	datetime	First event timestamp
end_time	datetime	Last event timestamp
duration_ms	int	Duration in milliseconds
error_count	int	Number of error events
tool_call_count	int	Number of tool call events
handoff_count	int	Number of handoff events

Trace Events

events = client.traces.get_events("tr_abc123")
for event in events:
    print(event.span_id, event.identifier, event.event_type)