OpenTelemetry Java 入门

OpenTelemetry Java 是为 Java 生态系统打造的一套 OpenTelemetry 可观测性工具集。 从宏观层面来看，它由 API、SDK 和插桩（instrumentation）三部分组成。

本页面将介绍该生态系统，包括概念性的概述、一份文档导航指南 ，以及一份含发版信息和构件等关键详情的仓库清单。

概述

API 是一组用于记录关键可观察性信号中的遥测数据的类和接口。它支持多种实现方式， 开箱即用地提供了低开销的极简 Noop（“no operation”的缩写，即 “无操作”，发音为“no op”）和 SDK 参考实现。 它旨在作为直接依赖项，供希望添加插桩的库、框架及应用所有者使用。 它具备强大的向后兼容性保证，零传递依赖，并且支持 Java 8 及以上版本。

SDK 是 API 的内置参考实现，用于处理和导出由插桩 API 调用生成的遥测数据。 配置 SDK 以进行适当的处理和导出是将 OpenTelemetry 集成到应用程序中的重要步骤。 SDK 提供自动配置和编程式配置选项。

插桩通过 API 记录遥测数据。插桩分为多种类型，包括：零代码 Java 代理、 零代码 Spring Boot 启动器、库（library）、原生（native）、手动（manual）和适配层（Shim）。

若需与编程语言无关的概述，请参阅 OpenTelemetry 概念。

文档导航

OpenTelemetry Java 文档的组织结构如下：

• 通过示例快速入门：一个帮助你快速上手 OpenTelemetry Java 的示例， 演示如何将 OpenTelemetry Java 代理集成到简单的 Web 应用中。
• 插桩生态系统：一份关于 OpenTelemetry Java 插桩生态系统的指南。 这是供希望将 OpenTelemetry Java 集成到应用程序中的开发者使用的核心资源。 了解插桩的不同类型，并确定最适合你的方案。
• 使用 API 记录遥测数据：一份关于 OpenTelemetry API 的技术参考文档，其中通过 可运行的代码示例探讨了该 API 的所有关键方面。 大多数用户会将本页面当作工具书使用，根据需求查阅各章节索引，而非从头至尾通读。
• 使用 SDK 管理遥测数据：一份关于 OpenTelemetry SDK 的技术参考文档，其中通过 可运行的代码示例，探讨了 SDK 的所有插件扩展点以及编程式配置 API。 大多数用户会将本页面当作工具书使用，根据需求查阅各章节索引，而非从头至尾通读。
• 配置 SDK：一份关于 SDK 配置的技术参考文档，重点介绍零代码自动配置。 其中包含用于配置 SDK 的所有受支持环境变量和系统属性的参考说明。 本文探讨了所有编程式自定义切入点，并提供可运行的代码示例。 大多数用户会将本页面当作工具书使用，根据需求查阅各章节索引，而非从头至尾通读。
• 了解更多：补充资源包括端到端 示例、 Java 文档、 组件注册表和 性能参考文档。

仓库

OpenTelemetry Java 的源代码被组织在多个代码仓库中：

opentelemetry-java、opentelemetry-java-instrumentation 和 opentelemetry-java-contrib 各自均发布了大量的构件。 请查阅各代码仓库获取详细信息，或查看物料清单表格中的“管理依赖项”列，以获取完整的管理依赖列表。

一般而言，从同一代码仓库发布的构件具有相同的版本号。 这一规则的例外是 opentelemetry-java-contrib，它可被视为一组独立项目的集合， 这些项目共处同一代码仓库是为了利用共享工具链。 目前，opentelemetry-java-contrib 的构件版本保持一致，但这只是巧合，未来这种情况将会改变。

各代码仓库的发布节奏与其高层级依赖结构相匹配，具体如下：

• opentelemetry-java 是核心仓库，每月最先发布。
• opentelemetry-java-instrumentation 依赖于 opentelemetry-java，随后进行发布。
• opentelemetry-java-contrib 依赖于 opentelemetry-java-instrumentation 和 opentelemetry-java ，是最后发布的。
• 虽然 semantic-conventions-java 是 opentelemetry-java-instrumentation 的一个依赖, 但是它是一个独立构件，拥有独立的发布计划。

依赖项与物料清单（BOM）

物料清单，简称 BOM， 是一种用于帮助保持相关依赖项版本一致的构件。 OpenTelemetry Java 发布了多个 BOM，以满足不同的使用场景，按范围从小到大的顺序列出如下。 我们强烈建议使用 BOM。

点击 “管理依赖项” 列中的链接，即可查看该 BOM 所管理的构件列表。

以下代码片段演示了如何添加 BOM 依赖， 其中 {{bomGroupId}}、{{bomArtifactId}} 和 {{bomVersion}} 分别对应表格中 “Group ID”、“Artifact ID” 和“当前版本”列的值。

• Gradle
• Maven

dependencies {
  implementation(platform("{{bomGroupId}}:{{bomArtifactId}}:{{bomVersion}}"))
  // 在构件上添加一个依赖，其版本由该 BOM 管理。
  implementation("io.opentelemetry:opentelemetry-api")
}

<project>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>{{bomGroupId}}</groupId>
        <artifactId>{{bomArtifactId}}</artifactId>
        <version>{{bomVersion}}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <!-- 在构件上添加一个依赖，其版本由该 BOM 管理。 -->
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>