JMX メトリクス

OpenTelemetry を使用して JMX MBean からメトリクスを収集します

このページでは、JMX (Java Management Extensions) MBean からメトリクスを収集し、OpenTelemetry にエクスポートする方法を説明します。

概要

JMX (Java Management Extensions) は、JMX MBean (Managed Bean) を介してアプリケーションを管理・監視するためのツールを提供する Java の技術です。これらの MBean は外部から観測可能な管理用の属性や操作を公開します。

OpenTelemetry の JMX Metric Insight モジュールを使うと、JMX メトリクスを OpenTelemetry にブリッジでき、次のことが可能になります。

JVM メトリクス（メモリ、ガベージコレクション、スレッドなど）の監視
アプリケーション固有の MBean からのメトリクス収集
JMX データを他の OpenTelemetry テレメトリーシグナルと並べてエクスポート
人気のあるターゲットシステム（Tomcat、Jetty、Wildfly など）向けの定義済みメトリクスマッピングの利用

インストール

Java エージェントを使用する

JMX メトリクスを収集する最も簡単な方法は、JMX メトリクス拡張を備えた OpenTelemetry Java エージェントを使用することです。

OpenTelemetry Java エージェントをダウンロードします（まだインストールしていない場合）。

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

エージェントを使用してアプリケーションを実行し、JMX メトリクスを有効化します。

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.jmx.target.system=tomcat \
  -Dotel.jmx.config=/path/to/custom-metrics.yaml \
  -jar myapp.jar

JMX メトリクス収集は、次の設定オプションのいずれか（または両方）を設定することで有効になります。

otel.jmx.target.system で有効化する定義済みメトリクスセットを選択する
otel.jmx.config でカスタム JMX ルールへのパスを指定する

Java エージェントを使用する場合、JVM ランタイムメトリクス（CPU、メモリなど）は runtime-telemetry モジュールを通じて取得され、追加の設定なしでデフォルトで有効になっています。

設定

JMX メトリクスは 2 つの方法で収集できます。

JVM の内部から: Java エージェントを使用して内部 JMX インターフェイスから収集
JVM の外部から: JMX Scraper を使用してリモート JMX インターフェイスから収集

Java エージェントの設定

OpenTelemetry Java エージェントを使用する場合、次のプロパティで JMX メトリクスを設定します。

システムプロパティ	環境変数	説明	デフォルト
`otel.jmx.enabled`	`OTEL_JMX_ENABLED`	JMX メトリクス収集を有効化	`true`
`otel.jmx.target.system`	`OTEL_JMX_TARGET_SYSTEM`	使用する定義済みメトリクスセットのカンマ区切りリスト	なし
`otel.jmx.config`	`OTEL_JMX_CONFIG`	メトリクスマッピング用のカスタム YAML へのパス	なし

JMX Scraper の設定

スタンドアロンの JMX Scraper を使用してリモート JVM からメトリクスを収集する場合、次のプロパティで設定します（注: otel.jmx.enabled は不要です）。

システムプロパティ	環境変数	説明	デフォルト
`otel.jmx.service.url`	`OTEL_JMX_SERVICE_URL`	リモート JVM 接続用の JMX サービス URL	（必須）
`otel.jmx.target.system`	`OTEL_JMX_TARGET_SYSTEM`	使用する定義済みメトリクスセットのカンマ区切りリスト	なし
`otel.jmx.config`	`OTEL_JMX_CONFIG`	メトリクスマッピング用のカスタム YAML へのパス	なし

完全な設定リファレンスは JMX Scraper ドキュメントを参照してください。

リモート JVM はリモート JMX 接続を受け付けるように設定されている必要があることに注意してください。 jconsole や visualvm ツールを使用して接続できることを最初に確認することで、設定とオプションの認証が期待どおりに動作していることを確認できます。

定義済みターゲットシステム

OpenTelemetry は、人気のある Java フレームワークおよびアプリケーションサーバー向けの定義済みメトリクスマッピングを提供します。 otel.jmx.target.system プロパティを使用してそれらを有効化します（Java エージェントと JMX Scraper の両方で利用可能）。

例 - Tomcat の監視（Java エージェント）:

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.jmx.target.system=tomcat \
  -jar myapp.jar

利用可能なターゲットシステムの完全なリストは次を参照してください。

複数のターゲットシステムをカンマで区切って指定できます。

リモート JMX 接続

リモート JVM からメトリクスを収集するには、JMX Scraper を使用する必要があります。これには 2 つの別々の JVM が関係します。

ターゲット JVM - 監視されるアプリケーション
Scraper JVM - JMX メトリクススクレイパー

ステップ 1: ターゲット JVM の設定

まず、JMX リモートを有効にしてターゲットアプリケーションを起動します。

java -Dcom.sun.management.jmxremote \
  -Dcom.sun.management.jmxremote.port=9999 \
  -Dcom.sun.management.jmxremote.authenticate=false \
  -Dcom.sun.management.jmxremote.ssl=false \
  -jar myapp.jar

上記の例では、単純さのために認証と SSL を無効化しています。

本番環境では、JMX 接続に対して必ず認証と SSL を有効化してください。

ステップ 2: JMX Scraper の実行

OpenTelemetry Java Contrib のリリースページから JMX Scraper をダウンロードします（opentelemetry-jmx-scraper-<version>-all.jar を探してください）。

次に、スクレイパーを実行してターゲット JVM を指定します。

java -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://tomcat.example.com:9999/jmxrmi \
  -Dotel.jmx.target.system=tomcat \
  -jar opentelemetry-jmx-scraper.jar

Java エージェントと同じプロパティ（ターゲットシステム、収集間隔など）を使用してスクレイパーを設定できます。

詳細は JMX Scraper ドキュメントを参照してください。

非推奨となった JMX Metric Gatherer から移行する場合は、移行ガイドを参照してください。

カスタムメトリクスマッピング

アプリケーション固有の MBean やカスタムの監視要件に対しては、YAML 設定ファイルを使用してカスタムメトリクスマッピングを作成できます。

カスタム YAML 設定の作成

JMX 属性を OpenTelemetry メトリクスにマッピングする方法を定義する YAML ファイルを作成します。

例 - custom-jmx-metrics.yaml:

rules:
  - bean: com.myapp:type=CustomMetrics
    mapping:
      RequestCount:
        metric: myapp.requests.count
        type: counter
        description: Total request count
        unit: '1'
      ResponseTime:
        metric: myapp.response.time
        type: gauge
        description: Average response time
        unit: ms
      ActiveSessions:
        metric: myapp.sessions.active
        type: updowncounter
        description: Active sessions
        unit: '1'

このファイルをアプリケーションで使用します。

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.jmx.config=/path/to/custom-jmx-metrics.yaml \
  -jar myapp.jar

YAML 構文の完全なリファレンスは JMX メトリクス設定ドキュメントを参照してください。

検証

JMX メトリクスが収集されていることを検証するには:

ログを確認する - JMX メトリクス収集が開始されたことを示すメッセージを探します
ロギングエクスポーターを使用する - バックエンドを必要とせずにコンソールでメトリクスを確認するために、ロギングエクスポーターを設定します
メトリクスバックエンドを使用する - OTLP エクスポーターを設定し、オブザーバビリティプラットフォームでメトリクスを表示します
JConsole を使用する - JConsole でアプリケーションに接続して、MBean にアクセスできることを確認します

例 - ロギングエクスポーターを使用（Java エージェント）:

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.metrics.exporter=logging \
  -jar myapp.jar

例 - OTLP エクスポーターを使用（Java エージェント）:

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.metrics.exporter=otlp \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -jar myapp.jar

例 - OTLP エクスポーターを使用（JMX Scraper）:

java -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://myapp.example.com:9999/jmxrmi \
  -Dotel.jmx.target.system=tomcat \
  -Dotel.metrics.exporter=otlp \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -jar opentelemetry-jmx-scraper.jar

追加リソース

JMX Scraper ドキュメント - 完全な設定リファレンスと例
JMX Scraper 移行ガイド - 非推奨となった JMX Metric Gatherer からの移行
JMX メトリクス（Java エージェント） - Java エージェントの JMX メトリクスドキュメント
定義済みターゲットシステム - 人気のあるフレームワーク向けの組み込みメトリクスセット
Java エージェントドキュメント - 一般的な Java エージェントの設定
設定ガイド - OpenTelemetry SDK 設定オプション

計装エコシステム - その他の計装オプション
シム - 他のオブザーバビリティライブラリのブリッジ
メトリクス API - カスタムメトリクスの作成

フィードバック

このページは役に立ちましたか?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

最終更新 June 7, 2026: [ja] add translation of content/en/docs/languages/java/jmx.md (#10105) (4b99ea56)