OpenTelemetry Collector

将追踪发送到任何兼容 OpenTelemetry 的后端

OpenTelemetry 是用于采集、处理和导出遥测数据的开源可观测性框架。OpenRouter 可以向任何支持 OpenTelemetry 协议（OTLP）的后端发送追踪，包括 Axiom、Jaeger、Grafana Tempo 以及自托管采集器。

第 1 步：获取 OTLP 端点和凭据

设置兼容 OpenTelemetry 的后端，并获取 OTLP 追踪端点 URL 以及所需的身份验证请求头。

对于 Axiom：

1. 创建 Axiom 账户和数据集
2. 前往 设置 > API 令牌（Settings > API Tokens） 并创建新令牌
3. 端点为 https://api.axiom.co/v1/traces
4. 你需要这些请求头：Authorization: Bearer xaat-xxx 和 X-Axiom-Dataset: your-dataset

对于自托管采集器：

1. 部署带有 OTLP receiver 的 OpenTelemetry Collector
2. 将 receiver 配置为监听可从公网访问的端点
3. 记下端点 URL（通常以 /v1/traces 结尾）

第 2 步：在 OpenRouter 中启用广播

前往 设置 > 可观测性（Settings > Observability），打开 启用广播（Enable Broadcast） 开关。

第 3 步：配置 OpenTelemetry Collector

点击 OpenTelemetry Collector 旁的编辑图标，并填写：

• Endpoint：你的 OTLP 追踪端点 URL（例如 https://api.axiom.co/v1/traces 或 https://your-collector.example.com:4318/v1/traces）
• Headers（可选）：用于身份验证的自定义 HTTP 请求头，格式为 JSON 对象

Axiom 的请求头示例：

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

需要身份验证的采集器的请求头示例：

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

第 4 步：测试并保存

点击 测试连接（Test Connection） 验证配置。仅当测试通过时才会保存配置。

第 5 步：发送测试追踪

通过 OpenRouter 发出一次 API 请求，然后在 OpenTelemetry 后端中查看该追踪。

兼容后端

OpenTelemetry Collector 目标端适用于任何支持通过 HTTP 传输 OTLP 的后端，包括：

• Axiom - 云原生日志与追踪管理
• Jaeger - 分布式追踪平台
• Grafana Tempo - 高规模分布式追踪后端
• Honeycomb - 面向分布式系统的可观测性
• Lightstep - 云原生可观测性平台
• 自托管 OpenTelemetry Collector - 将追踪路由到多个后端

自定义元数据

trace 字段中的自定义元数据会作为 Span 属性随 OTLP 载荷发送。这些元数据的呈现方式取决于下游后端。

支持的元数据键

示例

{
  "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 属性

自定义元数据键会作为 Span 属性包含在 trace.metadata.* 命名空间下。例如，trace 字段中的 environment 在 OTLP 载荷中会变为 trace.metadata.environment。

模型、Token 用量和费用属性使用标准 GenAI 语义约定（gen_ai.*）。

补充说明

• user 字段会映射到 Span 属性中的 user.id
• session_id 字段会映射到 Span 属性中的 session.id
• 下游后端决定这些属性如何被索引、查询和展示
• 使用 parent_span_id 可将 OpenRouter 追踪关联到应用中已有的分布式追踪

隐私模式

当该目标端启用 隐私模式 时，追踪中会排除提示词和补全内容。其余追踪数据——Token 用量、费用、时间信息、模型信息以及自定义元数据——仍会正常发送。详情见 隐私模式。