Broadcast to OpenTelemetry Collector - Send Traces to OTLP Backends

OpenTelemetry is an open-source observability framework for collecting, processing, and exporting telemetry data. OpenRouter can send traces to any backend that supports the OpenTelemetry Protocol (OTLP), including Axiom, Jaeger, Grafana Tempo, and self-hosted collectors.

Step 1: Get your OTLP endpoint and credentials

Set up your OpenTelemetry-compatible backend and obtain the OTLP traces endpoint URL along with any required authentication headers. For Axiom:

Create an Axiom account and dataset
Go to Settings > API Tokens and create a new token
Your endpoint is https://api.axiom.co/v1/traces
You’ll need headers: Authorization: Bearer xaat-xxx and X-Axiom-Dataset: your-dataset

For self-hosted collectors:

Deploy an OpenTelemetry Collector with an OTLP receiver
Configure the receiver to listen on a publicly accessible endpoint
Note the endpoint URL (typically ending in /v1/traces)

Step 2: Enable Broadcast in OpenRouter

Go to Settings > Observability and toggle Enable Broadcast.

Step 3: Configure OpenTelemetry Collector

Click the edit icon next to OpenTelemetry Collector and enter:

Endpoint: Your OTLP traces endpoint URL (e.g., https://api.axiom.co/v1/traces or https://your-collector.example.com:4318/v1/traces)
Headers (optional): Custom HTTP headers as a JSON object for authentication

Example headers for Axiom:

{
  "Authorization": "Bearer xaat-your-token",
  "X-Axiom-Dataset": "your-dataset"
}

Example headers for authenticated collectors:

{
  "Authorization": "Bearer your-token",
  "X-Custom-Header": "value"
}

Step 4: Test and save

Click Test Connection to verify the setup. The configuration only saves if the test passes.

Step 5: Send a test trace

Make an API request through OpenRouter and view the trace in your OpenTelemetry backend.

Compatible backends

The OpenTelemetry Collector destination works with any backend that supports OTLP over HTTP, including:

Axiom - Cloud-native log and trace management
Jaeger - Distributed tracing platform
Grafana Tempo - High-scale distributed tracing backend
Honeycomb - Observability for distributed systems
Lightstep - Cloud-native observability platform
Self-hosted OpenTelemetry Collector - Route traces to multiple backends

OpenRouter sends traces using the OTLP/HTTP protocol with JSON encoding. Ensure your collector or backend is configured to accept OTLP over HTTP on the /v1/traces path.

Custom Metadata

Custom metadata from the trace field is sent as span attributes in the OTLP payload. How this metadata appears depends on your downstream backend.

Supported Metadata Keys

Key	OTLP Mapping	Description
`trace_id`	Trace ID	Group multiple requests into a single trace
`trace_name`	Span Name	Custom name for the root span
`span_name`	Span Name	Name for intermediate spans in the hierarchy
`generation_name`	Span Name	Name for the LLM generation span
`parent_span_id`	Parent Span ID	Link to an existing span in your trace hierarchy

Example

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_id": "app_trace_001",
    "trace_name": "Chat Handler",
    "generation_name": "Generate Response",
    "environment": "staging",
    "deployment": "us-east-1"
  }
}

Span Attributes

Custom metadata keys are included as span attributes under the trace.metadata.* namespace. For example, environment from the trace field becomes trace.metadata.environment in the OTLP payload. Standard GenAI semantic conventions (gen_ai.*) are used for model, token usage, and cost attributes.

Additional Context

The user field maps to user.id in span attributes
The session_id field maps to session.id in span attributes
Your downstream backend determines how these attributes are indexed, queried, and displayed
Using parent_span_id lets you link OpenRouter traces to your application’s existing distributed traces

Billing quantities

Cache-write details are exported as numeric attributes on the generation span:

Attribute	Meaning
`gen_ai.usage.input_tokens.cache_write`	Total cache-write tokens.
`gen_ai.usage.input_tokens.cache_write_5m`	Five-minute cache-write tokens, when available.
`gen_ai.usage.input_tokens.cache_write_1h`	One-hour cache-write tokens, when available.

With Cost enabled under Additional generation metadata, the same quantities and native-tool counters are also queryable under span.metadata.openrouter_generation.*. For example:

{
  "span.metadata.openrouter_generation.cache_write_tokens": 300,
  "span.metadata.openrouter_generation.cache_creation.ephemeral_5m_input_tokens": 100,
  "span.metadata.openrouter_generation.cache_creation.ephemeral_1h_input_tokens": 200,
  "span.metadata.openrouter_generation.native_server_tool_use.web_search_requests": 1,
  "span.metadata.openrouter_generation.native_server_tool_use.code_execution_requests": 2,
  "span.metadata.openrouter_generation.usage_is_estimated": false
}

The example shows attribute values as a flat map; OTLP encodes numbers as intValue and the estimate flag as boolValue. Root spans also carry generation metadata under trace.metadata.openrouter_generation.*. Read each generation once. These representations repeat the same generation quantities; do not add them together. Unavailable quantities are omitted from OTEL attributes, while zero and false are preserved. See Token and cost fields for interpretation and billing caveats.

Raw provider usage

Unlike the quantities above, upstream_raw_response_usage is not flattened into one attribute per provider field. It is sent as a single stringValue attribute holding JSON, because its keys are provider-controlled and can change without notice:

{
  "span.metadata.openrouter_generation.upstream_raw_response_usage": "{\"input_tokens\":4,\"output_tokens\":373,\"cache_creation_input_tokens\":300}"
}

Decode that string in your collector or query layer to read individual provider fields. The decoded value can be an object, an array of usage reports in provider order, or null — which is sent as the four-character string null, distinct from the attribute being absent. When it decodes to null, upstream_raw_response_usage_suppression_reason says whether the value was suppressed or simply unavailable. This attribute keeps its path even when a generation carries more ordinary metadata than fits in the attribute budget. Because collectors and backends impose their own attribute value length limits, verify that your pipeline stores the complete JSON string before relying on it.

Privacy Mode

When Privacy Mode is enabled for this destination, prompt and completion content is excluded from traces. All other trace data — token usage, costs, timing, model information, and custom metadata — is still sent normally. Raw provider usage is replaced with null and reported as privacy_mode, because a provider’s usage object can contain arbitrary future fields. See Privacy Mode for details.

Overview

Models & Routing

Tool Calling

Features

Ori

Privacy

Best Practices

Community

OpenTelemetry Collector

Step 1: Get your OTLP endpoint and credentials

Step 2: Enable Broadcast in OpenRouter

Step 3: Configure OpenTelemetry Collector

Step 4: Test and save

Step 5: Send a test trace

Compatible backends

Custom Metadata

Supported Metadata Keys

Example

Span Attributes

Additional Context

Billing quantities

Raw provider usage

Privacy Mode

​Step 1: Get your OTLP endpoint and credentials

​Step 2: Enable Broadcast in OpenRouter

​Step 3: Configure OpenTelemetry Collector

​Step 4: Test and save

​Step 5: Send a test trace

​Compatible backends

​Custom Metadata

​Supported Metadata Keys

​Example

​Span Attributes

​Additional Context

​Billing quantities

​Raw provider usage

​Privacy Mode

Step 1: Get your OTLP endpoint and credentials

Step 2: Enable Broadcast in OpenRouter

Step 3: Configure OpenTelemetry Collector

Step 4: Test and save

Step 5: Send a test trace

Compatible backends

Custom Metadata

Supported Metadata Keys

Example

Span Attributes

Additional Context

Billing quantities

Raw provider usage

Privacy Mode