Configure an OpenTelemetry exporter or Collector to reach Galtea’s public OTel endpoint: endpoint, authentication, and how spans map to Trace 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:
Enrich existing inference results. Spans correlated to an inference result become Trace records on it. Correlation uses the shared trace ID from the traceparent header Galtea propagates during Direct Inference, or the explicit galtea.inference_result.id span attribute. See W3C Trace Context Propagation.
The endpoint, authentication, and exporter configuration on this page are the same for both.
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.
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:
The same ${GALTEA_API_KEY} syntax works in a docker-compose.ymlenvironment: 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:
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 osfrom opentelemetry import tracefrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporterfrom opentelemetry.sdk.trace import TracerProviderfrom 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 osfrom opentelemetry import tracefrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporterfrom opentelemetry.sdk.trace import TracerProviderfrom 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.
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:
${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.
When a span becomes a Trace record — whether it enriches an existing inference result or is assembled into a production conversation — its input and output are filled per field, using the first source that provides a value:
galtea.trace.* explicit attributes — full control, always wins.
gen_ai.* GenAI semantic conventions — the OpenTelemetry standard for LLM telemetry.
Human-readable description of the operation. Max 1MB.
galtea.trace.input
string (JSON)
inputData
Input data, JSON-serialized. Max 10MB.
galtea.trace.output
string (JSON)
outputData
Output data, JSON-serialized. Max 10MB.
galtea.trace.error
string
error
Error message. Takes precedence over OTel span status error.
galtea.trace.metadata
string (JSON)
metadata
Custom metadata, JSON-serialized. Max 10MB.
galtea.inference_result.id
string
inferenceResultId
Explicitly links the span to an inference result. Only needed if the automatic traceId correlation does not apply (e.g., spans not originating from a Galtea direct inference call). A span that names an inference result 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.trace.input / galtea.trace.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
If your system is already instrumented with plain OpenTelemetry GenAI conventions, input and output 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 OTel fields are mapped automatically for every span, whichever source above you use:
All remaining unmapped span attributes are collected into the metadata field, so no data is lost.
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.trace.output). This is the convention Galtea will use to read retrieval context from traces (that reader arrives in a later release), 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 trace’s metadata field, so nothing is lost, but evaluations that read the trace input and output will not see it.
