パッケージjdk.jfr
イベントの定義
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の文字列表現。
| "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
-
クラス説明ラベル、説明、ユニットなどのイベント・メタデータについて説明します。イベント・フィールド注釈。値がブール・フラグ、
trueまたはfalse値であることを指定します。イベント・タイプをカテゴリに関連付けるイベント注釈(判読可能なパス形式)。構成を記述する構成とメタデータの集まり。メタ注釈は、注釈がコンテンツ・タイプ(タイム・スパン、頻度など)を表すことを示します。イベント・フィールド注釈で、値がデータ(たとえば、バイト)の量を表すことを指定します。文または2つを使用して要素を記述する注釈。イベント注釈は、デフォルトでイベントを有効にするかどうかを決定します。イベントのベース・クラスで、イベントとそのフィールドを定義するためにサブクラス化されます。実行時にイベントを定義するためのクラスです。レコーディングにイベント設定を適用するための簡易クラスです。イベント、フィールド、設定、注釈を記述します。要素が試験的なものであり、予告なしに変更される可能性があることを指定する注釈。Flight Recorderへのアクセス、制御および管理のためのクラス。Flight Recorderのライフサイクルを監視するためのコールバック・インタフェース。Flight Recorderへのアクセスを制御するための許可。イベント・フィールド注釈で、値がHzで測定される頻度であることを指定します。要素(たとえば、"Maximum Throughput")に判読可能な名前を設定する注釈。イベント・フィールド注釈は、値がメモリー・アドレスであることを示します。新しいタイプのイベント・メタデータを定義するためのメタ注釈。要素のデフォルト名を設定する注釈。分数(通常は0.0と1.0の間)で使用するイベント・フィールド注釈で、値がパーセントであることを指定します。イベント注釈で、定期イベントのデフォルト設定値を指定します。レコーディング・データをディスクに構成、開始、停止、ダンプする手段を提供します。レコーディングのライフサイクルの状態を示します。プログラムによるイベント登録のためのイベント注釈。注釈で使用される、リレーショナル注釈のメタ注釈。設定コントロールを作成するための基本クラス。イベント・クラスのメソッドをイベントの除外に使用する必要があることを指定する注釈。イベント設定を記述します。イベント注釈。デフォルトでイベントにスタック・トレースがあるかどうかを判別します。イベント注釈で、イベントが(たとえば、"20 ms")に記録されないデフォルト期間を指定します。イベント・フィールド注釈は、値が期間であることを指定します。イベント・フィールド注釈は、値が特定の時点であることを示します。イベント・フィールド注釈で、イベントがスレッドから遷移することを指定します。イベント・フィールド注釈では、イベントがスレッドにすぐに遷移することを指定します。イベント・フィールド注釈は、値が符号なしデータ型であることを示します。イベント・フィールドおよび注釈要素を説明します。