Module jdk.jfr

Package jdk.jfr

Class FlightRecorder

java.lang.Object

jdk.jfr.FlightRecorder

public final class FlightRecorder
extends Object

Class for accessing, controlling and managing Flight Recorder.

This class provides the methods necessary for creating, starting, stopping and destroying recordings as well as listen to state changes.

Since:

9

Method Summary

Modifier and Type	Method	Description
static void	addListener(FlightRecorderListener changeListener)	Adds a recorder listener and captures the AccessControlContext to be used when invoking the listener.
static void	addPeriodicEvent(Class<? extends Event> eventClass, Runnable hook)	Adds a callback for a periodic event.
List<EventType>	getEventTypes()	Returns an immutable list containing all currently registered events.
static FlightRecorder	getFlightRecorder()	Returns the Flight Recorder for the platform.
List<Recording>	getRecordings()	Returns an immutable list of available recordings.
static boolean	isAvailable()	Returns true if the JVM has Flight Recorder capabilities.
static boolean	isInitialized()	Returns true if Flight Recorder has been initialized.
static void	register(Class<? extends Event> eventClass)	Registers an event class.
static boolean	removeListener(FlightRecorderListener changeListener)	Removes a recorder listener.
static boolean	removePeriodicEvent(Runnable hook)	Removes callback hook for a periodic event.
Recording	takeSnapshot()	Creates a recording snapshot of all available recorded data.
static void	unregister(Class<? extends Event> eventClass)	Unregisters an event class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getRecordings

public List<Recording> getRecordings()

Returns an immutable list of available recordings. A recording becomes available when it is created, and unavailable when it is in the CLOSED state, typically after a call to Recording.close() .

Returns:

a list of recordings, not null

takeSnapshot

public Recording takeSnapshot()

Creates a recording snapshot of all available recorded data.

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

A snapshot gives stable data access for later operations, such as narrowing the time interval or reducing the data size.

Example,

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

It is the caller's responsibility to close the recording when access to the data is no longer needed.

Returns:

a snapshot of all available recording data, not null

register

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

Registers an event class.

If the event class is already registered the invocation of this method will be ignored.

Parameters:

eventClass - event class to register, not null

Throws:

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

unregister

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

Unregisters an event class.

If the event class is not registered the invocation to this method will be ignored.

Parameters:

eventClass - event class to unregistered, not null

Throws:

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

getFlightRecorder

public static FlightRecorder getFlightRecorder()
                                        throws IllegalStateException,
                                               SecurityException

Returns the Flight Recorder for the platform.

Returns:

a Flight Recorder instance, not null

Throws:

IllegalStateException - if the platform Flight Recorder couldn't be created, for instance if commercial features isn't unlocked, 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")

addPeriodicEvent

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

Adds a callback 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 commit one or more events of the specified type. Once a hook has been added, the interval at which the call will be invoked is configurable using the "period" setting.

Parameters:

eventClass - class that hook should run for, not null

hook - the hook, not null

Throws:

IllegalArgumentException - if class is not a subclass of Event, is abstract or the hook has already been added

IllegalStateException - if the event class has the annotation Registered(false) and was not registered manually

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

removePeriodicEvent

public static boolean removePeriodicEvent(Runnable hook)
                                   throws SecurityException

Removes callback hook for a periodic event.

Parameters:

hook - the hook to remove, not null

Returns:

true if hook was removed, false otherwise

Throws:

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

getEventTypes

public List<EventType> getEventTypes()

Returns an immutable list containing 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 calling register(Class).

Returns:

list of events, not null

addListener

public static void addListener(FlightRecorderListener changeListener)

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

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

Parameters:

changeListener - the listener to add, not null

Throws:

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

removeListener

public static boolean removeListener(FlightRecorderListener changeListener)

Removes a recorder listener.

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

Parameters:

changeListener - listener to remove, not null

Returns:

true, if the listener could be removed, false otherwise

Throws:

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

isAvailable

public static boolean isAvailable()

Returns true if the JVM has Flight Recorder capabilities.

Purpose of this method is to quickly check if 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:

true, if flight recorder is available, false otherwise

See Also:

for callback when Flight Recorder is initialized

isInitialized

public static boolean isInitialized()

Returns true if Flight Recorder has been initialized.

Returns:

true, if flight recorder has been initialized, false otherwise

See Also:

for callback when Flight Recorder is initialized