モジュール 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