- 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
-
-
メソッドのサマリー
すべてのメソッド インスタンス・メソッド 具象メソッド 修飾子と型 メソッド 説明 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()
このレコーディングの一意のIDを返します。Duration
getMaxAge()
データが削除される前にディスク・リポジトリに保持される時間の長さを返します。long
getMaxSize()
ディスクのリポジトリに保存されなくなったデータの最大サイズ(バイト単位)を返します。String
getName()
このレコーディングの名前を返します。Map<String,String>
getSettings()
このレコーディングで使用される設定を返します。long
getSize()
ディスク・リポジトリ内のこのレコーディングの現在のサイズをバイト単位で返します。Instant
getStartTime()
このレコーディングが開始された時間を返します。RecordingState
getState()
このレコーディングが現在保持されているレコーディング状態を返します。Instant
getStopTime()
このレコーディングが停止した時間を返します。InputStream
getStream(Instant start, Instant end)
指定された間隔のデータ・ストリームを作成します。boolean
isToDisk()
このレコーディングがディスク・リポジトリを使用する場合はtrue
を返し、そうでない場合はtrue
を返します。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()
このレコーディングを停止します。
-
-
-
コンストラクタの詳細
-
Recording
public Recording()
設定なしでレコーディングを作成します。新しく作成されたレコーディングは、
RecordingState.NEW
状態にあります。 レコーディングを開始するには、start()
メソッドを呼び出します。- 例外:
IllegalStateException
- flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないかSecurityException
- セキュリティ・マネージャが使用され、FlightRecorderPermission "accessFlightRecorder"が設定されていない場合。
-
Recording
public Recording(Configuration configuration)
構成からの設定でレコーディングを作成します。次の例は、事前定義済の構成を使用するレコーディングの作成方法を示しています。
Recording r = new Recording(Configuration.getConfiguration("default"));
RecordingState.NEW
状態にあります。 レコーディングを開始するには、start()
メソッドを呼び出します。- パラメータ:
configuration
- 使用する設定が含まれている(null
ではない)構成- 例外:
IllegalStateException
- flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないかSecurityException
- セキュリティ・マネージャが使用され、FlightRecorderPermission "accessFlightRecorder"が設定されていない場合。- 関連項目:
Configuration
-
-
メソッドの詳細
-
start
public void start()
このレコーディングを開始します。このメソッドを呼び出す前に、レコーディング・オプションとイベント設定を構成することをお薦めします。 これを行う利点は、記録されたデータを分析するときの一貫性のある状態となり、構成をアトミックに適用できるためパフォーマンスが向上します。
このメソッドが正常に起動されると、このレコーディングは
RUNNING
状態になります。- 例外:
IllegalStateException
- レコーディングがすでに開始されているか、CLOSED
状態にあるか
-
scheduleStart
public void scheduleStart(Duration delay)
遅延後にこのレコーディングを開始します。このメソッドが正常に起動されると、このレコーディングは
DELAYED
状態になります。- パラメータ:
delay
-null
ではなく、このレコーディングを開始する前に待機する時間- 例外:
IllegalStateException
- レコーディングがNEW
状態でないかどうか
-
stop
public boolean stop()
このレコーディングを停止します。レコーディングを停止すると、再開できません。 このレコーディングに宛先が含まれる場合、データはその宛先に書き込まれ、レコーディングは閉じられます。 レコーディングを閉じると、データは使用できなくなります。
このメソッドが正常に起動されると、このレコーディングは
STOPPED
状態になります。- 戻り値:
- レコーディングが停止すると
true
、それ以外の場合はfalse
- 例外:
IllegalStateException
- レコーディングが開始されていないか、すでに停止している場合SecurityException
- セキュリティ・マネージャが存在し、呼出し側が宛先パスに書き込むFilePermission
を持っていない場合- 関連項目:
setDestination(Path)
-
getSettings
public Map<String,String> getSettings()
このレコーディングで使用される設定を返します。返された
Map
を変更しても、このレコーディングの設定は変更されません。このレコーディングの設定がない場合、空の
Map
が返されます。- 戻り値:
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("jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap()); settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap()); settings.put("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()
このレコーディングが現在保持されているレコーディング状態を返します。- 戻り値:
null
ではなく、レコーディング状態- 関連項目:
RecordingState
-
close
public void close()
このレコーディングに関連付けられているすべてのデータを解放します。このメソッドが正常に起動されると、このレコーディングは
CLOSED
状態になります。- 定義:
close
、インタフェースAutoCloseable
- 定義:
close
、インタフェースCloseable
-
copy
public Recording copy(boolean stop)
新しいレコーディングIDと名前を使用して、このレコーディングのクローンを返します。 クローンは、レコーディングを停止せずにデータをダンプするのに便利です。 クローンが作成されると、コピーするデータ量はsetMaxAge(Duration)
メソッドとsetMaxSize(long)
methodで制約されます。- パラメータ:
stop
- 新しく作成したコピーをすぐに停止する必要がある場合はtrue
、それ以外の場合はfalse
- 戻り値:
null
ではなく、レコーディング・コピー
-
dump
public void dump(Path destination) throws IOException
レコーディング・データをファイルに書き込みます。レコーディングを開始する必要がありますが、必ずしも停止する必要はありません。
- パラメータ:
destination
-null
ではなく、レコーディング・データが書き込まれるロケーション- 例外:
IOException
- 指定したロケーションにレコーディングをコピーできない場合SecurityException
- セキュリティ・マネージャが存在し、呼出し側が宛先パスに書き込むFilePermission
を持っていない場合
-
isToDisk
public boolean isToDisk()
このレコーディングがディスク・リポジトリを使用する場合はtrue
を返し、そうでない場合はtrue
を返します。値が設定されていない場合、
true
が戻されます。- 戻り値:
- レコーディングでディスク・リポジトリが使用される場合は、
true
、そうでない場合はtrue
-
setMaxSize
public void setMaxSize(long maxSize)
ディスク・リポジトリに保持されるデータ量を決定します。ディスクに格納されるデータのレコーディング量を制御するために、保持するデータの最大量を指定できます。 上限を超えた場合、Java Virtual Machine (JVM)は最も古いチャンクを削除し、新しいチャンクのための余裕を作成します。
最大限度または最大経過時間を設定しないと、レコーディングのサイズが無期限に拡大することがあります。
- パラメータ:
maxSize
- 保存するデータの量(無限大の場合は0
)- 例外:
IllegalArgumentException
-maxSize
が負の場合IllegalStateException
- レコーディングがCLOSED
状態にある場合
-
setMaxAge
public void setMaxAge(Duration maxAge)
ディスク・リポジトリに保存されるバック・データの量を決定します。ディスクに格納されるデータのレコーディング量を制御するために、データを保持する最大時間を指定できます。 指定した時間よりも古いディスクに格納されているデータは、Java Virtual Machine (JVM)によって削除されます。
最大限度または最大経過時間を設定しないと、レコーディングのサイズが無期限に拡大することがあります。
- パラメータ:
maxAge
- データが保持される時間の長さ(無限大の場合はnull
)。- 例外:
IllegalArgumentException
-maxAge
が負の場合IllegalStateException
- レコーディングがCLOSED
状態にあるかどうか
-
setDestination
public void setDestination(Path destination) throws IOException
データがレコーディング停止時に書き込まれるロケーション、またはデータがダンプされない場合はnull
を設定します。宛先が設定されている場合、データが宛先パスに正常にコピーされた後、このレコーディングは自動的に閉じられます。
宛先が設定されていない場合、Flight Recorderでは、このレコーディングがクローズされるまでレコーディング・データを保持します。
dump(Path)
メソッドを使用して、データを手動でファイルに書き込みます。- パラメータ:
destination
- 宛先パス、または、レコーディングを停止時にダンプしない場合はnull
- 例外:
IllegalStateException
- レコーディングがSTOPPED
またはCLOSED
状態にあるかどうか。SecurityException
- セキュリティ・マネージャが存在し、呼出し側がFilePermission
を持ってdestination
ファイルの読取り、書込みおよび削除を行うことができない場合IOException
- パスが書込み可能でない場合
-
getDestination
public Path getDestination()
レコーディングが停止したときにレコーディング・データが書き込まれる宛先ファイルを返します。宛先が設定されていない場合はnull
を返します。- 戻り値:
- 宛先ファイル、または設定されていない場合は
null
。
-
getId
public long getId()
このレコーディングの一意のIDを返します。- 戻り値:
- レコーディングID
-
setName
public void setName(String name)
解読可能な名前(たとえば、"My Recording"
)を設定します。- パラメータ:
name
-null
ではなく、レコーディング名- 例外:
IllegalStateException
- レコーディングがCLOSED
状態にある場合
-
setDumpOnExit
public void setDumpOnExit(boolean dumpOnExit)
このレコーディングを、JVMの終了時にディスクにダンプするかどうかを設定します。- パラメータ:
dumpOnExit
- このレコーディングをJVMの終了時にダンプする必要がある場合
-
getDumpOnExit
public boolean getDumpOnExit()
このレコーディングがJVMの終了時にディスクにダンプされるかどうかを返します。終了時にダンプが設定されていない場合、
false
が戻されます。- 戻り値:
- レコーディングが終了時にダンプされる場合は
true
、それ以外の場合はfalse
。
-
setToDisk
public void setToDisk(boolean disk)
このレコーディングをディスク・リポジトリに継続的にフラッシュするか、またはメモリー・バッファで使用可能なデータに制限するかを決定します。- パラメータ:
disk
- このレコーディングがディスクに書き込まれる場合true
、イン・メモリーならばfalse
-
getStream
public InputStream getStream(Instant start, Instant end) throws IOException
指定された間隔のデータ・ストリームを作成します。ストリームには、指定された範囲外のデータが含まれる場合があります。
- パラメータ:
the
- ストリームの開始時間またはnull
を開始してレコーディングの開始時間からデータを取得the
- ストリームの終了時間、または現在の時間までデータを取得するnull
。- 戻り値:
- 入力ストリーム、または
null
が指定されている場合は、その間隔でデータが使用可能になります。 - 例外:
IllegalArgumentException
-end
がstart
より前に発生した場合IOException
- ストリームを開くことができない場合
-
getDuration
public Duration getDuration()
このレコーディングに指定された継続時間を返します。継続時間が設定されていない場合はnull
を返します。レコーディングが
RecordingState.NEW
状態にある場合にのみ、期間を設定できます。- 戻り値:
- 希望のレコーディング時間、または時間が設定されていない場合は
null
。
-
setDuration
public void setDuration(Duration duration)
レコーディングが停止するまでの期間を設定します。デフォルトでは、レコーディングには(
null
)の期間はありません。- パラメータ:
duration
- 期間が設定されていない場合はnull
- 例外:
IllegalStateException
- レコーディングがSTOPPED
またはCLOSED
状態にあるかどうか
-
enable
public EventSettings enable(String name)
指定された名前のイベントを有効にします。複数のイベントの名前が(たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)である場合、名前と一致するすべてのイベントが有効になります。 特定のクラスを有効にするには、イベント・タイプIDの
enable(Class)
メソッドまたはString
表現を使用します。- パラメータ:
name
-null
ではなく、イベントの設定- 戻り値:
null
ではなく、さらなる構成のためのイベント設定- 関連項目:
EventType
-
disable
public EventSettings disable(String name)
指定された名前のイベントを無効にします。(たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)同じ名前のイベントが複数ある場合(たとえば、同じクラスが別のクラス・ローダーにロードされる)、名前に一致するすべてのイベントが無効になります。 特定のクラスを無効にするには、イベント・タイプIDの
disable(Class)
メソッドまたは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
のサブクラスでない場合
-
-