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 等）
实现步骤：

下载 opentelemetry-javaagent.jar

启动时添加 JVM 参数：

bash 复制代码

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 手动埋点。
适用场景 ：需定制关键业务方法的追踪（如核心算法、外部调用）。
实现步骤：

添加依赖：

XML 复制代码

<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>

在方法上添加注解：

java 复制代码

import io.opentelemetry.instrumentation.annotations.WithSpan;

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

3. 手动埋点（SDK 编程）

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

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

java 复制代码

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）：

yaml 复制代码

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

方案选择建议

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

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