モジュール jdk.jfr
パッケージ jdk.jfr.consumer

インタフェースEventStream

すべてのスーパー・インタフェース:
AutoCloseable
既知のすべての実装クラス:
RecordingStream, RemoteRecordingStream
public interface EventStream extends AutoCloseable
イベントのストリームを表します。

ストリームとは一連のイベントであり、ストリームとの対話方法はアクションの登録です。 EventStreamインタフェースが実装されておらず、将来のバージョンのJDKでは完全に使用できない可能性があります。

イベントの到着時に通知を受信するには、onEvent(Consumer)メソッドを使用してアクションを登録します。 特定の名前を持つイベントのストリームをフィルタするには、onEvent(String, Consumer)メソッドを使用します。

デフォルトでは、同じRecordedEventオブジェクトを使用して2つ以上の個別のイベントを表すことができます。 そのオブジェクトは、同じアクションおよび他のアクションに複数回配信できます。 アクションの完了後にイベント・オブジェクトを使用するには、setReuse(boolean)メソッドをfalseに設定して、イベントごとに新しいオブジェクトが割り当てられるようにします。

イベントは、バッチで配信されます。 バッチが完了したときに通知を受け取るには、onFlush(Runnable)メソッドを使用してアクションを登録します。 これは、Java Virtual Machine (JVM)が次のバッチを準備している間に、外部システムに対してデータを集約またはプッシュする機会です。

バッチ内のイベントは、終了時間によって時系列順にソートされます。 確定イベントは、フラッシュの時点でJVMに使用可能なイベント、つまり単一バッチで1単位として配信されるイベントのセットに対してのみ維持されます。 そのため、バッチ内に配信されたイベントは、以前のバッチで配信されたイベントと比較して順不同になることがありますが、同じバッチ内のイベントとは順不同になることはありません。 順序付けが懸念されない場合は、setOrdered(boolean)メソッドを使用してソートを無効にできます。

登録されたアクションにイベントをディスパッチするには、ストリームを開始する必要があります。 現在のスレッドで処理を開始するには、start()メソッドを呼び出します。 別のスレッドでアクションを非同期に処理するには、startAsync()メソッドを呼び出します。 ストリームの完了を待機するには、awaitTermination awaitTermination()またはawaitTermination(Duration)メソッドを使用します。

ストリームが終了すると、自動的にクローズされます。 イベントの処理を手動で停止するには、close()メソッドを呼び出してストリームを閉じます。 また、ストリームは、たとえばモニターしているJVMが終了した場合など、例外的な状況で自動的にクローズされることもあります。 これらのいずれかのタイミングで通知を受信するには、onClose(Runnable)メソッドを使用してアクションを登録します。

アクションで予期しない例外が発生した場合は、エラー・ハンドラで例外を捕捉できます。 エラー・ハンドラは、onError(Consumer)メソッドを使用して登録できます。 エラー・ハンドラが登録されていない場合、デフォルトの動作では、例外とそのバック・トレースが標準エラー・ストリームに出力されます。

次の例では、Flight Recorderを実行しているJVMでイベントをリスニングするためにEventStreamを使用する方法を示します 

 try (var es = EventStream.openRepository()) {
   es.onEvent("jdk.CPULoad", event -> {
     System.out.println("CPU Load " + event.getEndTime());
     System.out.println(" Machine total: " + 100 * event.getFloat("machineTotal") + "%");
     System.out.println(" JVM User: " + 100 * event.getFloat("jvmUser") + "%");
     System.out.println(" JVM System: " + 100 * event.getFloat("jvmSystem") + "%");
     System.out.println();
   });
   es.onEvent("jdk.GarbageCollection", event -> {
     System.out.println("Garbage collection: " + event.getLong("gcId"));
     System.out.println(" Cause: " + event.getString("cause"));
     System.out.println(" Total pause: " + event.getDuration("sumOfPauses"));
     System.out.println(" Longest pause: " + event.getDuration("longestPause"));
     System.out.println();
   });
   es.start();
 }

ストリームとのレコーディングを開始するには、RecordingStreamを参照してください。

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

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    awaitTermination()
    すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
    void
    awaitTermination(Duration timeout)
    すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。
    void
    close()
    このストリームに関連付けられているすべてのリソースを解放します。
    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)
    ストリームのフラッシュ後に実行するアクションを登録します。
    default void
    onMetadata(Consumer<MetadataEvent> action)
    新しいメタデータがストリームに到着したときに実行するアクションを登録します。
    static EventStream
    openFile(Path file)
    ファイルからイベント・ストリームを作成します。
    static EventStream
    openRepository()
    現行のJava Virtual Machine (JVM)のリポジトリからストリームを作成します。
    static EventStream
    openRepository(Path directory)
    ディスク・リポジトリからイベント・ストリームを作成します。
    boolean
    remove(Object action)
    アクションを登録解除します。
    void
    setEndTime(Instant endTime)
    ストリームの終了時間を指定します。
    void
    setOrdered(boolean ordered)
    イベントがストリームにコミットされた時間でソートされて、時系列順にイベントが到着することを指定します。
    void
    setReuse(boolean reuse)
    onEvent(Consumer)処理のイベント・オブジェクトを再利用できることを指定します。
    void
    setStartTime(Instant startTime)
    ストリームの開始時間を指定します。
    void
    start()
    アクションの処理を開始します。
    void
    startAsync()
    アクションの非同期処理を開始します。

  • メソッドの詳細

    • openRepository

      static EventStream openRepository() throws IOException
      現行のJava Virtual Machine (JVM)のリポジトリからストリームを作成します。

      デフォルトでは、ストリームはFlight Recorderによりフラッシュされる次のイベントから開始されます。

      戻り値:
      イベント・ストリーム(nullではない)
      例外:
      IOException - ストリームを開けない場合、またはリポジトリにアクセスしようとしたときにI/Oエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、呼び出し元にFlightRecorderPermission("accessFlightRecorder")がない場合

    • openRepository

      static EventStream openRepository(Path directory) throws IOException
      ディスク・リポジトリからイベント・ストリームを作成します。

      デフォルトでは、ストリームはFlight Recorderによりフラッシュされる次のイベントから開始されます。

      信頼できるディスク・リポジトリのみを開く必要があります。

      パラメータ:
      directory - nullではなく、ディスク・リポジトリのロケーション
      戻り値:
      イベント・ストリーム(nullではない)
      例外:
      IOException - ストリームを開けない場合、またはリポジトリにアクセスしようとしたときにI/Oエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkReadメソッドがディレクトリへの読取りアクセスを拒否するか、ディレクトリ内のファイルを拒否する場合。

    • openFile

      static EventStream openFile(Path file) throws IOException
      ファイルからイベント・ストリームを作成します。

      デフォルトでは、ストリームはファイルの最初のイベントから開始されます。

      信頼できるソースからの記録ファイルのみを開く必要があります。

      パラメータ:
      file - nullではなく、ファイルのロケーション
      戻り値:
      イベント・ストリーム(nullではない)
      例外:
      IOException - ファイルを開くことができない場合または読取り中にI/Oエラーが発生した場合。
      SecurityException - セキュリティ・マネージャが存在し、そのcheckReadメソッドがファイルへの読取りアクセスを拒否した場合

    • onMetadata

      default void onMetadata(Consumer<MetadataEvent> action)
      新しいメタデータがストリームに到着したときに実行するアクションを登録します。 イベントのイベント・タイプは、常に実際のイベントより前に到着します。 ストリームを開始する前に、アクションを登録する必要があります。
      実装要件:
      このメソッドのデフォルト実装は空です。
      パラメータ:
      action - nullではなく実行
      例外:
      IllegalStateException - ストリームの開始後にアクションが追加された場合

    • onEvent

      void onEvent(Consumer<RecordedEvent> action)
      ストリーム内のすべてのイベントで実行するアクションを登録します。
      パラメータ:
      action - nullではなく、各RecordedEventで実行するアクション。

    • onEvent

      void onEvent(String eventName, Consumer<RecordedEvent> action)
      名前と一致するすべてのイベントに対して実行するアクションを登録します。
      パラメータ:
      eventName - イベントの名前(null以外)
      action - nullではなく、イベント名と一致する各RecordedEventに対して実行するアクション

    • onFlush

      void onFlush(Runnable action)
      ストリームのフラッシュ後に実行するアクションを登録します。
      パラメータ:
      action - ストリームのフラッシュ後に実行するアクション。nullではありません

    • onError

      void onError(Consumer<Throwable> action)
      例外が発生した場合に実行するアクションを登録します。

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

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

      このメソッド自体が例外をスローすると、結果として生じる動作は未定義です。

      パラメータ:
      action - nullではなく例外が発生した場合に実行するアクション

    • onClose

      void onClose(Runnable action)
      ストリームが閉じられたときに実行するアクションを登録します。

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

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

    • close

      void close()
      このストリームに関連付けられているすべてのリソースを解放します。

      ストリームが非同期または同期的に起動された場合は、すぐに、または次のフラッシュの後に停止されます。 このメソッドは、登録されているすべてのアクションが戻る前に完了することを保証しません。

      すでに閉じられているストリームを閉じても、何の影響もありません。

      定義:
      close、インタフェースAutoCloseable

    • remove

      boolean remove(Object action)
      アクションを登録解除します。

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

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

    • setReuse

      void setReuse(boolean reuse)
      onEvent(Consumer)処理のイベント・オブジェクトを再利用できることを指定します。

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

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

    • setOrdered

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

    • setStartTime

      void setStartTime(Instant startTime)
      ストリームの開始時間を指定します。

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

      パラメータ:
      startTime - 開始時間(nullではない)
      例外:
      IllegalStateException - ストリームがすでに開始されている場合
      関連項目:

    • setEndTime

      void setEndTime(Instant endTime)
      ストリームの終了時間を指定します。

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

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

      パラメータ:
      endTime - 終了時間(nullではない)
      例外:
      IllegalStateException - ストリームがすでに開始されている場合
      関連項目:

    • start

      void start()
      アクションの処理を開始します。

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

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

      例外:
      IllegalStateException - ストリームがすでに開始されているか、閉じている場合

    • startAsync

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

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

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

      例外:
      IllegalStateException - ストリームがすでに開始されているか、閉じている場合

    • awaitTermination

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

    • awaitTermination

      void awaitTermination() throws InterruptedException
      すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
      例外:
      InterruptedException - 待機中に割込みが発生した場合
      関連項目: