- All Implemented Interfaces:
Closeable
,AutoCloseable
The following example shows how configure, start, stop and dump recording data to disk.
Configuration c = Configuration.getConfiguration("default");
try (Recording r = new Recording(c)) {
r.start();
System.gc();
Thread.sleep(5000);
r.stop();
r.dump(Files.createTempFile("my-recording", ".jfr"));
}
- Since:
- 9
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Releases all data that is associated with this recording.copy
(boolean stop) Returns a clone of this recording, with a new recording ID and name.Disables event.Disables event with the specified name.void
Writes recording data to a file.Enables event.Enables the event with the specified name.Returns the destination file, where recording data is written when the recording stops, ornull
if no destination is set.boolean
Returns whether this recording is dumped to disk when the JVM exits.Returns the specified duration for this recording, ornull
if no duration is set.long
getId()
Returns a unique ID for this recording.Returns the length of time that the data is kept in the disk repository before it is removed.long
Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.getName()
Returns the name of this recording.Returns settings used by this recording.long
getSize()
Returns the current size of this recording in the disk repository, measured in bytes.Returns the time when this recording was started.getState()
Returns the recording state that this recording is currently in.Returns the time when this recording was stopped.Creates a data stream for a specified interval.boolean
isToDisk()
Returnstrue
if this recording uses the disk repository,false
otherwise.void
scheduleStart
(Duration delay) Starts this recording after a delay.void
setDestination
(Path destination) Sets a location where data is written on recording stop, ornull
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
(Duration duration) Sets a duration for how long a recording runs before it stops.void
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
Sets a human-readable name (for example,"My Recording"
).void
setSettings
(Map<String, 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.
-
Constructor Details
-
Recording
Creates a recording with settings from a map of name-value pairs.A newly created recording is in the
RecordingState.NEW
state. To start the recording, invoke thestart()
method.- Parameters:
settings
- settings as a map of name-value pairs, notnull
- 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 is used and FlightRecorderPermission "accessFlightRecorder" is not set.- See Also:
-
Recording
public Recording()Creates a recording without any settings.A newly created recording is in the
RecordingState.NEW
state. To start the recording, invoke thestart()
method.- 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 is used and FlightRecorderPermission "accessFlightRecorder" is not set.
-
Recording
Creates a recording with settings from a configuration.The following example shows how create a recording that uses a predefined configuration.
Recording r = new Recording(Configuration.getConfiguration("default"));
RecordingState.NEW
state. To start the recording, invoke thestart()
method.- Parameters:
configuration
- configuration that contains the settings to be use, notnull
- 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 is used and FlightRecorderPermission "accessFlightRecorder" is not set.- See Also:
-
-
Method Details
-
start
public void start()Starts this recording.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.- Throws:
IllegalStateException
- if recording is already started or is in theCLOSED
state
-
scheduleStart
Starts this recording after a delay.After a successful invocation of this method, this recording is in the
DELAYED
state.- Parameters:
delay
- the time to wait before starting this recording, notnull
- Throws:
IllegalStateException
- if the recording is not it theNEW
state
-
stop
public boolean stop()Stops this recording.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.- Returns:
true
if recording is stopped,false
otherwise- Throws:
IllegalStateException
- if the recording is not started or is already stoppedSecurityException
- if a security manager exists and the caller doesn't haveFilePermission
to write to the destination path- See Also:
-
getSettings
-
getSize
public long getSize()Returns the current size of this recording in the disk repository, measured in bytes.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
.- Returns:
- amount of recorded data, measured in bytes, or
0
if the recording is not written to the disk repository
-
getStopTime
Returns the time when this recording was stopped.- Returns:
- the time, or
null
if this recording is not stopped
-
getStartTime
Returns the time when this recording was started.- Returns:
- the time, or
null
if this recording is not started
-
getMaxSize
public long getMaxSize()Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.- Returns:
- maximum size in bytes, or
0
if no maximum size is set
-
getMaxAge
Returns the length of time that the data is kept in the disk repository before it is removed.- Returns:
- maximum length of time, or
null
if no maximum length of time has been set
-
getName
Returns the name of this recording.By default, the name is the same as the recording ID.
- Returns:
- the recording name, not
null
-
setSettings
Replaces all settings for this recording.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);
Map<String, String> settings = recording.getSettings(); settings.putAll(additionalSettings); recording.setSettings(settings);
- Parameters:
settings
- the settings to set, notnull
-
getState
Returns the recording state that this recording is currently in.- Returns:
- the recording state, not
null
- See Also:
-
close
public void close()Releases all data that is associated with this recording.After a successful invocation of this method, this recording is in the
CLOSED
state.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
copy
Returns a clone of this recording, with a new recording ID and name.Clones are useful for dumping data without stopping the recording. After a clone is created, the amount of data to copy is constrained with the
setMaxAge(Duration)
method and thesetMaxSize(long)
method.- Parameters:
stop
-true
if the newly created copy should be stopped immediately,false
otherwise- Returns:
- the recording copy, not
null
-
dump
Writes recording data to a file.For a dump to succeed, the recording must either be 1) running, or 2) stopped and to disk. If the recording is in any other state, an
IOException
is thrown.- Parameters:
destination
- the location where recording data is written, notnull
- Throws:
IOException
- if recording data can't be copied to the specified location, for example, if the recording is closed or the destination path is not writableSecurityException
- if a security manager exists and the caller doesn't haveFilePermission
to write to the destination path- See Also:
-
isToDisk
public boolean isToDisk()Returnstrue
if this recording uses the disk repository,false
otherwise.If no value is set,
true
is returned.- Returns:
true
if the recording uses the disk repository,false
otherwise
-
setMaxSize
public void setMaxSize(long maxSize) Determines how much data is kept in the disk repository.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.
- Parameters:
maxSize
- the amount of data to retain,0
if infinite- Throws:
IllegalArgumentException
- ifmaxSize
is negativeIllegalStateException
- if the recording is inCLOSED
state
-
setMaxAge
Determines how far back data is kept in the disk repository.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.
- Parameters:
maxAge
- the length of time that data is kept, ornull
if infinite- Throws:
IllegalArgumentException
- ifmaxAge
is negativeIllegalStateException
- if the recording is in theCLOSED
state
-
setDestination
Sets a location where data is written on recording stop, ornull
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.- Parameters:
destination
- the destination path, ornull
if recording should not be dumped at stop- Throws:
IllegalStateException
- if recording is in theSTOPPED
orCLOSED
state.SecurityException
- if a security manager exists and the caller doesn't haveFilePermission
to read, write, and delete thedestination
fileIOException
- if the path is not writable
-
getDestination
Returns the destination file, where recording data is written when the recording stops, ornull
if no destination is set.- Returns:
- the destination file, or
null
if not set.
-
getId
public long getId()Returns a unique ID for this recording.- Returns:
- the recording ID
-
setName
Sets a human-readable name (for example,"My Recording"
).- Parameters:
name
- the recording name, notnull
- Throws:
IllegalStateException
- if the recording is inCLOSED
state
-
setDumpOnExit
public void setDumpOnExit(boolean dumpOnExit) Sets whether this recording is dumped to disk when the JVM exits.- Parameters:
dumpOnExit
- if this recording should be dumped when the JVM exits
-
getDumpOnExit
public boolean getDumpOnExit()Returns whether this recording is dumped to disk when the JVM exits.If dump on exit is not set,
false
is returned.- Returns:
true
if the recording is dumped on exit,false
otherwise.
-
setToDisk
public 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.- Parameters:
disk
-true
if this recording is written to disk,false
if in-memory
-
getStream
Creates a data stream for a specified interval.The stream may contain some data outside the specified range.
If the recording is not to disk, a stream can't be created and
null
is returned.- Parameters:
start
- the start time for the stream, ornull
to get data from start time of the recordingend
- the end time for the stream, ornull
to get data until the present time.- Returns:
- an input stream, or
null
if no data is available in the interval, or the recording was not recorded to disk - Throws:
IllegalArgumentException
- ifend
happens beforestart
IOException
- if a stream can't be opened- See Also:
-
getDuration
Returns the specified duration for this recording, ornull
if no duration is set.The duration can be set only when the recording is in the
RecordingState.NEW
state.- Returns:
- the desired duration of the recording, or
null
if no duration has been set.
-
setDuration
Sets a duration for how long a recording runs before it stops.By default, a recording has no duration (
null
).- Parameters:
duration
- the duration, ornull
if no duration is set- Throws:
IllegalStateException
- if recording is in theSTOPPED
orCLOSED
state
-
enable
Enables the event with the specified 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 aString
representation of the event type ID.- Parameters:
name
- the settings for the event, notnull
- Returns:
- an event setting for further configuration, not
null
- See Also:
-
disable
Disables event with the specified 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 aString
representation of the event type ID.- Parameters:
name
- the settings for the event, notnull
- Returns:
- an event setting for further configuration, not
null
-
enable
Enables event.- Parameters:
eventClass
- the event to enable, notnull
- Returns:
- an event setting for further configuration, not
null
- Throws:
IllegalArgumentException
- ifeventClass
is an abstract class or not a subclass ofEvent
-
disable
Disables event.- Parameters:
eventClass
- the event to enable, notnull
- Returns:
- an event setting for further configuration, not
null
- Throws:
IllegalArgumentException
- ifeventClass
is an abstract class or not a subclass ofEvent
-