public final class FlightRecorder
extends java.lang.Object
This class provides the methods necessary for creating, starting, stopping, and destroying recordings.
| Modifier and Type | Method and Description |
|---|---|
static void |
addListener(FlightRecorderListener changeListener)
Adds a recorder listener and captures the
AccessControlContext to
use when invoking the listener. |
static void |
addPeriodicEvent(java.lang.Class<? extends Event> eventClass,
java.lang.Runnable hook)
Adds a hook for a periodic event.
|
java.util.List<EventType> |
getEventTypes()
Returns an immutable list that contains all currently registered events.
|
static FlightRecorder |
getFlightRecorder()
Returns the Flight Recorder for the platform.
|
java.util.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(java.lang.Class<? extends Event> eventClass)
Registers an event class.
|
static boolean |
removeListener(FlightRecorderListener changeListener)
Removes a recorder listener.
|
static boolean |
removePeriodicEvent(java.lang.Runnable hook)
Removes a hook for a periodic event.
|
Recording |
takeSnapshot()
Creates a snapshot of all available recorded data.
|
static void |
unregister(java.lang.Class<? extends Event> eventClass)
Unregisters an event class.
|
public java.util.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().
nullpublic Recording takeSnapshot()
A snapshot is a synthesized recording in a STOPPPED 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.nullpublic static void register(java.lang.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 nulljava.lang.IllegalArgumentException - if class is abstract or not a subclass
of Eventjava.lang.SecurityException - if a security manager exists and the caller
does not have FlightRecorderPermission("registerEvent")public static void unregister(java.lang.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 nulljava.lang.IllegalArgumentException - if a class is abstract or not a subclass
of Eventjava.lang.SecurityException - if a security manager exists and the caller
does not have FlightRecorderPermission("registerEvent")public static FlightRecorder getFlightRecorder() throws java.lang.IllegalStateException, java.lang.SecurityException
nulljava.lang.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)java.lang.SecurityException - if a security manager exists and the caller does
not have FlightRecorderPermission("accessFlightRecorder")public static void addPeriodicEvent(java.lang.Class<? extends Event> eventClass, java.lang.Runnable hook) throws java.lang.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 nullhook - the hook, not nulljava.lang.IllegalArgumentException - if a class is not a subclass of
Event, is abstract, or the hook is already addedjava.lang.IllegalStateException - if the event class has the
Registered(false) annotation and is not registered manuallyjava.lang.SecurityException - if a security manager exists and the caller
does not have FlightRecorderPermission("registerEvent")public static boolean removePeriodicEvent(java.lang.Runnable hook)
throws java.lang.SecurityException
hook - the hook to remove, not nulltrue if hook is removed, false otherwisejava.lang.SecurityException - if a security manager exists and the caller
does not have FlightRecorderPermission("registerEvent")public java.util.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.
nullpublic 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 nulljava.lang.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 nulltrue, if the listener could be removed, false
otherwisejava.lang.SecurityException - 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
otherwisefor callback when Flight Recorder is
initializedpublic static boolean isInitialized()
true if Flight Recorder is initialized.true, if Flight Recorder is initialized,
false otherwisefor callback when Flight Recorder is
initialized