> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> [!WARNING]
>
> You are reading the docs of Galtea 5.14. [Read this page in the latest version](https://docs.galtea.ai/sdk/tutorials/send-opentelemetry-traces-to-galtea.md).

Galtea exposes a public [OpenTelemetry](https://opentelemetry.io/) (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](https://docs.galtea.ai/v5.14/concepts/product/version/session.md) that [Monitors](https://docs.galtea.ai/v5.14/concepts/product/monitor.md) 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](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md).
* **Enrich existing Galtea Traces.** Spans correlated to a [Trace](https://docs.galtea.ai/v5.14/concepts/product/version/session/trace.md) become [Span](https://docs.galtea.ai/v5.14/concepts/product/version/session/span.md) records on it. [Spans of a Trace that already exists](#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`.

> [accordion] 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

> [tab] 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`:
>
> > [tab] HTTP (port 4318)
> >
> > ```bash theme={"system"}
> > 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`.
> >
> > > [!NOTE]
> > >
> > > 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.
>
> > [tab] gRPC (port 4317)
> >
> > The header variable is reused — only the endpoint, protocol, and port change:
> >
> > ```bash theme={"system"}
> > 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}"
> > ```
> >
> > > [!NOTE]
> > >
> > > 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.
>
> > [!WARNING]
> >
> > 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.

> [tab] 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.
>
> > [tab] HTTP (port 4318)
> >
> > ```python theme={"system"}
> > 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))
> > ```
>
> > [tab] gRPC (port 4317)
> >
> > Use the gRPC exporter from `opentelemetry.exporter.otlp.proto.grpc` and point it at port 4317 (no URL path):
> >
> > ```python theme={"system"}
> > 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))
> > ```
> >
> > > [!NOTE]
> > >
> > > 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.

> [tab] 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:
>
> > [tab] HTTP (port 4318)
> >
> > ```yaml theme={"system"}
> > 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]
> > ```
>
> > [tab] gRPC (port 4317)
> >
> > ```yaml theme={"system"}
> > 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]
> > ```
>
> > [!WARNING]
> >
> > `${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:

```bash theme={"system"}
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](https://docs.galtea.ai/v5.14/concepts/product/version/session/span.md) 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](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md#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](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md#what-you-get).

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

> [!NOTE]
>
> These keys had different names before version 5.0.0, and Galtea still reads the old ones. See
> [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.14/sdk/migration-guides/entity-renames.md) if your collector already
> sends them.

> [tab] 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](#spans-of-a-trace-that-already-exists). |

> [tab] 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](https://opentelemetry.io/docs/specs/semconv/gen-ai/) 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](#token-usage-and-cost) below.
>
> > [!TIP]
> >
> > If your system is already instrumented with plain OpenTelemetry GenAI conventions, input, output and span type map with **zero** Galtea-specific attributes.

> [tab] 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](https://mlflow.org/docs/latest/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](https://docs.galtea.ai/v5.14/concepts/model.md) 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.

> [!NOTE]
>
> **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.

> [!WARNING]
>
> 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](https://docs.galtea.ai/v5.14/concepts/product.md) and one of its [Versions](https://docs.galtea.ai/v5.14/concepts/product/version.md). 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](https://docs.galtea.ai/v5.14/concepts/product/version/session.md).

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.

> [!NOTE]
>
> A span that names an existing [Trace](https://docs.galtea.ai/v5.14/concepts/product/version/session/trace.md) 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](#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:

```bash Version ID theme={"system"}
# An existing Version. Each agent change needs a new ID here.
export OTEL_RESOURCE_ATTRIBUTES="galtea.version.id=<version-id>"
```

```bash Product ID and facts theme={"system"}
# Galtea finds or creates the Version. No setup in Galtea.
export OTEL_RESOURCE_ATTRIBUTES="galtea.product.id=<product-id>,galtea.version.fact.model=gpt-4o,galtea.version.fact.release=1.4.2"
```

```bash Standard attributes theme={"system"}
# Set the product key values and version attributes first.
export OTEL_RESOURCE_ATTRIBUTES="service.name=checkout-agent,service.version=1.4.2"
```

The conversation key is a span attribute, so your code sets it on each turn. See [Which conversation](#3-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](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md#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](https://docs.galtea.ai/v5.14/concepts/product/version.md#version-facts) 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](https://docs.galtea.ai/v5.14/sdk/api/version/get-or-create.md). 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](https://docs.galtea.ai/v5.14/concepts/product/version.md#model-facts). So `galtea.version.fact.model` can link the model, and a version attribute such as `app.agent.model` never does.

> [!WARNING]
>
> 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](https://docs.galtea.ai/v5.14/concepts/product/dataset/test-case.md) the conversation exercises. Galtea creates the session as non-production and links it to that test case, so no [Monitor](https://docs.galtea.ai/v5.14/concepts/product/monitor.md) 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](#spans-of-a-trace-that-already-exists). |

[Set a conversation key](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md#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](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md#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](https://docs.galtea.ai/v5.14/sdk/tutorials/direct-inferences-and-evaluations-from-platform.md), 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](https://docs.galtea.ai/v5.14/concepts/product/endpoint-connection-configuration.md#baggage) 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](https://docs.galtea.ai/v5.14/concepts/product.md#product-properties) 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](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md) walks through the full setup, step by step.

## Learn More

> [card] [Monitor Real User Traffic via OpenTelemetry](https://docs.galtea.ai/v5.14/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry.md)
>
> Turn your live traffic's traces into production sessions that Monitors evaluate.

> [card] [W3C Trace Context Propagation](https://docs.galtea.ai/v5.14/sdk/tutorials/direct-inferences-and-evaluations-from-platform.md#option-3-w3c-trace-context-propagation)
>
> Attach OTel spans to the test runs Galtea triggers via Direct Inference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.