OpenTelemetryを理解する 第4回: JavaアプリをOpenTelemetryで計装する

OpenTelemetry Javaは、OpenTelemetryのJavaによる言語固有の実装です。他の言語と同様に、アプリケーションプログラミングインターフェース（API）とソフトウェア開発キット（SDK）があり、これらはopentelemetry-javaプロジェクトで見ることができます。ライブラリやアプリケーションの作者は、コードを計測するためにAPIを使用します。SDKはAPIの実装を定義しています。生成された計装データをどのように処理してエクスポートするかを記述するために、アプリケーションはSDKを設定します。 

さらに、OpenTelemetryには、New RelicのJavaエージェントに類似したJavaエージェント（opentelemetry-java-instrumentation）があります。エージェントはアプリケーションに接続すると、よく使われているさまざまなライブラリやフレームワークのバイトコードを変更し、テレメトリーデータを取得します。このような、より自動化された計装は、しばしば「自動計装」オプションと呼ばれ、ほんの少しの設定でアプリケーションに関する多くの有用な情報を得ることができるため人気があります。自動計測機能が不足していたり、ニーズに合わない場合には、OpenTelemetry API を使って手動でカスタム計装機能を追加することができます。

このブログでは、OpenTelemetry Java プロジェクトでアプリケーションを手動で計装する方法（API と SDK の設定）と、Java エージェントで自動計装を使用する方法を説明します。OpenTelemetry と New Relic に関連するさまざまな例が含まれている newrelic-opentelemetry-examples GitHub リポジトリのソースコードを参照します。 

OpenTelemetryのサンプルビデオ

次のビデオでは、OpenTelemetry Java API と SDK を使ってカスタマイズを加えたシンプルなアプリケーションの例を紹介しています。

手動による計装

sdk-nr-configのデモでは、OpenTelemetry APIによるOpenTelemetry Javaの手動計装と、OpenTelemetry SDKによる設定を紹介しています。ビルドにはGradleを使用しており、プロジェクト内でコードを共有する複数のサンプルがあるため、マルチプロジェクトビルドとなっています。全体像を把握するには、 :sdk-nr-configモジュールとルートモジュール内のbuild.gradleファイルをよく見てください。

ルートモジュールのbuild.gradleファイルは、すべてのサブプロジェクトのOpenTelemetryのbill of materials（BOM）のプラットフォームから依存されています。BOM は、OpenTelemetry コンポーネントのバージョンを同期させるための便利な方法で、特定の依存関係のバージョンを省略することができます。

トレース API

計装を行うライブラリのトレーサーによりカスタム トレーシングを設定できます。トレーサーにより、スパンを構築し、スパンのコンテキストを設定することができます。スパンのコンテキストを設定することで、コードパス上に設定された後続のスパンが適切な親子関係を持つようになります。

トレースのセマンティック規約に目を通し、カスタムトレースのための計装が適用可能なオペレーションにおける確立されている規約に従っていることを確認してください。セマンティック規約により、New Relic のようなオブザーバビリティプラットフォームは、より意味のある方法でデータを解釈し、より良いエクスペリエンスを提供することができます。  

概念の説明やその他多くの例については、OpenTelemetry Java Tracing のドキュメントを参照してください。 

メトリクスAPI

計装されるライブラリのメーターによりカスタムメトリクスを設定できます。メーターにより計装器を作成できます。計装器を使用してデータを記録し、オプションで、データが記録されたコンテキストの主要な次元を記述する属性を関連付けることができます。 

トレースと同様に、一般的な操作のためのメトリクス計装器を追加する方法を説明するメトリクスのためのセマンティック規約群があります。必要に応じてこれらに従うようにしてください。 

概念の説明やその他の例については、OpenTelemetry Java Metrics のドキュメントを参照してください。OpenTelemetry Metrics はまだ完成していないので、この例の詳細は今後数ヶ月のうちに変更されるでしょう。

次のビデオでは、OpenTelemetry トレーサーとメーターの設定を説明しています。

OpenTelemetry SDKを構成する

デフォルトでは、OpenTelemetry API はクラスのno-op実装を返します。no-op実装とは記録されたデータをすべて単純にドロップする空の実装です。OpenTelemetry SDK を設定することで、データを有用な方法で処理したりエクスポートしたりできるようになります。 

OpenTelemetry API は、トレースやメトリクスの計測を初期化するためのスタティックなメソッドを公開していることに注意してください。そのため、アプリケーションのライフサイクルのできるだけ早い段階でSDKを設定することをお勧めします。そうしないと、SDKの実装がセットアップされる前に計装を初期化してしまう危険性があります。 

詳しくは、OpenTelemetry Java SDK Configuration ドキュメントをご覧ください。

次のビデオでは、データを送信する前にJava SDKを設定する必要がある理由を説明し、その方法を順を追って説明しています。

Traceの設定

OpenTelemetry SDKをトレース用に設定する際には以下の言葉の定義を確認してください。

• リソースはトレースデータが関連付けられているソフトウェアエンティティを定義します。
• スパン制限は、属性、イベント、リンクの最大数など、スパンに関連するデータに制限を課すために利用できます。
• Contextの伝搬は、分散トレーシングのために、トレースの状態がアプリケーションの境界を越えてどのように伝搬されるかを記述します。
• Sampling（サンプリング）は、すべてをトレースすることが現実的でない場合に、どのトレースをキャプチャするかを決定する方法を示します。 
• スパンプロセッサーは、スパンの開始および終了にフックし、任意のロジックを実行する手段を提供します。
• Exporting（エクスポート、エクスポーティング）は、トレースデータをアプリケーションからどのように送信するかを定義します。 

Metricの設定

OpenTelemetry SDK のメトリクスを設定する際には以下の言葉の定義を確認してください。

• リソースはメトリクスクデータが関連付けられているソフトウェアエンティティを定義します。
• ビューでは、集約タイプ（サマリー、カウンター、ヒストグラム）、集約の一時性（累積またはデルタ）、保持する属性など、メトリクスデータの集約方法をカスタマイズできます。 
• Exporting（エクスポート、エクスポーティング）はメトリクスデータがアプリケーションからどのように送信されるかを定義します。

OpenTelemetry Metricsはまだ完成していないため、メトリクスSDKの設定の詳細は今後数ヶ月のうちに変更される予定です。

自動計装

agent-nr-configのデモではOpenTelemetry Java Agentによる自動計装を紹介しています。サポートされているライブラリとフレームワークのリストは、Libraries / Frameworksをご覧ください。

エージェントを使用するには、通常、次のようなワークフローを使用します。

1. エージェントのJARファイルをダウンロードします。
2. エージェントがOpenTelemetry SDKをどのように使用するかを設定するために、環境変数またはシステムプロパティを設定します。
3. -javaagent JVM引数でエージェントjarへのパスを参照した上でアプリケーションを実行します。

サンプルプロジェクトでは、Gradleのビルドで定義されたタスクによってこれらのステップを実行します。あなたのアプリケーションのビルドや環境に合わせて、これらのタスクを調整する必要があります。

次のビデオは、OpenTelemetryをJavaエージェントで実行する方法を示しています。

次回のブログでは、ローカルでコレクターをセットアップし、データをバックエンドプラットフォームに送信して視覚化と分析を行う方法をご紹介します。