# OpenTelemetry Java 介绍 > OpenTelemetry Java 生态系统介绍 --- LLMS index: [llms.txt](/llms.txt) --- OpenTelemetry Java 是为 Java 生态系统打造的一套 OpenTelemetry 可观测性工具集。 从宏观层面来看，它由 API、SDK 和插桩（instrumentation）三部分组成。 本页面将介绍该生态系统，包括概念性的[概述](#overview)、一份[文档导航](#navigating-the-docs)指南 ，以及一份含发版信息和构件等关键详情的[仓库](#repositories)清单。 ## 概述 {#overview} API 是一组用于记录关键可观察性信号中的遥测数据的类和接口。它支持多种实现方式， 开箱即用地提供了低开销的极简 Noop（“no operation”的缩写，即 “无操作”，发音为“no op”）和 SDK 参考实现。 它旨在作为直接依赖项，供希望添加插桩的库、框架及应用所有者使用。 它具备强大的向后兼容性保证，零传递依赖，并且支持 Java 8 及以上版本。 SDK 是 API 的内置参考实现，用于处理和导出由插桩 API 调用生成的遥测数据。 配置 SDK 以进行适当的处理和导出是将 OpenTelemetry 集成到应用程序中的重要步骤。 SDK 提供自动配置和编程式配置选项。 插桩通过 API 记录遥测数据。插桩分为多种类型，包括：零代码 Java 代理、 零代码 Spring Boot 启动器、库（library）、原生（native）、手动（manual）和适配层（Shim）。 若需与编程语言无关的概述，请参阅 [OpenTelemetry 概念](/docs/concepts/)。 ## 文档导航 {#navigating-the-docs} OpenTelemetry Java 文档的组织结构如下： - [通过示例快速入门](../getting-started/)：一个帮助你快速上手 OpenTelemetry Java 的示例， 演示如何将 OpenTelemetry Java 代理集成到简单的 Web 应用中。 - [插桩生态系统](../instrumentation/)：一份关于 OpenTelemetry Java 插桩生态系统的指南。 这是供希望将 OpenTelemetry Java 集成到应用程序中的开发者使用的核心资源。 了解插桩的不同类型，并确定最适合你的方案。 - [使用 API 记录遥测数据](../api/)：一份关于 OpenTelemetry API 的技术参考文档，其中通过 可运行的代码示例探讨了该 API 的所有关键方面。 大多数用户会将本页面当作工具书使用，根据需求查阅各章节索引，而非从头至尾通读。 - [使用 SDK 管理遥测数据](../sdk/)：一份关于 OpenTelemetry SDK 的技术参考文档，其中通过 可运行的代码示例，探讨了 SDK 的所有插件扩展点以及编程式配置 API。 大多数用户会将本页面当作工具书使用，根据需求查阅各章节索引，而非从头至尾通读。 - [配置 SDK](../configuration/)：一份关于 SDK 配置的技术参考文档，重点介绍零代码自动配置。 其中包含用于配置 SDK 的所有受支持环境变量和系统属性的参考说明。 本文探讨了所有编程式自定义切入点，并提供可运行的代码示例。 大多数用户会将本页面当作工具书使用，根据需求查阅各章节索引，而非从头至尾通读。 - **了解更多**：补充资源包括端到端 [示例](../examples/)、 [Java 文档](../api/)、 组件[注册表](../registry/)和 [性能参考文档](/docs/zero-code/java/agent/performance/)。 ## 仓库 {#repositories} OpenTelemetry Java 的源代码被组织在多个代码仓库中： | 仓库 | 描述 | Group ID | 当前 版本 | 发布周期 | | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | [opentelemetry-java](https://github.com/open-telemetry/opentelemetry-java) | API 和 SDK 核心组件 | `io.opentelemetry` | `1.53.0` | [每月第一个周一之后的周五](https://github.com/open-telemetry/opentelemetry-java/blob/main/RELEASING.md#release-cadence) | | [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) | 由 OpenTelemetry 官方维护的插桩工具，包括 OpenTelemetry Java 代理 | `io.opentelemetry.instrumentation` | `2.26.1` | [每月第二个周一之后的周三](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/RELEASING.md#release-cadence) | | [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib) | 由社区维护的组件，这些组件不适合纳入其他仓库的明确范围 | `io.opentelemetry.contrib` | `1.55.0` | [每月第二个周一之后的周五](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/RELEASING.md#release-cadence) | | [semantic-conventions-java](https://github.com/open-telemetry/semantic-conventions-java) | 为实现语义约定而自动生成的代码 | `io.opentelemetry.semconv` | `1.37.0` | 紧随[语义约定（semantic-conventions）](https://github.com/open-telemetry/semantic-conventions)的发布之后 | | [opentelemetry-proto-java](https://github.com/open-telemetry/opentelemetry-proto-java) | 为 OTLP 协议自动生成的绑定代码 | `io.opentelemetry.proto` | `1.3.2-alpha` | 紧随 [OpenTelemetry 协议定义（opentelemetry-proto）](https://github.com/open-telemetry/opentelemetry-proto)的发布之后 | | [opentelemetry-java-examples](https://github.com/open-telemetry/opentelemetry-java-examples) | 展示使用 API、SDK 和插装工具的多种模式的端到端代码示例 | n/a | n/a | n/a | `opentelemetry-java`、`opentelemetry-java-instrumentation` 和 `opentelemetry-java-contrib` 各自均发布了大量的构件。 请查阅各代码仓库获取详细信息，或查看[物料清单](#dependencies-and-boms)表格中的“管理依赖项”列，以获取完整的管理依赖列表。 一般而言，从同一代码仓库发布的构件具有相同的版本号。 这一规则的例外是 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） {#dependencies-and-boms} [物料清单](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Bill_of_Materials_.28BOM.29_POMs)，简称 BOM， 是一种用于帮助保持相关依赖项版本一致的构件。 OpenTelemetry Java 发布了多个 BOM，以满足不同的使用场景，按范围从小到大的顺序列出如下。 我们强烈建议使用 BOM。 点击 “管理依赖项” 列中的链接，即可查看该 BOM 所管理的构件列表。 | 概述 | 仓库 | Group ID | Artifact ID | 当前版本 | 管理依赖项 | | --------------------------------------------------------------------- | ------------------------------------ | ---------------------------------- | ----------------------------------------- | ------------------------------------------ | ------------------------------------------------------- | | API 和 SDK 的稳定核心构件 | `opentelemetry-java` | `io.opentelemetry` | `opentelemetry-bom` | `1.53.0` | [最新 pom.xml][opentelemetry-bom] | | API 和 SDK 的实验性核心构件, 包括 `opentelemetry-bom` 的全部内容 | `opentelemetry-java` | `io.opentelemetry` | `opentelemetry-bom-alpha` | `1.53.0-alpha` | [最新 pom.xml][opentelemetry-bom-alpha] | | 插桩的稳定构件, 包括 `opentelemetry-bom` 的全部内容 | `opentelemetry-java-instrumentation` | `io.opentelemetry.instrumentation` | `opentelemetry-instrumentation-bom` | `2.26.1` | [最新 pom.xml][opentelemetry-instrumentation-bom] | | 插桩的实验性构件, 包括 `opentelemetry-instrumentation-bom` 的全部内容 | `opentelemetry-java-instrumentation` | `io.opentelemetry.instrumentation` | `opentelemetry-instrumentation-bom-alpha` | `2.26.1-alpha` | [最新 pom.xml][opentelemetry-instrumentation-alpha-bom] | 以下代码片段演示了如何添加 BOM 依赖， 其中 `{{bomGroupId}}`、`{{bomArtifactId}}` 和 `{{bomVersion}}` 分别对应表格中 “Group ID”、“Artifact ID” 和“当前版本”列的值。 
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>
[opentelemetry-bom]: [opentelemetry-bom-alpha]: [opentelemetry-instrumentation-bom]: [opentelemetry-instrumentation-alpha-bom]: