接入教程：10 分钟用 OpenTelemetry 把链路接入炬鲸 OBSERVE

本文带你完成从零到有 Trace 的全过程：部署 Collector、改配置、埋点、在平台里看到第一条调用链。以 Java Spring Boot 为例，其他语言步骤一致。

第一步：部署 OpenTelemetry Collector

准备一台能访问平台的机器，用 Docker 起 Collector：

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
      http: { endpoint: 0.0.0.0:4318 }
exporters:
  otlp:
    endpoint: "ob.jjhub.cn:4317"
    headers:
      authorization: "Bearer <你的接入令牌>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp]

接入令牌在"接入管理 → OpenTelemetry"页面生成。启动后先确认 Collector 日志无报错，再进入下一步。如果内网无法直连平台，就在中间再加一层 Collector 做转发，配置不变，只改 endpoint。

第二步：业务侧引入 SDK 并配置导出

在 pom.xml 加依赖：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
</dependency>

用环境变量配置导出地址，不需要改代码逻辑：

OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector-host>:4318
OTEL_SERVICE_NAME=order-svc

第三步：关键路径埋点

自动埋点覆盖 HTTP、数据库、消息队列。对关键业务方法手动加 span：

Span span = tracer.spanBuilder("checkout")
    .setAttribute("order_id", orderId)
    .startSpan();
try (Scope scope = span.makeCurrent()) {
    // 业务逻辑
} finally {
    span.end();
}

span 名字用操作语义而非类名，这样链路读起来像一段叙事而不是堆栈。

第四步：在平台验证

发起一次请求后，打开"链路追踪 → 搜索"，按 service 过滤。能看到完整调用树、每个 span 的耗时和属性。若 trace 已关联日志，点 span 可直接跳到对应日志。

常见坑：服务名不一致会导致链路断裂，统一用 OTEL_SERVICE_NAME；采样率过高会淹没存储，先设 10% 再按需调整。