Span

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.

Spans are always linked to a trace, 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.

This entity was called Trace before SDK 5.0.0. The name galtea.traces now belongs to the Trace, so span code must move to galtea.spans. See Dataset, Trace, and Span Renames.

Why Use Spans?

Debugging

Identify exactly where and why your agent failed or produced unexpected results.

Performance Optimization

Pinpoint slow operations with latency tracking at every step.

Compliance & Auditing

Maintain a complete audit trail of all operations for regulatory requirements.

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.

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.

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

Use meaningful span names

Choose descriptive names that clearly indicate the operation being traced — e.g., search_documents rather than step_2.

Capture spans at meaningful boundaries

Trace operations that represent logical units of work (tool calls, LLM invocations, retrieval steps), not every single function.

Select appropriate span types

Classify operations correctly (TOOL, GENERATION, RETRIEVER, etc.) to enable better filtering and analysis in the dashboard.

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

Tracing Tutorial

Step-by-step guide to instrumenting your agent and collecting spans.

Span Service

Manage and collect spans for your AI agent operations using the SDK.

Span Properties

Trace

required

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

string

required

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

SpanType

The type of operation: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, or GUARDRAIL.

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.

string

The ID of the parent span for hierarchical relationships.

any

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

any

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

string

Error message if the operation failed.

float

The execution time of the operation in milliseconds.

string

ISO 8601 timestamp when the operation started.

string

ISO 8601 timestamp when the operation completed.

any

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

Concepts overview

How Galtea’s concepts connect — diagram + per-entity quick reference.

Tracing Agent Operations

Step-by-step guide to capturing and analyzing agent spans.

Trace

The traces that spans are linked to.

Introduction

SDK

CLI

Concepts

What is a Span?

Why Use Spans?

Debugging

Performance Optimization

Compliance & Auditing

Cost Analysis

Span Hierarchy

Span Types

Retrieval context in RETRIEVER spans

Best Practices

SDK Integration

Tracing Tutorial

Span Service

Span Properties

Concepts overview

Tracing Agent Operations

Trace

​What is a Span?

​Why Use Spans?

Debugging

Performance Optimization

Compliance & Auditing

Cost Analysis

​Span Hierarchy

​Span Types

​Retrieval context in RETRIEVER spans

​Best Practices

​SDK Integration

Tracing Tutorial

Span Service

​Span Properties

​Related

Concepts overview

Tracing Agent Operations

Trace

What is a Span?

Why Use Spans?

Span Hierarchy

Span Types

Retrieval context in RETRIEVER spans

Best Practices

SDK Integration

Span Properties

Related