Module jdk.jfr
Package jdk.jfr.consumer

Class 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();
}
自 JDK 版本:
14

  • Constructor Details

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

  • Method Details

    • enable

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

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

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

    • setSettings

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

      以下示例使用“default”配置记录20秒，然后将设置更改为“profile”配置。

      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 - 要设置的设置，不能为空
      参见:

    • enable

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

    • disable

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

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

      参数:
      name - 事件的设置，不能为空
      返回:
      用于进一步配置的事件设置，不能为空

    • disable

      public EventSettings disable(Class<? extends Event> eventClass)
      禁用事件。
      参数:
      eventClass - 要启用的事件，不能为空
      返回:
      用于进一步配置的事件设置，不能为空
      抛出:
      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) 操作中事件对象可以被重用。

      如果重用设置为 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 - 写入记录数据的位置，不能为空
      抛出：
      IOException - 如果无法将记录数据复制到指定位置，或者流已关闭或未启动
      SecurityException - 如果存在安全管理器且调用者没有写入目标路径的FilePermission
      自：
      17
      参见：

    • awaitTermination

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

    • awaitTermination

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