Skip to main content
You are reading the docs of Galtea 5.17. Read this page in the latest version.

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.
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. 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, completion and generate_content become GENERATION, embeddings becomes EMBEDDING, create_agent and invoke_agent become AGENT, and OpenLLMetry’s workflow and task become CHAIN.
  • 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 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 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).
  • A Galtea file in the content list of a span of any type reads as [File N] in its place. On deployments that send files to the judge, the judge also receives the file itself. Most deployments do not send files to the judge yet. Galtea numbers span files after every file of the session’s turns.

Best Practices

Choose descriptive names that clearly indicate the operation being traced — e.g., search_documents rather than step_2.
Trace operations that represent logical units of work (tool calls, LLM invocations, retrieval steps), not every single function.
Classify operations correctly (TOOL, GENERATION, RETRIEVER, etc.) to enable better filtering and analysis in the dashboard.
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. A stored span always carries one of these, because Galtea normalizes any other value you send. See Span Types.
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.Six 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, galtea.span.model and galtea.span.cache_read_above_input. Galtea writes them itself, to record what it changed or recovered, for galtea.span.model, the model name it read off the span, and for galtea.span.cache_read_above_input, that the span reported more cached tokens than input tokens. A seventh, 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.
string
The model the LLM call ran on, as the span reported it. Galtea sets it for spans it ingests through OpenTelemetry and for Langfuse file imports. Spans you create with the SDK or the span endpoints do not have it. See Model. Read-only.
string
The Model the span is linked to: a Model of your organization, or a global one, that has one of the span’s model names. A name also matches without its provider prefix, and the first name that matches wins. Empty when no Model had any of them when the span was stored. Deleting the Model keeps the link, so it can name a deleted Model. Read-only.
int
Input tokens this LLM call reported, cached input included. Galtea sets this and the seven fields below when it stores the span; see Token usage and cost. The counts and cost of a trace are the sums over the spans it counts. A call counts once for each side, input and output, from the deepest span that reports it, and a span that loses one side to a span below is priced again for the side it keeps. All eight are read-only, and null for a user without the evaluation.readInference permission (see Roles and permissions).
int
Output tokens this LLM call reported.
int
Input tokens this LLM call read from the model cache, a part of Input Tokens. A count above Input Tokens means the source counted the cache apart. The cached tokens are priced at the Model’s cache-read price, or its input price when it has none.
int
The input plus the output, plus the cache read when the source counted it apart from the input.
float
The input price the call was charged at. Galtea prices the call when it stores the span, at the Model that answered it, and keeps that price if the Model price changes later. A span that names no model is priced at the Model linked to the Version. A span whose model has no price in your organization has no prices and no cost.
float
The output price the call was charged at.
float
The price of a cached input token the call was charged at.
float
The cost of this LLM call: the input without the cached tokens at the input price, the cached tokens at the cache-read price, and the output at the output price. See the formula in Token usage and cost.

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.