Intro to Observability
Understand what Trailsense is, what telemetry it ingests, and how it turns OpenTelemetry traces into readable agent conversations.
Trailsense reads standard OpenTelemetry traces and applies a small number of conventions so those traces can be rendered as readable agent conversations. The examples in these docs use Python with OpenLLMetry, but any OTEL-compatible library can work with Trailsense.
What Data Trailsense Ingests
To integrate with Trailsense, your app needs instrumentation. Instrumentation means sending data to Trailsense about what the agent answered and how it produced that result.
An agent response usually maps to one trace, and one trace includes multiple spans. Each span represents a single unit of work, such as calling a tool, retrieving a document, or invoking an LLM endpoint. Spans and traces also contain attributes which are structured fields that describe what your agent did (think attributes as the fields in JSON).
The structure of these traces and spans is defined by OpenTelemetry. For your agent to produce them, you need instrumentation. Libraries such as OpenLLMetry can do this automatically.
What Are OTEL, Spans, and Traces?
OpenTelemetry
OpenTelemetry, often shortened to OTEL, is a standard for collecting telemetry from software systems. It gives applications a common way to emit traces, metrics, and logs.
Span
A span is one unit of work inside a trace. You can think of it as a timed operation with metadata.
For an agent application, a span might represent:
- one LLM call
- one tool execution
- one orchestration step
- one document retrieval
Each span has a start time, an end time, a span ID, and a set of attributes that describe what happened. Many of these are added automatically by the instrumentation library you use.
Trace
A trace is a tree of related spans that belong to one end-to-end execution. All spans in the same trace share the same trace ID.
In Trailsense, a trace usually represents one agent run or one conversation turn. A trace can have exactly one root span, and its child spans represent the internal work that happened underneath it.
If you want a working example, continue to the Quickstart with OpenLLMetry. If you already emit OTEL traces and want the exact Trailsense conventions, continue to OTEL Additions for Trailsense.