用 OpenTelemetry 给 Spring Boot 接链路追踪：从零到看到完整调用链

先想清楚：链路追踪要解决什么

排查慢接口最耗时的是"这条请求经过了哪些服务、卡在哪一段"。日志只能看单个服务的视角，链路追踪则把一次请求跨服务的调用串成一条链，每个 span 记一段耗时。上了追踪之后，一个 3 秒的订单接口是卡在数据库、卡在缓存、还是卡在下游 RPC，一眼就能定位。

本文用 Spring Boot 3 + OpenTelemetry Java Agent 把链路接到炬鲸 OBSERVE，不改业务代码、不手写埋点。

第一步：拉取 Agent

OpenTelemetry 官方提供 Java Agent，启动时 attach 即可自动埋点 Spring MVC、RestTemplate、Redis、MySQL 等主流组件。下载一个 jar、启动时挂上，埋点这一步就完成了。

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

第二步：配置导出器

启动参数里指定 Agent 和 OTLP 导出地址，指到炬鲸 OBSERVE 的采集网关：

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

跑在 Tomcat 里就把同样参数写进 JAVA_OPTS。service.name 建议用部署单元名字，别用默认的 unknown_service，否则所有服务会在界面里撞成一坨。

第三步：传播、采样与日志关联

跨服务传播靠 W3C Trace Context，Agent 默认开启，HTTP 调用自动带上 traceparent 头。采样决定存多少链路：生产环境先用 parentbased_always_on 保证入口请求都有 trace，量大了再改按比例采样。

-Dotel.traces.sampler=parentbased_traceidratio
-Dotel.traces.sampler.arg=0.1

顺手把 trace id 打进日志，排查时才能从一条日志直接跳到整条链路。Agent 会把 trace id 写进 MDC，在 logback 的 pattern 里加上：

<pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level [%X{trace_id}] %msg%n</pattern>

这一行，把"我找到了报错"变成"我找到了报错和引发它的整条请求"。

验证：一条请求看完整链路

发一次真实请求，回控制台「链路追踪」页，按 trace id 或服务 + 时间过滤，能看到完整瀑布图，每个 span 标着耗时。点开慢的那个 span，看它调的 SQL 或下游接口，基本就定位了。

常见坑：Agent 版本要和 JDK 匹配（JDK 21 需较新的 Agent）；防火墙放行 4317 端口；span 只有一层没有下游，多半是 HTTP 客户端没走被自动埋点的库，查一下调下游用的是哪个客户端。