jcmdコマンドの基本的な流れ
jcmdは、実行中のJavaアプリケーションに対し、コマンドを送信して情報取得や制御を行うための、JDKに含まれるツールです。jcmdコマンドを通じてJFRを操作するには、以下のコマンドを使います。
$jcmd <PID> [JFRのコマンド] [その他オプション]
したがって、起動しているJavaプロセスIDの把握が必要です。jpsコマンドや、OSで提供されているpsコマンドなどを使って確認できます。
JFRの記録を開始する
JFR のプロファイリング録を開始するには、以下のjcmdを実行します。
$jcmd <PID> JFR.start [オプション] // JFR.startのヘルプを参照する場合 $jcmd <PID> JFR.start -h
また、主に以下のオプションがあります。
| オプション | 説明 | 値の例 |
|---|---|---|
| name | 記録を管理する名称です。停止させる場合などに識別できるIDになります。 | rec_profile |
| duration | 記録を自動で停止するまでの継続時間を指定します。省略すると記録は無期限で継続します。 | 1m（1分）、 3h（3時間） |
| filename | 記録データを保存するファイルのパスを指定します。絶対パスで記述することを推奨。 | /tmp/recording.jfr |
| disk | 記録データをディスクに書き込むかどうかを指定します。 | falseまたはtrue |
| maxage | プロファイル用のメモリに保存するデータの最大期間を指定します。 | 1h（1時間） |
| maxsize | ディスクに保存するデータの最大サイズを指定します（disk=trueの場合のみ有効）。 | 25m |
| dumponexit | Javaのプロセスが終了したときに自動的にファイルにデータを書き出します。 | falseまたはtrue |
| settings | JFRの記録条件などの設定ファイル（jfcファイル）パスを指定します。 | /tmp/profile.jfc（作成方法は後述） |
例えば、自動的にファイルをローテートさせるならば、以下のコマンドで可能です。
$jcmd <PID> JFR.start \
name=rec_profile \
disk=true \
maxsize=250m \
maxage=1h \
filename=/tmp/jfr_report_%t.jfr // (1) ファイル名
（1）のようにファイル名に%tを含めると、「年_月_日_時_分_秒」に置き換わります。
このように、JFRは 24時間365日、動作中のJavaアプリケーションを監視し、問題発生時にその原因などが調査できるプロファイリング情報を提供するツールです。
JFRのプロファイリングデータの取得
JFRのプロファイリングデータは、任意のタイミングでも取得が可能です。この場合には、以下のコマンドで可能です。
$jcmd <PID> JFR.dump name=<記録名> filename=<ファイルパス>
このとき、ファイル名は絶対パスで記述するようにしてください。相対パスで記述すると、jcmdを実行しているディレクトリではなく、対象のJavaプログラムから見た相対パスになってしまいます。
このdumpコマンドは、死活監視やJMXなどの別手段でJavaプロセスやリソースを監視しており、アラートに応じて実行中のJavaプログラムの状況を即座に知りたい場合などに有効です。
JFRの記録停止
JFRのプロファイリングは、任意のタイミングで停止できます。
$jcmd <PID> JFR.stop name=<記録名> filename=<ファイルパス>
filenameを指定しない場合には、プロファイリングデータは出力されずに終了します。
JFRのプロファイリング設定ファイルを作成する
JFRを用いたプロファイリングでは、設定ファイル（.jfc形式）が利用可能です。この設定ファイルを事前に用意しておくことで、XML形式でプロファイリング条件をカスタマイズ／再利用でき、運用保守性が高まります。
$jfr configure --output [設定ファイル] [オプション]
作成された設定ファイルは、例えば次のようにsettingsオプションで指定してプロファイリングを開始できます。
$jcmd <PID> JFR.start settings=profile.jfc
設定ファイルは、手動で編集して「どのイベントを記録するか」「閾値は何か」「フィルタはどうか」などを細かく指定できます。ただし、duration／filename／maxsizeなど、録画そのもののメタオプションについては、設定ファイルではなく、JFRを開始するコマンド（例：JFR.start filename=... duration=...）で指定する必要があります。
なお、編集した設定ファイルを用いるには、変更を反映させるためにJFRを再起動するか、新しい録画を開始しなければなりません。
なお、ここで出力された設定ファイルの基本的なルールはAPIリファレンスにあります。
ただし、それぞれの設定は、実装依存として明確に整理されたドキュメントがないのが現状です。そのため、「<JDKのパス>/lib/jfr/default.jfc」もしくは、「<JDKのパス>/lib/jfr/profile.jfc」なども同時に参考にしてください。
