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, 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.

Why Use Traces?

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.

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.

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

Use meaningful trace names

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

Trace at meaningful boundaries

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

Select appropriate trace types

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

Keep input/output data reasonable

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

Tracing Tutorial

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

Trace Service

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

Trace Properties

Inference Result · InferenceResult · required

The inference result this trace belongs to. Every trace must be linked to an inference result.

Name · string · required

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

Type · TraceType

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

Description · string

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.

Parent Trace ID · string

The ID of the parent trace for hierarchical relationships.

Input Data · any

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

Output Data · any

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

Error · string

Error message if the operation failed.

Latency (ms) · float

The execution time of the operation in milliseconds.

Start Time · string

ISO 8601 timestamp when the operation started.

End Time · string

ISO 8601 timestamp when the operation completed.

Metadata · any

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

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 traces.

Inference Result

The inference results that traces are linked to.