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

目录

[1. 自动埋点（Java Agent）](#1. 自动埋点（Java Agent）)

[2. 注解驱动（@WithSpan）](#2. 注解驱动（@WithSpan）)

[3. 手动埋点（SDK 编程）](#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-service
  exporter.otlp.endpoint: http://otel-collector:4317
  traces.sampler: parentbased_always_on # 采样率控制

---

方案选择建议

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

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