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).
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.usage and galtea.span.model. Galtea writes all but galtea.span.usage itself, to record what it changed or recovered, and, for galtea.span.model, the model name it read off the span. Galtea no longer writes galtea.span.usage: the key holds the token counts only on a span stored before spans had their own token fields. 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, with the reported name. Empty when no Model had that name 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. 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 its spans. All eight are read-only, and
null for a user without the evaluation.readInference permission (see Roles and permissions).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.
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.