public final class FlightRecorder extends Object
This class provides the methods necessary for creating, starting, stopping, and destroying recordings.
Modifier and Type | Method | Description |
---|---|---|
static void |
addListener |
Adds a recorder listener and captures the AccessControlContext to use when invoking the listener. |
static void |
addPeriodicEvent |
Adds a hook for a periodic event. |
List |
getEventTypes() |
Returns an immutable list that contains all currently registered events. |
static FlightRecorder |
getFlightRecorder() |
Returns the Flight Recorder for the platform. |
List |
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 |
Registers an event class. |
static boolean |
removeListener |
Removes a recorder listener. |
static boolean |
removePeriodicEvent |
Removes a hook for a periodic event. |
Recording |
takeSnapshot() |
Creates a snapshot of all available recorded data. |
static void |
unregister |
Unregisters an event class. |
public List<Recording> getRecordings()
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()
.
null
public Recording takeSnapshot()
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"));
}
}
null
public static void register(Class<? extends Event> eventClass)
If the event class is already registered, then the invocation of this method is ignored.
eventClass
- the event class to register, not null
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 unregister(Class<? extends Event> eventClass)
If the event class is not registered, then the invocation of this method is ignored.
eventClass
- the event class to unregistered, not null
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 FlightRecorder getFlightRecorder() throws IllegalStateException, SecurityException
null
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 void addPeriodicEvent(Class<? extends Event> eventClass, Runnable hook) throws SecurityException
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.
eventClass
- the class that the hook should run for, not null
hook
- the hook, not null
IllegalArgumentException
- if a class is not a subclass of Event
, is abstract, or the hook is already addedIllegalStateException
- if the event class has the Registered(false)
annotation and is not registered manuallySecurityException
- if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")
public static boolean removePeriodicEvent(Runnable hook) throws SecurityException
hook
- the hook to remove, not null
true
if hook is removed, false
otherwiseSecurityException
- if a security manager exists and the caller does not have FlightRecorderPermission("registerEvent")
public List<EventType> getEventTypes()
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.
null
public static void addListener(FlightRecorderListener changeListener)
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.
changeListener
- the listener to add, not null
SecurityException
- if a security manager exists and the caller does not have FlightRecorderPermission("accessFlightRecorder")
public static boolean removeListener(FlightRecorderListener changeListener)
If the same listener is added multiple times, only one instance is removed.
changeListener
- listener to remove, not null
true
, if the listener could be removed, false
otherwiseSecurityException
- if a security manager exists and the caller does not have FlightRecorderPermission("accessFlightRecorder")
public static boolean isAvailable()
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.
true
, if Flight Recorder is available, false
otherwisepublic static boolean isInitialized()
true
if Flight Recorder is initialized.true
, if Flight Recorder is initialized, false
otherwise
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.jfr/jdk/jfr/FlightRecorder.html