Module jdk.jfr
Package jdk.jfr

Class Recording

java.lang.Object
jdk.jfr.Recording
所有已实现的接口:
Closeable, AutoCloseable
public final class Recording extends Object implements Closeable
提供配置、启动、停止和将记录数据转储到磁盘的方法。

以下示例展示了如何配置、启动、停止和将记录数据转储到磁盘。

Configuration c = Configuration.getConfiguration("default");
try (Recording r = new Recording(c)) {
    r.start();
    System.gc();
    Thread.sleep(5000);
    r.stop();
    r.dump(Files.createTempFile("my-recording", ".jfr"));
}
自 JDK 版本:
9

  • Constructor Details

    • Recording

      public Recording(Map<String,String> settings)
      使用名称-值对映射中的设置创建记录。

      新创建的记录处于RecordingState.NEW状态。要启动记录，请调用start()方法。

      参数:
      settings - 名称-值对映射中的设置，不能为空
      抛出:
      IllegalStateException - 如果无法创建 Flight Recorder（例如，如果 Java 虚拟机（JVM）缺少 Flight Recorder 支持，或者无法创建或访问文件存储库）
      SecurityException - 如果使用了安全管理器且未设置 FlightRecorderPermission "accessFlightRecorder"
      参见:

    • 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 - 包含要使用的设置的配置，不能为空
      抛出:
      IllegalStateException - 如果无法创建 Flight Recorder（例如，如果 Java 虚拟机（JVM）缺少 Flight Recorder 支持，或者无法创建或访问文件存储库）
      SecurityException - 如果使用了安全管理器且未设置 FlightRecorderPermission "accessFlightRecorder"
      参见:

  • Method Details

    • start

      public void start()
      启动此记录。

      建议在调用此方法之前配置记录选项和事件设置。这样做的好处是在分析记录的数据时状态更一致，并且性能得到改善，因为配置可以以原子方式应用。

      成功调用此方法后，此记录将处于RUNNING状态。

      抛出:
      IllegalStateException - 如果记录已启动或处于CLOSED状态

    • scheduleStart

      public void scheduleStart(Duration delay)
      在延迟后启动此记录。

      成功调用此方法后，此记录将处于DELAYED状态。

      参数:
      delay - 启动此记录前等待的时间，不能为空
      抛出:
      IllegalStateException - 如果记录不处于NEW状态

    • stop

      public boolean stop()
      停止此记录。

      停止记录后无法重新启动。如果此记录有目标，则数据将写入该目标并关闭记录。记录关闭后，数据将不再可用。

      成功调用此方法后，此记录将处于STOPPED状态。

      返回:
      如果记录已停止，则返回true，否则返回false
      抛出:
      IllegalStateException - 如果记录未启动或已停止
      SecurityException - 如果存在安全管理器且调用者没有FilePermission以写入目标路径
      参见:

    • getSettings

      public Map<String,String> getSettings()
      返回此记录使用的设置。

      修改返回的Map不会更改此记录的设置。

      如果未为此记录设置任何设置，则返回空的Map。

      返回:
      记录设置，不能为空

    • 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
      参见:

    • 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
      将录制数据写入文件。

      要成功转储，录制必须处于运行状态或已停止并写入磁盘。如果录制处于任何其他状态，将抛出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 - 如果存在安全管理器且调用方没有对destination文件进行读取、写入和删除的FilePermission
      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
      为指定的时间间隔创建数据流。

      流可能包含指定范围之外的一些数据。

      如果录制不写入磁盘，则无法创建流，将返回null。

      参数:
      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 - 如果录制处于STOPPED或CLOSED状态

    • enable

      public EventSettings enable(String name)
      启用指定名称的事件。

      如果多个事件具有相同名称（例如，在不同的类加载器中加载相同的类），则启用与名称匹配的所有事件。要启用特定类，请使用enable(Class)方法或事件类型ID的String表示。

      参数：
      name - 事件的设置，不为null
      返回：
      用于进一步配置的事件设置，不为null
      参见：

    • 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的子类