OpenTelemetry Java入門

OpenTelemetry JavaはJavaエコシステム向けのOpenTelemetryオブザーバビリティツールのセットです。 大まかに言えば、API、SDK、および計装で構成されています。

このページでは、概念的な概要、ドキュメントのナビゲートガイド、リリースとアーティファクトに関する主要な詳細を含むリポジトリのリストを使用して、エコシステムを紹介します。

概要

APIは、主要なオブザーバビリティシグナル全体でテレメトリーを記録するためのクラスとインターフェースのセットです。 複数の実装をサポートし、低オーバーヘッドのミニマリストNoop（「ノーオプ」と発音）とSDKリファレンス実装がすぐに使用できるように提供されています。 ライブラリ、フレームワーク、および計装を追加しようとしているアプリケーション所有者が直接依存関係として取得するように設計されています。 強力な後方互換性を保証し、推移的依存関係がなく、Java 8以降をサポートしています。

SDKはAPIの組み込みリファレンス実装であり、計装APIコールによって生成されたテレメトリーを処理およびエクスポートします。 SDKを適切に処理およびエクスポートするように構成することは、OpenTelemetryをアプリケーションに統合するための重要なステップです。 SDKには、自動構成とプログラムを書いて構成するオプションがあります。

計装はAPIを使用してテレメトリーを記録します。 ゼロコードJavaエージェント、ゼロコードSpring Bootスターター、ライブラリ、ネイティブ、手動、シムなど、さまざまなカテゴリの計装があります。

言語にとらわれない概要については、OpenTelemetryの概念を参照してください。

ドキュメントのナビゲート

OpenTelemetry Javaドキュメントは次のように整理されています。

• Getting Started by Example：OpenTelemetry Javaで素早く始めるためのクイックサンプルで、シンプルなWebアプリケーションへのOpenTelemetry Javaエージェントの統合をデモンストレーションします。
• 計装エコシステム：OpenTelemetry Java計装エコシステムへのガイドです。これは、OpenTelemetry Javaをアプリケーションに統合しようとしているアプリケーション作成者にとって重要なリソースです。さまざまなカテゴリの計装について学び、どれが適しているか決定してください。
• APIでテレメトリーを記録：動作するコード例を使用して、APIのすべての主要な側面を探るOpenTelemetry APIの技術リファレンスです。ほとんどのユーザーは、最初から最後まで読むかわりに、必要に応じてセクションのインデックスを参照しながら、百科事典のようにこのページを使用します。
• SDKでテレメトリーを管理：動作するコード例を使用して、すべてのSDKプラグイン拡張ポイントとプログラマティック構成APIを探るOpenTelemetry SDKの技術リファレンスです。ほとんどのユーザーは、最初から最後まで読むかわりに、必要に応じてセクションのインデックスを参照しながら、百科事典のようにこのページを使用します。
• SDKの設定：ゼロコード自動構成に焦点を当てたSDKを構成するための技術リファレンスです。SDKを構成するためのすべてのサポートされている環境変数とシステムプロパティのリファレンスが含まれています。動作するコード例を使用して、すべてのプログラマティックカスタマイゼーションポイントを探ります。ほとんどのユーザーは、最初から最後まで読むかわりに、必要に応じてセクションのインデックスを参照しながら、百科事典のようにこのページを使用します。
• さらに詳しく：エンドツーエンドの例、Javadoc、コンポーネントレジストリ、およびパフォーマンスリファレンスを含む補足リソース。

リポジトリ

OpenTelemetry Javaソースコードはいくつかのリポジトリに整理されています。

opentelemetry-java、opentelemetry-java-instrumentation、およびopentelemetry-java-contribはそれぞれアーティファクトの大きなカタログを公開しています。 詳細についてはリポジトリを参照するか、管理された依存関係の完全なリストを見るためにBill of Materialsテーブルの「管理された依存関係」列を参照してください。

一般的なルールとして、同じリポジトリから公開されたアーティファクトは同じバージョンを持ちます。 この例外は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}}"))
  // 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>