クラスRemoteRecordingStream

java.lang.Object
jdk.management.jfr.RemoteRecordingStream
すべての実装されたインタフェース:
AutoCloseable, EventStream
public final class RemoteRecordingStream extends Object implements EventStream
MBeanServerConnectionを使用してネットワーク経由でイベントを直列化できるEventStreamの実装。

次の例は、リモート・ホストでガベージ・コレクションの休止時間およびCPU使用率を記録し、イベントを標準出力に出力する方法を示しています。 

    
    String host = "com.example";
    int port = 4711;

    String url = "service:jmx:rmi:///jndi/rmi://" + host + ":" + port + "/jmxrmi";

    JMXServiceURL u = new JMXServiceURL(url);
    JMXConnector c = JMXConnectorFactory.connect(u);
    MBeanServerConnection conn = c.getMBeanServerConnection();

    try (var rs = new RemoteRecordingStream(conn)) {
        rs.enable("jdk.GCPhasePause").withoutThreshold();
        rs.enable("jdk.CPULoad").withPeriod(Duration.ofSeconds(1));
        rs.onEvent("jdk.CPULoad", System.out::println);
        rs.onEvent("jdk.GCPhasePause", System.out::println);
        rs.start();
    }

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

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

    コンストラクタ
    コンストラクタ
    説明
    RemoteRecordingStream(MBeanServerConnection connection)
    FlightRecorderMXBeanが登録されているMBeanServerConnectionに対して演算するイベント・ストリームを作成します。
    RemoteRecordingStream(MBeanServerConnection connection, Path directory)
    FlightRecorderMXBeanが登録されているMBeanServerConnectionに対して演算するイベント・ストリームを作成します。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    awaitTermination()
    すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。
    void
    awaitTermination(Duration timeout)
    すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。
    void
    close()
    このストリームに関連付けられているすべてのリソースを解放します。
    EventSettings
    disable(String name)
    指定された名前のイベントを無効にします。
    void
    dump(Path destination)
    レコーディング・データをファイルに書き込みます。
    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)
    ストリームのフラッシュ後に実行するアクションを登録します。
    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であるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

    インタフェースで宣言されたメソッド EventStream

    onMetadata
    修飾子と型
    メソッド
    説明
    default void
    onMetadata(Consumer<MetadataEvent> action)
    新しいメタデータがストリームに到着したときに実行するアクションを登録します。

  • コンストラクタの詳細

    • RemoteRecordingStream

      public RemoteRecordingStream(MBeanServerConnection connection) throws IOException
      FlightRecorderMXBeanが登録されているMBeanServerConnectionに対して演算するイベント・ストリームを作成します。

      イベント設定を構成するには、setSettings(Map)を使用します。

      パラメータ:
      connection - FlightRecorderMXBeanが登録されているMBeanServerConnection。nullではない
      スロー:
      IOException - ストリームをオープンできない場合、リポジトリまたはFlightRecorderMXBeanにアクセスしようとすると、I/Oエラーが発生

    • RemoteRecordingStream

      public RemoteRecordingStream(MBeanServerConnection connection, Path directory) throws IOException
      FlightRecorderMXBeanが登録されているMBeanServerConnectionに対して演算するイベント・ストリームを作成します。

      イベント設定を構成するには、setSettings(Map)を使用します。

      パラメータ:
      connection - FlightRecorderMXBeanが登録されているMBeanServerConnection。nullではない
      directory - nullではなく、ダウンロードされたイベント・データを格納するディレクトリ
      スロー:
      IOException - ストリームをオープンできない場合、リポジトリまたはFlightRecorderMXBeanにアクセスしようとすると、I/Oエラーが発生

  • メソッドの詳細

    • setSettings

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

      次の例では、"default"構成の設定を使用してリモート・ホストに接続し、イベントをストリームします。 

      {
    

    String host = "com.example";
    int port = 4711;

    String url = "service:jmx:rmi:///jndi/rmi://" + host + ":" + port + "/jmxrmi";

    JMXServiceURL u = new JMXServiceURL(url);
    JMXConnector c = JMXConnectorFactory.connect(u);
    MBeanServerConnection conn = c.getMBeanServerConnection();

    try (final var rs = new RemoteRecordingStream(conn)) {
        rs.onMetadata(e -> {
            for (Configuration c : e.getConfigurations()) {
                if (c.getName().equals("default")) {
                    rs.setSettings(c.getSettings());
                }
            }
        });
        rs.onEvent(System.out::println);
        rs.start();
    }

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

    • disable

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

      (たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)と同じ名前のイベントが複数ある場合、名前と一致するすべてのイベントが無効化されます。

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

    • enable

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

      複数のイベントの名前が(たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)である場合、名前と一致するすべてのイベントが有効になります。

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

    • 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状態にある場合

    • onEvent

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

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

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

    • onEvent

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

    • onFlush

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

    • onError

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

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

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

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

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

    • onClose

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

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

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

    • close

      public void close()
      インタフェース: EventStreamからコピーされた説明
      このストリームに関連付けられているすべてのリソースを解放します。

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

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

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

    • remove

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

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

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

    • 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ではない)
      関連項目:

    • start

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

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

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

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

    • startAsync

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

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

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

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

    • stop

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

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

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

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

        AtomicLong bytesWritten = new AtomicLong();
  try (var r = new RemoteRecordingStream(connection)) {
    r.setMaxSize(Long.MAX_VALUE);
    r.enable("jdk.FileWrite").withoutThreshold();
    r.onEvent(event ->
      bytesWritten.addAndGet(event.getLong("bytesWritten"))
    );
    r.startAsync();
    testFoo();
    r.stop();
    if (bytesWritten.get() > 1_000_000L) {
      r.dump(Path.of("file-write-events.jfr"));
      throw new AssertionError("testFoo() writes too much data to disk");
    }
  }

      戻り値:
      レコーディングが停止すると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 - 待機中に割込みが発生した場合
      関連項目: