模块 jdk.jfr
包 jdk.jfr

类 Recording

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.dump(Files.createTempFile("my-recording", ".jfr"));
自从：
9

  • 构造方法详细信息

    • Recording

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

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

      参数：
      settings - 设置为名称-值对的映射，而不是 null
      抛出：
      IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机 (JVM) 缺少飞行记录器支持，或者无法创建或访问文件存储库）
      SecurityException - 如果使用了安全管理器并且未设置 FlightRecorderPermission“accessFlightRecorder”。
      参见：

    • Recording

      public Recording()
      创建没有任何设置的记录。

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

      抛出：
      IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机 (JVM) 缺少飞行记录器支持，或者无法创建或访问文件存储库）
      SecurityException - 如果使用了安全管理器并且未设置 FlightRecorderPermission“accessFlightRecorder”。

    • Recording

      public Recording(Configuration  configuration)
      使用配置中的设置创建记录。

      以下示例显示如何创建使用预定义配置的记录。

      Recording r = new Recording(Configuration.getConfiguration("default"));
      新创建的记录处于RecordingState.NEW 状态。要开始录制，请调用 start() 方法。
      参数：
      configuration - 包含要使用的设置的配置，而不是 null
      抛出：
      IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机 (JVM) 缺少飞行记录器支持，或者无法创建或访问文件存储库）
      SecurityException - 如果使用安全管理器并且未设置 FlightRecorderPermission“accessFlightRecorder”。
      参见：

  • 方法详情

    • 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 来写入目标路径
      参见：

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

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

      要使转储成功，记录必须 1) 正在运行，或 2) 停止并写入磁盘。如果录音处于任何其他状态，则会抛出 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。

      如果设置了目的地，则在数据成功复制到目的地路径后，此记录将自动关闭。

      如果目的地设置为not，则飞行记录器会保留记录数据，直到该记录关闭。使用 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
      为指定的时间间隔创建数据流。

      流中可能包含一些超出指定范围的数据。

      如果记录不在磁盘上，则无法创建流并返回 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)
      启用具有指定名称的事件。

      如果多个事件具有相同的名称（例如，相同的类在不同的类加载器中加载），则启用所有匹配该名称的事件。要启用特定类，请使用事件类型 ID 的 enable(Class) 方法或 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 的子类