模块  jdk.jfr
软件包  jdk.jfr

Class Recording

  • 实现的所有接口
    Closeable ， AutoCloseable 
    public final class Recordingextends Objectimplements 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 - 如果录制处于 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的子类