OpenTelemetry 在 Spring Boot 项目中的3种集成方式

目录

1. 自动埋点（Java Agent）

2. 注解驱动（@WithSpan）

3. 手动埋点（SDK 编程）

配置关键点

方案选择建议

---

OpenTelemetry 在 Spring Boot 项目中的应用主要有以下三种方式，按实现复杂度由低到高排列：

---

1. 自动埋点（Java Agent）

原理：通过 JVM 的 -javaagent 参数加载 OpenTelemetry Java Agent，自动收集框架层（如 Spring MVC、JDBC、HTTP 客户端）的遥测数据。
优点：

• 零代码侵入：无需修改业务逻辑
• 开箱即用：支持主流组件（Tomcat、HikariCP、RestTemplate 等）
  实现步骤：

1. 下载 opentelemetry-javaagent.jar
2. 启动时添加 JVM 参数：

   java -javaagent:path/to/opentelemetry-javaagent.jar \-Dotel.service.name=your-service-name \-Dotel.exporter.otlp.endpoint=http://otel-collector:4317 \-jar your-spring-boot-app.jar
   

---

2. 注解驱动（@WithSpan）

原理：使用 OpenTelemetry 的注解标记需要追踪的方法，结合 SDK 手动埋点。
适用场景：需定制关键业务方法的追踪（如核心算法、外部调用）。
实现步骤：

1. 添加依赖：

   <dependency><groupId>io.opentelemetry</groupId><artifactId>opentelemetry-api</artifactId><version>1.32.0</version>
   </dependency>
   <dependency><groupId>io.opentelemetry</groupId><artifactId>opentelemetry-sdk</artifactId><version>1.32.0</version>
   </dependency>
   

2. 在方法上添加注解：

   import io.opentelemetry.instrumentation.annotations.WithSpan;@Service
   public class OrderService {@WithSpan("process-order") // 自定义 Span 名称public void processOrder(Order order) {// 业务逻辑}
   }
   

---

3. 手动埋点（SDK 编程）

原理：直接调用 OpenTelemetry API 创建 Span、记录事件。
适用场景：

• 需要精细控制追踪逻辑（如异步操作、复杂事务）
• 集成非标准组件
  代码示例：

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;@Service
public class PaymentService {private final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example.payment");public void pay(Order order) {Span span = tracer.spanBuilder("process-payment").startSpan();try (Scope scope = span.makeCurrent()) {span.addEvent("Payment started");// 支付逻辑span.setAttribute("payment.amount", order.getAmount());} catch (Exception e) {span.recordException(e);span.setStatus(StatusCode.ERROR);} finally {span.end();}}
}

---

配置关键点

所有方式均需配置 OTLP 导出器（以推送到 Collector）：

# application.yml
otel:service.name: order-serviceexporter.otlp.endpoint: http://otel-collector:4317traces.sampler: parentbased_always_on # 采样率控制

---

方案选择建议

方案	适用场景	维护成本
Java Agent	快速接入，标准组件监控	低
注解驱动	关键方法定制追踪	中
手动埋点	非标逻辑/深度定制	高

💡 最佳实践：优先使用 Java Agent 覆盖基础监控，再通过注解补充核心业务追踪，最后对特殊场景手动埋点。