模块 jdk.jfr
包 jdk.jfr.consumer

类 RecordingStream

java.lang.Object
jdk.jfr.consumer.RecordingStream
所有已实现的接口：
AutoCloseable , EventStream
public final class RecordingStream extends Object implements AutoCloseable , EventStream
记录流从当前 JVM（Java 虚拟机）生成事件。

以下示例显示如何使用默认配置记录事件并将垃圾收集、CPU 负载和 JVM 信息事件打印到标准输出。

Configuration c = Configuration.getConfiguration("default");
try (var rs = new RecordingStream(c)) {
  rs.onEvent("jdk.GarbageCollection", System.out::println);
  rs.onEvent("jdk.CPULoad", System.out::println);
  rs.onEvent("jdk.JVMInformation", System.out::println);
  rs.start();
}
自从：
14

  • 构造方法详细信息

    • RecordingStream

      public RecordingStream()
      为当前 JVM（Java 虚拟机）创建一个事件流。
      抛出：
      IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机 (JVM) 缺少飞行记录器支持，或者无法创建或访问文件存储库）
      SecurityException - 如果存在安全管理器且调用者没有 FlightRecorderPermission("accessFlightRecorder")

    • RecordingStream

      public RecordingStream(Configuration  configuration)
      使用配置中的设置创建录制流。

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

      var c = Configuration.getConfiguration("default");
try (var rs = new RecordingStream(c)) {
  rs.onEvent(System.out::println);
  rs.start();
}
      参数：
      configuration - 包含要使用的设置的配置，而不是 null
      抛出：
      IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机 (JVM) 缺少飞行记录器支持，或者无法创建或访问文件存储库）
      SecurityException - 如果使用安全管理器并且未设置 FlightRecorderPermission“accessFlightRecorder”。
      参见：

  • 方法详情

    • enable

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

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

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

    • setSettings

      public void setSettings(Map <String ,String > settings)
      替换此录制流的所有设置。

      以下示例使用“默认”配置记录 20 秒，然后将设置更改为“配置文件”配置。

      Configuration defaultConfiguration = Configuration.getConfiguration("default");
Configuration profileConfiguration = Configuration.getConfiguration("profile");
try (var rs = new RecordingStream(defaultConfiguration)) {
  rs.onEvent(System.out::println);
  rs.startAsync();
  Thread.sleep(20_000);
  rs.setSettings(profileConfiguration.getSettings());
  Thread.sleep(20_000);
}
      参数：
      settings - 要设置的设置，而不是 null
      参见：

    • enable

      public EventSettings  enable(Class <? extends Event > eventClass)
      启用事件。
      参数：
      eventClass - 要启用的事件，而不是 null
      返回：
      用于进一步配置的事件设置，而不是null
      抛出：
      IllegalArgumentException - 如果 eventClass 是抽象类或不是 Event 的子类

    • disable

      public EventSettings  disable(String  name)
      禁用具有指定名称的事件。

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

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

    • disable

      public EventSettings  disable(Class <? extends Event > eventClass)
      禁用事件。
      参数：
      eventClass - 要启用的事件，而不是 null
      返回：
      用于进一步配置的事件设置，而不是null
      抛出：
      IllegalArgumentException - 如果 eventClass 是抽象类或不是 Event 的子类

    • setMaxAge

      public void setMaxAge(Duration  maxAge)
      确定为流保留多远的数据。

      要控制存储在磁盘上的记录数据量，可以指定保留数据的最大时间长度。 Java 虚拟机 (JVM) 删除存储在磁盘上超过指定时间长度的数据。

      如果既没有设置最大限制也没有设置最大年龄，如果事件发生，记录的大小可能会无限增长

      参数：
      maxAge - 数据保存的时间长度，或者 null 如果无限
      抛出：
      IllegalArgumentException - 如果 maxAge 为负
      IllegalStateException - 如果录音处于 CLOSED 状态

    • setMaxSize

      public void setMaxSize(long maxSize)
      确定为流保留多少数据。

      要控制存储在磁盘上的记录数据量，可以指定要保留的最大数据量。当超过最大限制时，Java 虚拟机 (JVM) 会删除最旧的块以为更新的块腾出空间。

      如果既没有设置最大限制也没有设置最大年龄，记录的大小可能会无限增长。

      大小以字节为单位。

      参数：
      maxSize - 要保留的数据量，0 如果无限
      抛出：
      IllegalArgumentException - 如果 maxSize 为负
      IllegalStateException - 如果录音处于 CLOSED 状态

    • setReuse

      public void setReuse(boolean reuse)
      从接口 EventStream 复制的描述
      指定可以重复使用EventStream.onEvent(Consumer) 操作中的事件对象。

      如果 reuse 设置为 true ，则动作完成后不应保留对事件对象的引用。

      指定者：
      setReuse 在接口 EventStream 中
      参数：
      reuse - true 如果事件对象可以重用，false 否则

    • setOrdered

      public void setOrdered(boolean ordered)
      从接口 EventStream 复制的描述
      指定事件按时间顺序到达，按它们提交到流的时间排序。
      指定者：
      setOrdered 在接口 EventStream 中
      参数：
      ordered - 如果事件对象按时间顺序到达 EventStream.onEvent(Consumer)

    • setStartTime

      public void setStartTime(Instant  startTime)
      从接口 EventStream 复制的描述
      指定流的开始时间。

      必须在开始流之前设置开始时间

      指定者：
      setStartTime 在接口 EventStream 中
      参数：
      startTime - 开始时间，而不是 null
      参见：

    • setEndTime

      public void setEndTime(Instant  endTime)
      从接口 EventStream 复制的描述
      指定流的结束时间。

      必须在开始流之前设置结束时间。

      在结束时间，流关闭。

      指定者：
      setEndTime 在接口 EventStream 中
      参数：
      endTime - 结束时间，而不是 null
      参见：

    • onEvent

      public void onEvent(String  eventName, Consumer <RecordedEvent > action)
      从接口 EventStream 复制的描述
      注册一个操作以对所有匹配名称的事件执行。
      指定者：
      onEvent 在接口 EventStream 中
      参数：
      eventName - 事件的名称，而不是 null
      action - 对每个与事件名称匹配的 RecordedEvent 执行的操作，而不是 null

    • onEvent

      public void onEvent(Consumer <RecordedEvent > action)
      从接口 EventStream 复制的描述
      注册一个操作以对流中的所有事件执行。

      要对事件类型的子集执行操作，请考虑使用 EventStream.onEvent(String, Consumer) 和 EventStream.onMetadata(Consumer) ，因为它可能比通用操作中实现的任何选择或过滤机制更高效。

      指定者：
      onEvent 在接口 EventStream 中
      参数：
      action - 对每个 RecordedEvent 执行的操作，而不是 null
      参见：

    • onFlush

      public void onFlush(Runnable  action)
      从接口 EventStream 复制的描述
      注册在流被刷新后执行的操作。
      指定者：
      onFlush 在接口 EventStream 中
      参数：
      action - 在刷新流后执行的操作，而不是 null

    • onClose

      public void onClose(Runnable  action)
      从接口 EventStream 复制的描述
      注册在流关闭时要执行的操作。

      如果流已经关闭，则将在当前线程中立即执行操作。

      指定者：
      onClose 在接口 EventStream 中
      参数：
      action - 在流关闭后执行的操作，而不是 null
      参见：

    • onError

      public void onError(Consumer <Throwable > action)
      从接口 EventStream 复制的描述
      注册发生异常时要执行的操作。

      如果未注册操作，则会将异常堆栈跟踪打印到标准错误。

      注册一个动作会重写默认行为。如果注册了多个动作，则按照注册的顺序执行。

      如果此方法本身抛出异常，则结果行为是未定义的。

      指定者：
      onError 在接口 EventStream 中
      参数：
      action - 发生异常时要执行的操作，而不是 null

    • close

      public void close()
      从接口 AutoCloseable 复制的描述
      关闭此资源，放弃任何基础资源。在 try -with-resources 语句管理的对象上自动调用此方法。
      指定者：
      close 在接口 AutoCloseable 中
      指定者：
      close 在接口 EventStream 中

    • remove

      public boolean remove(Object  action)
      从接口 EventStream 复制的描述
      注销一个动作。

      如果动作已被注册多次，则所有实例都将被注销。

      指定者：
      remove 在接口 EventStream 中
      参数：
      action - 注销操作，而不是 null
      返回：
      true 如果操作未注册，false 否则
      参见：

    • start

      public void start()
      从接口 EventStream 复制的描述
      开始处理动作。

      操作在当前线程中执行。

      要停止流，请使用 EventStream.close() 方法。

      指定者：
      start 在接口 EventStream 中

    • startAsync

      public void startAsync()
      开始异步处理动作。

      操作在一个单独的线程中执行。

      要停止流，请使用 close() 方法。

      以下示例打印十秒钟的 CPU 使用率。当当前线程离开 try-with-resources 块时，流将停止/关闭。

      try (var stream = new RecordingStream()) {
  stream.enable("jdk.CPULoad").withPeriod(Duration.ofSeconds(1));
  stream.onEvent("jdk.CPULoad", event -> {
    System.out.println(event);
  });
  stream.startAsync();
  Thread.sleep(10_000);
}
      指定者：
      startAsync 在接口 EventStream 中
      抛出：
      IllegalStateException - 如果流已经启动或关闭

    • stop

      public boolean stop()
      停止录制流。

      停止开始的流并等待记录中的所有事件都被消耗。

      在操作中调用此方法，例如在 onEvent(Consumer) 方法中，可能会无限期地阻止流。要突然停止流，请使用 close() 方法。

      以下代码片段说明了如何将此方法与 startAsync() 方法结合使用来监视测试方法期间发生的情况：

      AtomicBoolean socketUse = new AtomicBoolean();
try (var r = new RecordingStream()) {
  r.setMaxSize(Long.MAX_VALUE);
  r.enable("jdk.SocketWrite").withoutThreshold();
  r.enable("jdk.SocketRead").withoutThreshold();
  r.onEvent(event -> socketUse.set(true));
  r.startAsync();
  testFoo();
  r.stop();
  if (socketUse.get()) {
    r.dump(Path.of("socket-events.jfr"));
    throw new AssertionError("testFoo() should not use network");
  }
}
      返回：
      true 如果录制停止，false 否则
      抛出：
      IllegalStateException - 如果录制未开始或已经停止
      自从：
      20

    • dump

      public void dump(Path  destination) throws IOException
      将录音数据写入文件。

      录制流必须开始，但不能关闭。

      强烈建议在开始流之前设置最大年龄或最大大小。否则，转储可能不包含任何事件。

      参数：
      destination - 写入记录数据的位置，而不是 null
      抛出：
      IOException - 如果无法将录制数据复制到指定位置，或者流已关闭或未启动。
      SecurityException - 如果存在安全管理器并且调用者没有 FilePermission 来写入目标路径
      自从：
      17
      参见：

    • awaitTermination

      public void awaitTermination(Duration  timeout) throws InterruptedException
      从接口 EventStream 复制的描述
      阻塞直到所有操作完成，或者流关闭，或者发生超时，或者当前线程被中断，以先发生者为准。
      指定者：
      awaitTermination 在接口 EventStream 中
      参数：
      timeout - 最长时间等待，而不是 null
      抛出：
      InterruptedException - 如果在等待时被打断
      参见：

    • awaitTermination

      public void awaitTermination() throws InterruptedException
      从接口 EventStream 复制的描述
      阻塞直到所有操作完成，或者流关闭，或者当前线程被中断，以先发生者为准。
      指定者：
      awaitTermination 在接口 EventStream 中
      抛出：
      InterruptedException - 如果在等待时被打断
      参见：