OpenTelemetry Java Instrumentationの導入境界

Javaエージェントの役割

このリポジトリの主な成果物は、Java 8 以降のあらゆるアプリケーションにアタッチできる Java エージェント JAR である。アタッチすると、エージェントはバイトコードを動的に注入し、多くの一般的なライブラリやフレームワークからテレメトリを収集する。README は、コード変更なしで Java アプリケーションからテレメトリデータを集められることが最終的な結果だと述べている。エクスポートはさまざまな形式に対応し、エージェントとエクスポーターの両方をコマンドライン引数または環境変数で設定できる。リポジトリのメタデータは、このプロジェクトを「Java 向けの自動計装および計装ライブラリ」と説明している。エージェントのアタッチにはアプリケーションのコード変更も再コンパイルも不要で、これが手動計装との大きな違いである。同じリポジトリは複数のライブラリ向けのスタンドアロン計装も公開しており、エージェントよりこちらを好むユーザー向けに、README は対応ライブラリのドキュメントにあるスタンドアロン計装の列を参照している。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、Javaエージェントの役割に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

自動計装とライブラリ計装

README の入門手順は、GitHub のリリースページから最新の opentelemetry-javaagent.jar をダウンロードすることから始まる。このパッケージには計装エージェントに加え、対応するすべてのライブラリ向けの計装と、利用可能なすべてのデータエクスポーターが含まれる。エージェントは JVM の -javaagent フラグで有効にする。README の例は `java -javaagent:path/to/opentelemetry-javaagent.jar -jar myapp.jar` である。デフォルトでは、エージェントは OTLP エクスポーターを使い、http://localhost:4318 の OpenTelemetry コレクターにデータを送るように設定されている。README はこのコレクターのデプロイ方法や、デフォルトエンドポイント以外の接続パラメータの変更方法を説明しておらず、代わりにコレクターのリポジトリとエクスポーターのソースディレクトリへのリンクを載せている。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、自動計装とライブラリ計装に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

エージェントの設定項目

設定パラメータは、Java のシステムプロパティ（-D フラグ）または環境変数として渡す。README の例では `-Dotel.resource.attributes=service.name=your-service-name` を設定し、`-Dotel.traces.exporter=zipkin` でトレースエクスポーターを Zipkin に切り替えている。README はエージェントを「高度に設定可能」と説明し、エクスポーターの選択、データの送信先などのエクスポーター設定、トレースコンテキストの伝搬ヘッダーなどを対象としている。エージェント設定と SDK 設定の 2 つのドキュメントページがリンクされている。README は、設定パラメータ名は時間とともに変わる可能性が非常に高いと警告し、新しいバージョンを試す際には確認し、バグや予期しない動作を報告するよう求めている。したがって、具体的な設定項目の一覧は、その時点のバージョンのドキュメントで確認する必要があり、README の例を固定のインターフェースとして扱うべきではない。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、エージェントの設定項目に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

対応ライブラリを確認する場所

README は、膨大な数のライブラリとフレームワーク、そして最も人気のあるアプリケーションサーバーの大半をサポートしていると主張し、そのサポートはすぐに使える状態だと述べている。これは、エージェントをアタッチすれば追加設定なしでそれらのライブラリの呼び出しを認識するという意味である。完全なリストは docs/supported-libraries.md に委ねられており、この文書は無効化された計装と、不要な計装を抑止する方法も扱っている。README 自体は具体的なライブラリ名、バージョン、数を挙げていないため、具体的なリストはリンク先の文書で確認する必要がある。また README は「膨大」「大半」という表現を数値で裏付けていないため、実際のカバレッジはその文書でしか確認できない。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、対応ライブラリを確認する場所に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

メトリクス、ログ、トレースの出力

エージェント拡張機能は、別のディストリビューションを作成したりリポジトリをフォークしたりせずに、エージェントに新機能を追加する。README は例としてカスタムサンプラー、スパンエクスポーター、新しいデフォルト値を挙げ、これらをすべてエージェントに埋め込んで単一の JAR ファイルを得られるとしている。別のページではエージェントディストリビューションの作成を取り上げており、カスタム機能を組み込んでエージェントを再パッケージするための例の集まりとして説明している。README はほとんどのユーザーに拡張機能を勧めている。拡張機能のほうが簡単で、OpenTelemetry Java エージェントのリリースのたびに再ビルドする必要がないからだ。ディストリビューションページの役割はより限定的で、カスタム機能を組み込んだ再パッケージの方法を示すことにあり、拡張機能を書くより重い作業になる。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、メトリクス、ログ、トレースの出力に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

ビルドとテストの構成

ほとんどのユーザーにとって、そのまま使える計装で十分だが、README は自動スパンに属性を追加したい場合や、独自コード用にスパンを手動で作成したい場合を説明し、手動計装のドキュメントにリンクしている。また、ロガー MDC 自動計装は、トレース ID やスパン ID などのトレース情報を独自のアプリケーションログに注入できる。詳細は専用のドキュメントにある。どちらの経路もエージェントを置き換えるのではなく、エージェントの上に追加する形になる。自動計装に依存しているユーザーでも、必要に応じてカスタムスパンや属性を追加できる。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、ビルドとテストの構成に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

リリースとApache 2.0

デバッグログは `-Dotel.javaagent.debug=true` で有効になる。README は、これらのログは非常に冗長であり、デバッグログはアプリケーションのパフォーマンスに悪影響を及ぼすと注意している。貢献の指針は CONTRIBUTING.md にある。メンテナーは 2 名（Splunk の Lauri Tulmin と Microsoft の Trask Stalnaker）が挙げられ、さらに Grafana Labs、Splunk、Elastic、Alibaba、Sublime Security から 8 名の approver と、かつての役割が記された 4 名の emeritus メンバーがいる。リポジトリのメタデータは、スター 2,601、フォーク 1,125、未解決 issue 277 件を示している。リポジトリはアーカイブされておらず、デフォルトブランチは main、ホームページは opentelemetry.io である。ライセンスは Apache-2.0 である。このライセンスは、永続的で、世界的で、非独占的で、無償で、ロイヤルティ不要で、取り消し不能な著作権ライセンスと、記載された条件で終了する類似の特許ライセンスを付与し、再配布条件を含む。ライセンス文書はサポート、保証、セキュリティ態勢については何も述べておらず、README もこれらの点を扱っていない。

open-telemetry/opentelemetry-java-instrumentationについてREADMEが明記する範囲をこの章で確認する。導入前には、リリースとApache 2.0に対応するコマンド、ファイル、設定名、対応対象を本文と一次資料で照合し、記載のない性能や互換性を推定しない。

編集部の結論

README はエージェントを標準の経路とし、スタンドアロン計装を代替案として位置づけ、対応ライブラリの完全なリスト、設定項目、抑制の仕組みを別の文書に委ねている。デプロイで必要な具体的情報のほとんどは、README 自体ではなくリンク先の文書に書かれている。 採用候補にする場合は、open-telemetry/opentelemetry-java-instrumentation固有のREADMEにある対象環境、入力形式、設定ファイル、実行手順を固定し、記載された出力または画面上の結果を確認してから範囲を決める。資料にない性能、互換性、サポートは前提にしない。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes