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.

Since:

9

Method Summary

Modifier and Type	Method	Description
static void	addListener(FlightRecorderListener changeListener)	Adds a recorder listener.
static void	addPeriodicEvent(Class<? extends Event> eventClass, Runnable hook)	Adds a hook for a periodic event.
List<EventType>	getEventTypes()	Returns an immutable list that contains all currently registered events.
static FlightRecorder	getFlightRecorder()	Returns the Flight Recorder for the platform.
List<Recording>	getRecordings()	Returns an immutable list of the available recordings.
static boolean	isAvailable()	Returns true if the Java Virtual Machine (JVM) has Flight Recorder capabilities.
static boolean	isInitialized()	Returns true if Flight Recorder is 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 a hook for a periodic event.
Recording	takeSnapshot()	Creates a snapshot of all available recorded data.
static void	unregister(Class<? extends Event> eventClass)	Unregisters an event class.

Methods declared in class Object

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

Modifier and Type	Method	Description
protected Object	clone()	Creates and returns a copy of this object.
boolean	equals(Object obj)	Indicates whether some other object is "equal to" this one.
protected void	finalize()	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
final Class<?>	getClass()	Returns the runtime class of this Object.
int	hashCode()	Returns a hash code value for this object.
final void	notify()	Wakes up a single thread that is waiting on this object's monitor.
final void	notifyAll()	Wakes up all threads that are waiting on this object's monitor.
String	toString()	Returns a string representation of the object.
final void	wait()	Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
final void	wait(long timeoutMillis)	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
final void	wait(long timeoutMillis, int nanos)	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Method Details

getRecordings

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:

a list of recordings, not null

takeSnapshot

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:

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, then the invocation of this method is ignored.

Parameters:

eventClass - the event class to register, not null

Throws:

IllegalArgumentException - if class is abstract or not a subclass of Event

unregister

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 - the event class to unregistered, not null

Throws:

IllegalArgumentException - if a class is abstract or not a subclass of Event

getFlightRecorder

public static FlightRecorder getFlightRecorder()
                                        throws IllegalStateException

Returns the Flight Recorder for the platform.

Returns:

a Flight Recorder instance, not null

Throws:

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)

addPeriodicEvent

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

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 - the class that the hook should run for, not null

hook - the hook, not null

Throws:

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

removePeriodicEvent

public static boolean removePeriodicEvent(Runnable hook)

Removes a hook for a periodic event.

Parameters:

hook - the hook to remove, not null

Returns:

true if hook is removed, false otherwise

getEventTypes

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 register(Class) method.

Returns:

list of events, not null

addListener

public static void addListener(FlightRecorderListener changeListener)

Adds a recorder 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 - the listener to add, not null

removeListener

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 - listener to remove, not null

Returns:

true, if the listener could be removed, false otherwise

isAvailable

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:

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 is initialized.

Returns:

true, if Flight Recorder is initialized, false otherwise

See Also:

• for callback when Flight Recorder is initialized