用 OpenTelemetry Collector 把多语言服务接入 OBSERVE

为什么用 Collector 而不是 SDK 直连

接入可观测平台有两种姿势：SDK 直连后端，或在中间加一层 OpenTelemetry Collector。多语言、多服务团队我强烈建议用 Collector，原因有三：

1. SDK 直连意味着每个服务都要配上报地址和 Token，改动分散、升级麻烦；用 Collector，凭证集中在一个配置文件里。
2. Collector 统一做采样、脱敏、批量、重试，应用端只管把数据发到本地 Agent，逻辑简单。
3. 换后端时（比如从 A 平台迁到 OBSERVE），只改 Collector 一处 exporter，不用动几十个服务。

Collector 是单二进制，每台机器或每个集群跑一个，接收各语言的 OTLP，再汇成一路统一上报。

安装与基础配置

下载二进制，指向 otel-collector-config.yaml：

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

processors:
  batch:
    timeout: 5s
    send_batch_size: 1024

exporters:
  otlphttp:
    endpoint: https://ob.example.com/otlp
    headers:
      Authorization: Bearer <你的接入Token>

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

应用只需把数据发到本机 4317（gRPC）或 4318（HTTP）端口。traces / logs / metrics 三条 pipeline 分开声明，可以先只开一条，确认稳定再逐个加。

多语言服务的配置要点

• Java：用 opentelemetry-javaagent，启动参数加 -javaagent:opentelemetry-javaagent.jar，配合环境变量 OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318。零代码侵入，自动采集 HTTP、DB、MQ。
• Go：用 otelhttp 包一层路由，手动 start/end span。Go 最大的坑是 context：子 span 必须传父级的 context.Context，否则 trace 会悄悄断成几截。
• Python：opentelemetry-instrument 自动注入，再加一行 FlaskInstrumentor().instrument_app(app)。
• Node.js：@opentelemetry/sdk-trace-node 配 NodeTracerProvider，要在路由定义之前注册；注意请求头 traceparent 透传。

关键点：让日志和链路关联起来。日志里带上 trace_id，排查时才能从一条日志直接跳到整条调用链。Java Agent 会自动把 trace id 注入 MDC，logging.pattern 里加 %X{trace_id} 即可；Go 和 Python 需要自己写几行，把当前 span 的 trace id 写进每条日志。

验证

1. 启动 Collector，看日志确认三个 pipeline 都 Ready。
2. 发一次请求，在 OBSERVE 控制台「链路追踪」按 trace id 搜到整条链。
3. 点开任意 span，看是否能跳转到关联日志。

常见坑

• 数据没上来：先 curl Collector 的健康检查端口，再查 exporter 报错；多半是 Token 或网络问题。
• trace 断了：跨服务没透传 traceparent 头，检查中间件/网关是否拦截了 trace 头。
• 日志量暴增：没开 batch 和采样。把 tail_sampling 配好，健康检查这类高频低价值请求直接丢弃。