Module jdk.jfr
Package jdk.jfr

Class FlightRecorder

java.lang.Object
jdk.jfr.FlightRecorder
public final class FlightRecorder extends Object
用于访问、控制和管理飞行记录器的类。

该类提供了创建、启动、停止和销毁记录的方法。

自 JDK 版本:
9

  • Method Details

    • getRecordings

      public List<Recording> getRecordings()
      返回一个包含所有可用记录的不可变列表。

      当记录创建时，记录变为可用。当记录处于 CLOSED 状态时（通常在调用 Recording.close() 后），记录变为不可用。

      返回值:
      记录列表，不为 null

    • takeSnapshot

      public Recording takeSnapshot()
      创建所有可用记录数据的快照。

      快照是处于 STOPPED 状态的合成记录。如果没有数据可用，则返回大小为 0 的记录。

      快照提供稳定的数据访问，以供后续操作使用（例如，更改间隔或减少数据大小的操作）。

      以下示例显示了如何创建快照并将数据子集写入文件。

      try (Recording snapshot = FlightRecorder.getFlightRecorder().takeSnapshot()) {
    if (snapshot.getSize() > 0) {
        snapshot.setMaxSize(100_000_000);
        snapshot.setMaxAge(Duration.ofMinutes(5));
        snapshot.dump(Paths.get("snapshot.jfr"));
    }
}
      当不再需要访问数据时，调用方必须关闭记录。
      返回值:
      所有可用记录数据的快照，不为 null

    • register

      public static void register(Class<? extends Event> eventClass)
      注册一个事件类。

      如果事件类已经注册，则忽略此方法的调用。

      参数:
      eventClass - 要注册的事件类，不为 null
      抛出:
      IllegalArgumentException - 如果类是抽象的或不是 Event 的子类
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("registerEvent")

    • unregister

      public static void unregister(Class<? extends Event> eventClass)
      注销一个事件类。

      如果事件类未注册，则忽略此方法的调用。

      参数:
      eventClass - 要注销的事件类，不为 null
      抛出:
      IllegalArgumentException - 如果类是抽象的或不是 Event 的子类
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("registerEvent")

    • getFlightRecorder

      public static FlightRecorder getFlightRecorder() throws IllegalStateException, SecurityException
      返回平台的飞行记录器。
      返回值:
      飞行记录器实例，不为 null
      抛出:
      IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机（JVM）缺少飞行记录器支持，或者无法创建或访问文件存储库）
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("accessFlightRecorder")

    • addPeriodicEvent

      public static void addPeriodicEvent(Class<? extends Event> eventClass, Runnable hook) throws SecurityException
      添加一个周期性事件的挂钩。

      挂钩的实现应尽快返回，以避免阻塞其他飞行记录器操作。挂钩应发出一个或多个指定类型的事件。添加挂钩时，可以使用 "period" 设置来配置调用的间隔。

      参数:
      eventClass - 挂钩应运行的类，不为 null
      hook - 挂钩，不为 null
      抛出:
      IllegalArgumentException - 如果类不是 Event 的子类、是抽象的或挂钩已添加
      IllegalStateException - 如果事件类具有 Registered(false) 注解且未手动注册
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("registerEvent")

    • removePeriodicEvent

      public static boolean removePeriodicEvent(Runnable hook) throws SecurityException
      移除一个周期性事件的挂钩。
      参数:
      hook - 要移除的挂钩，不为 null
      返回值:
      如果成功移除挂钩则返回 true，否则返回 false
      抛出:
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("registerEvent")

    • getEventTypes

      public List<EventType> getEventTypes()
      返回一个包含当前所有已注册事件的不可变列表。

      默认情况下，事件在首次使用时注册，通常在分配事件对象时。要确保尽早可见事件，可以通过调用 register(Class) 方法来触发注册。

      返回值:
      事件列表，不为 null

    • addListener

      public static void addListener(FlightRecorderListener changeListener)
      添加一个记录器监听器并捕获 AccessControlContext 以在调用监听器时使用。

      如果在添加监听器时飞行记录器已初始化，则在从此方法返回之前会调用 FlightRecorderListener.recorderInitialized(FlightRecorder) 方法。

      参数:
      changeListener - 要添加的监听器，不为 null
      抛出:
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("accessFlightRecorder")

    • removeListener

      public static boolean removeListener(FlightRecorderListener changeListener)
      移除一个记录器监听器。

      如果多次添加相同的监听器，则只会移除一个实例。

      参数:
      changeListener - 要移除的监听器，不为 null
      返回值:
      如果成功移除监听器则返回 true，否则返回 false
      抛出:
      SecurityException - 如果存在安全管理器且调用方没有 FlightRecorderPermission("accessFlightRecorder")

    • isAvailable

      public static boolean isAvailable()
      如果 Java 虚拟机（JVM）具有飞行记录器功能，则返回 true。

      此方法可以快速检查飞行记录器是否可以初始化，而无需实际执行初始化工作。该值可能在运行时更改，不建议缓存它。

      返回值:
      如果飞行记录器可用则返回 true，否则返回 false
      参见:

    • isInitialized

      public static boolean isInitialized()
      如果飞行记录器已初始化，则返回 true。
      返回值:
      如果飞行记录器已初始化则返回 true，否则返回 false
      参见: