public final class Recording
extends java.lang.Object
implements java.io.Closeable
The following example shows how configure, start, stop and dump recording data to disk.
Configuration c = Configuration.getConfiguration("default");
Recording r = new Recording(c);
r.start();
System.gc();
Thread.sleep(5000);
r.stop();
r.dump(Files.createTempFile("my-recording", ".jfr"));
| Constructor and Description |
|---|
Recording()
Creates a recording without any settings.
|
Recording(Configuration configuration)
Creates a recording with settings from a configuration.
|
Recording(java.util.Map<java.lang.String,java.lang.String> settings) |
| Modifier and Type | Method and Description |
|---|---|
void |
close()
Releases all data that is associated with this recording.
|
Recording |
copy(boolean stop)
Returns a clone of this recording, with a new recording ID and name.
|
EventSettings |
disable(java.lang.Class<? extends Event> eventClass)
Disables event.
|
EventSettings |
disable(java.lang.String name)
Disables event with the specified name.
|
void |
dump(java.nio.file.Path destination)
Writes recording data to a file.
|
EventSettings |
enable(java.lang.Class<? extends Event> eventClass)
Enables event.
|
EventSettings |
enable(java.lang.String name)
Enables the event with the specified name.
|
java.nio.file.Path |
getDestination()
Returns the destination file, where recording data is written when the
recording stops, or
null if no destination is set. |
boolean |
getDumpOnExit()
Returns whether this recording is dumped to disk when the JVM exits.
|
java.time.Duration |
getDuration()
Returns the specified duration for this recording, or
null if no
duration is set. |
long |
getId()
Returns a unique ID for this recording.
|
java.time.Duration |
getMaxAge()
Returns the length of time that the data is kept in the disk repository
before it is removed.
|
long |
getMaxSize()
Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.
|
java.lang.String |
getName()
Returns the name of this recording.
|
java.util.Map<java.lang.String,java.lang.String> |
getSettings()
Returns settings used by this recording.
|
long |
getSize()
Returns the current size of this recording in the disk repository,
measured in bytes.
|
java.time.Instant |
getStartTime()
Returns the time when this recording was started.
|
RecordingState |
getState()
Returns the recording state that this recording is currently in.
|
java.time.Instant |
getStopTime()
Returns the time when this recording was stopped.
|
java.io.InputStream |
getStream(java.time.Instant start,
java.time.Instant end)
Creates a data stream for a specified interval.
|
boolean |
isToDisk()
Returns
true if this recording uses the disk repository, false otherwise. |
void |
scheduleStart(java.time.Duration delay)
Starts this recording after a delay.
|
void |
setDestination(java.nio.file.Path destination)
Sets a location where data is written on recording stop, or
null if data is not to be dumped. |
void |
setDumpOnExit(boolean dumpOnExit)
Sets whether this recording is dumped to disk when the JVM exits.
|
void |
setDuration(java.time.Duration duration)
Sets a duration for how long a recording runs before it stops.
|
void |
setMaxAge(java.time.Duration maxAge)
Determines how far back data is kept in the disk repository.
|
void |
setMaxSize(long maxSize)
Determines how much data is kept in the disk repository.
|
void |
setName(java.lang.String name)
Sets a human-readable name (for example,
"My Recording"). |
void |
setSettings(java.util.Map<java.lang.String,java.lang.String> settings)
Replaces all settings for this recording.
|
void |
setToDisk(boolean disk)
Determines whether this recording is continuously flushed to the disk
repository or data is constrained to what is available in memory buffers.
|
void |
start()
Starts this recording.
|
boolean |
stop()
Stops this recording.
|
public Recording(java.util.Map<java.lang.String,java.lang.String> settings)
public Recording()
A newly created recording is in the RecordingState.NEW state. To start
the recording, invoke the start() method.
java.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 is used and
FlightRecorderPermission "accessFlightRecorder" is not set.public Recording(Configuration configuration)
The following example shows how create a recording that uses a predefined configuration.
Recording r = new Recording(Configuration.getConfiguration("default"));
The newly created recording is in the RecordingState.NEW state. To
start the recording, invoke the start() method.configuration - configuration that contains the settings to be use, not
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 is used and
FlightRecorderPermission "accessFlightRecorder" is not set.Configurationpublic void start()
It's recommended that the recording options and event settings are configured before calling this method. The benefits of doing so are a more consistent state when analyzing the recorded data, and improved performance because the configuration can be applied atomically.
After a successful invocation of this method, this recording is in the
RUNNING state.
java.lang.IllegalStateException - if recording is already started or is in the
CLOSED statepublic void scheduleStart(java.time.Duration delay)
After a successful invocation of this method, this recording is in the
DELAYED state.
delay - the time to wait before starting this recording, not
nulljava.lang.IllegalStateException - if the recording is not it the NEW statepublic boolean stop()
When a recording is stopped it can't be restarted. If this recording has a destination, data is written to that destination and the recording is closed. After a recording is closed, the data is no longer available.
After a successful invocation of this method, this recording will be
in the STOPPED state.
true if recording is stopped, false otherwisejava.lang.IllegalStateException - if the recording is not started or is already stoppedjava.lang.SecurityException - if a security manager exists and the caller
doesn't have FilePermission to write to the destination
pathsetDestination(Path)public java.util.Map<java.lang.String,java.lang.String> getSettings()
Modifying the returned Map will not change the settings for this recording.
If no settings are set for this recording, an empty Map is
returned.
nullpublic long getSize()
The size is updated when recording buffers are flushed. If the recording is
not written to the disk repository the returned size is always 0.
0 if the
recording is not written to the disk repositorypublic java.time.Instant getStopTime()
null if this recording is not stoppedpublic java.time.Instant getStartTime()
null if this recording is not startedpublic long getMaxSize()
0 if no maximum size is setpublic java.time.Duration getMaxAge()
null if no maximum length of time
has been setpublic java.lang.String getName()
By default, the name is the same as the recording ID.
nullpublic void setSettings(java.util.Map<java.lang.String,java.lang.String> settings)
The following example shows how to set event settings for a recording.
Map <String, String > settings = new HashMap < >();
settings.putAll(EventSettings.enabled("jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap());
settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap());
settings.put("jdk.ExecutionSample#period", "10 ms");
recording.setSettings(settings);
The following example shows how to merge settings.
Map<String, String> settings = recording.getSettings();
settings.putAll(additionalSettings);
recording.setSettings(settings);
settings - the settings to set, not nullpublic RecordingState getState()
nullRecordingStatepublic void close()
After a successful invocation of this method, this recording is in the
CLOSED state.
close in interface java.io.Closeableclose in interface java.lang.AutoCloseablepublic Recording copy(boolean stop)
setMaxAge(Duration) method and the setMaxSize(long)method.stop - true if the newly created copy should be stopped
immediately, false otherwisenullpublic void dump(java.nio.file.Path destination)
throws java.io.IOException
Recording must be started, but not necessarily stopped.
destination - the location where recording data is written, not
nulljava.io.IOException - if the recording can't be copied to the specified
locationjava.lang.SecurityException - if a security manager exists and the caller doesn't
have FilePermission to write to the destination pathpublic boolean isToDisk()
true if this recording uses the disk repository, false otherwise.
If no value is set, true is returned.
true if the recording uses the disk repository, false
otherwisepublic void setMaxSize(long maxSize)
To control the amount of recording data that is stored on disk, the maximum amount of data to retain can be specified. When the maximum limit is exceeded, the Java Virtual Machine (JVM) removes the oldest chunk to make room for a more recent chunk.
If neither maximum limit or the maximum age is set, the size of the recording may grow indefinitely.
maxSize - the amount of data to retain, 0 if infinitejava.lang.IllegalArgumentException - if maxSize is negativejava.lang.IllegalStateException - if the recording is in CLOSED statepublic void setMaxAge(java.time.Duration maxAge)
To control the amount of recording data stored on disk, the maximum length of time to retain the data can be specified. Data stored on disk that is older than the specified length of time is removed by the Java Virtual Machine (JVM).
If neither maximum limit or the maximum age is set, the size of the recording may grow indefinitely.
maxAge - the length of time that data is kept, or null if infinitejava.lang.IllegalArgumentException - if maxAge is negativejava.lang.IllegalStateException - if the recording is in the CLOSED statepublic void setDestination(java.nio.file.Path destination)
throws java.io.IOException
null if data is not to be dumped.
If a destination is set, this recording is automatically closed after data is successfully copied to the destination path.
If a destination is not set, Flight Recorder retains the
recording data until this recording is closed. Use the dump(Path) method to
manually write data to a file.
destination - the destination path, or null if recording should
not be dumped at stopjava.lang.IllegalStateException - if recording is in the STOPPED or
CLOSED state.java.lang.SecurityException - if a security manager exists and the caller
doesn't have FilePermission to read, write, and delete the
destination filejava.io.IOException - if the path is not writablepublic java.nio.file.Path getDestination()
null if no destination is set.null if not set.public long getId()
public void setName(java.lang.String name)
"My Recording").name - the recording name, not nulljava.lang.IllegalStateException - if the recording is in CLOSED statepublic void setDumpOnExit(boolean dumpOnExit)
dumpOnExit - if this recording should be dumped when the JVM exitspublic boolean getDumpOnExit()
If dump on exit is not set, false is returned.
true if the recording is dumped on exit, false
otherwise.public void setToDisk(boolean disk)
disk - true if this recording is written to disk,
false if in-memorypublic java.io.InputStream getStream(java.time.Instant start,
java.time.Instant end)
throws java.io.IOException
The stream may contain some data outside the specified range.
start - the start time for the stream, or null to get data from
start time of the recordingend - the end time for the stream, or null to get data until the
present time.null if no data is available in the
interval.java.lang.IllegalArgumentException - if end happens before
startjava.io.IOException - if a stream can't be openedpublic java.time.Duration getDuration()
null if no
duration is set.
The duration can be set only when the recording is in the
RecordingState.NEW state.
null if no duration
has been set.public void setDuration(java.time.Duration duration)
By default, a recording has no duration (null).
duration - the duration, or null if no duration is setjava.lang.IllegalStateException - if recording is in the STOPPED or CLOSED statepublic EventSettings enable(java.lang.String name)
If multiple events have the same name (for example, the same class is loaded
in different class loaders), then all events that match the name are enabled. To
enable a specific class, use the enable(Class) method or a String
representation of the event type ID.
name - the settings for the event, not nullnullEventTypepublic EventSettings disable(java.lang.String name)
If multiple events with same name (for example, the same class is loaded
in different class loaders), then all events that match the
name is disabled. To disable a specific class, use the
disable(Class) method or a String representation of the event
type ID.
name - the settings for the event, not nullnullpublic EventSettings enable(java.lang.Class<? extends Event> eventClass)
eventClass - the event to enable, not nullnulljava.lang.IllegalArgumentException - if eventClass is an abstract
class or not a subclass of Eventpublic EventSettings disable(java.lang.Class<? extends Event> eventClass)
eventClass - the event to enable, not nullnulljava.lang.IllegalArgumentException - if eventClass is an abstract
class or not a subclass of Event