把 BitRouter 的 OpenTelemetry 导出接到 Collector、Honeycomb、Grafana 或 Datadog——含采样、内容捕获与验证。

导出 trace 到你的 OTel 后端

BitRouter 通过 bitrouter-observe 插件以 OTLP 推送 trace 与指标。本指南是可观测性的实操版：如何把导出指向你已经在运行的后端、调节采样与内容捕获，并确认其正常工作。这里的一切都运行在你自己的基础设施上——中间不存在任何 BitRouter 的遥测端点。

OTLP 传输层在编译二进制时选择：otel-http（OTLP/HTTP + protobuf，默认）或 otel-grpc（OTLP/gRPC）。下面的配置对两者完全一致——只有当你的后端只支持其中一种时才需要关心传输层。

1. 最小配置

在插件下加一个 otel 块并给它一个端点，仅此即可开启导出：

plugins:
  bitrouter-observe:
    otel:
      endpoint: "http://localhost:4318"
      service_name: "bitrouter"

把密钥排除在提交的文件之外——任何鉴权 header 都用 ${VAR} 引用，加载时从环境解析：

plugins:
  bitrouter-observe:
    otel:
      endpoint: "https://api.honeycomb.io"
      headers:
        x-honeycomb-team: "${HONEYCOMB_API_KEY}"

在容器里更想用环境变量？每个字段都有覆盖项——你完全可以不写 otel 块：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=$HONEYCOMB_API_KEY"
export OTEL_SERVICE_NAME=bitrouter

2. 各后端配置

下面每个块都是某个常见后端的 plugins.bitrouter-observe.otel 配置。

OpenTelemetry Collector

把所有数据发往本地或集群内的 Collector，再由它分发到你真正的后端（这也是接入基于 Prometheus 的技术栈的途径——Collector 的 Prometheus exporter 弥补了 BitRouter 没有抓取端点这一点）：

otel:
  endpoint: "http://otel-collector:4318"
  service_name: "bitrouter"
  resource_attributes:
    deployment.environment: "prod"

Honeycomb

otel:
  endpoint: "https://api.honeycomb.io"
  service_name: "bitrouter"
  headers:
    x-honeycomb-team: "${HONEYCOMB_API_KEY}"

Grafana Cloud / Tempo

Grafana Cloud 的 OTLP 网关使用 basic auth（实例 ID + API token，base64 编码）。自托管的 Tempo 则指向它的 OTLP 端口并去掉 header。

otel:
  endpoint: "https://otlp-gateway-<region>.grafana.net/otlp"
  service_name: "bitrouter"
  headers:
    Authorization: "Basic ${GRAFANA_OTLP_TOKEN}"

Datadog

Datadog 通过 Datadog Agent 而非公开 OTLP URL 接收 OTLP——以启用 OTLP 接收的方式运行 Agent，并把 BitRouter 指向它：

otel:
  endpoint: "http://datadog-agent:4318"
  service_name: "bitrouter"
  resource_attributes:
    deployment.environment: "prod"

3. 调节采样

默认情况下 BitRouter 遵循入站的 trace 决策，否则采样全部（parentbased_always_on）。在高吞吐下，改为采样一部分：

otel:
  endpoint: "http://otel-collector:4318"
  sampler: "parentbased_traceidratio"
  sampler_arg: 0.1                       # 保留 10% 的根 trace

`sampler`	行为
`always_on`	采样每一条 trace
`always_off`	全部不采样
`traceidratio`	按比例（`sampler_arg`）采样，忽略父级
`parentbased_always_on`	跟随父级；无父级时采样（默认）
`parentbased_always_off`	跟随父级；无父级时丢弃
`parentbased_traceidratio`	跟随父级；否则按 `sampler_arg` 采样

parentbased_* 变体会尊重上游的决策，因此你的 agent 发起的 trace 不会在路由器处被 “半采样”。指标导出间隔与 trace 批处理队列可分别在 metrics 与 traces.batch 下调节，以在新鲜度与开销之间权衡。

4. 决定是否捕获内容

消息内容默认不导出。仅当你需要在 span 上看到 prompt 与响应正文用于调试时才开启：

otel:
  content_capture: "full"   # off（默认） | full

full 会把用户 prompt 与模型响应写入你的遥测后端，这些内容随后将继承该后端的访问控制与保留策略。在共享或受监管的环境中，请保持 off，仅在受限、短时的调试会话中捕获内容。

5. 验证

reload（或重启）路由器，然后询问运行中的守护进程它在做什么：

bitrouter reload                  # 不中断连接地应用配置变更
bitrouter observe status          # 端点、采样器、基数、在途 span
bitrouter observe status --json

如果它报告 stopped，说明导出器未接好——检查 otel 块是否有 endpoint（或是否设置了 OTEL_EXPORTER_OTLP_ENDPOINT），以及二进制是否带某个 OTLP 传输特性编译。然后通过路由器发一个请求，确认 trace 进入你的后端；你应当看到每次请求有一个入站 chat span，每次上游尝试有一个 CLIENT 子 span。

导出 trace 到你的 OTel 后端

导出 trace 到你的 OTel 后端

1. 最小配置

2. 各后端配置

OpenTelemetry Collector

Honeycomb

Grafana Cloud / Tempo

Datadog

3. 调节采样

4. 决定是否捕获内容

5. 验证

下一步

可观测性

自托管 BitRouter

模型故障转移

On this page