Skip to main content

​
What is a Trace?

A trace is a single turn in a conversation — one user input paired with one AI output. It belongs to a session and can optionally include metadata like latency, token usage, cost, and retrieval context (for RAG evaluations). You can create traces from the Galtea dashboard (using Endpoint Connections) or programmatically using the Galtea SDK.
This entity was called Inference Result before SDK 5.0.0, and galtea.traces used to mean what is now a Span. See Dataset, Trace, and Span Renames for what to change in your code.
Two things are called “trace” here. A Galtea Trace is the turn described on this page, and its own id is id. An OpenTelemetry trace is a distributed-tracing correlation id, the API field traceId. The OpenTelemetry Trace ID property below holds that one, not the id of this Trace. The dashboard uses the same two names: “Galtea Trace ID” for this turn’s id and “OpenTelemetry Trace ID” for the correlation id.

​
SDK Integration

Trace Service SDK

Manage traces using the Python SDK

​
Trace Properties

​
Session
required
The session to which the trace belongs.
​
string | object
The input text or prompt for the trace. For most runs this is a plain string. For phone (voice) runs, when the simulated user’s audio was captured, this is a content-parts envelope {"user_message": "<transcript>", "content": [{"type": "audio", "uri": "...", "transcript": "..."}]} — the user_message field is the canonical scored scalar. Access the envelope via the SDK’s .input_data field and the spoken transcript via .input.
​
string | object
The generated output or response for the trace. For most runs this is a plain string. For phone (voice) runs, when the agent’s audio was captured, this is a content-parts envelope {"assistant_message": "<transcript>", "content": [{"type": "audio", "uri": "...", "transcript": "..."}]} — the assistant_message field is the canonical scored scalar. Access the envelope via the SDK’s .actual_output_data field and the scored transcript via .actual_output.
Retrieval context is not a stored field on the trace. It is derived from the trace’s RETRIEVER spans. You can still supply retrieval_context when logging (on create, update, or an agent response); Galtea records it as a RETRIEVER span.If your agent already emits spans, we recommend sending RETRIEVER spans directly instead. This keeps one source of truth and lets you capture several retrieval steps per turn, which a single retrieval_context value cannot.
​
float
The latency in milliseconds for the model’s response.
​
dict
Token usage information for the trace.
​
dict
Cost information for the trace.
​
int
How many spans sent with this trace were not stored. Empty when none were. A span is dropped when its data is invalid, for example an empty name or a negative latency, and each drop adds to this count as more spans arrive. An unrecognized span type never causes a drop; Galtea normalizes it instead. The dashboard shows the count on the trace so you do not have to read a log to learn a span is missing.
​
string
The W3C trace ID for the root span created during Direct Inference. This is the OpenTelemetry trace id, not the id of this Trace, which is id. It is the same trace ID propagated to your endpoint via the traceparent header, enabling correlation with your OTEL-instrumented service. Only present when the inference was generated via Direct Inference with W3C trace context propagation enabled.

Concepts overview

How Galtea’s concepts connect — diagram + per-entity quick reference.

Session

The conversation that groups traces together.

Evaluation

Score traces using metrics.

Span

Capture internal operations linked to traces.