モジュール jdk.jfr

パッケージ jdk.jfr

このパッケージには、イベントを作成してFlight Recorderを制御するためのクラスが含まれています。

イベントの定義

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の文字列表現の後に空白があり、次のいずれかの単位が続きます:

"ns" (nanoseconds)
"us" (microseconds)
"ms" (milliseconds)
"s" (seconds)
"m" (minutes)
"h" (hours)
"d" (days)
"0",
"10 ms",
"1秒"
period 定期的な場合は、イベントを発行する間隔。 "everyChunk" "everyChunk"、ファイルのローテーションごとに定期的なイベントを出力する必要がある場合はLongの正の文字列、空白のスペース、および次の単位のいずれかを指定します:

"ns" (nanoseconds)
"us" (microseconds)
"ms" (milliseconds)
"s" (seconds)
"m" (minutes)
"h" (hours)
"d" (days)
"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/をご覧ください。