java/8 : jdk/management/jfr/FlightRecorderMXBean.java

FlightRecorderMXBean

https://openjdk.java.net/

GPLv2 + Classpath Exception

/*
 * Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package jdk.management.jfr;

import java.io.IOException;
import java.lang.management.PlatformManagedObject;
import java.time.Instant;
import java.util.List;
import java.util.Map;

import jdk.jfr.Configuration;
import jdk.jfr.EventType;
import jdk.jfr.Recording;

Management interface for controlling Flight Recorder.

The object name for identifying the MXBean in the platform MBean
server is: 
 jdk.management.jfr:type=FlightRecorder 

Flight Recorder can be configured in the following ways:

Recording options

Specify how long a recording should last, and where and when data
should be dumped.
Settings

Specify which events should be enabled and what kind information each
event should capture.
Configurations

Predefined sets of settings, typically derived from a settings file,
that specify the configuration of multiple events simultaneously.

 See the package jdk.jfr documentation for descriptions of the settings syntax and the ConfigurationInfo class documentation for configuration information. 
Recording options
 The following table shows the options names to use with setRecordingOptions(long, Map<String,String>) and getRecordingOptions(long). 

Recording options


Name
Descripion
Default value
Format
Example values




name
Sets a human-readable recording name
String representation of the recording id
String
"My Recording", 
 "profiling"


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 disk=true, otherwise this parameter is ignored.
"0" (no limit)
"0" if no limit is imposed, otherwise a string representation of a positive Long value followed by an empty space and one of the following units,


 "ns" (nanoseconds)
 "us" (microseconds)
 "ms" (milliseconds)
 "s" (seconds)
 "m" (minutes)
 "h" (hours)
 "d" (days)


"2 h",
 "24 h",
 "2 d",
 "0"


maxSize
Specifies the size, measured in bytes, at which data is kept in disk repository. Only works if disk=true, otherwise this parameter is ignored.
"0" (no limit)
String representation of a Long value, must be positive
"0", 
 "1000000000"


dumpOnExit
Dumps recording data to disk on Java Virtual Machine (JVM) exit
"false"
String representation of a Boolean value, "true" or "false"
"true",
 "false"


destination
Specifies the path where recording data is written when the recording stops.
"false"
See 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.}
"c:\recording\recotding.jfr",
 "/recordings/recording.jfr", "recording.jfr"


disk
Stores recorded data as it is recorded
"false"
String representation of a Boolean value, "true" or "false"
"true",
 "false"

duration
Sets how long the recording should be running
"0" (no limit, continuous)
"0" if no limit should be imposed, otherwise a string representation of a positive Long followed by an empty space and one of the following units:


 "ns" (nanoseconds)
 "us" (microseconds)
 "ms" (milliseconds)
 "s" (seconds)
 "m" (minutes)
 "h" (hours)
 "d" (days)


"60 s",
 "10 m",
 "4 h",
 "0"



Since: 8/**
 * Management interface for controlling Flight Recorder.
 * <p>
 * The object name for identifying the MXBean in the platform MBean
 * server is: <blockquote> {@code jdk.management.jfr:type=FlightRecorder} </blockquote>
 * <p>
 * Flight Recorder can be configured in the following ways:
 * <ul>
 * <li><b>Recording options</b><br>
 * Specify how long a recording should last, and where and when data
 * should be dumped.</li>
 * <li><b>Settings</b><br>
 * Specify which events should be enabled and what kind information each
 * event should capture.</li>
 * <li><b>Configurations</b><br>
 * Predefined sets of settings, typically derived from a settings file,
 * that specify the configuration of multiple events simultaneously.</li>
 * </ul>
 * <p>
 * See the package {@code jdk.jfr} documentation for descriptions of the settings
 * syntax and the {@link ConfigurationInfo} class documentation for configuration information.
 *
 * <h3>Recording options</h3>
 * <p>
 * The following table shows the options names to use with {@link #setRecordingOptions(long, Map)}
 * and {@link #getRecordingOptions(long)}.
 *
 * <table class="striped">
 * <caption>Recording options</caption>
 * <thead>
 * <tr>
 * <th scope="col">Name</th>
 * <th scope="col">Descripion</th>
 * <th scope="col">Default value</th>
 * <th scope="col">Format</th>
 * <th scope="col">Example values</th>
 * </tr>
 * </thead>
 * <tbody>
 * <tr>
 * <th scope="row">{@code name}</th>
 * <td>Sets a human-readable recording name</td>
 * <td>String representation of the recording id</td>
 * <td>{@code String}</td>
 * <td>{@code "My Recording"}, <br>
 * {@code "profiling"}</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code maxAge}</th>
 * <td>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.</td>
 * <td>{@code "0"} (no limit)</td>
 * <td>{@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,<br>
 * <br>
 * {@code "ns"} (nanoseconds)<br>
 * {@code "us"} (microseconds)<br>
 * {@code "ms"} (milliseconds)<br>
 * {@code "s"} (seconds)<br>
 * {@code "m"} (minutes)<br>
 * {@code "h"} (hours)<br>
 * {@code "d"} (days)<br>
 * </td>
 * <td>{@code "2 h"},<br>
 * {@code "24 h"},<br>
 * {@code "2 d"},<br>
 * {@code "0"}</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code maxSize}</th>
 * <td>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.</td>
 * <td>{@code "0"} (no limit)</td>
 * <td>String representation of a {@code Long} value, must be positive</td>
 * <td>{@code "0"}, <br>
 * {@code "1000000000"}</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code dumpOnExit}</th>
 * <td>Dumps recording data to disk on Java Virtual Machine (JVM) exit</td>
 * <td>{@code "false"}</td>
 * <td>String representation of a {@code Boolean} value, {@code "true"} or
 * {@code "false"}</td>
 * <td>{@code "true"},<br>
 * {@code "false"}</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code destination}</th>
 * <td>Specifies the path where recording data is written when the recording stops.</td>
 * <td>{@code "false"}</td>
 * <td>See {@code Paths#getPath} for format. <br>
 * 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.}</td>
 * <td>{@code "c:\recording\recotding.jfr"},<br>
 * {@code "/recordings/recording.jfr"}, {@code "recording.jfr"}</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code disk}</th>
 * <td>Stores recorded data as it is recorded</td>
 * <td><code>"false"</code></td>
 * <td>String representation of a {@code Boolean} value, {@code "true"} or
 * {@code "false"}</td>
 * <td>{@code "true"},<br>
 * {@code "false"}</td>
 * <tr>
 * <th scope="row">{@code duration}</th>
 * <td>Sets how long the recording should be running</td>
 * <td>{@code "0"} (no limit, continuous)</td>
 * <td>{@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:<br>
 * <br>
 * {@code "ns"} (nanoseconds)<br>
 * {@code "us"} (microseconds)<br>
 * {@code "ms"} (milliseconds)<br>
 * {@code "s"} (seconds)<br>
 * {@code "m"} (minutes)<br>
 * {@code "h"} (hours)<br>
 * {@code "d"} (days)<br>
 * </td>
 * <td>{@code "60 s"},<br>
 * {@code "10 m"},<br>
 * {@code "4 h"},<br>
 * {@code "0"}</td>
 * </tr>
 * </tbody>
 * </table>
 *
 * @since 8
 */
public interface FlightRecorderMXBean extends PlatformManagedObject {
    String representation of the ObjectName for the FlightRecorderMXBean. /**
     * String representation of the {@code ObjectName} for the
     * {@code FlightRecorderMXBean}.
     */
    public static final String MXBEAN_NAME = "jdk.management.jfr:type=FlightRecorder";

    Creates a recording, but doesn't start it.
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 exists and the caller does not have ManagementPermission("control")
See Also: Recording
Returns: a unique ID that can be used to start, stop, close and
        configure the recording/**
     * Creates a recording, but doesn't start it.
     *
     * @return a unique ID that can be used to start, stop, close and
     *         configure the recording
     *
     * @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)
     *
     * @throws java.lang.SecurityException if a security manager exists and the
     *         caller does not have {@code ManagementPermission("control")}
     *
     * @see Recording
     */
    long newRecording() throws IllegalStateException, SecurityException;

    Creates a snapshot recording of all available recorded data.
 A snapshot is a synthesized recording in a stopped 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 time interval or to reduce the data size).

The caller must close the recording when access to the data is no longer
needed.
Throws: SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: Recording
Returns: a snapshot of all available recording data, not null
Returns: a unique ID that can be used for reading recording data./**
     * Creates a snapshot recording of all available recorded data.
     * <p>
     * A snapshot is a synthesized recording in a stopped state. If no data is
     * available, a recording with size {@code 0} is returned.
     * <p>
     * A snapshot provides stable access to data for later operations (for example,
     * operations to change the time interval or to reduce the data size).
     * <p>
     * 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 "Clone of recording". If the original recording is running, then the clone is also running. 
Params: recordingId – the recording ID of the recording to create a clone
       from
stop – if the newly created clone is stopped before
       returning.
Throws: IllegalArgumentException – if a recording with the specified ID
        doesn't exist
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: Recording
Returns: a unique ID that can be used to start, stop,
        close and configure the recording/**
     * Creates a copy of an existing recording, useful for extracting parts of a
     * recording.
     * <p>
     * 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.
Params: recordingId – ID of the recording to start
Throws: IllegalArgumentException – if a recording with the specified ID
        doesn't exist
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: Recording/**
     * Starts the recording with the specified ID.
     * <p>
     * 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.
Params: recordingId – the ID of the recording to stop
Throws: IllegalArgumentException – if a recording with the specified ID
        doesn't exist
IllegalStateException – if the recording is not running
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: newRecording()
Returns: true if the recording is stopped, false otherwise/**
     * 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.
Params: recordingId – the ID of the recording to close
Throws: IllegalArgumentException – if a recording with the specified ID
        doesn't exist
IOException – if an I/O error occurs
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: newRecording()/**
     * Closes the recording with the specified ID and releases any system
     * resources that are associated with the recording.
     * <p>
     * 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 0 to get data irrespective of recording. 
Recording stream options


Name
Descripion
Default value
Format
Example values




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.
Instant.MIN_VALUE.toString()
ISO-8601. See Instant.toString

or milliseconds since epoch
"2015-11-03T00:00",
 "1446508800000"


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.
Instant.MAX_VALUE.toString()
ISO-8601. See Instant.toString 

or milliseconds since epoch
"2015-11-03T01:00", 
 "1446512400000"


blockSize
Specifies the maximum number of bytes to read with a call to readStream 
"50000"
A positive long value. 


 Setting blockSize to a very high value may result in OutOfMemoryError or an IllegalArgumentException, if the Java Virtual Machine (JVM) deems the value too large to handle.
"50000",
 "1000000",




If an option is omitted from the map the default value is used.

The recording with the specified ID must be stopped before a stream can
be opened. This restriction might be lifted in future releases.
Params: recordingId – ID of the recording to open the stream for
streamOptions – a map that contains the options that controls the amount of data and how it is read, or null to get all data for the recording with the default block size
Throws: IllegalArgumentException – if a recording with the iD doesn't exist, or if options contains invalid values
IOException – if the recording is closed, an I/O error occurs, or
        no data is available for the specified recording or
        interval
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
Returns: a unique ID for the stream./**
     * Opens a data stream for the recording with the specified ID, or {@code 0}
     * to get data irrespective of recording.
     * <table class="striped">
     * <caption>Recording stream options</caption>
     * <thead>
     * <tr>
     * <th scope="col">Name</th>
     * <th scope="col">Descripion</th>
     * <th scope="col">Default value</th>
     * <th scope="col">Format</th>
     * <th scope="col">Example values</th>
     * </tr>
     * </thead>
     * <tbody>
     * <tr>
     * <th scope="row">{@code startTime}</th>
     * <td>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.</td>
     * <td>{@code Instant.MIN_VALUE.toString()}</td>
     * <td>ISO-8601. See {@link Instant#toString}<br>
     * or milliseconds since epoch</td>
     * <td>{@code "2015-11-03T00:00"},<br>
     * {@code "1446508800000"}</td>
     * </tr>
     * <tr>
     * <th scope="row">{@code endTime}</th>
     * <td>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.</td>
     * <td>{@code Instant.MAX_VALUE.toString()}</td>
     * <td>ISO-8601. See {@link Instant#toString} <br>
     * or milliseconds since epoch</td>
     * <td>{@code "2015-11-03T01:00"}, <br>
     * {@code "1446512400000"}</td>
     * </tr>
     *
     * <tr>
     * <th scope="row">{@code blockSize}</th>
     * <td>Specifies the maximum number of bytes to read with a call to {@code readStream}
     * </td>
     * <td>{@code "50000"}</td>
     * <td>A positive {@code long} value. <br>
     * <br>
     * 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.</td>
     * <td>{@code "50000"},<br>
     * {@code "1000000"},<br>
     * </tr>
     * </tbody>
     * </table>
     * If an option is omitted from the map the default value is used.
     * <p>
     * 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<String, String> streamOptions) throws IOException;

    Closes the recording stream with the specified ID and releases any system
resources that are associated with the stream.

If the stream is already closed, invoking this method has no effect.
Params: streamId – the ID of the stream
Throws: IllegalArgumentException – if a stream with the specified ID doesn't
        exist
IOException – if an I/O error occurs while trying to close the stream
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: openStream(long, Map<String,String>)/**
     * Closes the recording stream with the specified ID and releases any system
     * resources that are associated with the stream.
     * <p>
     * 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 null if no more data is available.  To read all data for a recording, invoke this method repeatedly until null is returned. 
Params: streamId – the ID of the stream
Throws: IOException – if the stream is closed, or an I/O error occurred while
        trying to read the stream
IllegalArgumentException – if no recording with the stream ID exists
SecurityException – if a security manager exists and the caller does not have ManagementPermission("monitor")
Returns: byte array that contains recording data, or null when no more data is available/**
     * Reads a portion of data from the stream with the specified ID, or returns
     * {@code null} if no more data is available.
     * <p>
     * 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 FlightRecorderMXBean for available option names. 
Params: recordingId – the ID of the recording to get options for
Throws: IllegalArgumentException – if no recording with the
        specified ID exists
SecurityException – if a security manager exists and the caller does not have ManagementPermission("monitor")
Returns: a map describing the recording options, not null/**
     * 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).
     * <p>
     * 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<String, String> getRecordingOptions(long recordingId) throws IllegalArgumentException;

    Returns a Map that contains the settings for the recording with the specified ID, (for example, the event thresholds)  If multiple recordings are running at the same time, more data could be recorded than what is specified in the Map object. 
 The name in the Map is the event name and the setting name separated by "#" (for example, "jdk.VMInfo#period"). The value is a textual representation of the settings value (for example, "60 s"). 
Params: recordingId – the ID of the recordings to get settings for
Throws: IllegalArgumentException – if no recording with the specified ID exists
SecurityException – if a security manager exists and the caller does not have ManagementPermission("monitor")
Returns: a map that describes the recording settings, not null/**
     * Returns a {@code Map} that contains the settings for the recording with the specified ID,
     * (for example, the event thresholds)
     * <p>
     * If multiple recordings are running at the same time, more data could be
     * recorded than what is specified in the {@code Map} object.
     * <p>
     * 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<String, String> getRecordingSettings(long recordingId) throws IllegalArgumentException;

    Sets a configuration as a string representation for the recording with the
specified ID.
Params: recordingId – ID of the recording
contents – a string representation of the configuration file to use, not null
Throws: IllegalArgumentException – if no recording with the
        specified ID exists or if the configuration could not be parsed.
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: Configuration.getContents()/**
     * Sets a configuration as a string representation for the recording with the
     * specified ID.
     *
     * @param recordingId ID of the recording
     * @param contents a string representation of the configuration file to use,
     *        not {@code null}
     * @throws IllegalArgumentException if no recording with the
     *         specified ID exists or if the configuration could not be parsed.
     * @throws java.lang.SecurityException if a security manager exists and the
     *         caller does not have {@code ManagementPermission("control")}
     *
     * @see Configuration#getContents()
     */
    void setConfiguration(long recordingId, String contents) throws IllegalArgumentException;

    Sets a predefined configuration for the recording with the specified ID.
Params: recordingId – ID of the recording to set the configuration for
configurationName – the name of the configuration (for example, "profile" or "default"), not null
Throws: IllegalArgumentException – if no recording with the
        specified ID exists
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: getConfigurations()/**
     * Sets a predefined configuration for the recording with the specified ID.
     *
     * @param recordingId ID of the recording to set the configuration for
     * @param configurationName the name of the configuration (for example,
     *        {@code "profile"} or {@code "default"}), 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 #getConfigurations()
     */
    void setPredefinedConfiguration(long recordingId, String configurationName) throws IllegalArgumentException;

    Sets and replaces all previous settings for the specified recording.

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:
 
  <event-name> + "#" + <setting-name>
 

or
 
  <event-id> + "#" + <setting-name>
 
 For example, to set the sample interval of the CPU Load event to once every second, use the name "jdk.CPULoad#period" and the value "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 "56#period". The ID for an event is obtained by invoking 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 FlightRecorder.getEventTypes() and EventType.getName(). A list of available settings for an event type is obtained by invoking EventType.getSettingDescriptors() and ValueDescriptor.getName(). 
Params: recordingId – ID of the recording
settings – name value map of the settings to set, not null
Throws: IllegalArgumentException – if no recording with the specified ID exists
SecurityException – if a security manager exists and the caller does not have ManagementPermission("control")
See Also: Recording.getId()/**
     * Sets and replaces all previous settings for the specified recording.
     * <p>
     * A setting consists of a name/value pair, where <em>name</em> specifies the
     * event and setting to configure, and the <em>value</em> specifies what to set
     * it to.
     * <p>
     * The name can be formed in the following ways:
     * <p>
     * {@code
     *   <event-name> + "#" + <setting-name>
     * }
     * <p>
     * or
     * <p>
     * {@code
     *   <event-id> + "#" + <setting-name>
     * }
     * <p>
     * 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.
     * <p>
     * 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<String, String> settings) throws IllegalArgumentException;

    Configures the recording options (for example, destination file and time span
to keep data).
 See FlightRecorderMXBean for a description of the options and values that can be used. Setting a value to null restores the value to the default value. 
Params: recordingId – the ID of the recording to set options for
options – name/value map of the settings to set, not null
Throws: IllegalArgumentException – if no recording with the specified ID exists
SecurityException – if a security manager exists, and the caller does not have ManagementPermission("control") or an option contains a file that the caller does not have permission to operate on.
See Also: Recording.getId()/**
     * Configures the recording options (for example, destination file and time span
     * to keep data).
     * <p>
     * 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<String, String> options) throws IllegalArgumentException;

    Returns the list of the available recordings, not necessarily running.

MBeanServer access:
 The mapped type of RecordingInfo is CompositeData with attributes as specified in the 
RecordingInfo.from method. 
Throws: SecurityException – if a security manager exists and the caller does not have  ManagementPermission("monitor")
See Also: RecordingInfo
Recording
Returns: list of recordings, not null/**
     * Returns the list of the available recordings, not necessarily running.
     * <p>
     * <b>MBeanServer access</b>:<br>
     * 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<RecordingInfo> getRecordings();

    Returns the list of predefined configurations for this Java Virtual Machine (JVM).

MBeanServer access:
 The mapped type of ConfigurationInfo is CompositeData with attributes as specified in the 
ConfigurationInfo.from method. 
Throws: SecurityException – if a security manager exists and the caller does not have ManagementPermission("monitor")
See Also: ConfigurationInfo
Configuration
Returns: the list of predefined configurations, not null/**
     * Returns the list of predefined configurations for this Java Virtual Machine (JVM).
     * <p>
     * <b>MBeanServer access</b>:<br>
     * 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<ConfigurationInfo> getConfigurations();

    Returns the list of currently registered event types.

MBeanServer access:
 The mapped type of EventTypeInfo is CompositeData with attributes as specified in the 
EventTypeInfo.from method. 
Throws: SecurityException – if a security manager exists and the caller does not have ManagementPermission("monitor")
See Also: EventTypeInfo
EventType
Returns: the list of registered event types, not null/**
     * Returns the list of currently registered event types.
     * <p>
     * <b>MBeanServer access</b>:<br>
     * 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<EventTypeInfo> getEventTypes();

    Writes recording data to the specified file.
 If this method is invoked remotely from another process, the data is written to a file named 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. 
Params: recordingId – the ID of the recording to dump data for
outputFile – the system-dependent file name where data is written, not null
Throws: IOException – if the recording can't be dumped due to an I/O error (for
        example, an invalid path)
IllegalArgumentException – if a recording with the specified ID doesn't
        exist
IllegalStateException – if the recording is not yet started or if it is
        already closed
SecurityException – if a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the named file or the caller does not have ManagmentPermission("control")
See Also: Path.toString()
Recording.dump(Path)/**
     * Writes recording data to the specified file.
     * <p>
     * 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;
}

Name	Descripion	Default value	Format	Example values
`name`	Sets a human-readable recording name	String representation of the recording id	`String`	`"My Recording"`, `"profiling"`
`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 `disk=true`, otherwise this parameter is ignored.	`"0"` (no limit)	`"0"` if no limit is imposed, otherwise a string representation of a positive `Long` value followed by an empty space and one of the following units, `"ns"` (nanoseconds) `"us"` (microseconds) `"ms"` (milliseconds) `"s"` (seconds) `"m"` (minutes) `"h"` (hours) `"d"` (days)	`"2 h"`, `"24 h"`, `"2 d"`, `"0"`
`maxSize`	Specifies the size, measured in bytes, at which data is kept in disk repository. Only works if `disk=true`, otherwise this parameter is ignored.	`"0"` (no limit)	String representation of a `Long` value, must be positive	`"0"`, `"1000000000"`
`dumpOnExit`	Dumps recording data to disk on Java Virtual Machine (JVM) exit	`"false"`	String representation of a `Boolean` value, `"true"` or `"false"`	`"true"`, `"false"`
`destination`	Specifies the path where recording data is written when the recording stops.	`"false"`	See `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.}	`"c:\recording\recotding.jfr"`, `"/recordings/recording.jfr"`, `"recording.jfr"`
`disk`	Stores recorded data as it is recorded	`"false"`	String representation of a `Boolean` value, `"true"` or `"false"`	`"true"`, `"false"`
`duration`	Sets how long the recording should be running	`"0"` (no limit, continuous)	`"0"` if no limit should be imposed, otherwise a string representation of a positive `Long` followed by an empty space and one of the following units: `"ns"` (nanoseconds) `"us"` (microseconds) `"ms"` (milliseconds) `"s"` (seconds) `"m"` (minutes) `"h"` (hours) `"d"` (days)	`"60 s"`, `"10 m"`, `"4 h"`, `"0"`

Name	Descripion	Default value	Format	Example values
`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.	`Instant.MIN_VALUE.toString()`	ISO-8601. See `Instant.toString` or milliseconds since epoch	`"2015-11-03T00:00"`, `"1446508800000"`
`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.	`Instant.MAX_VALUE.toString()`	ISO-8601. See `Instant.toString` or milliseconds since epoch	`"2015-11-03T01:00"`, `"1446512400000"`
`blockSize`	Specifies the maximum number of bytes to read with a call to `readStream`	`"50000"`	A positive `long` value. Setting `blockSize` to a very high value may result in `OutOfMemoryError` or an `IllegalArgumentException`, if the Java Virtual Machine (JVM) deems the value too large to handle.	`"50000"`, `"1000000"`,

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 exists and the caller does not have `ManagementPermission("control")`
See Also:	Recording
Returns:	a unique ID that can be used to start, stop, close and configure the recording

Throws:	SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	Recording
Returns:	a snapshot of all available recording data, not `null`
Returns:	a unique ID that can be used for reading recording data.

Params:	recordingId – the recording ID of the recording to create a clone from stop – if the newly created clone is stopped before returning.
Throws:	IllegalArgumentException – if a recording with the specified ID doesn't exist SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	Recording
Returns:	a unique ID that can be used to start, stop, close and configure the recording

Params:	recordingId – ID of the recording to start
Throws:	IllegalArgumentException – if a recording with the specified ID doesn't exist SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	Recording

Params:	recordingId – the ID of the recording to stop
Throws:	IllegalArgumentException – if a recording with the specified ID doesn't exist IllegalStateException – if the recording is not running SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	newRecording()
Returns:	`true` if the recording is stopped, `false` otherwise

Params:	recordingId – ID of the recording to open the stream for streamOptions – a map that contains the options that controls the amount of data and how it is read, or `null` to get all data for the recording with the default block size
Throws:	IllegalArgumentException – if a recording with the iD doesn't exist, or if `options` contains invalid values IOException – if the recording is closed, an I/O error occurs, or no data is available for the specified recording or interval SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
Returns:	a unique ID for the stream.

Params:	streamId – the ID of the stream
Throws:	IllegalArgumentException – if a stream with the specified ID doesn't exist IOException – if an I/O error occurs while trying to close the stream SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	openStream(long, Map<String,String>)

Params:	recordingId – the ID of the recordings to get settings for
Throws:	IllegalArgumentException – if no recording with the specified ID exists SecurityException – if a security manager exists and the caller does not have `ManagementPermission("monitor")`
Returns:	a map that describes the recording settings, not `null`

Params:	recordingId – ID of the recording contents – a string representation of the configuration file to use, not `null`
Throws:	IllegalArgumentException – if no recording with the specified ID exists or if the configuration could not be parsed. SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	Configuration.getContents()

Params:	recordingId – ID of the recording to set the configuration for configurationName – the name of the configuration (for example, `"profile"` or `"default"`), not `null`
Throws:	IllegalArgumentException – if no recording with the specified ID exists SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	getConfigurations()

Params:	recordingId – ID of the recording settings – name value map of the settings to set, not `null`
Throws:	IllegalArgumentException – if no recording with the specified ID exists SecurityException – if a security manager exists and the caller does not have `ManagementPermission("control")`
See Also:	Recording.getId()

/

java/ 8/ jdk/management/jfr/FlightRecorderMXBean.java

Recording options