Docs/Aigovernance/Airesilient/Tracing

Distributed Tracing

A trace records one request through your agent: every retrieval, tool call and LLM generation as a nested observation with start and end time, input, output, usage, cost and level. Traces are the base for every latency, error and cost view in ANTS Platform.

ℹ

View traces under Discover AI → Tracing and grouped conversations under Discover AI → Sessions. For setup in each language see Python SDK, JS/TS SDK and Java SDK.

Creating traces

With the Python SDK, nested context managers become nested observations. Errors raised inside a context manager are recorded on that observation.

python

from ants_platform import get_client client = get_client() question = "Where is my order?" with client.start_as_current_span(name="customer-support-agent") as root: root.update_trace(user_id="user-123", session_id="session-abc", input=question) with client.start_as_current_span(name="retrieve-context") as retrieval: documents = ["Order 1042 ships tomorrow."] retrieval.update(output=documents) with client.start_as_current_generation( name="llm-inference", model="gpt-4o-mini", input=[{"role": "user", "content": question}], ) as generation: answer = "Your order ships tomorrow." generation.update(output=answer, usage_details={"input": 120, "output": 9}) root.update_trace(output=answer) client.flush()

To mark a handled failure, set the level and a status message on the observation:

python

generation.update(level="ERROR", status_message="Provider timeout after 30s")

Traffic sent through Budget AI is traced automatically, with routing details for each attempt. OpenTelemetry spans can be sent to the platform's OTLP endpoint. See Sending Data In.

Reading a trace

Open a trace in Discover AI → Tracing to see:

The tree of observations with the duration of each step, so the slowest step stands out.
Input, output, metadata, model, usage and cost for each generation.
Level and status message for each observation. Filter the trace list by Level to find traces that contain errors.
A graph view of the agent's steps. See Trace Graphs.

text

customer-support-agent 2.5s ├─ retrieve-context 200ms └─ llm-inference 2.0s ERROR Provider timeout after 30s

Traces can also be fetched with the public API, GET /api/public/traces/{traceId}. See the API Reference.

Next steps

Metrics & Monitoring: latency percentiles and error views built from traces.
Traces: the full guide to the Tracing view.