- 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(类<? extends Event> eventClass)
禁用事件。EventSettings
disable(String name)
禁用具有指定名称的事件。void
dump(Path destination)
将记录数据写入文件。EventSettings
enable(类<? 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
如果这个记录使用的磁盘库,false
否则。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虚拟机(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虚拟机(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
状态。- Specified by:
-
close
在界面AutoCloseable
- Specified by:
-
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
- 如果无法将录制内容复制到指定位置 -
SecurityException
- 如果存在安全管理器且调用者没有FilePermission
写入目标路径
-
isToDisk
public boolean isToDisk()
返回true
如果这个记录使用的磁盘库,false
否则。如果未设置任何值,则返回
true
。- 结果
-
true
如果录制使用磁盘存储库,false
-
setMaxSize
public void setMaxSize(long maxSize)
确定磁盘存储库中保留的数据量。要控制存储在磁盘上的记录数据量,可以指定要保留的最大数据量。 超过最大限制时,Java虚拟机(JVM)将删除最旧的块,以便为更新的块腾出空间。
如果既未设置最大限制也未设置最大年龄,则录制的大小可能会无限增长。
- 参数
-
maxSize
- 要保留的数据量,如果无限,0
- 异常
-
IllegalArgumentException
- 如果maxSize
是负数 -
IllegalStateException
- 如果录制处于CLOSED
状态
-
setMaxAge
public void setMaxAge(Duration maxAge)
确定将数据保留在磁盘存储库中的距离。要控制存储在磁盘上的记录数据量,可以指定保留数据的最大时间长度。 存储在磁盘上的数据早于指定的时间长度将被Java虚拟机(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(类<? extends Event> eventClass)
启用事件。- 参数
-
eventClass
- 要启用的事件,而不是null
- 结果
-
进一步配置的事件设置,而不是
null
- 异常
-
IllegalArgumentException
- 如果eventClass
是抽象类或不是Event
的子类
-
disable
public EventSettings disable(类<? extends Event> eventClass)
禁用事件。- 参数
-
eventClass
- 要启用的事件,而不是null
- 结果
-
进一步配置的事件设置,而不是
null
- 异常
-
IllegalArgumentException
- 如果eventClass
是抽象类或不是Event
的子类
-
-