添加 OpenTelemetry 依赖

欢迎回到第 9 章的学习。在上一节，我们创建了 Spring Boot 项目。现在我们要添加 OpenTelemetry 依赖，让项目具备可观察性能力。

本节将学习：Spring Boot Starter 依赖、自动插桩依赖、以及版本选择。

Spring Boot Starter 依赖

OpenTelemetry Spring Boot Starter 是什么？ 它提供了 OpenTelemetry 的自动配置，包含了 OpenTelemetry SDK、自动插桩支持、Collector Exporter、Resource 配置。

添加步骤是什么？

第一步：在 pom.xml 中添加依赖。 添加

opentelemetry-spring-boot-starter

2.3.0-alpha

第二步：刷新 Maven 依赖。 在 IDE 中刷新 Maven 项目，或运行

mvn clean install

第三步：验证依赖。 检查依赖是否下载成功，查看依赖树。

代码改动：

文件路径：

pom.xml

<!-- in <properties> Add version properties (recommended)） -->
<properties>
    <java.version>17</java.version>
    <opentelemetry.version>2.3.0-alpha</opentelemetry.version>
</properties>

<!-- in <dependencies> Added to OpenTelemetry Starter relying -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-spring-boot-starter</artifactId>
    <version>${opentelemetry.version}</version>
</dependency>

Starter 依赖会自动引入所有必需的依赖。

自动插桩依赖

Spring Boot Starter 已包含哪些自动插桩呢？

• Spring MVC： HTTP 请求追踪。
• Spring Data JPA： 数据库查询追踪。
• JDBC： 数据库连接追踪。
• HTTP Client： HTTP 调用追踪。

可选插桩有哪些呢？

• Kafka： Kafka 消息追踪。
• RabbitMQ： RabbitMQ 消息追踪。
• Redis： Redis 操作追踪。
• MongoDB： MongoDB 操作追踪。

自动插桩的工作原理： 使用 Java Agent 或字节码增强技术，在运行时自动注入追踪代码，无需修改业务代码。

可选插桩依赖示例：

<!-- Kafka Piles (optional)） -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-kafka-clients-2.6</artifactId>
    <version>${opentelemetry.version}</version>
</dependency>

<!-- RabbitMQ Piles (optional)） -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-rabbitmq-2.7</artifactId>
    <version>${opentelemetry.version}</version>
</dependency>

自动插桩让追踪变得简单，零侵入。

版本选择

版本选择有什么原则呢？

第一个原则：使用稳定版。 避免使用 alpha/beta 版本（除非必要），使用最新稳定版，查看发布说明。

第二个原则：保持版本一致。 所有 OpenTelemetry 依赖使用相同版本，避免版本冲突。

第三个原则：兼容性检查。 检查 Spring Boot 版本兼容性，检查 Java 版本兼容性。

版本选择示例： Spring Boot 3.2.x，OpenTelemetry 2.3.0-alpha，Java 17+。OpenTelemetry 2.3.0-alpha 兼容 Spring Boot 3.x，需要 Java 17+。

版本管理代码：

<!-- in <properties> Use version variables for unified management -->
<properties>
    <java.version>17</java.version>
    <opentelemetry.version>2.3.0-alpha</opentelemetry.version>
</properties>

<!-- all OpenTelemetry Dependent usage ${opentelemetry.version} -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-spring-boot-starter</artifactId>
    <version>${opentelemetry.version}</version>
</dependency>

版本管理： 选择版本 → 检查兼容性（Spring Boot 兼容、Java 版本兼容）→ 统一版本号 → 使用版本变量。

版本管理很重要，避免版本冲突和兼容性问题。

本节小结

在本节中，我们学习了添加 OpenTelemetry 依赖：

第一个是 Spring Boot Starter 依赖。 提供 OpenTelemetry 自动配置，包含了 SDK、自动插桩支持、Collector Exporter。

第二个是自动插桩依赖。 Spring MVC、JPA、JDBC 等已包含，Kafka、RabbitMQ、Redis 等可选。

第三个是版本选择。 使用稳定版，保持版本一致，检查兼容性。

依赖添加流程： 打开 pom.xml → 添加 Starter 依赖 → 刷新 Maven 项目 → 验证依赖下载 → 可选：添加插桩依赖。

这就是添加 OpenTelemetry 依赖。依赖已添加，可以开始配置 OpenTelemetry 了。

在下一节，我们将学习 OpenTelemetry 配置。学习如何配置服务名称、Collector 端点、采样率。