5 分钟接入 OpenTelemetry：把链路追踪数据送进炬鲸 OBSERVE

准备工作

先确认三样东西：一台能访问外网的服务器、一个炬鲸 OBSERVE 账号（拿到接入端点）、以及一个跑着 Java 服务的应用。本文以 Spring Boot 为例，其他语言思路一致，只换 SDK 和启动参数。

第一步：自动埋点，不改业务代码

OpenTelemetry 对 Java 提供了 Java Agent，通过 -javaagent 参数在启动时自动注入埋点，覆盖 HTTP、数据库、消息队列等常见框架，业务代码一行不用改。下载 agent：

curl -LO https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

启动时加上参数，把数据先发到本地的 Collector：

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

service.name 一定要设成稳定、语义化的名字，后面所有检索和告警都依赖它，别用默认的 unknown_service。

第二步：配置 Collector 转发到 OBSERVE

Agent 只负责采集，落地到平台由 Collector 完成。装一个 Collector，写入下面配置：

receivers:
  otlp:
    protocols: { grpc: { endpoint: 0.0.0.0:4317 } }
processors:
  batch:
  resource:
    attributes:
      - key: deployment.environment
        value: production
        action: upsert
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otel
    headers:
      authorization: Bearer <你的接入令牌>
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlphttp]

resource processor 用来给所有数据统一打上环境标签，避免每个服务各写各的。batch processor 负责攒批，能显著降低网络开销。

第三步：验证数据进来了

启动服务和 Collector 后，随便打一次请求，然后到平台的「链路追踪」页面按 service.name 过滤。正常情况下几十秒内能看到 trace；点进去能看到完整的 span 瀑布图和耗时分布。如果看不到，按顺序查三处：agent 是否真的加载（看启动日志）、Collector 日志有无 exporter 报错、令牌是否填对。

常见坑

1. 端口不通：agent 走 gRPC 4317，export 走 HTTP 4318，防火墙别只开一个。
2. 时间漂移：服务器 NTP 不同步会导致 span 时间错乱，接入前先校准时间。
3. 采样率：生产流量大时建议在 Collector 配 tail_sampling，别把所有 trace 都存下来。