> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Span

> Track and visualize the internal operations of your AI agent during inference

> [!WARNING]
>
> You are reading the docs of Galtea 5.12. [Read this page in the latest version](https://docs.galtea.ai/concepts/product/version/session/span.md).

## What is a Span?

A span in Galtea represents a single operation or function call that occurs during an AI agent's execution. Spans capture the internal workings of your agent—such as tool calls, retrieval operations, chain orchestrations, and LLM invocations—providing deep visibility into how your agent processes requests.

<video autoPlay muted loop playsInline src="https://mintcdn.com/galtea/dyF29XMGyYjp0rSG/videos/traces-overview.mp4?fit=max&auto=format&n=dyF29XMGyYjp0rSG&q=85&s=f11f230fedc8cdde0dad66c5122a47d7" />

Spans are **always linked to a [trace](https://docs.galtea.ai/v5.12/concepts/product/version/session/trace.md)**, enabling you to understand not just *what* your agent responded, but *how* it arrived at that response. Every span must belong to a specific trace.

Spans can also be ingested directly from OpenTelemetry spans; see [Send OpenTelemetry Traces to Galtea](https://docs.galtea.ai/v5.12/sdk/tutorials/send-opentelemetry-traces-to-galtea.md).

> [!NOTE]
>
> **This entity was called Trace before SDK 5.0.0.** The name `galtea.traces` now belongs to the
> [Trace](https://docs.galtea.ai/v5.12/concepts/product/version/session/trace.md), so span code must move to `galtea.spans`. See
> [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.12/sdk/migration-guides/entity-renames.md).

## Why Use Spans?

> [card] Debugging
>
> Identify exactly where and why your agent failed or produced unexpected results.

> [card] Performance Optimization
>
> Pinpoint slow operations with latency tracking at every step.

> [card] Compliance & Auditing
>
> Maintain a complete audit trail of all operations for regulatory requirements.

> [card] Cost Analysis
>
> Understand which operations consume the most resources.

## Span Hierarchy

Spans support parent-child relationships, allowing you to visualize the complete execution flow of your agent. When a traced function calls another traced function, the hierarchy is automatically captured.

```python theme={"system"}
Agent Call (root)
├─ Route Query (CHAIN)
├─ Retrieve Context (RETRIEVER)
│  └─ Vector Search (TOOL)
├─ Fetch Product Data (TOOL)
└─ Calculate Discount (TOOL)
```

Each span includes:

* **`id`**: Unique identifier for the span
* **`parent_trace_id`**: Reference to the parent span (null for root spans)
* **`name`**: The operation name
* **`type`**: Classification of the operation (SpanType)
* **`description`**: Human-readable description of what the operation does

## Span Types

Spans are classified by type to help you understand the nature of each operation and debug issues more effectively.

| Type | Definition | Why This Matters |
| - | - | - |
| **SPAN** | Generic durations of work in a span. | Default type for general operations that don't fit other categories. Useful for grouping related work. |
| **GENERATION** | AI model generations including prompts, token usage, and costs. | This is where cost (tokens) and latency come from. Clearly see these operations and identify expensive calls and bottlenecks. |
| **EVENT** | Discrete point-in-time events. | Capture important moments without duration, like user interactions or state changes. |
| **AGENT** | Agent that orchestrates flow and uses tools with LLM guidance. | High-level orchestration nodes that coordinate multiple operations and make decisions. |
| **TOOL** | Tool/function calls (e.g., external APIs, calculations). | Deterministic or external calls where inputs, outputs, and side effects determine correctness. |
| **CHAIN** | Links between different application steps. | Composite orchestration nodes that run multiple internal steps and pass data between stages. |
| **RETRIEVER** | Data retrieval steps (vector store, database). | Operations that fetch contextual data which directly affect prompt relevance and the context window. |
| **EVALUATOR** | Functions that assess LLM outputs. | Operations that evaluate quality, safety, or correctness of generated content. |
| **EMBEDDING** | Embedding model calls. | Vector embedding operations for semantic search or similarity. |
| **GUARDRAIL** | Components that protect against malicious content. | Safety checks that filter or validate inputs/outputs. |

Send the type your own system uses. Galtea never drops a span for a type it does not recognize. It normalizes the value to one of the types above, and keeps your original label in the span's `metadata` under the key `galtea.span.original_type`.

Galtea reads the type you sent and never the span name, so a step you called `search_tool` is only a **TOOL** if you typed it as one. The rules, in order:

* A value matching one of the types above is kept as it is, in any capitalization.
* A word for a type Galtea spells differently maps to it: `LLM`, `CHAT_MODEL`, `chat`, `text_completion` and `generate_content` become **GENERATION**, `embeddings` becomes **EMBEDDING**, and `create_agent` and `invoke_agent` become **AGENT**.
* A label that names a handoff or a transfer to an agent becomes **AGENT**.
* A label that ends in `tool` becomes **TOOL**.
* Everything else becomes **SPAN**.

A span you send with no type at all becomes **SPAN** too. The one exception is an OpenTelemetry span, where Galtea falls back to the span kind your own platform declares. See [Send OpenTelemetry traces to Galtea](https://docs.galtea.ai/v5.12/sdk/tutorials/send-opentelemetry-traces-to-galtea.md) for that order.

A span is dropped only when its **data** is invalid, for example an empty name or a negative latency. One dropped span never costs the others sent with it, and the count appears on the [trace](https://docs.galtea.ai/v5.12/concepts/product/version/session/trace.md) so you can see it without reading a log.

### Retrieval context in RETRIEVER spans

If your product uses RAG (retrieval-augmented generation, where the model reads retrieved documents before answering), the convention for recording what was retrieved is a **RETRIEVER** span:

* Put the retrieved data in the span's **output**. This is how Galtea reads retrieval context: it is derived from your `RETRIEVER` spans. It is no longer a stored field on the trace.
* The output has **no required shape**. It is stored as-is, so a plain string, a list of chunks, or any other structure all work.
* One RETRIEVER span per retrieval step is fine. If a trace has several RETRIEVER spans, Galtea joins their outputs in chronological order (by start time).

## Best Practices

> [accordion] Use meaningful span names
>
> Choose descriptive names that clearly indicate the operation being traced — e.g., `search_documents` rather than `step_2`.

> [accordion] Capture spans at meaningful boundaries
>
> Trace operations that represent logical units of work (tool calls, LLM invocations, retrieval steps), not every single function.

> [accordion] Select appropriate span types
>
> Classify operations correctly (TOOL, GENERATION, RETRIEVER, etc.) to enable better filtering and analysis in the dashboard.

> [accordion] Keep input/output data reasonable
>
> The `@traced` decorator captures function arguments automatically. Avoid tracing functions that receive very large inputs (e.g., full documents) — pass summaries or IDs instead.

## SDK Integration

> [card] [Tracing Tutorial](https://docs.galtea.ai/v5.12/sdk/tutorials/tracing-agent-operations.md)
>
> Step-by-step guide to instrumenting your agent and collecting spans.

> [card] [Span Service](https://docs.galtea.ai/v5.12/sdk/api/span/service.md)
>
> Manage and collect spans for your AI agent operations using the SDK.

## Span Properties

**Trace** `Trace` *required*

The trace this span belongs to. Every span must be linked to a trace.

**Name** `string` *required*

The name of the traced operation (e.g., function name).

**Type** `SpanType`

The type of operation: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, or GUARDRAIL. A stored span always carries one of these, because Galtea normalizes any other value you send. See [Span Types](#span-types).

**Description** `string`

A human-readable description of the operation. Can be set manually via `start_span(description=...)` or automatically from function docstrings using `@traced(include_docstring=True)`. Maximum size: 1MB.

**Parent Span ID** `string`

The ID of the parent span for hierarchical relationships.

**Input Data** `any`

The input parameters passed to the operation. Maximum size: 10MB.

**Output Data** `any`

The result returned by the operation. Maximum size: 10MB.

**Error** `string`

Error message if the operation failed.

**Latency (ms)** `float`

The execution time of the operation in milliseconds.

**Start Time** `string`

ISO 8601 timestamp when the operation started.

**End Time** `string`

ISO 8601 timestamp when the operation completed.

**Metadata** `any`

Additional custom metadata about the span. Maximum size: 10MB.

Five keys are reserved for Galtea and removed from anything you send, on every path and without an error: `galtea.synthetic`, `galtea.span.original_name`, `galtea.span.input_from_source_rule`, `galtea.span.output_from_source_rule` and `galtea.span.usage`. Galtea writes them itself, to record what it changed or recovered, and, for `galtea.span.usage`, the [token counts](https://docs.galtea.ai/v5.12/sdk/tutorials/send-opentelemetry-traces-to-galtea.md#token-usage-and-cost) it read off the span. A sixth, `galtea.span.original_type`, is removed from a direct span write and kept on OpenTelemetry ingest, where a replayed export legitimately carries your original label in it.

## Related

> [card] [Concepts overview](https://docs.galtea.ai/v5.12/concepts/overview.md)
>
> How Galtea's concepts connect — diagram + per-entity quick reference.

> [card] [Tracing Agent Operations](https://docs.galtea.ai/v5.12/sdk/tutorials/tracing-agent-operations.md)
>
> Step-by-step guide to capturing and analyzing agent spans.

> [card] [Trace](https://docs.galtea.ai/v5.12/concepts/product/version/session/trace.md)
>
> The traces that spans are linked to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.