> ## 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.
# Trace
> Track and visualize the internal operations of your AI agent during inference
## What is a Trace?
A trace in Galtea represents a single operation or function call that occurs during an AI agent's execution. Traces 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.
Traces are **always linked to an [inference result](/concepts/product/version/session/inference-result)**, enabling you to understand not just *what* your agent responded, but *how* it arrived at that response. Every trace must belong to a specific inference result.
Traces can also be ingested from OpenTelemetry spans; see [Send OpenTelemetry Traces to Galtea](/sdk/tutorials/send-opentelemetry-traces-to-galtea).
## Why Use Traces?
Identify exactly where and why your agent failed or produced unexpected results.
Pinpoint slow operations with latency tracking at every step.
Maintain a complete audit trail of all operations for regulatory requirements.
Understand which operations consume the most resources.
## Trace Hierarchy
Traces 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 trace includes:
* **`id`**: Unique identifier for the trace
* **`parent_trace_id`**: Reference to the parent trace (null for root traces)
* **`name`**: The operation name
* **`type`**: Classification of the operation (TraceType)
* **`description`**: Human-readable description of what the operation does
## Trace Types
Traces are classified by type to help you understand the nature of each operation and debug issues more effectively.
| Type | Definition | Why This Matters for Tracing |
| -------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **SPAN** | Generic durations of work in a trace. | 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 traces
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** trace:
* Put the retrieved data in the trace's **output**. This is how Galtea reads retrieval context: it is derived from your `RETRIEVER` trace spans. It is no longer a stored field on the inference result.
* 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 trace per retrieval step is fine. If an inference result has several RETRIEVER traces, Galtea joins their outputs in chronological order (by start time).
## 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 `@trace` decorator captures function arguments automatically. Avoid tracing functions that receive very large inputs (e.g., full documents) — pass summaries or IDs instead.
## SDK Integration
Step-by-step guide to instrumenting your agent and collecting traces.
Manage and collect traces for your AI agent operations using the SDK.
## Trace Properties
The inference result this trace belongs to. Every trace must be linked to an inference result.
The name of the traced operation (e.g., function name).
The type of operation: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, or GUARDRAIL.
A human-readable description of the operation. Can be set manually via `start_trace(description=...)` or automatically from function docstrings using `@trace(include_docstring=True)`. Maximum size: 1MB.
The ID of the parent trace for hierarchical relationships.
The input parameters passed to the operation. Maximum size: 10MB.
The result returned by the operation. Maximum size: 10MB.
Error message if the operation failed.
The execution time of the operation in milliseconds.
ISO 8601 timestamp when the operation started.
ISO 8601 timestamp when the operation completed.
Additional custom metadata about the trace. Maximum size: 10MB.
## Related
How Galtea's concepts connect — diagram + per-entity quick reference.
Step-by-step guide to capturing and analyzing agent traces.
The inference results that traces are linked to.