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

設定と構成

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

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

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

または

<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" (ナノ秒)
  • "us" (マイクロ秒)
  • "ms" (ミリ秒)
  • "s" (秒)
  • "m" (分)
  • "h" (時間)
  • "d" (日)
"0"
"10 ms"
"1秒"
period イベントが定期的な場合にイベントを発行する間隔を指定します "everyChunk" "everyChunk"。ファイル・ローテーションごとに定期的なイベントが発行される必要がある場合、それ以外の場合は、正のLong値の文字列表現の後に空のスペースと次のいずれかの単位が続きます。
  • "ns" (ナノ秒)
  • "us" (マイクロ秒)
  • "ms" (ミリ秒)
  • "s" (秒)
  • "m" (分)
  • "h" (時間)
  • "d" (日)
"20 ms"
"1 s"
"everyChunk"
stackTrace Event#commit()メソッドからのスタック・トレースが記録されるかどうかを指定します "true" Booleanの文字列表現("true"または"false") "true",
"false"

NULL処理

すべてのメソッドは、Javadocでnullを受け入れるか返すかを定義します。 通常、これは"not null"として表されます。 許可されていない場所でnullパラメータが使用されている場合は、java.lang.NullPointerExceptionがスローされます。 java.io.IOExceptionなどの他の例外をスローするメソッドにnullパラメータを渡すと、java.lang.NullPointerExceptionが優先されます。ただし、メソッドのJavadocでnullの処理方法(つまり、java.lang.IllegalArgumentExceptionをスロー)が明示的に示されている場合を除きます。

導入されたバージョン:
9