このドキュメントでは、オープンソースの OpenTelemetry フレームワークを使用してトレースと指標データを収集するように Java アプリを変更する方法と、構造化 JSON ログを標準出力に出力する方法について説明します。このドキュメントでは、インストールして実行できる Java Spring Boot アプリのサンプルについても説明します。このアプリは、指標、トレース、ログを生成するように構成されています。この手順は、Spring Boot Framework を使用しているかどうかにかかわらず同じです。
計測について詳しくは、次のドキュメントをご覧ください。
手動計測と自動計測について
このドキュメントで説明するインストルメンテーションでは、OpenTelemetry 自動インストルメンテーションを使用して Google Cloud プロジェクトにテレメトリーを送信します。Java の場合、自動インストルメンテーションとは、バイトコードをライブラリやフレームワークに動的に挿入してテレメトリーをキャプチャする手法です。自動インストルメンテーションでは、着信と発信の HTTP 呼び出しなどのテレメトリーを収集できます。詳細については、Java の自動インストルメンテーションをご覧ください。
OpenTelemetry には、独自のコードにカスタム計測を追加するための API も用意されています。OpenTelemetry では、これを手動インストルメンテーションと呼びます。このドキュメントでは、手動インストルメンテーションについては説明しません。このトピックの例と情報については、手動インストルメンテーションをご覧ください。
始める前に
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
アプリを計測してトレース、指標、ログを収集する
アプリを計測して、トレースと指標データを収集し、構造化 JSON を標準出力に出力するには、このドキュメントの以降のセクションで説明する手順を実施します。
OpenTelemetry Java エージェントを使用するようにアプリを構成する
構造化ログを書き込むようにアプリを構成し、OpenTelemetry を使用して指標とトレースデータを収集するには、OpenTelemetry Java Agent を使用するようにアプリの呼び出しを更新します。このアプリの計測方法は、アプリコードを変更する必要がないことから、自動計測と呼ばれます。
次のコードサンプルは、OpenTelemetry Java Agent JAR ファイルをダウンロードして、-javaagent
フラグを渡すようにコマンドライン呼び出しを更新する Dockerfile を示しています。
サンプル全体を表示するには、more_vert(その他)をクリックして、[GitHub で表示] を選択します。
また、JAVA_TOOL_OPTIONS
環境変数で -javaagent
フラグを設定することもできます。
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
OpenTelemetry を構成する
OpenTelemetry Java Agent のデフォルト構成では、OTLP プロトコルを使用してトレースと指標をエクスポートします。また、トレース コンテキストの伝播に W3C トレース コンテキスト形式を使用するように OpenTelemetry を構成します。この構成により、トレース内でスパンが正しい親子関係を持つことが保証されます。
詳細と構成オプションについては、OpenTelemetry Java 自動計測をご覧ください。
構造化ロギングを構成する
標準出力に書き込まれる JSON 形式のログにトレース情報を含めるには、構造化ログを JSON 形式で出力するようにアプリを構成します。ロギングの実装として Log4j2 を使用することをおすすめします。次のコードサンプルは、JSON テンプレート レイアウトを使用して JSON 構造化ログを出力するように構成された log4j2.xml
ファイルを示しています。
前の構成では、SLF4J のマッピングされた診断コンテキストから、アクティブなスパンに関する情報が抽出され、その情報が属性としてログに追加されます。これらの属性を使用して、ログをトレースに関連付けることができます。
logging.googleapis.com/trace
: ログエントリに関連付けられているトレースのリソース名。logging.googleapis.com/spanId
: ログエントリに関連付けられているトレースのスパン ID。logging.googleapis.com/trace_sampled
: このフィールドの値はtrue
またはfalse
にする必要があります。
これらのフィールドの詳細については、LogEntry
構造体をご覧ください。
構造化ログを書き込む
トレースにリンクする構造化ログを書き込むには、SLF4J ロギング API を使用します。たとえば、次のステートメントは Logger.info()
メソッドを呼び出す方法を示しています。
logger.info("handle /multi request with subRequests={}", subRequests);
OpenTelemetry Java エージェントは、OpenTelemetry Context で現在アクティブなスパンのスパン コンテキストを、SLF4J のマッピングされた診断コンテキストに自動的に挿入します。マッピングされた診断コンテキストは、構造化ロギングを構成するで説明されているように、JSON ログに含まれます。
テレメトリーを収集するように構成されたサンプルアプリを実行する
サンプルアプリでは、ログに JSON、指標とトレースに OTLP を使用し、さらに Spring Boot フレームワークを使用するなど、ベンダーに依存しない形式を使用しています。テレメトリーを Google Cloud にルーティングするため、このサンプルでは Google エクスポータで構成された OpenTelemetry Collector
を使用します。このアプリには 2 つのエンドポイントがあります。
/multi
エンドポイントは、handleMulti
関数によって処理されます。アプリの負荷生成ツールが/multi
エンドポイントにリクエストを発行します。このエンドポイントは、リクエストを受信すると、ローカル サーバーの/single
エンドポイントに 3~7 件のリクエストを送信します。/single
エンドポイントは、handleSingle
関数によって処理されます。このエンドポイントは、リクエストを受信すると、少しの間スリープしてから、文字列で応答します。
アプリをダウンロードしてデプロイする
サンプルを実行するには、次の操作を行います。
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
リポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java
サンプル ディレクトリに移動します。
cd opentelemetry-operations-java/examples/instrumentation-quickstart
サンプルをビルドして実行します。
docker compose up --abort-on-container-exit
Cloud Shell で実行していない場合は、認証情報ファイルを指す
GOOGLE_APPLICATION_CREDENTIALS
環境変数を使用してアプリケーションを実行します。アプリケーションのデフォルト認証情報は、$HOME/.config/gcloud/application_default_credentials.json
にある認証情報ファイルを提供します。# Set environment variables export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" export USERID="$(id -u)" # Run docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
指標を表示する
サンプルアプリの OpenTelemetry 計測は、Metrics Explorer で表示可能な Prometheus 指標を生成します。
Prometheus/http_server_duration_milliseconds/histogram
は、サーバー リクエストの所要時間を記録し、結果をヒストグラムに保存します。Prometheus/http_client_duration_milliseconds/histogram
は、クライアント リクエストの所要時間を記録し、結果をヒストグラムに保存します。
-
Google Cloud コンソールで、[leaderboardMetrics explorer] ページに移動します。
検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。
- [指標] 要素の [指標を選択] メニューを開いてフィルタバーに「
http_server
」と入力し、サブメニューを使用して特定のリソースタイプと指標を選択します。- [有効なリソース] メニューで、[Prometheus Target] を選択します。
- [有効な指標カテゴリ] メニューで、[Http] を選択します。
- [ACTIVE METRICS] メニューで指標を選択します。
- [適用] をクリックします。
- データの表示方法を構成します。
指標の測定値が累積の場合、Metrics Explorer はアライメント期間ごとに測定データを自動的に正規化し、グラフに率を表示します。詳細については、種類、タイプ、変換をご覧ください。
2 つの
counter
指標など、integer 値または double 値が測定されると、Metrics Explorer はすべての時系列を自動的に合計します。HTTP ルート/multi
と/single
のデータを表示するには、[集計] エントリの最初のメニューを [なし] に設定します。グラフの構成の詳細については、Metrics Explorer 使用時の指標の選択をご覧ください。
トレースを表示する
トレースデータを表示するには、次の操作を行います。
-
Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
このページは、検索バーを使用して見つけることもできます。
- 散布図で、URI が
/multi
のトレースを選択します。 [トレースの詳細] パネルのガントチャートで、
/multi
というラベルのスパンを選択します。パネルが開き、HTTP リクエストに関する情報が表示されます。詳細には、メソッド、ステータス コード、バイト数、呼び出し元のユーザー エージェントが含まれます。
このトレースに関連付けられているログを表示するには、[ログとイベント] タブを選択します。
このタブには、個々のログが表示されます。ログエントリの詳細を表示するには、ログエントリを開きます。[ログを表示] をクリックし、ログ エクスプローラを使用してログを表示することもできます。
Cloud Trace エクスプローラの使用方法について詳しくは、トレースを検索して調査するをご覧ください。
ログを表示する
ログ エクスプローラではログを調査できます。また、関連するトレース(存在する場合)を確認することもできます。
-
Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。
検索バーを使用してこのページを検索する場合は、小見出しが「Logging」の結果を選択します。
handle /multi request
の説明を含むログを見つけます。ログの詳細を表示するには、ログエントリを開きます。
「handle /multi request」メッセージを含むログエントリの [ トレース] をクリックし、[トレースの詳細表示] を選択します。
[トレースの詳細] パネルが開き、選択したトレースが表示されます。
ログ エクスプローラの使用方法については、ログ エクスプローラを使用してログを表示するをご覧ください。