Javaで分散トレーシング with OpenTelemetry — JJUG CCC 2025 Fall スポンサー LT 書き起こし #jjug_ccc

Mackerel のトレーシング機能では OpenTelemetry という標準化された技術を採用しています。

今回 Mackerel として Java のコミュニティカンファレンスである JJUG CCC に初めてスポンサーさせていただき、スポンサー LT の機会をいただきました。サービスや会社の紹介よりも技術的な内容の方が少しでも楽しんでいただけると考え OpenTelemetry を用いて Java アプリケーションからトレーシングを取得する初めの一歩をご紹介しました。

以下当日お話しした内容を書き起こしたものです。

システムのオブザーバビリティ高められていますか？
分散トレーシングとは
OpenTelemetry とは
初めの一歩は簡単2ステップ
- 1. OpenTelemetry Java Agent をダウンロード
- 2. ダウンロードした Java Agent とトレースのエクスポート先を指定してアプリケーションを起動
取得できたトレースの確認
次の一歩
- Java WebアプリケーションのOpenTelemetry計装ガイド

システムのオブザーバビリティ高められていますか？

メトリックの監視をすると個々のサーバの異常に気づくことができます。しかし、異常に気付いた後にこんな対応をせざるを得ないという状況を見たり聞いたりしたことはないでしょうか。

🔥 障害発生
- 👀 ログを目 grep してエラー箇所を特定
- 👀 熟練の経験と勘でメトリックを睨み問題のあるシステムを特定

こういった状況の改善を進めるために、分散トレーシングを導入しシステムのオブザーバビリティを高めよう！というのが本トークのテーマです。すぐにお試しいただける初めの一歩をご紹介します！

分散トレーシングとは

分散トレーシングとは、リクエストやトランザクション全体の流れを記録して可視化する技術です。テクノロジーの発展やサービス要件の複雑化に伴いシステムも複雑化しているという背景の中で、個々のシステムのメトリックを監視するだけでは「異常」は検知できても「原因」の特定が困難になってきています。

分散トレーシングを活用することで、システムのどこでどのように問題が起きているかという原因により近づきやすくなります。

OpenTelemetry とは

OpenTelemetry とはメトリック、ログ、トレースなどのオブザーバビリティのためのテレメトリデータの生成・収集・エクスポートのためのフレームワークでありツールキットです。これらテレメトリデータの仕様やセマンティック規約、プロトコル、API、SDK などを内包しています。また、ベンダーニュートラルを掲げオープンソースとして開発されています。

OpenTelemetryとは | OpenTelemetry

今回は OpenTelemetry のプロジェクトで開発されている Java Agent の使い方をご紹介します。以下のステップに沿って OpenTelemetry を活用し、分散トレーシングで Java アプリケーションを可視化してみましょう！

初めの一歩は簡単2ステップ

1. OpenTelemetry Java Agent をダウンロード

GitHub リポジトリのリリースページに JAR ファイルが用意されているのでダウンロードします

open-telemetry/opentelemetry-java-instrumentation: OpenTelemetry auto-instrumentation and instrumentation libraries for Java
- Releases · open-telemetry/opentelemetry-java-instrumentation

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

2. ダウンロードした Java Agent とトレースのエクスポート先を指定してアプリケーションを起動

-javaagent オプションで先ほどダウンロードした Java Agent のパスを指定します。さらにトレースのエクスポート先や認証のための API キーも指定して起動します。環境変数 MACKEREL_APIKEY には Web コンソールから確認できる API キーを指定してください。

また、今回は build/libs/demo-0.0.1-SNAPSHOT.jar としてビルドした Spring Boot アプリケーションを指定しています。

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=jjug-ccc-2025-sample-java-app \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.endpoint=https://otlp-vaxila.mackerelio.com \
  -Dotel.exporter.otlp.headers="Accept=*/*,Mackerel-Api-Key=${MACKEREL_APIKEY}" \
  -jar build/libs/demo-0.0.1-SNAPSHOT.jar

プロパティファイルや環境変数で設定することもできます。

プロパティファイルでの例:

otel.service.name=jjug-ccc-2025-sample-java-app
otel.exporter.otlp.protocol=http/protobuf
otel.exporter.otlp.endpoint=https://otlp-vaxila.mackerelio.com
otel.exporter.otlp.headers=Accept=*/*,Mackerel-Api-Key=${MACKEREL_APIKEY}

java -javaagent:opentelemetry-javaagent.jar \
  -Dspring.config.location=application.properties \
  -jar build/libs/demo-0.0.1-SNAPSHOT.jar

環境変数での例:

OTEL_SERVICE_NAME=jjug-ccc-2025-sample-java-app
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-vaxila.mackerelio.com
OTEL_EXPORTER_OTLP_HEADERS=Accept=*/*,Mackerel-Api-Key=${MACKEREL_APIKEY}

java -javaagent:opentelemetry-javaagent.jar \
  -jar build/libs/demo-0.0.1-SNAPSHOT.jar

取得できたトレースの確認

Java Agent を指定してアプリケーションを起動し、エンドポイントにアクセスしてみます。すると以下のようなトレースがエクスポートされリクエストが可視化されます。

アプリケーションに手を入れたり特別な設定をしていないにも関わらず、/products というエンドポイントとそこから呼び出されているリポジトリ層、エンティティ層が可視化され、最終的に発行されている SQL まで確認できます。これはゼロコード計装と呼ばれる仕組みで、一般的なライブラリやフレームワークからテレメトリーデータを自動的に取得してくれます。

次の一歩

Java アプリケーションのリクエストを OpenTelemetry によって可視化するための初めの一歩をご紹介しました。まずシステムの理解を進めるためにゼロコード計装から初め、必要に応じて手動計装でシステム固有のビジネスロジックなども可視化していくと、よりオブザーバビリティを高めることができます。

実際に動かせるサンプルアプリケーションを題材に、ゼロコード計装や手動計装のやり方を詳細に解説した計装ガイドが以下からダウンロードできます。

Java WebアプリケーションのOpenTelemetry計装ガイド

OpenTelemetryの基本概念（トレーシング、スパン）から入り、コード修正不要なJava Agentによるゼロコード計装、さらに詳細な情報を取得するための手動計装の方法を、Spring Bootのサンプルアプリケーションを用いて実践的に紹介します。

計装ガイドをダウンロードする

ブログ

#mackerelio