モジュール jdk.jfr

パッケージ jdk.jfr

クラス Recording

java.lang.Object

jdk.jfr.Recording

すべての実装されたインタフェース:

Closeable, AutoCloseable

public final class Recording
extends Object
implements Closeable

記録データをディスクに構成、開始、停止、ダンプする手段を提供します。

例,

 
   Configuration c = Configuration.getConfiguration("default");
   Recording r = new Recording(c);
   r.start();
   System.gc();
   Thread.sleep(5000);
   r.stop();
   r.copyTo(Files.createTempFile("my-recording", ".jfr"));
 
 

導入されたバージョン:

9

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

コンストラクタ

コンストラクタ	説明
Recording()	設定なしで記録を作成します。
Recording(Configuration configuration)	構成からの設定でレコーディングを作成します。

メソッドのサマリー

修飾子と型	メソッド	説明
void	close()	この記録に関連するすべてのデータを解放します。
Recording	copy(boolean stop)	このレコーディングのクローンを返しますが、新しいレコーディングIDと名前を返します。
EventSettings	disable(Class<? extends Event> eventClass)	イベントを無効にします。
EventSettings	disable(String name)	指定された名前のイベントを無効にします。
void	dump(Path destination)	記録データをファイルに書き込みます。
EventSettings	enable(Class<? extends Event> eventClass)	イベントを有効にします。
EventSettings	enable(String name)	指定された名前のイベントを有効にします。
Path	getDestination()	記録が終わると記録データが書き込まれる宛先ファイル、または記録先が設定されていない場合はnullを返します。
boolean	getDumpOnExit()	JVMが終了したときにこのレコーディングをディスクにダンプするかどうかを返します。
Duration	getDuration()	このレコーディングの所要時間を返します。時間が設定されていない場合はnullを返します。
long	getId()	このレコーディングの一意の識別子を返します。
Duration	getMaxAge()	破棄されるまでの間にデータがディスク・リポジトリに保持される期間を返します。
long	getMaxSize()	データがディスク・リポジトリに保持されなくなる最大サイズをバイト単位で返します。
String	getName()	このレコーディングの名前を返します。
Map<String,String>	getSettings()	このレコーディングで使用される設定を返します。
long	getSize()	ディスク・リポジトリ内のこのレコーディングの現在のサイズをバイト単位で返します。
Instant	getStartTime()	この記録が開始された時間を返します。
RecordingState	getState()	このレコーディングが現在あるRecordingStateを返します。
Instant	getStopTime()	この記録が停止した時間を返します。
InputStream	getStream(Instant start, Instant end)	指定された間隔のデータ・ストリームを作成します。
boolean	isToDisk()	この記録がディスクに行われている場合に返します。
void	scheduleStart(Duration delay)	遅延後にこの記録を開始します。
void	setDestination(Path destination)	記録停止時にデータが書き込まれるロケーションを設定するか、データを自動的にダンプしない場合はnullを設定します。
void	setDumpOnExit(boolean dumpOnExit)	JVMが終了したときにこの記録をディスクにダンプするかどうかを設定します。
void	setDuration(Duration duration)	記録を停止するまでの時間を設定します。
void	setMaxAge(Duration maxAge)	ディスク・リポジトリに保持するデータの範囲を決定します。
void	setMaxSize(long maxSize)	ディスク・リポジトリに保持するデータの量を決定します。
void	setName(String name)	"My Recording"など、人間が判読可能な名前を設定します。
void	setSettings(Map<String,String> settings)	この記録のすべての設定を置き換えます。
void	setToDisk(boolean disk)	この記録をディスクに連続的にフラッシュするか、またはデータをメモリー・バッファで使用できるものに制限するかを決定します。
void	start()	この記録を開始します。
boolean	stop()	この記録を停止します。

クラス java.lang.Objectから継承されたメソッド

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

コンストラクタの詳細

記録

public Recording()

設定なしで記録を作成します。

新しく作成された記録はRecordingState.NEWになります。 記録を開始するには、start()を呼び出します。

例外:

IllegalStateException - 商用機能がロックされていない場合、またはファイル・リポジトリを作成またはアクセスできない場合など、プラットフォームFlight Recorderを作成できなかった場合。

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

記録

public Recording(Configuration configuration)

構成からの設定でレコーディングを作成します。

例,

 
 Recording r = new Recording(Configuration.getConfiguration("default"));
 
 

新しく作成されたレコーディングはRecordingState.NEWになります。 記録を開始するには、start()を呼び出します。

パラメータ:

configuration - nullではなく、使用する設定を含む構成

例外:

IllegalStateException - 商用機能がロックされていない場合、またはファイル・リポジトリを作成またはアクセスできない場合など、プラットフォームFlight Recorderを作成できなかった場合。

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

関連項目:

Configuration

メソッドの詳細

start

public void start()

この記録を開始します。

このメソッドを呼び出す前に、記録されたデータを分析する際のより一貫した状態を保証するため、記録オプションとイベント設定を構成することをお勧めします。 構成が原子的に適用できるため、パフォーマンス上の利点もあります。

このメソッドが正常に呼び出されると、この記録の状態はRUNNING状態になります。

例外:

IllegalStateException - 記録が既に開始されているか、またはCLOSED状態になっている場合

scheduleStart

public void scheduleStart(Duration delay)

遅延後にこの記録を開始します。

このメソッドが正常に呼び出されると、この記録の状態はDELAYED状態になります。

パラメータ:

delay - nullではなく、この記録を開始する前に待機する時間

例外:

IllegalStateException - 既に開始されているか、またはCLOSED状態にある場合

stop

public boolean stop()

この記録を停止します。

記録が停止されると、記録は再開できません。 この記録に目的地がある場合、その目的地にデータが書き込まれ、記録が閉じられます。 記録が終了すると、データは使用できなくなります。

このメソッドが正常に呼び出されると、この記録の状態はSTOPPED状態になります。

戻り値:

記録が停止した場合はtrue、それ以外の場合はfalse

例外:

IllegalStateException - 開始されていないか、既に停止している場合

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

関連項目:

setDestination(Path)

getSettings

public Map<String,String> getSettings()

このレコーディングで使用される設定を返します。

返されたマップを変更しても、この記録の設定は変更されません。

この記録に設定されていない場合は、空のマップが返されます。

戻り値:

nullではなく、記録設定

getSize

public long getSize()

ディスク・リポジトリ内のこのレコーディングの現在のサイズをバイト単位で返します。 バッファがフラッシュされると、サイズが更新されます。 記録がディスクに記録されていない場合、返されるのは常に0です。

戻り値:

記録されたデータの量(バイト単位)、または記録がディスクでない場合は0

getStopTime

public Instant getStopTime()

この記録が停止した時間を返します。

戻り値:

時間、またはこの記録が停止していない場合はnull

getStartTime

public Instant getStartTime()

この記録が開始された時間を返します。

戻り値:

時間、またはこの記録が開始されていない場合はnull

getMaxSize

public long getMaxSize()

データがディスク・リポジトリに保持されなくなる最大サイズをバイト単位で返します。

戻り値:

バイト単位の最大サイズ、または最大サイズが設定されていない場合は0

getMaxAge

public Duration getMaxAge()

破棄されるまでの間にデータがディスク・リポジトリに保持される期間を返します。

戻り値:

最大年齢が設定されていない場合は最大年齢、またはnull

getName

public String getName()

このレコーディングの名前を返します。

デフォルトでは、名前は記録IDと同じです。

戻り値:

nullではなく、記録名

setSettings

public void setSettings(Map<String,String> settings)

この記録のすべての設定を置き換えます。

例,

 
     Map<String, String> settings = new HashMap<>();
     settings.putAll(EventSettings.enabled("com.oracle.jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap());
     settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap());
     settings.put("com.oracle.jdk.ExecutionSample#period", "10 ms");
     recording.setSettings(settings);
 
 

既存の設定とマージするには。

 
 Map<String, String> settings = recording.getSettings();
 settings.putAll(additionalSettings));
 recording.setSettings(settings);
 
 

パラメータ:

settings - nullではなく、設定する設定

getState

public RecordingState getState()

このレコーディングが現在あるRecordingStateを返します。

戻り値:

nullではなく、記録状態

関連項目:

RecordingState

close

public void close()

この記録に関連するすべてのデータを解放します。

このメソッドが正常に呼び出されると、この記録の状態はCLOSED状態になります。

定義:

close、インタフェース: AutoCloseable

定義:

close、インタフェース: Closeable

copy

public Recording copy(boolean stop)

このレコーディングのクローンを返しますが、新しいレコーディングIDと名前を返します。 クローンは、記録を停止せずにデータをダンプするのに便利です。 クローンが作成された後、コピーされるデータの量は、setMaxAge(Duration)とsetMaxSize(long)を使用して制限することができます。

パラメータ:

stop - 新しく作成したコピーをすぐに停止する必要がある場合はtrue、それ以外の場合はfalse

戻り値:

nullではなく、記録コピー

dump

public void dump(Path destination)
          throws IOException

記録データをファイルに書き込みます。

記録を開始する必要がありますが、必ずしも停止する必要はありません。

パラメータ:

destination - nullではなく、記録データを書き込むべき場所

例外:

IOException - pathに記録をコピーできない場合

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

isToDisk

public boolean isToDisk()

この記録がディスクに行われている場合に返します。

値が設定されていない場合、trueが返されます。

戻り値:

記録がディスクの場合はtrue、それ以外の場合はfalse

setMaxSize

public void setMaxSize(long maxSize)

ディスク・リポジトリに保持するデータの量を決定します。

ディスクに保存されている記録データの量を無制限に増加させないために、最大サイズを使用して保持するデータ量を制限することができます。 maxSizeの制限を超えた場合、JVMは一番古いチャンクを削除して、より新しいチャンクのための空き領域を確保します。

パラメータ:

maxSize - 無限であれば0

例外:

IllegalArgumentException - maxSizeが負の場合

IllegalStateException - 記録がCLOSED状態にある場合

setMaxAge

public void setMaxAge(Duration maxAge)

ディスク・リポジトリに保持するデータの範囲を決定します。

ディスクに保存されている記録データの量を無制限に増加させないために、maxAgeを使用して保持するデータの量を制限することができます。 maxAgeより古いディスクに保存されているデータは、Flight Recorderによって削除されます。

パラメータ:

maxAge - データを保持できる期間、または無限であればnull

例外:

IllegalArgumentException - maxAgeが負の場合

IllegalStateException - 記録が閉じている場合

setDestination

public void setDestination(Path destination)
                    throws IOException

記録停止時にデータが書き込まれるロケーションを設定するか、データを自動的にダンプしない場合はnullを設定します。

コピー先が設定されている場合、コピー先のパスにデータが正常にコピーされた後、この記録は自動的に閉じられます。

目的地が設定されていない場合、Flight Recorderはこの記録が終了するまでデータの記録を保持します。 dump(Path)を使用して、手動でファイルにデータを書き込みます。

パラメータ:

destination - パス、またはnullを指定してください。

例外:

IllegalStateException - 記録がETOPPEDまたはCLOSED状態にある場合。

SecurityException - セキュリティ・マネージャが存在し、呼び出し元がFilePermissionを読み取らない場合は、destinationファイルを書き込み、削除

IOException - パスが書き込み可能でない場合

getDestination

public Path getDestination()

記録が終わると記録データが書き込まれる宛先ファイル、または記録先が設定されていない場合はnullを返します。

戻り値:

宛先ファイル、または設定されていない場合はnull。

getId

public long getId()

このレコーディングの一意の識別子を返します。

戻り値:

記録識別子

setName

public void setName(String name)

"My Recording"など、人間が判読可能な名前を設定します。

パラメータ:

name - nullではなく、記録名

例外:

IllegalStateException - 記録が閉じている場合

setDumpOnExit

public void setDumpOnExit(boolean dumpOnExit)

JVMが終了したときにこの記録をディスクにダンプするかどうかを設定します。

パラメータ:

dumpOnExit - 記録をJVM出口にダンプする必要がある場合

getDumpOnExit

public boolean getDumpOnExit()

JVMが終了したときにこのレコーディングをディスクにダンプするかどうかを返します。

dump on exitが設定されていない場合、falseが返されます。

戻り値:

終了時に記録をダンプする必要がある場合はtrue、それ以外の場合はfalse。

setToDisk

public void setToDisk(boolean disk)

この記録をディスクに連続的にフラッシュするか、またはデータをメモリー・バッファで使用できるものに制限するかを決定します。

パラメータ:

disk - ディスクに記録を書き込む場合はtrue、イン・メモリーの場合はfalse

getStream

public InputStream getStream(Instant start,
                             Instant end)
                      throws IOException

指定された間隔のデータ・ストリームを作成します。 ストリームには、指定された範囲外のデータが含まれる場合があります。

パラメータ:

start - ストリームの開始時間、またはnullが記録の開始時刻からデータを取得

end - ストリームの終了時間、または現時点までのデータを取得するnull。

戻り値:

入力ストリーム、またはnullが指定されている場合は、その間隔でデータが使用可能になります。

例外:

IllegalArgumentException - endがstartより前に発生した場合

IOException - ストリームを開くことができない場合

getDuration

public Duration getDuration()

このレコーディングの所要時間を返します。時間が設定されていない場合はnullを返します。

この持続時間は、記録状態がRecordingState.NEWの場合にのみ設定することができます。

戻り値:

希望の記録時間、または時間が設定されていない場合はnull。

setDuration

public void setDuration(Duration duration)

記録を停止するまでの時間を設定します。

デフォルトでは、記録時間は(null)です。

パラメータ:

duration - 持続時間を使用しない場合は期間またはnull

例外:

IllegalStateException - 記録が停止状態またはクローズ状態の場合

enable

public EventSettings enable(String name)

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

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

パラメータ:

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

戻り値:

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

関連項目:

EventType

disable

public EventSettings disable(String name)

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

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

パラメータ:

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

戻り値:

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

enable

public EventSettings enable(Class<? extends Event> eventClass)

イベントを有効にします。

パラメータ:

eventClass - nullではなく、有効にするイベント

戻り値:

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

例外:

IllegalArgumentException - eventClassが抽象クラスであるか、Eventのサブクラスでない場合

disable

public EventSettings disable(Class<? extends Event> eventClass)

イベントを無効にします。

パラメータ:

eventClass - nullではなく、有効にするイベント

戻り値:

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

例外:

IllegalArgumentException - eventClassが抽象クラスであるか、Eventのサブクラスでない場合