用 OpenTelemetry Collector 把指标、日志、Trace 统一接入炬鲸

为什么用 Collector 而不是直连

OpenTelemetry 生态里，应用侧用 SDK 埋点，数据落地则靠 Collector。Collector 是一个独立的采集/转发进程，好处有三：一是把「应用怎么埋」和「数据发给谁」解耦，后端换地址不用改应用；二是能在入口统一做采样、脱敏、限流，省下大量带宽；三是支持几十种 receiver/exporter，一份数据可以同时发往多个后端。

对炬鲸来说，推荐架构是：应用 SDK → Collector（OTLP）→ 炬鲸。直连也不是不行，但少了采样和缓冲，生产环境不推荐。

环境准备

先确认版本：Collector 用官方 release（本文以 otelcol-contrib 0.9x 为例，contrib 版内置了更多 receiver）。炬鲸侧需要准备三个信息：

• OTLP 接收地址：https://otlp.ob.jjhub.cn（gRPC 4317 / HTTP 4318）
• 鉴权 token：在炬鲸控制台「接入管理 → OpenTelemetry」创建，格式类似 jj_xxxxxxxx
• 租户标识：如果多租户部署，写入 resource 属性，否则默认 platform

Collector 配置

下面是一份可直接用的最小配置，同时采集 OTLP 过来的三类数据并导出到炬鲸：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 512

exporters:
  otlphttp:
    endpoint: https://otlp.ob.jjhub.cn
    headers:
      Authorization: "Bearer jj_xxxxxxxx"
  retry_on_failure:
    enabled: true
    initial_interval: 5s

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

要点说明：

• 导出用 otlphttp 走 HTTP/4318，比 gRPC 更容易穿透企业代理；如果内网直连没问题，也可换成 otlp exporter 走 4317。
• batch processor 一定要加，它把零散数据攒批再发，能把出口请求数降一个数量级。
• retry_on_failure 建议开启，Collector 默认遇到网络错误会直接丢数据。

让应用把数据发给 Collector

应用侧只要把 OTLP endpoint 指向 Collector 即可，SDK 层面几乎不用改。以 Java 为例，环境变量配置：

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector-host:4318
OTEL_SERVICE_NAME=order-service

启动后，SDK 会自动把 trace 和 metrics 通过 OTLP 发给 Collector。日志接入推荐走 OTLP 日志协议，或用 filelog receiver 采集已有日志文件再转 OTLP，避免侵入式改代码。

值得配置的 resource 属性

resource 属性是炬鲸区分不同环境的依据。在 SDK 或 Collector 的 resource processor 里设一次，每条 span、指标、日志都会带上：

processors:
  resource:
    attributes:
      - key: deployment.environment
        value: prod
        action: upsert

我们依赖的标准属性：service.name（必填）、deployment.environment、service.version。配好之后，就可以在三个信号类型里按环境统一过滤和告警，而不是各自单独配置。

验证与排查

接入后按这个顺序验证：

1. 先看 Collector 自身日志，确认 exporter 没有 401/403（token 错误）或 connection refused（地址不通）。
2. 在炬鲸「链路追踪」页面按 service 名过滤，能看到最近 5 分钟内的 trace。
3. 「监控指标」里看 service.name 维度是否出现，确认 resource 属性带上了服务名。
4. 「日志检索」里查 otel.source 是否为 collector。

常见报错：401 Unauthorized 一般是 token 过期或复制时多了空格；context deadline exceeded 多为网络不通，先 curl -v 测一下 endpoint 连通性；数据有但不全，多半是采样率设太高，检查 SDK 的 sampler 配置。

完成以上步骤，三类数据就统一走 OTLP 进炬鲸了。后续加新服务，只需在新应用里配 OTEL_EXPORTER_OTLP_ENDPOINT，Collector 和炬鲸侧不用再动。