十分钟给 Spring Boot 接上 OpenTelemetry 链路追踪

准备：三样东西

接入只需要三样：一个 Spring Boot 3.x 应用（3.2+ 内置 Micrometer Tracing，能省掉一半配置）、一个 OpenTelemetry Collector（用 Docker 起，负责接收并转发到炬鲸）、以及炬鲸平台的接入地址和 token。

第一步：加依赖

Maven 加两个依赖即可：

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Spring Boot 3.2+ 通过 actuator 自动装配链路追踪，不用手动 new Tracer，也不用手写 Span 导出逻辑。

第二步：配置 application.yml

spring:
  application:
    name: order-service
management:
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces

spring.application.name 会被自动用作 service.name，排查时靠它过滤服务。probability: 1.0 是 100% 采样，本地开发没问题，生产建议降到 0.1~0.3。endpoint 指向本地 Collector 的 HTTP 端口 4318。

第三步：起 Collector 并验证

Collector 配置 otel-collector-config.yaml：

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/v1/traces
    headers:
      Authorization: Bearer <token>
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]

启动：docker run -v $PWD/otel-collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector-contrib

请求几次你的接口，打开炬鲸的 Trace 列表，按 service.name 过滤，就能看到整条调用链。点开某个 span，能看到耗时、状态码、自定义属性。

自定义埋点与进阶

框架埋点覆盖 HTTP、数据库、消息，但业务关键步骤还得自己埋。注入 Tracer，给下单、扣库存这类关键方法加 span：

Span span = tracer.nextSpan().name("place_order").start();
try (var scope = tracer.withSpan(span)) {
    span.setTag("txn_id", txnId);
    // 业务逻辑
} finally {
    span.end();
}

生产环境建议把采样交给 Collector 做 tail-based sampling：慢于 500ms 或出错的 trace 全采，其余按比例，既保住存储又不错过关键链路。

踩过的坑

• 看不到数据：先确认端口，4318 是 HTTP、4317 是 gRPC，两端必须一致。
• 只有单段 span：多半是 traceparent 没透传到下游，检查 RestTemplate/WebClient 是否用自动装配的版本，跨服务要保证头透传。
• service.name 全是 unknown：没配 spring.application.name。
• 采样率太高打爆存储：本地 1.0 无妨，生产从 0.1 起步，观察存储增长再调。