+ * 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. There are + *
+ * See the package {@code jdk.jfr} documentation for descriptions of the settings + * syntax and the {@link ConfigurationInfo} for configuration related 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 VM is running. If destination is a relative path, it + * is relative to the working directory where the target VM 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 identifier that can be used for reading recording data. + * + * @see RecordingT + */ + 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 identifier 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 identifier 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 this map.
+ *
+ * The name in the map is the event name and the setting name separated by
+ * {@code "#"} (for example, {@code "com.oracle.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 "com.oracle.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)s
+ *
+ * @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