This class provides the methods necessary for creating, starting, stopping, and destroying recordings.
- Since:
- 9
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
addListener
(FlightRecorderListener changeListener) Adds a recorder listener and captures theAccessControlContext
to use when invoking the listener.static void
addPeriodicEvent
(Class<? extends Event> eventClass, Runnable hook) Adds a hook for a periodic event.Returns an immutable list that contains all currently registered events.static FlightRecorder
Returns the Flight Recorder for the platform.Returns an immutable list of the available recordings.static boolean
Returnstrue
if the Java Virtual Machine (JVM) has Flight Recorder capabilities.static boolean
Returnstrue
if Flight Recorder is initialized.static void
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.Creates a snapshot of all available recorded data.static void
unregister
(Class<? extends Event> eventClass) Unregisters an event class.
-
Method Details
-
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 toRecording.close()
.- Returns:
- a list of recordings, not
null
-
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 size0
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")); } }
- Returns:
- a snapshot of all available recording data, not
null
-
register
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, notnull
- Throws:
IllegalArgumentException
- if class is abstract or not a subclass ofEvent
SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("registerEvent")
-
unregister
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, notnull
- Throws:
IllegalArgumentException
- if a class is abstract or not a subclass ofEvent
SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("registerEvent")
-
getFlightRecorder
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)SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("accessFlightRecorder")
-
addPeriodicEvent
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
- the class that the hook should run for, notnull
hook
- the hook, notnull
- Throws:
IllegalArgumentException
- if a class is not a subclass ofEvent
, is abstract, or the hook is already addedIllegalStateException
- if the event class has theRegistered(false)
annotation and is not registered manuallySecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("registerEvent")
-
removePeriodicEvent
Removes a hook for a periodic event.- Parameters:
hook
- the hook to remove, notnull
- Returns:
true
if hook is removed,false
otherwise- Throws:
SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("registerEvent")
-
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
Adds a recorder listener and captures theAccessControlContext
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
- the listener to add, notnull
- Throws:
SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("accessFlightRecorder")
-
removeListener
Removes a recorder listener.If the same listener is added multiple times, only one instance is removed.
- Parameters:
changeListener
- listener to remove, notnull
- Returns:
true
, if the listener could be removed,false
otherwise- Throws:
SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("accessFlightRecorder")
-
isAvailable
public static boolean isAvailable()Returnstrue
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:
-
isInitialized
public static boolean isInitialized()Returnstrue
if Flight Recorder is initialized.- Returns:
true
, if Flight Recorder is initialized,false
otherwise- See Also:
-