計装エコシステム

計装はAPIを使用してテレメトリーを記録します。SDKはAPIの組み込みリファレンス実装であり、計装APIコールによって生成されたテレメトリーを処理およびエクスポートするように構成されています。 このページでは、エンドユーザー向けのリソースと横断的な計装トピックを含む、OpenTelemetry JavaにおけるOpenTelemetryエコシステムについて説明します。

• さまざまなユースケースとインストールパターンに対応する計装カテゴリ。
• コンテキスト伝播は、トレース、メトリクス、およびログ間の相関を提供し、シグナルが互いに補完し合えるようにします。
• セマンティック規約は、標準操作のテレメトリーを生成する方法を定義します。
• ログ計装は、既存のJavaロギングフレームワークからOpenTelemetryにログを取得するために使用されます。

計装カテゴリ

計装にはいくつかのカテゴリがあります。

• ゼロコード：Javaエージェントは、アプリケーションのバイトコードを動的に操作するゼロコード計装 [1] の形式です。
• ゼロコード：Spring Bootスターターは、Springの自動構成を活用してライブラリ計装をインストールするゼロコード計装 [1] の形式です。
• ライブラリ計装は、ライブラリをラップまたは拡張ポイントを使用して計装し、ユーザーがライブラリの使用をインストールおよび/または適応させる必要があります。
• ネイティブ計装は、ライブラリとフレームワークに直接組み込まれています。
• 手動計装は、アプリケーション作成者によって記述され、通常はアプリケーションドメインに固有です。
• シムは、あるオブザーバビリティライブラリから別のライブラリ（通常は何らかのライブラリ_から_OpenTelemetry）にデータをブリッジします。

[1]：ゼロコード計装は、検出されたライブラリ/フレームワークに基づいて自動的にインストールされます。

opentelemetry-java-instrumentationプロジェクトには、Javaエージェント、Spring Bootスターター、およびライブラリ計装のソースコードが含まれています。

ゼロコード：Javaエージェント

Javaエージェントは、アプリケーションのバイトコードを動的に操作するゼロコード自動計装の形式です。

Javaエージェントによって計装されたライブラリのリストについては、サポートされているライブラリの「自動計装バージョン」列を参照してください。

詳細については、Javaエージェントを参照してください。

ゼロコード：Spring Bootスターター

Spring Bootスターターは、Springの自動構成を活用してライブラリ計装をインストールするゼロコード自動計装の形式です。

詳細については、Spring Bootスターターを参照してください。

ライブラリ計装

ライブラリ計装は、ライブラリをラップまたは拡張ポイントを使用して計装し、ユーザーがライブラリの使用をインストールおよび/または適応させる必要があります。

計装ライブラリのリストについては、サポートされているライブラリの「スタンドアロンライブラリ計装」列を参照してください。

ネイティブ計装

ネイティブ計装は、ライブラリまたはフレームワークに直接組み込まれています。 OpenTelemetryは、APIを使用してネイティブ計装を追加することをライブラリ作成者に推奨しています。 長期的には、ネイティブ計装が標準になることを期待しており、opentelemetry-java-instrumentationでOpenTelemetryによって維持される計装は、ギャップを埋める一時的な手段と見なしています。

• Elasticsearch Java API Client
• Quarkus

手動計装

手動計装は、アプリケーション作成者によって記述され、通常はアプリケーションドメインに固有です。

シム

シムは、あるオブザーバビリティライブラリから別のライブラリにデータをブリッジする計装であり、通常は何らかのライブラリ_から_OpenTelemetryへです。

OpenTelemetry Javaエコシステムで維持されているシム。

コンテキスト伝播

OpenTelemetry APIは補完的に設計されており、全体が部分の合計よりも大きくなります。 各シグナルには独自の強みがあり、集合的に説得力のあるオブザーバビリティストーリーをつなぎ合わせます。

重要なことに、さまざまなシグナルからのデータは、トレースコンテキストを介して相互にリンクされています。

• スパンは、スパンの親とリンクを介して他のスパンに関連付けられており、それぞれが関連するスパンのトレースコンテキストを記録します。
• メトリクスは、特定の測定のトレースコンテキストを記録するエグザンプラーを介してスパンに関連付けられています。
• ログは、ログレコードにトレースコンテキストを記録することによってスパンに関連付けられています。

この相関が機能するためには、トレースコンテキストがアプリケーション全体（関数呼び出しやスレッド間）およびアプリケーション境界を越えて伝播される必要があります。 コンテキストAPIはこれを促進します。計装は、コンテキストを認識する方法で記述される必要があります。

• アプリケーションへのエントリポイントを表すライブラリ（HTTPサーバー、メッセージコンシューマーなど）は、受信メッセージからコンテキストを抽出する必要があります。
• アプリケーションからの出口ポイントを表すライブラリ（HTTPクライアント、メッセージプロデューサーなど）は、送信メッセージにコンテキストを注入する必要があります。
• ライブラリは、暗黙的または明示的に、コールスタックおよびスレッド間でコンテキストを渡す必要があります。

セマンティック規約

セマンティック規約は、標準操作のテレメトリーを生成する方法を定義します。 とりわけ、セマンティック規約は、スパン名、スパンの種類、メトリック計器、メトリック単位、メトリックタイプ、および属性キー、値、および要件レベルを指定します。

計装を記述する際は、セマンティック規約を参照し、ドメインに適用可能なものに準拠してください。

OpenTelemetry Javaは、属性キーと値の生成された定数を含む、セマンティック規約に準拠するのに役立つアーティファクトを公開しています。

ログ計装

LoggerProvider / Logger APIは、同等のトレースおよびメトリクス APIと構造的に類似していますが、異なるユースケースに対応しています。 現時点では、LoggerProvider / Loggerおよび関連するクラスはログブリッジAPIを表しており、他のログAPI/フレームワークを介して記録されたログをOpenTelemetryにブリッジするログアペンダーを記述するために存在します。 これらは、Log4j / SLF4J / Logbackなどの代替としてエンドユーザーが使用することを意図したものではありません。

OpenTelemetryでログ計装を使用するための2つの典型的なワークフローがあり、さまざまなアプリケーション要件に対応しています。

コレクターへの直接送信

コレクターへの直接送信ワークフローでは、ログはネットワークプロトコル（例：OTLP）を使用してアプリケーションからコレクターに直接出力されます。 このワークフローは、追加のログ転送コンポーネントを必要としないため設定が簡単で、ログデータモデルに準拠する構造化ログをアプリケーションが簡単に出力できるようにします。 ただし、アプリケーションがネットワークの場所にログをキューイングしてエクスポートするために必要なオーバーヘッドは、すべてのアプリケーションに適しているわけではありません。

このワークフローを使用するには。

• 適切なログアペンダーをインストールします。[1]
• OpenTelemetry ログSDKを構成して、ログレコードを目的のターゲット宛先（コレクターまたはその他）にエクスポートします。

[1]：ログアペンダーは、ログフレームワークからOpenTelemetryログSDKにログをブリッジするシムの一種です。「Log4jをOpenTelemetryにブリッジ」、「LogbackをOpenTelemetryにブリッジ」のエントリを参照してください。さまざまなシナリオのデモンストレーションについては、ログアペンダーの例を参照してください。

ファイルまたは標準出力経由

ファイルまたは標準出力ワークフローでは、ログはファイルまたは標準出力に書き込まれます。 別のコンポーネント（例：FluentBit）がログの読み取り/テーリング、より構造化された形式への解析、およびコレクターなどのターゲットへの転送を担当します。 このワークフローは、アプリケーション要件がコレクターへの直接送信からの追加のオーバーヘッドを許可しない状況で好ましい場合があります。 ただし、下流で必要なすべてのログフィールドがログにエンコードされ、ログを読み取るコンポーネントがデータをログデータモデルに解析する必要があります。 ログ転送コンポーネントのインストールと構成は、このドキュメントの範囲外です。

トレースとのログ相関は、OpenTelemetryコンテキストをログフレームワークにブリッジするシムをインストールすることで利用できます。「OpenTelemetryコンテキストをLog4jにブリッジ」、「OpenTelemetryコンテキストをLogbackにブリッジ」のエントリを参照してください。