Send OpenTelemetry Traces to Galtea

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. Correlation uses the shared trace ID from the traceparent header Galtea propagates during Direct Inference, or the explicit galtea.trace.id span attribute. Galtea also sends that attribute’s value in the baggage header of each conversation turn call, so your agent can copy it onto its spans. See W3C Trace Context Propagation.

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
Python code
OTel Collector

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)
gRPC (port 4317)

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.

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.

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)
gRPC (port 4317)

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))

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))

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)
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:
  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]

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:

galtea.span.* explicit attributes — full control, always wins.
gen_ai.* GenAI semantic conventions — the OpenTelemetry standard for LLM telemetry.
Recognized managed-platform span shapes — platform-specific formats Galtea knows.
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. 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:

galtea.span.type — always wins.
The span kind your platform already declares — MLflow’s mlflow.spanType, or a span shape that names the kind by itself.
gen_ai.operation.name — the OpenTelemetry GenAI operation, such as chat or embeddings.
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
OTel GenAI conventions
Managed platforms

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`	Explicitly links the span to a trace. Only needed if the automatic `traceId` correlation does not apply (e.g., spans not originating from a Galtea direct inference call). Galtea sends this value in the `baggage` header of each conversation turn call; see Baggage. A span that names a trace which does not exist, or is not visible to your API key, is rejected; it does not fall back to conversation assembly.

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.

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 fill a Span record. The keys below decide which session Galtea assembles the spans into. They apply to uncorrelated spans only, so a span already linked to a Trace ignores them.

Attribute Key	Set On	Description
`galtea.session.custom_id`	Span	Your own conversation ID. Spans sharing it become one session. Galtea also reads the standard `gen_ai.conversation.id` and `session.id` keys when this one is absent.
`galtea.version.id`	Resource	One of three ways to name the Version the session is created under. When it is set, Galtea uses it and does not read `galtea.product.id`, the fact attributes, or the version attributes. Without it, without the fact attributes, and without a version attribute, uncorrelated spans are rejected.
`galtea.product.id`	Resource	The Product the spans belong to. Send it with the fact attributes below. It must belong to the organization of your API key. Leave it out to let Galtea find the product from its key values (see the next table row).
Product key attributes, such as `service.name`	Resource	Standard resource attributes that name the product. The organization chooses which ones (its product key), and each product holds the values. Send the fact attributes below and no `galtea.product.id`, and Galtea routes to the product whose key values the resource carries. A resource must carry every attribute of the key. See Route Traces to a Product by Resource Attributes.
`galtea.version.fact.<key>`	Resource	One fact of the agent state, for example `galtea.version.fact.model`. The text after the prefix is the fact key. A value is text or an integer. Galtea uses the Version of the product that holds exactly these facts, and creates it when none does. A model fact such as `galtea.version.fact.model` links the model of a Version Galtea creates.
Version attributes, such as `service.version`	Resource	Standard resource attributes that make up a Version. The organization lists their names (its version attributes), and a product can replace the list with its own. Send them with `galtea.product.id`, or with the product key attributes, and no `galtea.version.id` or `galtea.version.fact.*`. 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. See Route to a product version.
`galtea.test_case.id`	Resource or 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 marks one conversation and wins over the resource value. Omit the key to get a production session.

Name the version in one of three ways. galtea.version.id points at a Version you already created. galtea.product.id plus the galtea.version.fact.<key> attributes describe the agent state instead. The third way sends no galtea.version.fact.* attributes. It sends the standard attributes that your organization or product lists as version attributes, and Galtea builds the facts from them. Either of the last two ways can drop galtea.product.id and send the product key attributes instead. In the last two ways Galtea finds or creates the matching Version with the rules of Get or Create Version: the same facts reuse one Version, and one changed value creates a new one. The route follows the first present of galtea.version.id, galtea.version.fact.*, and the version attributes, so a resource that sets more than one is read by the first. Its later attributes are ignored. When a resource has galtea.product.id and the key attributes, galtea.product.id wins. Monitor Real User Traffic via OpenTelemetry shows each setup. Galtea rejects the uncorrelated spans of a resource, while the rest of the payload still ingests, when it sends fact attributes, or attributes your organization lists as version attributes, with no usable galtea.product.id and its resource attributes route to no single product of your organization (no product has those key values, or two products with keys of the same size do), when the facts are not valid, whether sent as fact attributes or built from the version attributes (a value that is not text or an integer, more than 32 keys, or more than 2000 bytes in all), or when the product does not exist in your organization. The last case also covers an API key whose role cannot create a Version when no Version holds the facts yet. Galtea rejects one conversation, while the rest of the payload still ingests, when the test case does not exist, when it belongs to another product than the version, when two spans of one conversation name different test case IDs or two resources do, or when the conversation key already holds another session on that version. Galtea also rejects a span whose trace ID matches a Direct Inference turn that was removed. It does not assemble that span into a new session. Those spans are counted in the export response’s partialSuccess.rejectedSpans. The response’s partialSuccess.errorMessage names the reason that applied, so your collector log says what to change. Monitor Real User Traffic via OpenTelemetry walks through the full setup.

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.

Getting Started

Core Workflows

Production & Monitoring

Advanced

Playbooks

Integrations

Security & Administration

Migration Guides

Send OpenTelemetry Traces to Galtea

Endpoint and authentication

Configure your exporter

Verify your key and endpoint

How span content maps to Span records

Token usage and cost

Attributes that route a conversation

Learn More

Monitor Real User Traffic via OpenTelemetry

W3C Trace Context Propagation

​Endpoint and authentication

​Configure your exporter

​Verify your key and endpoint

​How span content maps to Span records

​Token usage and cost

​Attributes that route a conversation

​Learn More

Monitor Real User Traffic via OpenTelemetry

W3C Trace Context Propagation

Endpoint and authentication

Configure your exporter

Verify your key and endpoint

How span content maps to Span records

Token usage and cost

Attributes that route a conversation

Learn More