モジュール jdk.jfr

パッケージ jdk.jfr

このパッケージは、イベントを作成してFlight Recorderを制御するクラスを提供します。

イベントの定義

Flight Recorderでは、データをイベントとして収集します。 イベントにはタイムスタンプ、継続時間および通常はアプリケーション固有のペイロードがあり、実行中のアプリケーションを障害またはクラッシュにまで診断する際に役立ちます。

Flight Recorderイベントを定義するには、Eventを拡張し、ペイロードのデータ型と一致するフィールドを追加します。 フィールドに関するメタデータ(ラベル、説明およびユニットなど)を追加するには、jdk.jfrパッケージで使用可能な注釈を使用するか、MetadataDefinition注釈を持つユーザー定義注釈を使用します。

イベント・クラスを定義すると、インスタンスは(イベント・オブジェクト)を作成できます。 データは、フィールドにデータを割り当てることで、イベントに格納されます。 イベントのタイミングは、Eventクラスで使用可能なbeginおよびendメソッドを使用して明示的に制御できます。

イベントに格納するデータの収集にはコストがかかる場合があります。 Event.shouldCommit()メソッドを使用すると、Event#commit()メソッドが呼び出されたときにイベント・インスタンスが実際にシステムに書き込まれるかどうかを検証できます。 Event.shouldCommit()がfalseを戻す場合は、これらの操作を回避できます。

コンパイル時にイベントのフィールド・レイアウトがわからないことがあります。 その場合は、イベントを動的に定義できます。 ただし、動的イベントのパフォーマンスは、静的に定義されたイベントとは異なり、レイアウトを知らなくてもデータを識別およびビジュアル化できない場合があります。

イベントを動的に定義するには、EventFactoryクラスを使用し、ValueDescriptorクラスを使用してフィールドを定義し、AnnotationElementクラスを使用して注釈を定義します。 ファクトリを使用してイベントを割り当て、Event.set(int, Object)メソッドを使用してイベントを設定します。

Flight Recorderの制御

Flight Recorderは、jcmdコマンドライン・ツールを使用するか、プラットフォームMBeanServerに登録されたFlightRecorderMXBeanインタフェースを使用してリモートで制御できます。 直接プログラム・アクセスが必要な場合は、FlightRecorder.getFlightRecorder()を起動することによってFlight Recorderインスタンスを取得でき、レコードの量が構成されるRecordingクラスを使用して、レコーディングが作成されます。

設定と構成

設定は名前と値のペアで構成され、nameは構成するイベントと設定を示し、valueはその設定内容を示します。

名前は、次の方法で構成できます。

<event-name> + "#" + <setting-name>

or

<event-id> + "#" + <setting-name>

たとえば、CPU負荷イベントのサンプル間隔を1秒ごとに1回設定するには、"jdk.CPULoad#period"という名前と"1 s"という値を使用します。 複数のイベントが同じ名前を使用する場合、たとえばイベント・クラスが複数のクラス・ローダーにロードされ、それらの間に区別が必要な場合、名前は"56#period"になります。 イベントのIDはEventType.getId()メソッドを呼び出して取得され、イベントが登録されているJava Virtual Machineインスタンスに有効です。

使用可能なイベント名のリストは、FlightRecorder.getEventTypes()およびEventType.getName()を起動することによって取得されます。 イベント・タイプに使用可能な設定のリストは、EventType.getSettingDescriptors()およびValueDescriptor.getName()を起動することで取得されます。

事前定義済設定

イベント設定名とその目的。

名前	説明	デフォルト値	書式	値の例
enabled	イベントが記録されるかどうかを指定します	"true"	Boolean ("true"または"false")の文字列表現	"true" "false"
threshold	イベントが記録されない期間を指定します	"0" (制限なし)	しきい値が使用されていない場合はLongの文字列表現、スペースおよび次のユニットのいずれかが続く場合は、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

インタフェースのサマリー

インタフェース	説明
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	文または2つを使用して要素を記述する注釈。
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	イベント・フィールド注釈は、値が符号なしデータ型であることを示します。