モジュール jdk.management.jfr

パッケージ jdk.management.jfr

クラス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()	レコーディング・ストリームを停止します。

クラスjava.lang.Objectで宣言されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

onMetadata

コンストラクタの詳細

RemoteRecordingStream

public RemoteRecordingStream(MBeanServerConnection connection) throws IOException

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

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

パラメータ:

connection - FlightRecorderMXBeanが登録されているMBeanServerConnection。nullではない

例外:

IOException - ストリームをオープンできない場合、リポジトリまたはFlightRecorderMXBeanにアクセスしようとすると、I/Oエラーが発生

SecurityException - セキュリティ・マネージャが存在し、checkReadメソッドがディレクトリへの読取りアクセスを拒否するか、ディレクトリ内のファイルを拒否する場合。

RemoteRecordingStream

public RemoteRecordingStream(MBeanServerConnection connection, Path directory) throws IOException

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

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

パラメータ:

connection - FlightRecorderMXBeanが登録されているMBeanServerConnection。nullではない

directory - nullではなく、ダウンロードされたイベント・データを格納するディレクトリ

例外:

IOException - ストリームをオープンできない場合、リポジトリまたはFlightRecorderMXBeanにアクセスしようとすると、I/Oエラーが発生

SecurityException - セキュリティ・マネージャが存在し、checkReadメソッドがディレクトリへの読取りアクセスを拒否するか、ディレクトリ内のファイルを拒否する場合。

メソッドの詳細

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ではなく、設定する設定

関連項目:

• Recording.setSettings(Map)

disable

public EventSettings disable(String name)

指定された名前のイベントを無効にします。

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

パラメータ:

name - nullではなく、イベントの設定

戻り値:

nullではなく、さらなる構成のためのイベント構成

enable

public EventSettings enable(String name)

指定された名前のイベントを有効にします。

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

パラメータ:

name - nullではなく、イベントの設定

戻り値:

nullではなく、さらなる構成のためのイベント構成

関連項目:

• EventType

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で実行するアクション。

関連項目:

• EventStream.onEvent(Consumer)
• EventStream.onMetadata(Consumer)

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はクローズされません

関連項目:

• EventStream.close()

close

public void close()

インタフェース: EventStreamからコピーされた説明

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

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

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

定義:

close、インタフェースAutoCloseable

定義:

インタフェースEventStream内のclose

remove

public boolean remove(Object action)

インタフェース: EventStreamからコピーされた説明

アクションを登録解除します。

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

定義:

インタフェースEventStream内のremove

パラメータ:

action - 登録解除する処理(nullではない)

戻り値:

アクションが登録解除された場合はtrue、登録されていない場合はfalse

関連項目:

• EventStream.onEvent(Consumer)
• EventStream.onEvent(String, Consumer)
• EventStream.onFlush(Runnable)
• EventStream.onClose(Runnable)
• EventStream.onError(Consumer)

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ではない)

関連項目:

• EventStream.start()
• EventStream.startAsync()

setEndTime

public void setEndTime(Instant endTime)

インタフェース: EventStreamからコピーされた説明

ストリームの終了時間を指定します。

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

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

定義:

インタフェースEventStream内のsetEndTime

パラメータ:

endTime - 終了時間(nullではない)

関連項目:

• EventStream.start()
• EventStream.startAsync()

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 - 指定されたロケーションにレコーディング・データをコピーできない場合、またはストリームが閉じているか、または開始されていない場合。

SecurityException - セキュリティ・マネージャが存在し、呼出し側が宛先パスに書き込むFilePermissionを持っていない場合

導入されたバージョン:

17

関連項目:

• setMaxAge(Duration)
• setMaxSize(long)

awaitTermination

public void awaitTermination(Duration timeout) throws InterruptedException

インタフェース: EventStreamからコピーされた説明

すべてのアクションが完了するか、ストリームがクローズされるか、タイムアウトが発生するか、現在のスレッドが中断されるまで、いずれか先に発生するまでブロックします。

定義:

インタフェースEventStream内のawaitTermination

パラメータ:

timeout - nullではなく最大待機時間

例外:

InterruptedException - 待機中に割込みが発生した場合

関連項目:

• EventStream.start()
• EventStream.startAsync()
• Thread.interrupt()

awaitTermination

public void awaitTermination() throws InterruptedException

インタフェース: EventStreamからコピーされた説明

すべてのアクションが完了するか、ストリームがクローズされるか、現在のスレッドが中断されるまで、いずれか早いほうで発生します。

定義:

インタフェースEventStream内のawaitTermination

例外:

InterruptedException - 待機中に割込みが発生した場合

関連項目:

• EventStream.start()
• EventStream.startAsync()
• Thread.interrupt()