Send OpenTelemetry Traces to Galtea

Configure an OpenTelemetry exporter or Collector to reach Galtea’s public OTel endpoint: endpoint, authentication, and how spans map to Span records.

Galtea exposes a public OpenTelemetry (OTel) endpoint. OTel is the open standard for emitting traces. The endpoint is an OTLP collector, where OTLP is the OTel export protocol. Send your traces there to enable two use cases:

• Create production sessions from real traffic. Uncorrelated spans become production Sessions that Monitors evaluate automatically. Spans that name a test case become a non-production session instead, which no Monitor scores. See Monitor Real User Traffic via OpenTelemetry.
• Enrich existing Galtea Traces. Spans correlated to a Trace become Span records on it. Spans of a Trace that already exists explains how a span names its Trace.

The endpoint, authentication, and exporter configuration on this page are the same for both.

Endpoint and authentication

Configure your OTel exporter to send traces to the Galtea collector. Every request must carry an Authorization: Bearer <Galtea-API-key> header — without it, the gateway returns 401 Unauthorized before the request reaches the collector.

All examples below use the Galtea platform hostname: otel.platform.prod-main.galtea.ai.

Using a dedicated tenant deployment?

If your organization has a private Galtea deployment, replace the hostname with your tenant-specific endpoint:

otel.platform.<TENANT>.galtea.ai

Your Galtea account team will provide the exact hostname during onboarding.

Configure your exporter

Environment variables

The OpenTelemetry SDK reads endpoint and headers from environment variables. Use shell substitution to expand ${GALTEA_API_KEY} before the value is stored in OTEL_EXPORTER_OTLP_TRACES_HEADERS:

HTTP (port 4318)

export GALTEA_API_KEY="gsk_..."
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://otel.platform.prod-main.galtea.ai:4318/otel/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer ${GALTEA_API_KEY}"

The same ${GALTEA_API_KEY} syntax works in a docker-compose.yml environment: block, but only when GALTEA_API_KEY is set in the shell that runs Compose or in a .env file Compose loads. Docker Compose substitutes ${...} from those sources when it renders the config. It does not read another entry in the same environment: block. If the variable is unset there, the exporter receives the literal string ${GALTEA_API_KEY} and the gateway returns 401 Unauthorized.

Use OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (the per-signal variant), not OTEL_EXPORTER_OTLP_ENDPOINT. The base variable auto-appends /v1/traces to the URL, but the Galtea collector expects the /otel/traces path.

gRPC (port 4317)

The header variable is reused — only the endpoint, protocol, and port change:

export GALTEA_API_KEY="gsk_..."
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://otel.platform.prod-main.galtea.ai:4317"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer ${GALTEA_API_KEY}"

Older deployments may reject the gRPC TLS handshake with missing selected ALPN property. This affects modern gRPC clients that strictly enforce ALPN (originally surfaced with grpc-go ≥ 1.67, and reproducible from grpcio too). It is a platform-side NLB configuration that is being rolled out — if you encounter it, use the HTTP/4318 endpoint until your environment is updated.

The OTel exporter does not interpolate placeholders inside OTEL_EXPORTER_OTLP_TRACES_HEADERS — it sends the value verbatim. Exporting Authorization=Bearer $GALTEA_API_KEY without shell expansion (for example, single-quoted, or written into a .env file that your runtime loads without expanding it) literally sends the string $GALTEA_API_KEY and the gateway returns 401 Unauthorized. Ensure the expansion happens at export time, not later.

Python code

If you would rather configure the exporter in code, build the OTLPSpanExporter directly and read the API key from the environment at runtime. The exporter sends the header value exactly as provided — the f"Bearer {galtea_api_key}" formatting happens once at startup, so there is no ambiguity about when the key is substituted.

HTTP (port 4318)

import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Read the Galtea API key from the environment at runtime.
# The exporter will send it as `Authorization: Bearer <key>` on every request.
galtea_api_key = os.environ.get("GALTEA_API_KEY")
if not galtea_api_key:
    raise ValueError("GALTEA_API_KEY environment variable is not set")

exporter = OTLPSpanExporter(
    endpoint="https://otel.platform.prod-main.galtea.ai:4318/otel/traces",
    headers={"Authorization": f"Bearer {galtea_api_key}"},
)

# Register the exporter without clobbering a provider another library may have
# already installed — e.g. `opentelemetry-bootstrap` auto-instrumentation (set up
# in step 2 above) or the Galtea SDK. `set_tracer_provider()` is a silent no-op if
# a real provider is already active, so only create one when the active provider is
# still the default proxy; otherwise attach the exporter to the existing provider.
provider = trace.get_tracer_provider()
if isinstance(provider, trace.ProxyTracerProvider):
    provider = TracerProvider()
    trace.set_tracer_provider(provider)

provider.add_span_processor(BatchSpanProcessor(exporter))

gRPC (port 4317)

Use the gRPC exporter from opentelemetry.exporter.otlp.proto.grpc and point it at port 4317 (no URL path):

import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Read the Galtea API key from the environment at runtime.
# The exporter will send it as `Authorization: Bearer <key>` on every request.
galtea_api_key = os.environ.get("GALTEA_API_KEY")
if not galtea_api_key:
    raise ValueError("GALTEA_API_KEY environment variable is not set")

# gRPC exporter: the endpoint is `host:port` (no URL path), with TLS enabled.
# gRPC metadata keys must be lowercase, so the header is `authorization`.
exporter = OTLPSpanExporter(
    endpoint="otel.platform.prod-main.galtea.ai:4317",
    insecure=False,
    headers=(("authorization", f"Bearer {galtea_api_key}"),),
)

# Register the exporter without clobbering a provider another library may have
# already installed — e.g. `opentelemetry-bootstrap` auto-instrumentation (set up
# in step 2 above) or the Galtea SDK. `set_tracer_provider()` is a silent no-op if
# a real provider is already active, so only create one when the active provider is
# still the default proxy; otherwise attach the exporter to the existing provider.
provider = trace.get_tracer_provider()
if isinstance(provider, trace.ProxyTracerProvider):
    provider = TracerProvider()
    trace.set_tracer_provider(provider)

provider.add_span_processor(BatchSpanProcessor(exporter))

Older deployments may reject the gRPC TLS handshake with missing selected ALPN property. This affects modern gRPC clients that strictly enforce ALPN (originally surfaced with grpc-go ≥ 1.67, and reproducible from grpcio too). It is a platform-side NLB configuration that is being rolled out — if you encounter it, use the HTTP/4318 exporter until your environment is updated.

OTel Collector

If you already run your own OpenTelemetry Collector, configure it to forward the traces pipeline to Galtea. Choose the outbound protocol that suits your deployment:

HTTP (port 4318)

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlphttp/galtea:
    # Galtea expects /otel/traces, NOT the OTLP default /v1/traces.
    traces_endpoint: https://otel.platform.prod-main.galtea.ai:4318/otel/traces
    headers:
      Authorization: "Bearer ${env:GALTEA_API_KEY}"
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/galtea]

gRPC (port 4317)

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlp/galtea:
    endpoint: otel.platform.prod-main.galtea.ai:4317
    tls:
      insecure: false
    headers:
      Authorization: "Bearer ${env:GALTEA_API_KEY}"
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/galtea]

${env:GALTEA_API_KEY} is the OpenTelemetry Collector’s own environment-variable interpolation syntax — it is resolved by the Collector itself when it loads the config. This is different from the shell ${GALTEA_API_KEY} syntax used in the SDK env-var tabs (which is resolved by the shell at export time). Using shell syntax in a Collector config (or Collector syntax in a shell export) will send a literal, unexpanded string and the gateway will return 401 Unauthorized.

Verify your key and endpoint

A quick way to confirm the header is being applied correctly is to POST an empty payload and inspect the status code:

curl -sS -w 'HTTP %{http_code}\n' -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GALTEA_API_KEY}" \
  -d '{"resourceSpans":[]}' \
  https://otel.platform.prod-main.galtea.ai:4318/otel/traces
# Expect: HTTP 200 with an empty-success body — Galtea's gateway returns {"partialSuccess":{}}
# Without the Authorization header: HTTP 401 — "Provide a valid galtea API key token"

How span content maps to Span records

When a span becomes a Span record — whether it enriches an existing trace or is assembled into a production conversation — its input and output are filled per field, using the first source that provides a value:

1. galtea.span.* explicit attributes — full control, always wins.
2. gen_ai.* GenAI semantic conventions — the OpenTelemetry standard for LLM telemetry.
3. Recognized managed-platform span shapes — platform-specific formats Galtea knows.
4. A configured span-source rule — otelInputSourceRule or otelOutputSourceRule on the Version, the Product, or the organization, which reads the field out of a named non-LLM span. See Recover the turn input from a non-LLM span.

A turn’s input and output follow a different order, because a turn has many spans: a configured source rule decides the field, else the turn’s single root span, else the earliest input and the latest output. Only an input that carries a user message counts, so an empty value such as {} or [] never becomes the turn input. A configured rule that fires on no span of the turn leaves that field empty; it never falls back. See Monitor real user traffic.

If you set no attributes, spans are still ingested. A span type Galtea does not recognize is also ingested: Galtea normalizes the value to a known span type and keeps your original label in the span’s metadata, under the key galtea.span.original_type.

The span type follows its own order, because only galtea.span.type is a Galtea attribute:

1. galtea.span.type — always wins.
2. The span kind your platform already declares — MLflow’s mlflow.spanType, or a span shape that names the kind by itself.
3. gen_ai.operation.name — the OpenTelemetry GenAI operation, such as chat or embeddings.
4. SPAN — when nothing above names a kind.

So a span imported from an instrumented platform is typed without any Galtea attribute: an MLflow RETRIEVER span becomes a RETRIEVER span, which is what Galtea reads retrieval context from. A vendor word Galtea spells differently still maps, so MLflow’s LLM becomes GENERATION.

These keys had different names before version 5.0.0, and Galtea still reads the old ones. See Dataset, Trace, and Span Renames if your collector already sends them.

Galtea span attributes

Attribute Key	Type	Maps To	Description
galtea.span.type	string	type	Span type. One of: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, GUARDRAIL. Any other value is normalized to one of these types instead of being rejected, and your original label is kept in metadata under galtea.span.original_type.
galtea.span.description	string	description	Human-readable description of the operation. Max 1MB.
galtea.span.input	string (JSON)	inputData	Input data, JSON-serialized. Max 10MB.
galtea.span.output	string (JSON)	outputData	Output data, JSON-serialized. Max 10MB.
galtea.span.error	string	error	Error message. Takes precedence over OTel span status error.
galtea.span.metadata	string (JSON)	metadata	Custom metadata, JSON-serialized. Max 10MB.
galtea.trace.id	string	inferenceResultId	Links the span to a Trace that already exists. See Spans of a Trace that already exists.

OTel GenAI conventions

No Galtea attributes needed. When galtea.span.input / galtea.span.output are not set, input and output are filled from the OpenTelemetry GenAI semantic conventions in any of these forms:

• gen_ai.input.messages / gen_ai.output.messages (the current conventions)
• the legacy gen_ai.prompt / gen_ai.completion attributes
• the GenAI content span events

gen_ai.operation.name sets the span type when you send no galtea.span.type: chat, text_completion and generate_content become GENERATION, embeddings becomes EMBEDDING, execute_tool becomes TOOL, and create_agent / invoke_agent become AGENT.

On an execute_tool span, send gen_ai.tool.name as well. The conventions name that span execute_tool get_weather, and Galtea stores the span name as the tool name. So without the attribute the tool reads as execute_tool get_weather, and a tool_correctness metric never matches it against get_weather.

gen_ai.usage.input_tokens and gen_ai.usage.output_tokens give Galtea the call’s token counts. See Token usage and cost below.

If your system is already instrumented with plain OpenTelemetry GenAI conventions, input, output and span type map with zero Galtea-specific attributes.

Managed platforms

For managed platforms, Galtea recognizes some span shapes automatically, with no configuration needed: platforms whose telemetry carries the abraxas span-event format (such as Mistral’s agent platform), and platforms instrumented with MLflow Tracing (recognized from MLflow’s own mlflow.* span attributes).

These shapes also set the span type. MLflow’s mlflow.spanType maps onto the Galtea span type (RETRIEVER, TOOL, CHAIN, AGENT and EMBEDDING map directly; LLM and CHAT_MODEL become GENERATION), and an abraxas LLM-call span becomes a GENERATION. MLflow’s UNKNOWN names no kind, so a span carrying it falls through to the next source in the order above.

These OTel fields are mapped automatically for every span, whichever source above you use:

• span.name → name
• startTimeUnixNano / endTimeUnixNano → startTime / endTime + latencyMs (computed)
• span.status → error (fallback when galtea.span.error is not set; only for STATUS_CODE_ERROR)
• parentSpanId → parentTraceId (parent-child hierarchy)

All remaining unmapped span attributes are collected into the metadata field, so no data is lost.

Token usage and cost

Galtea reads the token counts your spans report and adds them up per turn. Send them with the OpenTelemetry GenAI keys:

Attribute Key	Type	Description
gen_ai.usage.input_tokens	int	Input (prompt) tokens the call consumed.
gen_ai.usage.output_tokens	int	Output (completion) tokens the call produced.

A turn’s inputTokens, outputTokens and tokens are the sum over every span of that turn, so a turn that makes three LLM calls reports the three calls added together. A span that reports no usage adds nothing. Send no usage at all and the turn keeps what Galtea already had: nothing when no Model is linked to the Version, or the estimate Galtea derived from the turn text when one is.

Galtea also recognizes the usage a managed platform reports in its own format. MLflow Tracing’s mlflow.chat.tokenUsage works with no Galtea attribute. When a span carries both, the gen_ai.usage.* keys win, field by field.

Cost is derived from those counts and the per-token price of the Model linked to the Version. Link a Model with a known price and the turn’s cost is filled. With no Model, or with no price for it, cost stays empty rather than zero.

A reported count replaces one Galtea estimated earlier: your own figure is the accurate one. A cost you reported yourself is kept, and the new counts do not replace it: Galtea recomputes only a cost it derived from the counts and the Model price, never a different figure you set. Spans of a turn may arrive in several export batches, and each batch raises the turn’s total instead of replacing it. Re-sending the same spans changes nothing.

Retrieval context (RAG): to record what your system retrieved, type a span as RETRIEVER and put the retrieved data in its output (for example via galtea.span.output). This is how Galtea reads retrieval context: it is derived from your RETRIEVER spans, and the output has no required shape.

Some common instrumentation styles do not populate input/output yet: Traceloop / OpenLLMetry (gen_ai.prompt.0.content-style flattened attributes) and OpenInference (input.value). Their data is still stored in the span’s metadata field, so nothing is lost, but evaluations that read the span input and output will not see it.

Attributes that route a conversation

The keys above, except galtea.trace.id, fill a Span record. The keys below decide where Galtea stores the spans.

Galtea stores each conversation under a Product and one of its Versions. Your telemetry answers three questions:

1. Which product? A resource attribute names it.
2. Which version of that product? A resource attribute names it, or describes it so that Galtea finds or creates it.
3. Which conversation? A span attribute groups spans into one Session.

A resource attribute describes the whole telemetry source, not one span. So you can set it once, for example on your OTel Collector, even when a managed platform emits the spans.

A span that names an existing Trace skips the three questions. That is the usual case when Galtea calls your endpoint during Direct Inference. See Spans of a Trace that already exists. Every other span needs all three answers, even when its conversation key joins a session that already exists.

These are the three common setups. Pick one:

Version ID

# An existing Version. Each agent change needs a new ID here.
export OTEL_RESOURCE_ATTRIBUTES="galtea.version.id=<version-id>"

The conversation key is a span attribute, so your code sets it on each turn. See Which conversation.

1. Which product

Send one of these on the resource. Skip this step when you send galtea.version.id, because a Version ID already names its product.

Attribute	How Galtea uses it
galtea.product.id	The ID of the product. It must belong to the organization of your API key.
Product key attributes, service.name by default	Galtea picks the product whose key values the resource carries. Your organization chooses the attribute names (the product key), and each product stores its own values. The resource must carry every attribute of the key. See Route Traces to a Product by Resource Attributes.

When the resource carries both, galtea.product.id wins. A galtea.product.id that is empty or not text is rejected, and Galtea does not try the key values.

2. Which version

Send one of these on the resource. Galtea uses the first one present, in the order of the table. When that one fails, Galtea does not try the next one.

Attribute	How Galtea uses it
galtea.version.id	The ID of a Version you already created. Galtea uses a non-empty text value as it is, and then reads no other product or version attribute. An empty value counts as absent.
galtea.version.fact.<key>	One fact of your agent state per attribute, for example galtea.version.fact.model. The text after the prefix is the fact key.
Version attributes, such as service.version	Standard attributes that your organization lists. A product can replace the list with its own. Galtea builds the facts from the listed attributes the resource carries, with the full attribute name as the fact key. At least one must be present. A blank or null value counts as absent.

With facts, Galtea finds the Version of the product that holds exactly these facts, or creates it, with the rules of Get or Create Version. The same facts reuse one Version, whatever the order of the attributes. One changed value creates a new Version, so a new release needs no change in Galtea. A fact value is text or an integer.

A fact key such as model or model_name also links a model to a Version that Galtea creates, with the rules of Model facts. So galtea.version.fact.model can link the model, and a version attribute such as app.agent.model never does.

Never use a value that changes per request or per pod as a fact, such as a request ID, a trace ID, a timestamp, host.name, k8s.pod.name or service.instance.id. Every distinct value creates a new Version, and Galtea does not limit how many.

3. Which conversation

Attribute	How Galtea uses it
galtea.session.custom_id	Set it on the span. Your own conversation ID. Spans that share it become one session, and each OTel trace becomes one turn of it. When it is absent, Galtea uses a key it derives from a supported managed platform, then the standard gen_ai.conversation.id, then session.id.
galtea.test_case.id	Optional. Set it on the resource or on the span. The Test Case the conversation exercises. Galtea creates the session as non-production and links it to that test case, so no Monitor scores it. A span value wins over the resource value. An empty or non-text value counts as absent, so the session is production. Leave it out for real user traffic. During Direct Inference, the session already links its test case. See Spans of a Trace that already exists.

Set a conversation key names the managed platforms whose key Galtea derives. A span that carries no key waits for a later batch of its trace that does, up to a size limit. Past that limit, Galtea rejects it at once. See Batched Exporters and the Conversation Key.

Spans of a Trace that already exists

A Trace already exists when Galtea calls your endpoint during Direct Inference, or when your code created it with the SDK, the CLI or the API. Its Session already has its Version, and a Direct Inference session also has its Test Case. Your spans only need to name the Trace. Galtea then ignores the product, version, conversation and test case attributes.

How the span names the Trace	Where the value comes from
Its OTel trace ID	Direct Inference only. Galtea sends the trace ID in the traceparent header of each turn. A service instrumented with OpenTelemetry continues that trace with no code.
galtea.trace.id	The ID of the Trace. During Direct Inference, Galtea sends it in the X-Galtea-Inference-Id header and in the baggage header, which a baggage span processor can copy onto each span. With the SDK, use the ID of the Trace your code created. Set it when the trace ID does not match, for example when a proxy starts a new trace. Galtea reads it from each span, so set it on every span of the turn. Unlike the conversation key, the root span alone is not enough.

Galtea tries the trace ID first, then galtea.trace.id. A galtea.trace.id that names no Trace your API key can see is rejected, and Galtea does not route the span by product, version or conversation. A span with neither goes through the three questions, unless its trace ID matches a Direct Inference turn that was removed.

What Galtea rejects

Galtea never guesses where your data belongs. It rejects the spans of one resource, and the rest of the payload still ingests, in these cases:

• No version. The resource carries no galtea.version.id, no galtea.version.fact.* attribute, and no attribute of the version attribute list in force for its product: the product’s own list, or else the organization list.
• No product. The resource carries galtea.version.fact.* attributes or listed version attributes, and no galtea.product.id, and its product key attributes match no single product of your organization. That means no product holds those key values, or two products with keys of the same size do. A resource that routes by version attributes gets this reason only when it carries an attribute of the organization list. Otherwise the reason is no version.
• Invalid facts. A value is not text or an integer, a key after the galtea.version.fact. prefix is empty, all galtea.version.fact.* values are blank, or the facts have more than 32 keys or more than 2000 bytes in all. For version attributes, a blank or null value counts as absent instead.
• Unknown version or product. The Version or the product does not exist, or your API key cannot see it. With galtea.product.id, this also covers an API key whose role cannot create a Version, when no Version holds the facts yet. When the key values found the product, Galtea reports that case as no product.

It rejects one conversation, and the rest of the payload still ingests, in these cases:

• The test case does not exist, or it belongs to another product than the Version.
• Two spans of one conversation name different test case IDs, or two resources do.
• The conversation names a test case, and its key already holds another session on that Version: a production session, or one linked to another test case.
• The conversation is new, and the payload already opened 100 new conversations, the default limit.
• The session is closed, and the product’s Closed Session Inference Creation Policy is REJECT. Only the spans of the new turn are rejected.

Galtea also rejects a span whose trace ID matches a Direct Inference turn that was removed, unless its galtea.trace.id names a live Trace. It does not assemble that span into a new session.

The export response counts the rejected spans in partialSuccess.rejectedSpans. Its partialSuccess.errorMessage names each reason that applied, so your collector log says what to change.

Monitor Real User Traffic via OpenTelemetry walks through the full setup, step by step.

Learn More

Monitor Real User Traffic via OpenTelemetry

Turn your live traffic’s traces into production sessions that Monitors evaluate.

W3C Trace Context Propagation

Attach OTel spans to the test runs Galtea triggers via Direct Inference.