模块  jdk.jfr
软件包  jdk.jfr

Class Recording

  • 实现的所有接口
    CloseableAutoCloseable

    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

        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 - 如果录制处于 STOPPEDCLOSED状态。
        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 - 如果录制是在 STOPPEDCLOSED状态
      • 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的子类