5 分钟接入 OpenTelemetry：从零到第一条链路

前置准备

先明确三件事：应用用什么语言、跑在哪里、炬鲸 OBSERVE 的接入地址。OBSERVE 同时支持 OTLP/HTTP 和 OTLP/gRPC，Java、Go、Python、Node.js 都有官方 SDK。本文以 Java 应用 + OTLP/gRPC 为例，其他语言只换依赖和初始化代码。

第一步：部署 Collector

不建议应用直接连后端。中间放一个 OpenTelemetry Collector，负责接收、批处理、重试和导出，应用只连本地 Collector。

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otlp/v1
    headers:
      Authorization: Bearer ${OBSERVE_TOKEN}
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]

关键点：导出端配的是 OBSERVE 的 token，应用侧无需知道后端地址。这层解耦以后换后端只改 Collector，不动应用。

第二步：应用埋点

Java 用 OpenTelemetry Agent，零代码注入，启动时加一行 JVM 参数：

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

Go 需要引入 SDK 手动初始化，核心三行：

exp, _ := otlptracegrpc.New(ctx,
    otlptracegrpc.WithEndpoint("localhost:4317"),
    otlptracegrpc.WithInsecure())

Python、Node.js 类似：装对应 SDK，配置同样的 OTLP endpoint，设置 service.name。

第三步：验证链路

发一次真实请求，等 30 秒，在 OBSERVE 链路查询页按 service.name 过滤。能看到请求即成功；看不到按下面顺序排查：

1. 看 Collector 日志有没有 Exporting 记录。没有说明应用没连上 Collector，检查端口和网络。
2. 有导出但后端查不到，检查 token 是否过期、Endpoint 是否写错。
3. 有链路但 span 很少，多半是 SDK 没把上游 context 传下去，检查 HTTP client 是否用了带传播的拦截器。

常见坑

• 时区：span 时间戳是 UTC，界面按浏览器时区展示，别在查询时手动加减。
• 采样：默认 head-based 采样 100% 会放大流量，生产建议配 tail-based 或按错误率采样。
• service.name 不统一：多实例务必统一 service.name，否则链路会被拆散，查不到完整调用链。
• 版本混用：SDK 和 Collector 尽量保持同一主版本，跨版本偶发协议不兼容。

建议

先在 staging 跑通再上生产，用低采样率观察一周，确认 span 数量、存储增长和查询延迟都在预期内，再逐步调高。埋点这件事，先跑通比埋全更重要——一条真实链路的价值远大于一堆空 span。