OpenJDK 1.22 · jdk.jfr.FlightRecorder · APIdia, the JavaDoc alternative

Modifier and Type	Field and Description
private static volatile boolean	initialized
private final PlatformRecorder	internal
private static volatile FlightRecorder	platformRecorder

Access	Constructor and Description
private	FlightRecorder(PlatformRecorder internal)

Method Summary

Modifier and Type	Method and Description
public static void	addListener(FlightRecorderListener the listener to add, not `null` changeListener) Adds a recorder listener and captures the `AccessControlContext` to use when invoking the listener.
public static void	addPeriodicEvent(Class<? extends Event> the class that the hook should run for, not `null` eventClass, Runnable the hook, not `null` hook) Adds a hook for a periodic event.
public List<EventType>	Returns: list of events, not `null` getEventTypes() Returns an immutable list that contains all currently registered events.
public static FlightRecorder	Returns: a Flight Recorder instance, not `null` getFlightRecorder() Returns the Flight Recorder for the platform.
pack-priv PlatformRecorder	getInternal()
public List<Recording>	Returns: a list of recordings, not `null` getRecordings() Returns an immutable list of the available recordings.
public static boolean	Returns: `true`, if Flight Recorder is available, `false` otherwise isAvailable() Returns `true` if the Java Virtual Machine (JVM) has Flight Recorder capabilities.
public static boolean	Returns: `true`, if Flight Recorder is initialized, `false` otherwise isInitialized() Returns `true` if Flight Recorder is initialized.
public static void	register(Class<? extends Event> the event class to register, not `null` eventClass) Registers an event class.
public static boolean	Returns: `true`, if the listener could be removed, `false` otherwise removeListener(FlightRecorderListener listener to remove, not `null` changeListener) Removes a recorder listener.
public static boolean	Returns: `true` if hook is removed, `false` otherwise removePeriodicEvent(Runnable the hook to remove, not `null` hook) Removes a hook for a periodic event.
public Recording	Returns: a snapshot of all available recording data, not `null` takeSnapshot() Creates a snapshot of all available recorded data.
public static void	unregister(Class<? extends Event> the event class to unregistered, not `null` eventClass) Unregisters an event class.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

initialized	back to summary
private static volatile boolean initialized

internal	back to summary
private final PlatformRecorder internal

platformRecorder	back to summary
private static volatile FlightRecorder platformRecorder

FlightRecorder	back to summary
private FlightRecorder(PlatformRecorder internal)

Method Detail

addListener back to summary

addListener	back to summary
public static void addListener(FlightRecorderListener changeListener) Adds a recorder listener and captures the `AccessControlContext` to use when invoking the listener. If Flight Recorder is already initialized when the listener is added, then the method `FlightRecorderListener#recorderInitialized(FlightRecorder)` method is invoked before returning from this method. Parameters changeListener:FlightRecorderListener the listener to add, not `null` Exceptions SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("accessFlightRecorder")`

public static void addListener(FlightRecorderListener changeListener)

Adds a recorder listener and captures the AccessControlContext to use when invoking the listener.

If Flight Recorder is already initialized when the listener is added, then the method FlightRecorderListener#recorderInitialized(FlightRecorder) method is invoked before returning from this method.

Parameters

changeListener:FlightRecorderListener: the listener to add, not null

Exceptions

SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("accessFlightRecorder")

addPeriodicEvent back to summary

addPeriodicEvent	back to summary
public static void addPeriodicEvent(Class<? extends Event> eventClass, Runnable hook) throws SecurityException Adds a hook for a periodic event. The implementation of the hook should return as soon as possible, to avoid blocking other Flight Recorder operations. The hook should emit one or more events of the specified type. When a hook is added, the interval at which the call is invoked is configurable using the `"period"` setting. Parameters eventClass:Class<? extends Event> the class that the hook should run for, not `null` hook:Runnable the hook, not `null` Exceptions SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("registerEvent")` IllegalArgumentException: if a class is not a subclass of `Event`, is abstract, or the hook is already added IllegalStateException: if the event class has the `Registered(false)` annotation and is not registered manually

public static void addPeriodicEvent(Class<? extends Event> eventClass, Runnable hook) throws SecurityException

Adds a hook for a periodic event.

The implementation of the hook should return as soon as possible, to avoid blocking other Flight Recorder operations. The hook should emit one or more events of the specified type. When a hook is added, the interval at which the call is invoked is configurable using the "period" setting.

Parameters

eventClass:Class<? extends Event>: the class that the hook should run for, not null
hook:Runnable: the hook, not null

Exceptions

SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")
IllegalArgumentException:: if a class is not a subclass of Event, is abstract, or the hook is already added
IllegalStateException:: if the event class has the Registered(false) annotation and is not registered manually

getEventTypes back to summary

getEventTypes	back to summary
public List<EventType> getEventTypes() Returns an immutable list that contains all currently registered events. By default, events are registered when they are first used, typically when an event object is allocated. To ensure an event is visible early, registration can be triggered by invoking the `FlightRecorder#register(Class)` method. Returns:List<EventType> list of events, not `null`

public List<EventType> getEventTypes()

Returns an immutable list that contains all currently registered events.

By default, events are registered when they are first used, typically when an event object is allocated. To ensure an event is visible early, registration can be triggered by invoking the FlightRecorder#register(Class) method.

Returns:List<EventType>: list of events, not null

getFlightRecorder back to summary

getFlightRecorder	back to summary
public static FlightRecorder getFlightRecorder() throws IllegalStateException, SecurityException Returns the Flight Recorder for the platform. Returns:FlightRecorder a Flight Recorder instance, not `null` Exceptions IllegalStateException: if Flight Recorder can't be created (for example, if the Java Virtual Machine (JVM) lacks Flight Recorder support, or if the file repository can't be created or accessed) SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("accessFlightRecorder")`

public static FlightRecorder getFlightRecorder() throws IllegalStateException, SecurityException

Returns the Flight Recorder for the platform.

Returns:FlightRecorder

a Flight Recorder instance, not null

Exceptions

IllegalStateException:: if Flight Recorder can't be created (for example, if the Java Virtual Machine (JVM) lacks Flight Recorder support, or if the file repository can't be created or accessed)
SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("accessFlightRecorder")

getInternal	back to summary
pack-priv PlatformRecorder getInternal()

getRecordings back to summary

getRecordings	back to summary
public List<Recording> getRecordings() Returns an immutable list of the available recordings. A recording becomes available when it is created. It becomes unavailable when it is in the `CLOSED` state, typically after a call to `Recording#close()`. Returns:List<Recording> a list of recordings, not `null`

public List<Recording> getRecordings()

Returns an immutable list of the available recordings.

A recording becomes available when it is created. It becomes unavailable when it is in the CLOSED state, typically after a call to Recording#close().

Returns:List<Recording>: a list of recordings, not null

isAvailable back to summary

isAvailable	back to summary
public static boolean isAvailable() Returns `true` if the Java Virtual Machine (JVM) has Flight Recorder capabilities. This method can quickly check whether Flight Recorder can be initialized, without actually doing the initialization work. The value may change during runtime and it is not safe to cache it. Returns:boolean `true`, if Flight Recorder is available, `false` otherwise See Also {@link FlightRecorderListener} for callback when Flight Recorder is initialized

public static boolean isAvailable()

Returns true if the Java Virtual Machine (JVM) has Flight Recorder capabilities.

This method can quickly check whether Flight Recorder can be initialized, without actually doing the initialization work. The value may change during runtime and it is not safe to cache it.

Returns:boolean: true, if Flight Recorder is available, false otherwise
See Also: {@link FlightRecorderListener} for callback when Flight Recorder is initialized

isInitialized back to summary

isInitialized	back to summary
public static boolean isInitialized() Returns `true` if Flight Recorder is initialized. Returns:boolean `true`, if Flight Recorder is initialized, `false` otherwise See Also {@link FlightRecorderListener} for callback when Flight Recorder is initialized

public static boolean isInitialized()

Returns true if Flight Recorder is initialized.

Returns:boolean: true, if Flight Recorder is initialized, false otherwise
See Also: {@link FlightRecorderListener} for callback when Flight Recorder is initialized

register	back to summary
public static void register(Class<? extends Event> eventClass) Registers an event class. If the event class is already registered, then the invocation of this method is ignored. Parameters eventClass:Class<? extends Event> the event class to register, not `null` Exceptions IllegalArgumentException: if class is abstract or not a subclass of `Event` SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("registerEvent")`

public static void register(Class<? extends Event> eventClass)

Registers an event class.

If the event class is already registered, then the invocation of this method is ignored.

Parameters

eventClass:Class<? extends Event>: the event class to register, not null

Exceptions

IllegalArgumentException:: if class is abstract or not a subclass of Event
SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")

removeListener back to summary

removeListener	back to summary
public static boolean removeListener(FlightRecorderListener changeListener) Removes a recorder listener. If the same listener is added multiple times, only one instance is removed. Parameters changeListener:FlightRecorderListener listener to remove, not `null` Returns:boolean `true`, if the listener could be removed, `false` otherwise Exceptions SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("accessFlightRecorder")`

public static boolean removeListener(FlightRecorderListener changeListener)

Removes a recorder listener.

If the same listener is added multiple times, only one instance is removed.

Parameters

changeListener:FlightRecorderListener: listener to remove, not null

Returns:boolean

true, if the listener could be removed, false otherwise

Exceptions

SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("accessFlightRecorder")

removePeriodicEvent back to summary

removePeriodicEvent	back to summary
public static boolean removePeriodicEvent(Runnable hook) throws SecurityException Removes a hook for a periodic event. Parameters hook:Runnable the hook to remove, not `null` Returns:boolean `true` if hook is removed, `false` otherwise Exceptions SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("registerEvent")`

public static boolean removePeriodicEvent(Runnable hook) throws SecurityException

Removes a hook for a periodic event.

Parameters

hook:Runnable: the hook to remove, not null

Returns:boolean

true if hook is removed, false otherwise

Exceptions

SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")

takeSnapshot back to summary

takeSnapshot	back to summary
public Recording takeSnapshot() Creates a snapshot of all available recorded data. A snapshot is a synthesized recording in a `STOPPED` state. If no data is available, a recording with size `0` is returned. A snapshot provides stable access to data for later operations (for example, operations to change the interval or to reduce the data size). The following example shows how to create a snapshot and write a subset of the data to a file. `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")); } }` 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")); } } The caller must close the recording when access to the data is no longer needed. Returns:Recording a snapshot of all available recording data, not `null`

public Recording takeSnapshot()

Creates a snapshot of all available recorded data.

A snapshot is a synthesized recording in a STOPPED state. If no data is available, a recording with size 0 is returned.

A snapshot provides stable access to data for later operations (for example, operations to change the interval or to reduce the data size).

The following example shows how to create a snapshot and write a subset of the data to a file.

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"));
    }
}

The caller must close the recording when access to the data is no longer needed.

Returns:Recording: a snapshot of all available recording data, not null

unregister back to summary

unregister	back to summary
public static void unregister(Class<? extends Event> eventClass) Unregisters an event class. If the event class is not registered, then the invocation of this method is ignored. Parameters eventClass:Class<? extends Event> the event class to unregistered, not `null` Exceptions IllegalArgumentException: if a class is abstract or not a subclass of `Event` SecurityException: if a security manager exists and the caller does not have `FlightRecorderPermission("registerEvent")`

public static void unregister(Class<? extends Event> eventClass)

Unregisters an event class.

If the event class is not registered, then the invocation of this method is ignored.

Parameters

eventClass:Class<? extends Event>: the event class to unregistered, not null

Exceptions

IllegalArgumentException:: if a class is abstract or not a subclass of Event
SecurityException:: if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")

public final Class FlightRecorder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail