# What is Span?

Also called trace span.

A span is a single timed operation inside a trace, such as one model call, one database query, or one tool invocation. It records a start time, a duration, a name, a status, and structured attributes, and it points to its parent span. Spans nested under one another form the tree that makes up a complete trace.

A span has a name, a start timestamp, a duration, a status indicating success or failure, and a set of key and value attributes. It records the identifier of its parent, which is how nesting is reconstructed. Shared naming conventions, such as those published by the OpenTelemetry project, exist so that spans from different libraries can be queried together instead of each service inventing its own vocabulary.

Choosing what deserves a span is a judgment about the smallest useful unit of blame. Anything that can be slow or can fail on its own generally earns one: a model call, a database query, an external API request, a document parse. Attributes then make aggregate questions answerable, for example the duration of every span for one tool, or for one tenant, over a week.

Instrumentation errors are usually one of two extremes. One span per run hides everything inside it, so the trace shows only that something took a while. A span per loop iteration inside a hot path produces enormous volume and cost for little insight. A subtler problem is a span left with a successful status while its operation actually failed, which makes error dashboards understate real failure rates.

Spans are the building blocks that make tracing possible, and they are the natural place to attach the non-timing facts operators need later, including token counts, model configuration, retry counts, and result sizes. Aggregating one span type across many traces is how a per-dependency latency metric is produced without instrumenting that dependency separately.

## Key points

- The smallest unit of work recorded inside a trace.
- Carries name, timing, status, attributes, and a parent reference.
- Attributes let engineers filter runs by tool, model role, or tenant.
- Spans marked successful despite errors hide real failures from dashboards.

## In practice

Inside one agent run, a span named tool.send_email starts at 3.2 seconds, lasts 800 milliseconds, and carries attributes for the recipient domain and the message size. Its parent is the span for the model call that decided to send. When the email provider is slow one morning, filtering all spans with that name across thousands of runs shows the duration climbing hours before any user complains.

## Related terms

- [Tracing](/en/glossary/tracing)
- [Observability](/en/glossary/observability)
- [Latency](/en/glossary/latency)
- [Agent trajectory logging](/en/glossary/agent-trajectory-logging)

[Back to the AI Glossary](/en/glossary)