モジュール jdk.jfr

パッケージ jdk.jfr.consumer

クラス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)	ストリームのフラッシュ後に実行するアクションを登録します。
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

コンストラクタの詳細

RecordingStream

public RecordingStream()

現在のJVM (Java Virtual Machine)のイベント・ストリームを作成します。

例外:

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

SecurityException - セキュリティ・マネージャが存在し、呼び出し元にFlightRecorderPermission("accessFlightRecorder")がない場合

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のサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか

SecurityException - セキュリティ・マネージャが使用され、FlightRecorderPermission "accessFlightRecorder"が設定されていない場合。

関連項目:

• Configuration

メソッドの詳細

enable

public EventSettings enable(String name)

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

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

パラメータ:

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

戻り値:

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

関連項目:

• EventType

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

関連項目:

• Recording.setSettings(Map)

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

関連項目:

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

setEndTime

public void setEndTime(Instant endTime)

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

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

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

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

定義:

インタフェースEventStream内のsetEndTime

パラメータ:

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

関連項目:

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

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

関連項目:

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

onFlush

public void onFlush(Runnable action)

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

ストリームのフラッシュ後に実行するアクションを登録します。

定義:

インタフェースEventStream内のonFlush

パラメータ:

action - ストリームのフラッシュ後に実行するアクション。nullではありません

onClose

public void onClose(Runnable action)

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

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

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

定義:

インタフェースEventStream内のonClose

パラメータ:

action - ストリームが閉じられた後に実行するアクション。nullはクローズされません

関連項目:

• EventStream.close()

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

関連項目:

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

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

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()