5 分钟接入链路追踪：OpenTelemetry 到 OBSERVE 的完整配置

为什么走 OpenTelemetry

接入链路追踪最常见的坑，是应用直接绑定某家厂商的 SDK，换平台就重写埋点。OpenTelemetry（简称 OTel）把数据采集和存储解耦：应用只用一套 API 埋点，通过 Collector 把数据同时发给多个后端。对 OBSERVE 而言，这意味着你只需要改 Collector 的 exporter 配置，应用代码一行都不用动。

第一步：部署 Collector

Collector 负责接收应用的 trace 数据、做批处理和转发。用 Docker 起一个最简实例，关键是配好 OTLP 接收器和指向 OBSERVE 的 exporter：

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.jjhub.cn/otlp/v1/traces
    headers:
      Authorization: "Bearer <你的接入令牌>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

接入令牌在 OBSERVE 控制台的「接入管理 → 接入令牌」里创建，一个项目一个令牌，便于隔离数据。启动后执行 docker logs otel-collector，看到 Everything is ready 即说明配置加载成功。

第二步：应用侧埋点

Java 应用用 OpenTelemetry Java Agent，无需改代码，启动时挂上即可：

java -javaagent:opentelemetry-javaagent.jar   -Dotel.exporter.otlp.endpoint=http://localhost:4317   -Dotel.service.name=order-service   -Dotel.traces.exporter=otlp   -jar order-service.jar

Go 应用推荐用 go.opentelemetry.io/otel 手动埋点，至少在 HTTP 入口和数据库调用两个位置包一层，这样链路才有上下文。埋点粒度不必一开始就追求全自动，先覆盖入口、出站 HTTP、SQL 三层，就能回答 80% 的排查问题。

第三步：验证链路

发起几次真实请求，然后在 OBSERVE 的「链路追踪」页面按服务名搜索。确认三点：span 是否出现、parent/child 关系是否正确、各 span 耗时是否合理。如果 30 秒内还没有数据，按顺序检查：令牌是否写对、Collector 与应用网络是否互通（telnet <collector-ip> 4317）、应用是否真的产生了请求流量。

三个最常见的坑

一是只埋了入口没埋出站调用，导致链路是单节点，看不出下游慢在哪。二是没传 trace 上下文，跨服务调用断成两段，检查是否遗漏了 HTTP 头透传。三是时区/时间戳不一致，span 排序错乱，统一用 UTC 并让 NTP 同步即可。按这三步排查，九成采不上数据的问题都能解决。