Acceldata
 AIO
Search documentation… ⌘K

Last updated: Oct 06, 2026 15:41 UTC

Tracing overview

This page explains what a trace is in AIO and how data travels from your AI application to the AIO UI.

What a trace is

A trace records one piece of work your AI application does, such as a chat turn, a workflow run, or a scheduled job. Each trace is made of spans, and AIO groups related traces into sessions.

Term

What it means

Span

One step inside a trace, such as a model call, a tool call, a retrieval, an agent step, a chain step, an MCP call, or an HTTP call.

Trace

Every span that shares one trace ID. A trace's status is error if any of its spans errored.

Root span

The span that starts a trace. Open one for each unit of work, such as a chat turn, a workflow run, or a scheduled job.

Session

Every trace that shares one conversation ID. Traces without a conversation ID don't appear in any session.

Turn

One trace inside a session.

Project

The container that stores your traces. Every trace belongs to one project, and the UI always shows one project at a time.

The UI labels each span with its type. In a trace's waterfall, the legend lists these types: model call, tool, retrieval, agent, chain, mcp, http, and other.

Why it matters

Traces show you what your application actually did. For each span, you can read its input and output, token counts, cost, and any errors. That makes it easier to find slow steps, failed tool calls, and unexpected model output. Rules and evals also run on the same traces, so you can catch problems without reading every trace yourself.

Tracing is built not to stop your application. If the SDK can't start, it logs a message and your app keeps running without telemetry. For the one exception, see Instrument your code.

How it works

Diagram: your application's model, tool, and retrieval calls are recorded by the AIO Python SDK, which you start either from code or with the aio-instrument command. The SDK sends OpenTelemetry spans and prompt logs to AIO. AIO groups spans that share a trace ID into traces, and groups traces that share a conversation ID into sessions. You read traces, sessions, and spans in the AIO UI.

  1. Create a project. AIO stores every trace in a project, so you need one before you send data. For steps, see Create a project.
  2. Add the SDK to your application. Install the acceldata-aio-tracer Python software development kit (SDK). Then call aio.init() once at startup, before you create any HTTP or model clients. You give it your tenant, your project, and the AIO endpoint. To run an existing Python app without changing its code, use the aio-instrument command instead. For steps, see Instrument your code.
  3. Mark each unit of work. Wrap each chat turn, workflow run, or job in with aio.root_span(conversation_id, ...). Every span started inside that block belongs to the same trace. Reuse the same conversation_id across turns, and those traces group into one session. For details, see Track users and sessions.
  4. The SDK sends the data to AIO. While your app runs, the SDK records spans for model calls, tool calls, and other steps, and sends them to AIO as OpenTelemetry data. Prompts and completions travel with them. AIO tags each record with your tenant and project and stores it. Spans usually arrive within seconds.
  5. Open the trace in the UI. Go to your project's Traces list and choose a time range. From there, open a trace to read its span waterfall, or go to Sessions to follow a conversation turn by turn. For details, see Explore traces.

Tip

Already using OpenTelemetry? Send your existing data to AIO instead of adding a second setup. See OpenTelemetry.

To keep sensitive content inside your application, turn on redaction. It runs before any data is sent. See Redaction overview.

Next steps