* The object name for identifying the MXBean in the platform MBean * server is:
{@code jdk.management.jfr:type=FlightRecorder}*
* Flight Recorder can be configured in the following ways: *
* See the package {@code jdk.jfr} documentation for descriptions of the settings * syntax and the {@link ConfigurationInfo} class documentation for configuration information. * *
* The following table shows the options names to use with {@link #setRecordingOptions(long, Map)} * and {@link #getRecordingOptions(long)}. * *
| Name | *Descripion | *Default value | *Format | *Example values | *
|---|---|---|---|---|
| {@code name} | *Sets a human-readable recording name | *String representation of the recording id | *{@code String} | *{@code "My Recording"}, * {@code "profiling"} |
*
| {@code maxAge} | *Specify the length of time that the data is kept in the disk repository until the * oldest data may be deleted. Only works if {@code disk=true}, otherwise * this parameter is ignored. | *{@code "0"} (no limit) | *{@code "0"} if no limit is imposed, otherwise a string
* representation of a positive {@code Long} value followed by an empty space
* and one of the following units, * * {@code "ns"} (nanoseconds) * {@code "us"} (microseconds) * {@code "ms"} (milliseconds) * {@code "s"} (seconds) * {@code "m"} (minutes) * {@code "h"} (hours) * {@code "d"} (days) * |
* {@code "2 h"}, * {@code "24 h"}, * {@code "2 d"}, * {@code "0"} |
*
| {@code maxSize} | *Specifies the size, measured in bytes, at which data is kept in disk * repository. Only works if * {@code disk=true}, otherwise this parameter is ignored. | *{@code "0"} (no limit) | *String representation of a {@code Long} value, must be positive | *{@code "0"}, * {@code "1000000000"} |
*
| {@code dumpOnExit} | *Dumps recording data to disk on Java Virtual Machine (JVM) exit | *{@code "false"} | *String representation of a {@code Boolean} value, {@code "true"} or * {@code "false"} | *{@code "true"}, * {@code "false"} |
*
| {@code destination} | *Specifies the path where recording data is written when the recording stops. | *{@code "false"} | *See {@code Paths#getPath} for format. * If this method is invoked from another process, the data is written on the * machine where the target JVM is running. If destination is a relative path, it * is relative to the working directory where the target JVM was started.} |
* {@code "c:\recording\recotding.jfr"}, * {@code "/recordings/recording.jfr"}, {@code "recording.jfr"} |
*
| {@code disk} | *Stores recorded data as it is recorded | *"false" |
* String representation of a {@code Boolean} value, {@code "true"} or * {@code "false"} | *{@code "true"}, * {@code "false"} |
*
| {@code duration} | *Sets how long the recording should be running | *{@code "0"} (no limit, continuous) | *{@code "0"} if no limit should be imposed, otherwise a string
* representation of a positive {@code Long} followed by an empty space and one
* of the following units: * * {@code "ns"} (nanoseconds) * {@code "us"} (microseconds) * {@code "ms"} (milliseconds) * {@code "s"} (seconds) * {@code "m"} (minutes) * {@code "h"} (hours) * {@code "d"} (days) * |
* {@code "60 s"}, * {@code "10 m"}, * {@code "4 h"}, * {@code "0"} |
*
* A snapshot is a synthesized recording in a stopped state. If no data is * available, a recording with size {@code 0} is returned. *
* A snapshot provides stable access to data for later operations (for example, * operations to change the time interval or to reduce the data size). *
* The caller must close the recording when access to the data is no longer * needed. * * @return a snapshot of all available recording data, not {@code null} * * @throws java.lang.SecurityException if a security manager exists and the * caller does not have {@code ManagementPermission("control")} * * @return a unique ID that can be used for reading recording data. * * @see Recording */ public long takeSnapshot(); /** * Creates a copy of an existing recording, useful for extracting parts of a * recording. *
* The cloned recording contains the same recording data as the * original, but it has a new ID and a name prefixed with * {@code "Clone of recording"}. If the original recording is running, then * the clone is also running. * * @param recordingId the recording ID of the recording to create a clone * from * * @param stop if the newly created clone is stopped before * returning. * * @return a unique ID that can be used to start, stop, * close and configure the recording * * @throws IllegalArgumentException if a recording with the specified ID * doesn't exist * * @throws java.lang.SecurityException if a security manager exists and the * caller does not have {@code ManagementPermission("control")} * * @see Recording */ long cloneRecording(long recordingId, boolean stop) throws IllegalArgumentException, SecurityException; /** * Starts the recording with the specified ID. *
* A recording that is stopped can't be restarted. * * @param recordingId ID of the recording to start * * @throws IllegalArgumentException if a recording with the specified ID * doesn't exist * * @throws java.lang.SecurityException if a security manager exists and the * caller does not have {@code ManagementPermission("control")} * * @see Recording */ void startRecording(long recordingId) throws IllegalStateException, SecurityException; /** * Stops the running recording with the specified ID. * * @param recordingId the ID of the recording to stop * * @return {@code true} if the recording is stopped, {@code false} * otherwise * * @throws IllegalArgumentException if a recording with the specified ID * doesn't exist * @throws IllegalStateException if the recording is not running * @throws java.lang.SecurityException if a security manager exists and the * caller does not have {@code ManagementPermission("control")} * * @see #newRecording() */ boolean stopRecording(long recordingId) throws IllegalArgumentException, IllegalStateException, SecurityException; /** * Closes the recording with the specified ID and releases any system * resources that are associated with the recording. *
* If the recording is already closed, invoking this method has no effect. * * @param recordingId the ID of the recording to close * * @throws IllegalArgumentException if a recording with the specified ID * doesn't exist * @throws IOException if an I/O error occurs * @throws java.lang.SecurityException if a security manager exists and the * caller does not have {@code ManagementPermission("control")} * * @see #newRecording() */ void closeRecording(long recordingId) throws IOException; /** * Opens a data stream for the recording with the specified ID, or {@code 0} * to get data irrespective of recording. *
| Name | *Descripion | *Default value | *Format | *Example values | *
|---|---|---|---|---|
| {@code startTime} | *Specifies the point in time to start a recording stream. Due to * how data is stored, some events that start or end prior to the * start time may be included. | *{@code Instant.MIN_VALUE.toString()} | *ISO-8601. See {@link Instant#toString} * or milliseconds since epoch |
* {@code "2015-11-03T00:00"}, * {@code "1446508800000"} |
*
| {@code endTime} | *Specifies the point in time to end a recording stream. Due to how * data is stored, some events that start or end after the end time may * be included. | *{@code Instant.MAX_VALUE.toString()} | *ISO-8601. See {@link Instant#toString} * or milliseconds since epoch |
* {@code "2015-11-03T01:00"}, * {@code "1446512400000"} |
*
| {@code blockSize} | *Specifies the maximum number of bytes to read with a call to {@code readStream} * | *{@code "50000"} | *A positive {@code long} value. * * Setting {@code blockSize} to a very high value may result in * {@link OutOfMemoryError} or an {@link IllegalArgumentException}, if the * Java Virtual Machine (JVM) deems the value too large to handle. |
* {@code "50000"}, * {@code "1000000"}, * |
* The recording with the specified ID must be stopped before a stream can
* be opened. This restriction might be lifted in future releases.
*
* @param recordingId ID of the recording to open the stream for
*
* @param streamOptions a map that contains the options that controls the amount of data
* and how it is read, or {@code null} to get all data for the
* recording with the default block size
*
* @return a unique ID for the stream.
*
* @throws IllegalArgumentException if a recording with the iD doesn't
* exist, or if {@code options} contains invalid values
*
* @throws IOException if the recording is closed, an I/O error occurs, or
* no data is available for the specified recording or
* interval
*
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("control")}
*/
long openStream(long recordingId, Map
* If the stream is already closed, invoking this method has no effect.
*
* @param streamId the ID of the stream
*
* @throws IllegalArgumentException if a stream with the specified ID doesn't
* exist
* @throws IOException if an I/O error occurs while trying to close the stream
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("control")}
*
* @see #openStream(long, Map)
*/
void closeStream(long streamId) throws IOException;
/**
* Reads a portion of data from the stream with the specified ID, or returns
* {@code null} if no more data is available.
*
* To read all data for a recording, invoke this method repeatedly until
* {@code null} is returned.
*
* @param streamId the ID of the stream
*
* @return byte array that contains recording data, or {@code null} when no more
* data is available
* @throws IOException if the stream is closed, or an I/O error occurred while
* trying to read the stream
* @throws IllegalArgumentException if no recording with the stream ID exists
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("monitor")}
*/
byte[] readStream(long streamId) throws IOException;
/**
* Returns a map that contains the options for the recording with the
* specified ID (for example, the destination file or time span to keep
* recorded data).
*
* See {@link FlightRecorderMXBean} for available option names.
*
* @param recordingId the ID of the recording to get options for
*
* @return a map describing the recording options, not {@code null}
*
* @throws IllegalArgumentException if no recording with the
* specified ID exists
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("monitor")}
*
*/
Map
* If multiple recordings are running at the same time, more data could be
* recorded than what is specified in the {@code Map} object.
*
* The name in the {@code Map} is the event name and the setting name separated by
* {@code "#"} (for example, {@code "jdk.VMInfo#period"}). The value
* is a textual representation of the settings value (for example,
* {@code "60 s"}).
*
* @param recordingId the ID of the recordings to get settings for
*
* @return a map that describes the recording settings, not {@code null}
*
* @throws IllegalArgumentException if no recording with the specified ID exists
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("monitor")}
*/
Map
* A setting consists of a name/value pair, where name specifies the
* event and setting to configure, and the value specifies what to set
* it to.
*
* The name can be formed in the following ways:
*
* {@code
*
* or
*
* {@code
*
* For example, to set the sample interval of the CPU Load event to once every
* second, use the name {@code "jdk.CPULoad#period"} and the value
* {@code "1 s"}. If multiple events use the same name, for example if an event
* class is loaded in multiple class loaders, and differentiation is needed
* between them, then the name is {@code "56#period"}. The ID for an event is
* obtained by invoking {@link jdk.jfr.EventType#getId()} method and is valid
* for the Java Virtual Machine (JVM) instance that the event is registered in.
*
* A list of available event names is retrieved by invoking
* {@link jdk.jfr.FlightRecorder#getEventTypes()} and
* {@link jdk.jfr.EventType#getName()}. A list of available settings for an
* event type is obtained by invoking
* {@link jdk.jfr.EventType#getSettingDescriptors()} and
* {@link jdk.jfr.ValueDescriptor#getName()}.
*
*
* @param recordingId ID of the recording
*
* @param settings name value map of the settings to set, not {@code null}
*
* @throws IllegalArgumentException if no recording with the specified ID exists
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("control")}
*
* @see Recording#getId()
*/
void setRecordingSettings(long recordingId, Map
* See {@link FlightRecorderMXBean} for a description of the options and values
* that can be used. Setting a value to {@code null} restores the value to the
* default value.
*
* @param recordingId the ID of the recording to set options for
*
* @param options name/value map of the settings to set, not {@code null}
*
* @throws IllegalArgumentException if no recording with the specified ID exists
* @throws java.lang.SecurityException if a security manager exists, and the
* caller does not have {@code ManagementPermission("control")} or an
* option contains a file that the caller does not have permission to
* operate on.
* @see Recording#getId()
*/
void setRecordingOptions(long recordingId, Map
* MBeanServer access:
* MBeanServer access:
* MBeanServer access:
* If this method is invoked remotely from another process, the data is written
* to a file named {@code outputFile} on the machine where the target Java
* Virtual Machine (JVM) is running. If the file location is a relative path, it
* is relative to the working directory where the target JVM was started.
*
* @param recordingId the ID of the recording to dump data for
*
* @param outputFile the system-dependent file name where data is written, not
* {@code null}
*
* @throws IOException if the recording can't be dumped due to an I/O error (for
* example, an invalid path)
*
* @throws IllegalArgumentException if a recording with the specified ID doesn't
* exist
*
* @throws IllegalStateException if the recording is not yet started or if it is
* already closed
*
* @throws SecurityException if a security manager exists and its
* {@code SecurityManager.checkWrite(java.lang.String)} method denies
* write access to the named file or the caller does not have
* {@code ManagmentPermission("control")}
*
* @see java.nio.file.Path#toString()
* @see Recording#dump(java.nio.file.Path)
*/
void copyTo(long recordingId, String outputFile) throws IOException, SecurityException;
}
* The mapped type of {@code RecordingInfo} is {@code CompositeData} with
* attributes as specified in the {@link RecordingInfo#from
* RecordingInfo.from} method.
*
* @return list of recordings, not {@code null}
*
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("monitor")}
*
* @see RecordingInfo
* @see Recording
*/
List
* The mapped type of {@code ConfigurationInfo} is {@code CompositeData}
* with attributes as specified in the {@link ConfigurationInfo#from
* ConfigurationInfo.from} method.
*
* @return the list of predefined configurations, not {@code null}
*
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("monitor")}
*
* @see ConfigurationInfo
* @see Configuration
*/
List
* The mapped type of {@code EventTypeInfo} is {@code CompositeData} with
* attributes as specified in the {@link EventTypeInfo#from
* EventTypeInfo.from} method.
*
* @return the list of registered event types, not {@code null}
*
* @throws java.lang.SecurityException if a security manager exists and the
* caller does not have {@code ManagementPermission("monitor")}
*
* @see EventTypeInfo
* @see EventType
*/
List