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.id: Unique identifier for the spanparent_trace_id: Reference to the parent span (null for root spans)name: The operation nametype: 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,completionandgenerate_contentbecome GENERATION,embeddingsbecomes EMBEDDING,create_agentandinvoke_agentbecome AGENT, and OpenLLMetry’sworkflowandtaskbecome CHAIN. - A label that names a handoff or a transfer to an agent becomes AGENT.
- A label that ends in
toolbecomes TOOL. - Everything else becomes SPAN.
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
RETRIEVERspans. 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
contentlist 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
Use meaningful span names
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
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
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
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
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.
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.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.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.
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.
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).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.
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.
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.
Related
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.