OpenTelemetry Collector 接入教程：日志、指标、追踪一次配齐

为什么用 Collector，而不是应用直连后端

应用直接上报到后端，改配置要动每一个应用；团队里 Java、Go、Python 多个技术栈并存时，各写各的 SDK 配置，维护成本很快失控。OpenTelemetry Collector 作为独立网关，统一接收各语言的 OTLP 数据，在转发前做过滤、脱敏、限流，应用侧只需要知道"把数据发到 Collector 这一个地址"。

这里还有第二个好处：后端地址要换、Token 要轮换、要加一条敏感字段脱敏规则时，只改 Collector 一处，不用重新部署每个服务。对迭代快的团队，这是"五分钟改完"和"发一周工单"的区别。

第一步：下载并启动 Collector

curl -LO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.100.0/otelcol-contrib_0.100.0_linux_amd64.tar.gz
tar xzf otelcol-contrib_0.100.0_linux_amd64.tar.gz
./otelcol-contrib --config collector.yaml

生产环境建议用 systemd 或容器守护进程托管，保证挂了能自动拉起。

第二步：配置 collector.yaml

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

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  batch:
    timeout: 5s
    send_batch_size: 1024

exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otlp
    headers:
      Authorization: "Bearer <你的接入Token>"

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

三条 pipeline 分别对应链路、指标、日志，共用同一个 exporter，配置一份即可。memory_limiter 防止突发流量把 Collector 打 OOM，batch 把小 span 合并成大请求，省网络开销。

第三步：应用侧只改一个地址

不管什么语言，只要把 OTLP 上报地址指向 Collector 的 4317（gRPC）或 4318（HTTP）就完成接入。以 Go 为例：

import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"

exporter, _ := otlptracegrpc.New(ctx,
    otlptracegrpc.WithEndpoint("collector:4317"),
    otlptracegrpc.WithInsecure())

Java、Python 同理，把 endpoint 换成 Collector 地址即可，后端地址和 Token 只存在 Collector 一处，不用下发到每个应用。

第四步：验证三类数据都上来了

在炬鲸 OBSERVE 控制台分别打开「链路追踪」「指标监控」「日志检索」三个页面，确认同一服务的三类数据都能查到。重点验证日志与 trace 的关联：找一条带 trace id 的日志，点击应能跳到对应调用链；跳不过去，说明日志没做关联，回应用侧检查 span 上下文注入。

快速自检三条：发一次请求，几秒内应能看到新 trace；服务名应是你配置的那个，而不是默认值；时间戳应准确，无时区偏移。

常见坑

• 内存超限：先加 memory_limiter，否则高峰期 Collector 自己会 OOM，比后端还先挂。
• 明文传输：生产环境务必走 https，别把 Token 明文暴露在公网。
• 漏配 batch：batch 要写进 pipeline 才生效，漏掉会导致每个请求都单独发一次网络调用，延迟和开销都会上去。
• 时区：确认应用、Collector、后端三者的时区一致，否则时间戳会整体偏移。
• 协议对不上：exporter 用的协议（gRPC 4317 / HTTP 4318）要和 Collector 上配置的 receiver 一致。

跑通之后，Collector 就是你统一加脱敏规则、PII 过滤、采样决策的地方——在数据落到存储之前就把这些处理掉。