Appearance

メトリックプラグイン - mackerel-plugin-jvm ​

mackerel-plugin-jvm は jstat/jinfo/jps などのコマンドからJVMに関する各種メトリックを取得します。

本プラグインはJVMオプションにPerfDisableSharedMemが指定されている場合に動作しません。詳しくはこちらをご確認ください。

仕様

--javaname に指定したアプリケーションの lvmid、もしくは --pidfile に指定した pid ファイルに書かれているプロセス ID に対して、以下の jstat コマンドを実行し、出力された結果をもとにメトリックとして投稿します。メトリック名の最後のドット（.）より後の名前が、jstat コマンドによって取得できる各情報に対応しています。

  • jstat -gc
  • jstat -gccapacity
  • jstat -gcnew
  • jstat -gcold

監視できるメトリック

メトリック名やグラフ名の<javaname>には、--javanameオプションに指定したアプリケーション名が使用されます。

  • --metric-keyオプションの指定がある場合、メトリック名にはこちらに指定した文字列が使用されます。
  • --metric-labelオプションの指定がある場合、グラフ名にはこちらに指定した文字列が使用されます。

JVM <javaname> GC events ​

メトリック表示名メトリック名差分積み上げ表示説明
Young GC eventcustom.jvm.<javaname>.gc_events.YGC◯-Young GCの回数
Full GC eventcustom.jvm.<javaname>.gc_events.FGC◯-Full GCの回数
Concurrent GC eventcustom.jvm.<javaname>.gc_events.CGC◯-Concurrent GCの回数（Java11以降）

JVM <javaname> GC time (sec) ​

メトリック表示名メトリック名差分積み上げ表示説明
Young GC timecustom.jvm.<javaname>.gc_time.YGCT◯-Young GCの実行時間
Full GC timecustom.jvm.<javaname>.gc_time.FGCT◯-Full GCの実行時間
Concurrent GC timecustom.jvm.<javaname>.gc_time.CGCT◯-Concurrent GCの実行時間（Java11以降）

JVM <javaname> GC time percentage ​

メトリック表示名メトリック名差分積み上げ表示説明
Young GC timecustom.jvm.<javaname>.gc_time_percentage.YGCT◯-Young GCが60秒あたりのGC時間に占める割合
Full GC timecustom.jvm.<javaname>.gc_time_percentage.FGCT◯-Full GCが60秒あたりのGC時間に占める割合
Concurrent GC timecustom.jvm.<javaname>.gc_time_percentage.CGCT◯-Concurrent GCが60秒あたりのGC時間に占める割合（Java11以降）

JVM <javaname> New Space memory ​

メトリック表示名メトリック名差分積み上げ表示説明
New maxcustom.jvm.<javaname>.new_space.NGCMX--New世代の最大容量（KB）
New currentcustom.jvm.<javaname>.new_space.NGC--New世代の現在の容量（KB）
Eden usedcustom.jvm.<javaname>.new_space.EU--Eden領域の使用量（KB）
Survivor0 usedcustom.jvm.<javaname>.new_space.S0U--Survivor領域0の現在の容量（B）
Survivor1 usedcustom.jvm.<javaname>.new_space.S1U--Survivor領域1の現在の容量（KB）

JVM <javaname> Old Space memory ​

メトリック表示名メトリック名差分積み上げ表示説明
Old maxcustom.jvm.<javaname>.old_space.OGCMX--Old世代の最大容量（KB）
Old currentcustom.jvm.<javaname>.old_space.OGC--Old世代の現在の容量（KB）
Old usedcustom.jvm.<javaname>.old_space.OU--Old領域の使用量（KB）

JVM <javaname> Permanent Space ​

メトリック表示名メトリック名差分積み上げ表示説明
Perm maxcustom.jvm.<javaname>.perm_space.PGCMX--Permanent世代の最大容量 （KB）
Perm currentcustom.jvm.<javaname>.perm_space.PGC--Permanent世代の現在の容量 （KB）
Perm usedcustom.jvm.<javaname>.perm_space.PU--Permanent領域の使用量 （KB）
  • Java 8 以降は非対応です。

JVM <javaname> Metaspace ​

メトリック表示名メトリック名差分積み上げ表示説明
Metaspace capacity maxcustom.jvm.<javaname>.metaspace.MCMX--メタスペースの最大容量（KB）
Metaspace capacity mincustom.jvm.<javaname>.metaspace.MCMN--メタスペースの最小容量（KB）
Metaspace capacitycustom.jvm.<javaname>.metaspace.MC--メタスペースの容量（KB）
Metaspace utilizationcustom.jvm.<javaname>.metaspace.MU--メタスペースの使用量（KB）
Compressed Class Space Capacitycustom.jvm.<javaname>.metaspace.CCSC--圧縮されたクラス領域の容量（KB）
Compressed Class Space Usedcustom.jvm.<javaname>.metaspace.CCSU--使用されている圧縮されたクラス領域（KB）

JVM <javaname> MemorySpace ​

メトリック表示名メトリック名差分積み上げ表示説明
GC Old Memory Spacecustom.jvm.<javaname>.memorySpace.oldSpaceRate--Old世代の使用率
GC New Memory Spacecustom.jvm.<javaname>.memorySpace.newSpaceRate--New世代の使用率
CMS Initiating Occupancy Fractioncustom.jvm.<javaname>.memorySpace.CMSInitiatingOccupancyFraction--CMS GCを実行する閾値
  • GC Old Memory Space は (Old used / Old current ) * 100 で算出しています。
  • GC New Memory Space は (Survivor0 used + Survivor1 used + Eden used) / (Survivor0 current + Survivor1 current + Eden current) * 100 で算出しています。
  • CMS Initiating Occupancy Fraction は --remote オプションを指定した場合に投稿されません。
    • --remote オプションの指定がない場合は、情報取得の際に以下のコマンドが実行されます。
      • jinfo -flag UseConcMarkSweepGC
      • jinfo -flag CMSInitiatingOccupancyFraction

指定可能なオプション

プラグインに指定可能なオプションは以下の通りです。

オプション説明必須初期値
--hostjps/jstat のターゲットホスト名（非推奨）
--portjps/jstat のターゲットポート（非推奨）0
--remotejps/jstat のリモートターゲット。 hostname[:port][/servername]で指定
--jstatpathjstatコマンドのパス/usr/bin/jstat もしくは $JAVA_HOME/bin/jstat
--jinfopathjinfoコマンドのパス/usr/bin/jinfo もしくは $JAVA_HOME/bin/jinfo
--jpspathjpsコマンドのパス/usr/bin/jps もしくは $JAVA_HOME/bin/jps
--javaname監視対象のアプリケーション名○
--pidfilepidファイルのパス
--metric-keyメトリック名に使用する文字列--javaname に指定したアプリケーション名
--metric-labelグラフ名に使用する文字列列--javaname に指定したアプリケーション名
--tempfileTempファイル名
  • --remote オプションを指定する場合、jps および jstat は、このプラグインからローカルで実行可能である必要があります。
  • --javaname オプションに指定した名前のアプリケーションが複数存在する場合は、いずれか 1 つのメトリックのみ投稿されます。
    • 同一ホスト上の名前が重複する複数のアプリケーションを監視する場合は、アプリケーションごとにプラグインの設定を記述し、--pidfile オプションで監視対象にするアプリケーションの pid ファイルを指定してください。また、その際は --javaname または --metric-key と --metric-label に、アプリケーションごとに任意の異なる名前を指定してください（エージェントへの設定例 を参考にしてください）。

エージェントへの設定例

toml
[plugin.metrics.jvm-tomcat]
command = [ "mackerel-plugin-jvm", "--javaname", "tomcat", "--jstatpath", "/usr/bin/jstat", "--jpspath", "/usr/bin/jps", "--jinfopath", "/usr/bin/jinfo"]

同一ホスト上の名前が重複する複数のアプリケーションを監視する場合は、以下のように設定します。

toml
[plugin.metrics.app01]
command = ["mackerel-plugin-jvm", "--javaname", "app", "--pidfile", "/path/to/app01/app.pid", "--metric-key", "app01", "--metric-label", "app01"]

[plugin.metrics.app02]
command = ["mackerel-plugin-jvm", "--javaname", "app", "--pidfile", "/path/to/app02/app.pid", "--metric-key", "app02", "--metric-label", "app02"]

トラブルシューティング

mackerel-agentのログに Failed to run exec jinfo. jinfo command timed out. と出力されている ​

  • プラグインからjinfoのコマンドを実行する際に、一時的なホストの負荷などを要因としてタイムアウトが発生したものと考えられます。
  • 継続的に出力されている場合、手動にてjinfoコマンドを実行して状況をご確認ください。
  • 監視ルールのタイムアウト値（timeout_seconds）を調整することで回避できる場合もございます。設定項目を参考に調整してください。

リポジトリ

https://github.com/mackerelio/mackerel-agent-plugins/tree/master/mackerel-plugin-jvm