パッケージ jdk.jfr
イベントの定義
Flight Recorderのデータはイベントに格納されます。 イベントにはタイムスタンプ、継続時間、通常アプリケーション固有のペイロードがあり、障害/クラッシュまでのアプリケーションの診断に役立ちます。
Flight Recorderイベントを定義するには、Event
を拡張し、記録するペイロードのデータ型に一致するフィールドを追加します。 ラベル、説明、単位などのフィールドに関するメタデータは、jdk.jfr.annotation
パッケージで使用可能な注釈を使用して追加できます。または、ユーザー定義の注釈を(MetadataDefinition
注釈がある場合)で使用できます。
イベント・クラスが定義されると、個々のインスタンスを作成することができます((イベント・オブジェクト))。 データは、フィールドに割り当てることによってイベントに格納されます。 イベントのタイミングは、Event
クラスで使用可能なbegin
およびend
メソッドを使用して明示的に制御できます。
Flight Recorderシステムに実際にデータを格納するには、Event.commit()
メソッドを使用します。 イベントに格納するためにデータを収集するのが比較的高価な場合、アプリケーションはコミットする呼び出しでイベントがコミットされる場合にEvent.shouldCommit()
を使用して分岐することで、高価な操作を不必要に避けることができます。
コンパイル時にイベントのフィールド・レイアウトがわからないことがあります。 そうであれば、イベントを動的に定義することができます。 しかし、動的イベントには2つの欠点があります。静的に定義されたものと同じパフォーマンスを持たない場合や、レイアウトを知らなくてもツールがデータを識別して視覚化することは通常困難です。
イベントを動的に定義するには、EventFactory
を使用し、ValueDescriptor
クラスとAnnotationElement
クラスを使用する注釈を使用してフィールドを定義します。 ファクトリを使用してイベントを割り当て、Event.set(int, Object)
メソッドを使用してイベントを設定します。
Flight Recorderの制御
Flight Recorderは、jcmd
コマンドライン・ツールを使用するか、プラットフォームMBeanServerに登録されたFlightRecorderMXBean
を使用してJMX経由で制御することができます。 通常、ほとんどのユースケースではこれで十分ですが、直接的なプログラムによるアクセスが必要な場合は、FlightRecorder.getFlightRecorder()
を呼び出すことでインスタンスを取得できます。 Flight Recorderインスタンスを使用すると、Recording
を作成できます。Recording
から、記録するデータの量を構成できます。
設定と構成
設定は名前の値のペアで構成されます。ここで、nameは設定するイベントと設定を指定し、valueは設定する内容を決定します。
名前は2つの方法で形成することができますが、
<event-name> + "#" + <setting-name>
or
<event-id> + "#" + <setting-name>
たとえば、CPU Loadイベントのサンプル間隔を毎秒1回に設定するには、名前を"com.oracle.jdk.CPULoad#period"
と値"1 s"
にする必要があります。 イベント・クラスが複数のクラス・ローダーにロードされ、それらの間で区別が必要な場合など、複数のイベントが同じ名前を使用する場合は、2番目の形式を使用できます(例:"56#period"
)。 イベントのidはEventType.getId()
を呼び出すことで取得でき、イベントが登録されたJVMインスタンスに対してのみ有効です。
使用可能なイベント名のリストは、FlightRecorder.getEventTypes()
とEventType.getName()
を呼び出すことで取得できます。 EventType.getSettingDescriptors()
とValueDescriptor.getName()
を呼び出すと、イベント・タイプの利用可能な設定のリストを取得できます。
JDKには、次の定義済みの設定があります。
名 | 説明 | デフォルト値 | Format | 値の例 |
---|---|---|---|---|
enabled |
イベントをすべて記録する必要がある場合 | "true" |
Boolean ("true" または"false" )の文字列表現 |
"true" , "false" |
threshold |
イベントが記録されないはずのカットオフ | "0" (制限なし) |
"0" しきい値を使用しない場合はそれ以外の場合は、正のLong の文字列表現の後に空白があり、次のいずれかの単位が続きます:
| "0" , "10 ms" , "1秒" |
period |
定期的な場合は、イベントを発行する間隔。 | "everyChunk" |
"everyChunk" 、ファイルのローテーションごとに定期的なイベントを出力する必要がある場合はLong の正の文字列、空白のスペース、および次の単位のいずれかを指定します:
|
"20 ms" , "1 s" , "everyChunk" |
stackTrace |
Event#commit() メソッドからのスタック・トレースを記録する必要がある場合 |
"true" |
Boolean ("true" または"false" )の文字列表現 |
"true" , "false" |
Null-handling
すべてのメソッドは、Javadocでnull
を受け入れるか返すかを定義します。 通常これは"not null"
で表されます。 null
パラメータが使用されない場合は、java.lang.NullPointerException
がスローされます。 null
パラメータがjava.io.IOException
のような他の例外をスローするメソッドに渡された場合、メソッドのJavadocがnull
の処理方法、つまりjava.lang.IllegalArgumentException
を明示的に指定しない限り、java.lang.NullPointerException
が優先されます。
- 導入されたバージョン:
- 9
- 商用機能
- これは、使用する前にロックを解除する必要のある商用機能です。 商用機能の詳細とロック解除方法については、http://www.oracle.com/technetwork/java/javaseproducts/をご覧ください。
-
インタフェースのサマリー インタフェース 説明 FlightRecorderListener Flight Recorderのライフサイクルを監視するためのコールバック・インタフェース。 -
クラスのサマリー クラス 説明 AnnotationElement ラベル、説明、ユニットなどのイベント・メタデータについて説明します。Configuration 構成を記述する構成とメタデータの集まり。Event イベントのベース・クラスで、イベントとそのフィールドを定義するためにサブクラス化されます。EventFactory 実行時にイベントを定義するクラス。EventSettings 記録にイベント設定を適用するための簡易クラスです。EventType イベント、フィールド、設定、注釈を記述します。FlightRecorder Flight Recorderへのアクセス、制御、管理のためのクラス。FlightRecorderPermission Flight Recorderへのアクセスを制御するための許可。Recording 記録データをディスクに構成、開始、停止、ダンプする手段を提供します。SettingControl 設定コントロールを作成するための基本クラス。SettingDescriptor イベント設定を記述ValueDescriptor イベント・フィールドと注釈要素について説明します。 -
列挙型のサマリー 列挙型 説明 RecordingState 記録のライフサイクルの状態を示します。 -
注釈型のサマリー 注釈型 説明 BooleanFlag イベント・フィールドの注釈で、値がブール値フラグ、true
またはfalse
値であることを示します。Category イベントの注釈。イベントのタイプを人間が判読可能な形式でカテゴリに関連付けます。ContentType メタ注釈は、注釈がタイムスパンや頻度などのコンテンツ・タイプを表すことを示します。DataAmount イベント・フィールド注釈は、値がデータの量(バイトなど)を表すことを示します。Description 1つまたは複数の要素を記述する注釈。Enabled イベント注釈は、デフォルトでイベントを有効にするかどうかを決定します。Experimental 要素が実験的であり、今後の予告なしに変更される可能性があることを示す注釈。Frequency イベント・フィールド注釈は、その値がHzで測定された周波数であることを示します。Label 要素に人間が判読可能な名前を設定する注釈です(例:"Maximum Throughput"
)。MemoryAddress イベント・フィールドの注釈で、値がメモリー・アドレスであることを示します。MetadataDefinition 新しいタイプのイベント・メタデータを定義するためのメタ注釈。Name たとえば、イベントのデフォルト・パッケージが適切でない場合など、要素のデフォルト名を上書きする注釈。Percentage 典型的には0.0
と1.0
の間の分数で使用されるイベント・フィールド注釈で、値がパーセンテージであることを示します。Period イベント注釈は、定期イベントのデフォルト期間を決定します。Registered プログラムによるイベント登録のためのイベント注釈。Relational 注釈に使用されるリレーショナル注釈のメタ注釈。SettingDefinition イベントをフィルタリングするためにイベント・クラスのメソッドを使用する必要があることを示す注釈。StackTrace イベント注釈は、イベントがデフォルトでスタック・トレースを持つかどうかを決定します。Threshold イベント注釈は、"20 ms"
など、イベントを記録しないデフォルトのカットオフを決定します。Timespan イベント・フィールドの注釈で、値が継続時間であることを示します。Timestamp イベント・フィールドの注釈で、値がある時点であることを示します。TransitionFrom イベント・フィールド注釈は、イベントがスレッドから遷移したことを示します。TransitionTo イベント・フィールド注釈は、イベントがスレッドに移行しようとしていることを示します。Unsigned イベント・フィールドの注釈で、値が符号なしデータ型であることを示します。