Module jdk.management.jfr
Package jdk.management.jfr

Interface FlightRecorderMXBean

  • All Superinterfaces:
    PlatformManagedObject
    public interface FlightRecorderMXBean
extends PlatformManagedObject
    Management interface for controlling Flight Recorder.

    The ObjectName for identifying the MXBean in the platform MBean server is:

    jdk.management.jfr:type=FlightRecorder

    Flight Recorder can be configured in multiple ways. There are

    • Recording options
      that determines how long a recording should last, and where and when data should be dumped.
    • Settings
      that determines which events should be enabled and what kind information each event should capture.
    • Configurations
      that are predefined sets of settings, typically derived from a settings file, for convenient configuration of multiple events simultaneously.

    See package jdk.jfr documentation for a description of the settings syntax and ConfigurationInfo for configuration related information..

    Recording options

    List of options names to be used with setRecordingOptions(long, Map) and getRecordingOptions(long).

    Recording options and their purpose.
    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 When the duration of a recording exceeds the maxAge threshold, the oldest data may be deleted. Only works if disk=true, otherwise parameter is ignored. "0" (no limit) "0" if no limit should be 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 When the size of a recording, measured in bytes, exceeds the maxSize threshold, the oldest data may be deleted. Only works if disk=true, otherwise parameter is ignored. "0" (no limit) String representation of a Long value, must be positive "0",
    "1000000000"
    dumpOnExit Dumps recording data to disk on JVM exit "false" String representation of a Boolean value, "true" or "false" "true",
    "false"
    destination Path where recording data should be 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 VM is running. If destination is a relative path, it is relative to the working directory where the target VM was started.}    		 "c:\recording\recotding.jfr",
    "/recordings/recording.jfr", "recording.jfr"
    disk Stores recording to disk 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:
    9

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String MXBEAN_NAME
      String representation of the ObjectName for the FlightRecorderMXBean.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      long cloneRecording​(long recordingId, boolean stop)
      Creates a copy of an exiting recording, useful for extracting parts of a recording.
      void closeRecording​(long recordingId)
      Closes the recording with the specified id and releases any system resources associated with the recording.
      void closeStream​(long streamId)
      Closes the recording stream with the specified id and releases any system resources associated with the stream.
      void copyTo​(long recordingId, String outputFile)
      Writes recording data to the specified file.
      List<ConfigurationInfo> getConfigurations()
      Returns the list of predefined configurations.
      List<EventTypeInfo> getEventTypes()
      Returns the list of registered event types.
      Map<String,String> getRecordingOptions​(long recordingId)
      Returns a map containing options for the recording with the specified id.
      List<RecordingInfo> getRecordings()
      Returns the list of available recordings, not necessarily running.
      Map<String,String> getRecordingSettings​(long recordingId)
      Returns a map containing settings for the recording with the specified id, for example event thresholds.
      long newRecording()
      Creates a recording, but doesn't start it.
      long openStream​(long recordingId, Map<String,String> streamOptions)
      Opens a data stream for the recording with the specified id, or 0 to get data irrespective of recording.
      byte[] readStream​(long streamId)
      Reads a portion of data from the stream with the specified id, or returns null if there is no more data available.
      void setConfiguration​(long recordingId, String contents)
      Sets a configuration as string representation for the recording with the specified id.
      void setPredefinedConfiguration​(long recordingId, String configurationName)
      Sets a predefined configuration for the recording with the specified id.
      void setRecordingOptions​(long recordingId, Map<String,String> options)
      Configures recording options, for example destination file and timespan to keep data.
      void setRecordingSettings​(long recordingId, Map<String,String> settings)
      Sets and replaces all previous settings for the specified recording.
      void startRecording​(long recordingId)
      Starts the recording with the specified id.
      boolean stopRecording​(long recordingId)
      Stops the running recording with the specified id.
      long takeSnapshot()
      Creates a recording snapshot of all available recorded data.

    • Field Detail

      • MXBEAN_NAME

        static final String MXBEAN_NAME
        String representation of the ObjectName for the FlightRecorderMXBean.
        See Also:
        Constant Field Values

    • Method Detail

      • newRecording

        long newRecording()
           throws IllegalStateException,
                  SecurityException
        Creates a recording, but doesn't start it.
        Returns:
        a unique identifier that can be used for starting, stopping, closing and configuring the recording
        Throws:
        IllegalStateException - if Flight Recorder can't be started, for example if commercial features are not unlocked
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("control")
        See Also:
        Recording

      • takeSnapshot

        long takeSnapshot()
        Creates a recording snapshot of all available recorded data.

        A snapshot is a synthesized recording in a stopped state. If there is no data available, a recording with size 0 is returned.

        A snapshot gives stable data access for later operations, such as narrowing the time interval or reducing the data size.

        It is the caller's responsibility to close the recording when access to the data is no longer needed.

        Returns:
        a snapshot of all available recording data, not null
        Throws:
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("control")
        See Also:
        Recording

      • cloneRecording

        long cloneRecording​(long recordingId,
                    boolean stop)
             throws IllegalArgumentException,
                    SecurityException
        Creates a copy of an exiting recording, useful for extracting parts of a recording.

        The cloned recording will hold on to the same recording data as the original, but it will have a new id and a name prefixed with "Clone of recording ". If the original recording is running the clone will be started.

        Parameters:
        recordingId - the recording id of the recording to create a clone from, or p to create from all recordings
        stop - if the newly created clone should be stopped before returning.
        Returns:
        a unique identifier that can be used for starting, stopping, closing and configuring the recording
        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

      • closeRecording

        void closeRecording​(long recordingId)
             throws IOException
        Closes the recording with the specified id and releases any system resources associated with the recording.

        If the recording is already closed, invoking this method has no effect.

        Parameters:
        recordingId - 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()

      • openStream

        long openStream​(long recordingId,
                Map<String,String> streamOptions)
         throws IOException
        Opens a data stream for the recording with the specified id, or 0 to get data irrespective of recording.
        Streaming options and their purpose.
        Name Descripion Default value Format Example values
        startTime A point in time signifying the start of a recording stream. Due to how data is stored, some events beginning or ending prior to the startTime may be included. Instant.MIN_VALUE.toString() ISO-8601. See Instant.toString()
        or milliseconds since epoch        		 "2015-11-03T00:00",
        "1446508800000"
        endTime A point in time signifying the end of a recording stream. Due to how data is stored, some events beginning or ending after endTime may be included. Instant.MAX_VALUE.toString() ISO-8601. See Instant.toString()
        or milliseconds since epoch        		 "2015-11-03T01:00",
        "1446512400000"
        blockSize Maximum number of bytes to read with a call to readStream "50000" A positive long value.

        Note setting blockSize to a very high value may result in OutOfMemoryError or an IllegalArgumentException, if the JVM deems the value too large to handle.        		 "50000",
        "1000000",
        If an option is omitted from the map the default value will be used.

        The recording with the specified id must be stopped before a stream can be opened, a restriction that may be lifted in future versions.

        Parameters:
        recordingId - id of the recording to open the stream for
        streamOptions - a map containing option that controls amount of data and how it should be read, or null to get all data for the recording with the default block size
        Returns:
        a unique identifier for the stream.
        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 there is no data available for the specified recording or interval
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("control")

      • closeStream

        void closeStream​(long streamId)
          throws IOException
        Closes the recording stream with the specified id and releases any system resources associated with the stream.

        If the stream is already closed, invoking this method has no effect.

        Parameters:
        streamId - id of the stream
        Throws:
        IllegalArgumentException - if there is no stream with the specified id
        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)

      • readStream

        byte[] readStream​(long streamId)
           throws IOException
        Reads a portion of data from the stream with the specified id, or returns null if there is no more data available.

        To read all data for a recording, call this method repeatedly until null is returned.

        Parameters:
        streamId - id of the stream
        Returns:
        byte array containing recording data, or null when there is no more data
        Throws:
        IOException - if the stream is closed, or an I/O error occurred while trying to read the stream
        IllegalArgumentException - if there is no recording with the stream id
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("monitor")

      • getRecordingOptions

        Map<String,String> getRecordingOptions​(long recordingId)
                                throws IllegalArgumentException
        Returns a map containing options for the recording with the specified id. For example, the destination file or timespan to keep recorded data.

        See FlightRecorderMXBean for available option names.

        Parameters:
        recordingId - id of the recording to get options for
        Returns:
        a map describing the recording options, not null
        Throws:
        IllegalArgumentException - if there is no recording with the specified id
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("monitor")

      • getRecordingSettings

        Map<String,String> getRecordingSettings​(long recordingId)
                                 throws IllegalArgumentException
        Returns a map containing settings for the recording with the specified id, for example event thresholds.

        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 name of the setting, separated by "#", for example "com.oracle.jdk.VMInfo#period". The value is a textual representation of the settings value, for example "everyChunk".

        Parameters:
        recordingId - id of the recordings to get settings for
        Returns:
        a map describing the recording settings, not null
        Throws:
        IllegalArgumentException - if there is no recording with the specified id.
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("monitor")

      • setConfiguration

        void setConfiguration​(long recordingId,
                      String contents)
               throws IllegalArgumentException
        Sets a configuration as string representation for the recording with the specified id.
        Parameters:
        recordingId - the recording id
        contents - a string representation of the configuration file to use, not null
        Throws:
        IllegalArgumentException - if there is no recording with the specified id 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()

      • setPredefinedConfiguration

        void setPredefinedConfiguration​(long recordingId,
                                String configurationName)
                         throws IllegalArgumentException
        Sets a predefined configuration for the recording with the specified id.
        Parameters:
        recordingId - the recording id to the configuration for
        configurationName - the name of the configuration, for example "profile" or "default", not null
        Throws:
        IllegalArgumentException - if there is no recording with the specified id
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("control")
        See Also:
        getConfigurations()

      • setRecordingSettings

        void setRecordingSettings​(long recordingId,
                          Map<String,String> settings)
                   throws IllegalArgumentException
        Sets and replaces all previous settings for the specified recording.

        A setting consists of a name value pair, where the name specifies which event and setting to configure and the value what it should be set to.

        The name can be formed in two 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, the name should be "com.oracle.jdk.CPULoad#period" and the value "1 s". If multiple events use the same name, for instance if an event class is loaded in multiple class loaders, and differentiation is needed between them, the second form can be used, for example "56#period". The id for an event can be obtained by calling EventTypeInfo.getId() and is only valid for this JVM instance.

        A list of available event names can be obtained by calling getEventTypes() and EventTypeInfo.getName(). A list of supported setting for an event type can be obtained by calling EventTypeInfo.getSettingDescriptors() and SettingDescriptorInfo.getName().

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

      • setRecordingOptions

        void setRecordingOptions​(long recordingId,
                         Map<String,String> options)
                  throws IllegalArgumentException
        Configures recording options, for example destination file and timespan to keep data.

        See FlightRecorderMXBean for a description of options and values that can be used.. Setting a value to null restores the value to it's default.

        Parameters:
        recordingId - the id of the recording to set options for
        options - name-value map of the settings to set, not null
        Throws:
        IllegalArgumentException - if there is no recording with the specified id
        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()

      • getRecordings

        List<RecordingInfo> getRecordings()
        Returns the list of available recordings, not necessarily running.

        MBeanServer access:
        The mapped type of RecordingInfo is CompositeData with attributes as specified in the RecordingInfo.from method.

        Returns:
        list of recordings, not null
        Throws:
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("monitor")
        See Also:
        RecordingInfo, Recording

      • getConfigurations

        List<ConfigurationInfo> getConfigurations()
        Returns the list of predefined configurations.

        MBeanServer access:
        The mapped type of ConfigurationInfo is CompositeData with attributes as specified in the ConfigurationInfo.from method.

        Returns:
        the list of predefined configurations, not null
        Throws:
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("monitor")
        See Also:
        ConfigurationInfo, Configuration

      • getEventTypes

        List<EventTypeInfo> getEventTypes()
        Returns the list of registered event types.

        MBeanServer access:
        The mapped type of EventTypeInfo is CompositeData with attributes as specified in the EventTypeInfo.from method.

        Returns:
        the list of registered event types, not null
        Throws:
        SecurityException - if a security manager exists and the caller does not have ManagementPermission("monitor")
        See Also:
        EventTypeInfo, EventType

      • copyTo

        void copyTo​(long recordingId,
            String outputFile)
     throws IOException,
            SecurityException
        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 VM is running. If outputFile is a relative path, it is relative to the working directory where the target VM was started.

        Parameters:
        recordingId - id of the recording to dump data for
        outputFile - the system-dependent filename where data should be 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 has not yet started or if it has already been 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(java.nio.file.Path)