クラスRecordingStream

java.lang.Object
jdk.jfr.consumer.RecordingStream
すべての実装されたインタフェース:
AutoCloseable, EventStream
public final class RecordingStream extends Object implements AutoCloseable, EventStream
レコーディング・ストリームは、現在のJVM (Java Virtual Machine)からイベントを生成します。

次の例では、デフォルトの構成を使用してイベントを記録し、ガベージ・コレクション、CPUロードおよびJVM情報イベントを標準出力に出力する方法を示します。 

Configuration c = Configuration.getConfiguration("default");
try (var rs = new RecordingStream(c)) {
    rs.onEvent("jdk.GarbageCollection", System.out::println);
    rs.onEvent("jdk.CPULoad", System.out::println);
    rs.onEvent("jdk.JVMInformation", System.out::println);
    rs.start();
}

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

  • コンストラクタのサマリー

    コンストラクタ
    コンストラクタ
    説明
    RecordingStream()
    現在のJVM (Java Virtual Machine)のイベント・ストリームを作成します。
    RecordingStream(Configuration configuration)
    構成の設定を使用してレコーディング・ストリームを作成します。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    awaitTermination()
    すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
    void
    awaitTermination(Duration timeout)
    すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。
    void
    close()
    このリソースを閉じ、ベースとなるリソースをすべて解放します。
    EventSettings
    disable(Class<? extends Event> eventClass)
    イベントを無効にします。
    EventSettings
    disable(String name)
    指定された名前のイベントを無効にします。
    void
    dump(Path destination)
    レコーディング・データをファイルに書き込みます。
    EventSettings
    enable(Class<? extends Event> eventClass)
    イベントを有効にします。
    EventSettings
    enable(String name)
    指定された名前のイベントを有効にします。
    void
    onClose(Runnable action)
    ストリームが閉じられたときに実行するアクションを登録します。
    void
    onError(Consumer<Throwable> action)
    例外が発生した場合に実行するアクションを登録します。
    void
    onEvent(String eventName, Consumer<RecordedEvent> action)
    名前と一致するすべてのイベントに対して実行するアクションを登録します。
    void
    onEvent(Consumer<RecordedEvent> action)
    ストリーム内のすべてのイベントで実行するアクションを登録します。
    void
    onFlush(Runnable action)
    ストリームのフラッシュ後に実行するアクションを登録します。
    void
    onMetadata(Consumer<MetadataEvent> action)
    新しいメタデータがストリームに到着したときに実行するアクションを登録します。
    boolean
    remove(Object action)
    アクションを登録解除します。
    void
    setEndTime(Instant endTime)
    ストリームの終了時間を指定します。
    void
    setMaxAge(Duration maxAge)
    ストリームで保持される過去のデータの量を決定します。
    void
    setMaxSize(long maxSize)
    ストリーム用に保持されるデータ量を決定します。
    void
    setOrdered(boolean ordered)
    イベントがストリームにコミットされた時間でソートされた時系列順で到着することを指定します。
    void
    setReuse(boolean reuse)
    EventStream.onEvent(Consumer)処理のイベント・オブジェクトを再利用できることを指定します。
    void
    setSettings(Map<String,String> settings)
    このレコーディング・ストリームのすべての設定を置換します。
    void
    setStartTime(Instant startTime)
    ストリームの開始時間を指定します。
    void
    start()
    アクションの処理を開始します。
    void
    startAsync()
    アクションの非同期処理を開始します。
    boolean
    stop()
    レコーディング・ストリームを停止します。

    クラスオブジェクトで宣言されたメソッド

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    修飾子と型
    メソッド
    説明
    protected Object
    clone()
    このオブジェクトのコピーを作成して、返します。
    boolean
    equals(Object obj)
    このオブジェクトと他のオブジェクトが等しいかどうかを示します。
    protected void
    finalize()
    削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
    最終決定は非推奨であり、将来のリリースで削除される可能性があります。
    final Class<?>
    getClass()
    このObjectの実行時クラスを返します。
    int
    hashCode()
    このオブジェクトに対するハッシュ・コード値を返します。
    final void
    notify()
    このオブジェクトのモニターで待機中のスレッドを1つ再開します。
    final void
    notifyAll()
    このオブジェクトのモニターで待機中のすべてのスレッドを再開します。
    String
    toString()
    オブジェクトの文字列表現を返します。
    final void
    wait()
    現在のスレッドが目覚めるまで待機します。通常、notifiedまたはinterruptedです。
    final void
    wait(long timeoutMillis)
    現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。
    final void
    wait(long timeoutMillis, int nanos)
    現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

  • コンストラクタの詳細

    • RecordingStream

      public RecordingStream()
      現在のJVM (Java Virtual Machine)のイベント・ストリームを作成します。
      スロー:
      IllegalStateException - flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか

    • RecordingStream

      public RecordingStream(Configuration configuration)
      構成の設定を使用してレコーディング・ストリームを作成します。

      次の例では、事前定義された構成を使用するレコーディング・ストリームの作成方法を示します。 

      var c = Configuration.getConfiguration("default");
try (var rs = new RecordingStream(c)) {
    rs.onEvent(System.out::println);
    rs.start();
}

      パラメータ:
      configuration - nullではなく、使用する設定が含まれている構成
      スロー:
      IllegalStateException - flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか
      関連項目:

  • メソッドの詳細

    • enable

      public EventSettings enable(String name)
      指定された名前のイベントを有効にします。

      複数のイベントの名前が(たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)である場合、名前と一致するすべてのイベントが有効になります。 特定のクラスを有効にするには、イベント・タイプIDのenable(Class)メソッドまたはString表現を使用します。

      パラメータ:
      name - nullではなく、イベントの設定
      戻り値:
      nullではなく、さらなる構成のためのイベント構成
      関連項目:

    • setSettings

      public void setSettings(Map<String,String> settings)
      このレコーディング・ストリームのすべての設定を置換します。

      次の例では、"default"構成を使用して20秒記録し、その設定を"profile"構成に変更します。 

      Configuration defaultConfiguration = Configuration.getConfiguration("default");
Configuration profileConfiguration = Configuration.getConfiguration("profile");
try (var rs = new RecordingStream(defaultConfiguration)) {
    rs.onEvent(System.out::println);
    rs.startAsync();
    Thread.sleep(20_000);
    rs.setSettings(profileConfiguration.getSettings());
    Thread.sleep(20_000);
}

      パラメータ:
      settings - nullではなく、設定する設定
      関連項目:

    • enable

      public EventSettings enable(Class<? extends Event> eventClass)
      イベントを有効にします。
      パラメータ:
      eventClass - nullではなく、有効にするイベント
      戻り値:
      nullではなく、さらなる構成のためのイベント構成
      スロー:
      IllegalArgumentException - eventClassが抽象クラスであるか、Eventのサブクラスでない場合

    • disable

      public EventSettings disable(String name)
      指定された名前のイベントを無効にします。

      (たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)と同じ名前のイベントが複数ある場合、名前と一致するすべてのイベントが無効化されます。 特定のクラスを無効にするには、イベント・タイプIDのdisable(Class)メソッドまたはString表現を使用します。

      パラメータ:
      name - nullではなく、イベントの設定
      戻り値:
      nullではなく、さらなる構成のためのイベント構成

    • disable

      public EventSettings disable(Class<? extends Event> eventClass)
      イベントを無効にします。
      パラメータ:
      eventClass - nullではなく、有効にするイベント
      戻り値:
      nullではなく、さらなる構成のためのイベント構成
      スロー:
      IllegalArgumentException - eventClassが抽象クラスであるか、Eventのサブクラスでない場合

    • setMaxAge

      public void setMaxAge(Duration maxAge)
      ストリームで保持される過去のデータの量を決定します。

      ディスクに格納されるデータのレコーディング量を制御するために、データを保持する最大時間を指定できます。 指定した時間よりも古いディスクに格納されているデータは、Java Virtual Machine (JVM)によって削除されます。

      最大制限も最大有効期間も設定されていない場合、イベントが消費されないと、記録のサイズが無期限に大きくなる可能性があります。

      パラメータ:
      maxAge - データが保持される時間の長さ(無限大の場合はnull)。
      スロー:
      IllegalArgumentException - maxAgeが負の場合
      IllegalStateException - レコーディングがCLOSED状態にあるかどうか

    • setMaxSize

      public void setMaxSize(long maxSize)
      ストリーム用に保持されるデータ量を決定します。

      ディスクに格納されるデータのレコーディング量を制御するために、保持するデータの最大量を指定できます。 上限を超えた場合、Java Virtual Machine (JVM)は最も古いチャンクを削除し、新しいチャンクのための余裕を作成します。

      最大限度または最大経過時間を設定しないと、レコーディングのサイズが無期限に拡大することがあります。

      サイズはバイト単位で測定されます。

      パラメータ:
      maxSize - 保存するデータの量(無限大の場合は0)
      スロー:
      IllegalArgumentException - maxSizeが負の場合
      IllegalStateException - レコーディングがCLOSED状態にある場合

    • setReuse

      public void setReuse(boolean reuse)
      インタフェース: EventStreamからコピーされた説明
      EventStream.onEvent(Consumer)処理のイベント・オブジェクトを再利用できることを指定します。

      reuseがtrueに設定されている場合、アクションの完了後、アクションはイベント・オブジェクトへの参照を保持しません。

      定義:
      インタフェースEventStream内のsetReuse
      パラメータ:
      reuse - イベント・オブジェクトを再利用できる場合はtrue、それ以外の場合はfalse

    • setOrdered

      public void setOrdered(boolean ordered)
      インタフェース: EventStreamからコピーされた説明
      イベントがストリームにコミットされた時間でソートされた時系列順で到着することを指定します。
      定義:
      インタフェースEventStream内のsetOrdered
      パラメータ:
      ordered - イベント・オブジェクトがEventStream.onEvent(Consumer)に時系列で到着した場合

    • setStartTime

      public void setStartTime(Instant startTime)
      インタフェース: EventStreamからコピーされた説明
      ストリームの開始時間を指定します。

      開始時間は、ストリームの開始前に設定する必要があります

      定義:
      インタフェースEventStream内のsetStartTime
      パラメータ:
      startTime - 開始時間(nullではない)
      関連項目:

    • setEndTime

      public void setEndTime(Instant endTime)
      インタフェース: EventStreamからコピーされた説明
      ストリームの終了時間を指定します。

      終了時間は、ストリームの開始前に設定する必要があります。

      最後に、ストリームはクローズされます。

      定義:
      インタフェースEventStream内のsetEndTime
      パラメータ:
      endTime - 終了時間(nullではない)
      関連項目:

    • onEvent

      public void onEvent(String eventName, Consumer<RecordedEvent> action)
      インタフェース: EventStreamからコピーされた説明
      名前と一致するすべてのイベントに対して実行するアクションを登録します。
      定義:
      インタフェースEventStream内のonEvent
      パラメータ:
      eventName - イベントの名前(null以外)
      action - nullではなく、イベント名と一致する各RecordedEventに対して実行するアクション

    • onEvent

      public void onEvent(Consumer<RecordedEvent> action)
      インタフェース: EventStreamからコピーされた説明
      ストリーム内のすべてのイベントで実行するアクションを登録します。

      イベント・タイプのサブセットに対してアクションを実行するには、汎用アクションで実装される選択またはフィルタリング・メカニズムよりもパフォーマンスが高い可能性があるため、EventStream.onEvent(String, Consumer)およびEventStream.onMetadata(Consumer)の使用を検討してください。

      定義:
      インタフェースEventStream内のonEvent
      パラメータ:
      action - nullではなく、各RecordedEventで実行するアクション。
      関連項目:

    • onFlush

      public void onFlush(Runnable action)
      インタフェース: EventStreamからコピーされた説明
      ストリームのフラッシュ後に実行するアクションを登録します。
      定義:
      インタフェースEventStream内のonFlush
      パラメータ:
      action - ストリームのフラッシュ後に実行するアクション。nullではありません

    • onClose

      public void onClose(Runnable action)
      インタフェース: EventStreamからコピーされた説明
      ストリームが閉じられたときに実行するアクションを登録します。

      ストリームがすでにクローズされている場合は、現在のスレッド内でただちにアクションが実行されます。

      定義:
      インタフェースEventStream内のonClose
      パラメータ:
      action - ストリームが閉じられた後に実行するアクション。nullはクローズされません
      関連項目:

    • onError

      public void onError(Consumer<Throwable> action)
      インタフェース: EventStreamからコピーされた説明
      例外が発生した場合に実行するアクションを登録します。

      アクションが登録されていない場合は、例外スタック・トレースが標準エラーに出力されます。

      アクションを登録すると、デフォルトの動作がオーバーライドされます。 複数のアクションが登録されている場合は、登録順に実行されます。

      このメソッド自体が例外をスローした場合、結果の動作は未定義です。

      定義:
      インタフェースEventStream内のonError
      パラメータ:
      action - nullではなく例外が発生した場合に実行するアクション

    • close

      public void close()
      インタフェース: AutoCloseableからコピーされた説明
      このリソースを閉じ、ベースとなるリソースをすべて解放します。 このメソッドは、try-with-resources文で管理されているオブジェクトで自動的に呼び出されます。
      定義:
      close、インタフェースAutoCloseable
      定義:
      インタフェースEventStream内のclose

    • remove

      public boolean remove(Object action)
      インタフェース: EventStreamからコピーされた説明
      アクションを登録解除します。

      アクションが複数回登録されている場合、すべてのインスタンスが登録解除されます。

      定義:
      インタフェースEventStream内のremove
      パラメータ:
      action - 登録解除する処理(nullではない)
      戻り値:
      アクションが登録解除された場合はtrue、登録されていない場合はfalse
      関連項目:

    • start

      public void start()
      インタフェース: EventStreamからコピーされた説明
      アクションの処理を開始します。

      アクションは、現在のスレッドで実行されます。

      ストリームを停止するには、EventStream.close()メソッドを使用します。

      定義:
      インタフェースEventStream内のstart

    • startAsync

      public void startAsync()
      アクションの非同期処理を開始します。

      アクションは、単一の独立したスレッドで実行されます。

      ストリームを停止するには、close()メソッドを使用します。

      次の例では、CPU使用率を10秒間出力します。 現在のスレッドがtry-with-resourcesブロックから離れると、ストリームは停止/クローズされます。 

      try (var stream = new RecordingStream()) {
    stream.enable("jdk.CPULoad").withPeriod(Duration.ofSeconds(1));
    stream.onEvent("jdk.CPULoad", event -> {
        System.out.println(event);
    });
    stream.startAsync();
    Thread.sleep(10_000);
}

      定義:
      インタフェースEventStream内のstartAsync
      スロー:
      IllegalStateException - ストリームがすでに開始されているか、閉じている場合

    • stop

      public boolean stop()
      レコーディング・ストリームを停止します。

      開始されたストリームを停止し、レコーディング内のすべてのイベントが消費されるまで待機します。

      onEvent(Consumer)メソッドなどでアクションでこのメソッドを呼び出すと、ストリームを無期限にブロックできます。 ストリームを突然停止するには、close()メソッドを使用します。

      次のコード・スニペットは、このメソッドをstartAsync()メソッドとともに使用して、テスト・メソッド中に何が起こったかをモニターする方法を示しています: 

      AtomicBoolean socketUse = new AtomicBoolean();
try (var r = new RecordingStream()) {
    r.setMaxSize(Long.MAX_VALUE);
    r.enable("jdk.SocketWrite").withoutThreshold();
    r.enable("jdk.SocketRead").withoutThreshold();
    r.onEvent(event -> socketUse.set(true));
    r.startAsync();
    testFoo();
    r.stop();
    if (socketUse.get()) {
        r.dump(Path.of("socket-events.jfr"));
        throw new AssertionError("testFoo() should not use network");
    }
}

      戻り値:
      レコーディングが停止するとtrue、それ以外の場合はfalse
      スロー:
      IllegalStateException - レコーディングが開始されていないか、すでに停止している場合
      導入されたバージョン:
      20

    • dump

      public void dump(Path destination) throws IOException
      レコーディング・データをファイルに書き込みます。

      レコーディング・ストリームは開始する必要がありますが、クローズしないでください。

      ストリームを開始する前に、最大年齢または最大サイズを設定することを強くお薦めします。 それ以外の場合、ダンプにイベントが含まれていない可能性があります。

      パラメータ:
      destination - nullではなく、レコーディング・データが書き込まれるロケーション
      スロー:
      IOException - 指定されたロケーションにレコーディング・データをコピーできない場合、またはストリームが閉じているか、または開始されていない場合。
      導入されたバージョン:
      17
      関連項目:

    • awaitTermination

      public void awaitTermination(Duration timeout) throws InterruptedException
      インタフェース: EventStreamからコピーされた説明
      すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。
      定義:
      インタフェースEventStream内のawaitTermination
      パラメータ:
      timeout - nullではなく最大待機時間
      スロー:
      InterruptedException - 待機中に割込みが発生した場合
      関連項目:

    • awaitTermination

      public void awaitTermination() throws InterruptedException
      インタフェース: EventStreamからコピーされた説明
      すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
      定義:
      インタフェースEventStream内のawaitTermination
      スロー:
      InterruptedException - 待機中に割込みが発生した場合
      関連項目:

    • onMetadata

      public void onMetadata(Consumer<MetadataEvent> action)
      新しいメタデータがストリームに到着したときに実行するアクションを登録します。 イベントのイベント・タイプは、常に実際のイベントより前に到着します。 ストリームを開始する前に、アクションを登録する必要があります。

      次の例は、新しいイベント・タイプをリスニングし、イベント・タイプ名が正規表現に一致する場合はアクションを登録し、一致するイベントが見つかった場合はカウンタを増やす方法を示しています。 汎用のonEvent(Consumer)メソッドではなく、イベント・タイプごとにアクションを使用する利点は、ストリーム実装では、関心のないイベントの読取りを回避できることです。 

      static long count = 0;
public static void main(String... args) throws Exception {
    String regExp = args[0];
    var pr = Pattern.compile(regExp).asMatchPredicate();
    Configuration c = Configuration.getConfiguration("default");
    try (var s = new RecordingStream(c)) {
        s.setOrdered(false);
        s.onMetadata(metadata -> metadata.getAddedEventTypes()
         .stream().map(EventType::getName).filter(pr)
         .forEach(eventName -> s.onEvent(eventName, event -> count++)));
        s.startAsync();
        System.out.println("Running recording for 5 s. Please wait.");
        s.awaitTermination(Duration.ofSeconds(5));
        System.out.println(count + " events matches " + regExp);
    }
}

      定義:
      インタフェースEventStream内のonMetadata
      パラメータ:
      action - nullではなく実行
      スロー:
      IllegalStateException - ストリームの開始後にアクションが追加された場合
      導入されたバージョン:
      16