OpenTelemetry Java 入门

OpenTelemetry Java 是面向 Java 生态系统的 OpenTelemetry 可观测性工具集。从宏观角度来看，它包括 API、SDK 和插装。

本页将介绍该生态系统，提供一个概念性的 概述、一个 导航文档 的指南，以及一个包含关于发布和构件关键信息的 仓库 列表。

概述

API 是一组用于记录关键可观测性信号的遥测数据的类和接口。它支持多种实现，开箱即用提供了低开销的最小化无操作 (no-op) 和 SDK 参考实现。它旨在被库、框架和应用程序所有者作为直接依赖项来添加插装。它具有强大的向后兼容性保证、零传递依赖项，并支持 Java 8+。

SDK 是 API 的内置参考实现，用于处理和导出由插装 API 调用产生的遥测数据。配置 SDK 以适当地处理和导出遥测数据是集成 OpenTelemetry 到应用程序中的关键一步。SDK 提供了自动配置和编程配置选项。

插装使用 API 来记录遥测数据。插装有多种类别，包括：零代码 Java Agent、零代码 Spring Boot Starter、库、原生、手动和 Shim。

有关与语言无关的概述，请参阅 OpenTelemetry 概念。

导航文档

OpenTelemetry Java 文档的组织结构如下

• 通过示例入门：一个快速示例，用于演示将 OpenTelemetry Java Agent 集成到简单的 Web 应用程序中，以便快速上手 OpenTelemetry Java。
• 插装生态系统：OpenTelemetry Java 插装生态系统的指南。这是应用程序作者用于将 OpenTelemetry Java 集成到应用程序中的关键资源。了解不同类别的插装，并决定哪种适合您。
• 使用 API 记录遥测数据：OpenTelemetry API 的技术参考，通过工作代码示例探讨 API 的所有关键方面。大多数用户将此页面用作百科全书，根据需要查阅章节索引，而不是从头到尾阅读。
• 使用 SDK 管理遥测数据：OpenTelemetry SDK 的技术参考，通过工作代码示例探讨所有 SDK 插件扩展点和编程配置 API。大多数用户将此页面用作百科全书，根据需要查阅章节索引，而不是从头到尾阅读。
• 配置 SDK：用于配置 SDK 的技术参考，重点关注零代码自动配置。包括所有支持的环境变量和用于配置 SDK 的系统属性的参考。通过工作代码示例探讨所有可编程的自定义点。大多数用户将此页面用作百科全书，根据需要查阅章节索引，而不是从头到尾阅读。
• 了解更多：补充资源，包括端到端 示例、Javadoc、组件 注册表 和 性能参考。

代码仓库

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

物料清单 (Bill of Materials)，简称 BOM，是一种有助于保持相关依赖项版本一致的构件。OpenTelemetry Java 发布了几个满足不同用例的 BOM，如下表所示，按范围递增的顺序排列。我们强烈建议使用 BOM。

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

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

• Gradle
• Maven

dependencies {
  implementation(platform("{{bomGroupId}}:{{bomArtifactId}}:{{bomVersion}}"))
  // Add a dependency on an artifact whose version is managed by the 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>
  <!-- Add a dependency on an artifact whose version is managed by the bom -->
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>