模块  jdk.management.jfr
软件包  jdk.management.jfr

Interface FlightRecorderMXBean

  • All Superinterfaces:
    PlatformManagedObject 
    public interface FlightRecorderMXBeanextends PlatformManagedObject
    用于控制Flight Recorder的管理界面。

    用于标识平台MBean服务器中的MXBean的对象名称是：

    jdk.management.jfr:type=FlightRecorder

    可以通过以下方式配置Flight Recorder：

    • 录制选项
      指定录制的持续时间，以及应转储数据的位置和时间。
    • 设置
      指定应启用哪些事件以及每个事件应捕获的类型信息。
    • 配置
      预定义的设置集，通常从设置文件派生，同时指定多个事件的配置。

    有关配置信息的说明，请参阅包jdk.jfr文档以获取有关设置语法的说明和ConfigurationInfo类文档。

    录制选项

    下表显示了用于setRecordingOptions(long, Map)和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"
    从以下版本开始：
    9

    • 字段详细信息

      • MXBEAN_NAME

        static final String MXBEAN_NAME
        字符串表示 ObjectName的 FlightRecorderMXBean 。
        另请参见：
        常数字段值

    • 方法详细信息

      • newRecording

        long newRecording()           throws IllegalStateException,                  SecurityException
        创建录音，但不启动录音。
        结果
        一个唯一的ID，可用于启动，停止，关闭和配置录制
        异常
        IllegalStateException - 如果无法创建Flight Recorder（例如，如果Java虚拟机（JVM）缺少Flight Recorder支持，或者无法创建或访问文件存储库）
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        Recording

      • takeSnapshot

        long takeSnapshot()
        创建所有可用记录数据的快照记录。

        快照是处于停止状态的合成记录。 如果没有可用数据，则返回大小为0的录像。

        快照可为以后的操作提供对数据的稳定访问（例如，更改时间间隔或减小数据大小的操作）。

        当不再需要访问数据时，调用者必须关闭记录。

        结果
        所有可用录制数据的快照，而不是 null
        异常
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        Recording

      • cloneRecording

        long cloneRecording​(long recordingId,                    boolean stop)             throws IllegalArgumentException,                    SecurityException
        创建现有录制的副本，用于提取录制的部分内容。

        克隆的记录包含与原始记录相同的记录数据，但它具有新ID和名称前缀为"Clone of recording" 。 如果原始录制正在运行，则克隆也在运行。

        参数
        recordingId - 用于创建克隆的记录的记录ID
        stop - 如果在返回之前停止新创建的克隆。
        结果
        一个唯一的ID，可用于启动，停止，关闭和配置录制
        异常
        IllegalArgumentException - 如果不存在具有指定ID的录制
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        Recording

      • closeRecording

        void closeRecording​(long recordingId)             throws IOException
        关闭具有指定ID的记录，并释放与记录关联的所有系统资源。

        如果录制已关闭，则调用此方法无效。

        参数
        recordingId - 要关闭的录制内容的ID
        异常
        IllegalArgumentException - 如果不存在具有指定ID的录制
        IOException - 如果发生I / O错误
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        newRecording()

      • openStream

        long openStream​(long recordingId,                Map<String,​String> streamOptions)         throws IOException
        打开具有指定ID的记录的数据流，或0以获取数据而不管记录。 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",
        如果地图中省略了选项，则使用默认值。

        必须先停止具有指定ID的记录，然后才能打开流。 在将来的版本中可能会取消此限制。

        参数
        recordingId - 要为其打开流的记录的ID
        streamOptions - 包含控制数据量及其读取方式的选项的映射，或 null以使用默认块大小获取记录的所有数据
        结果
        流的唯一ID。
        异常
        IllegalArgumentException - 如果不存在使用iD的录制，或者 options包含无效值
        IOException - 如果录制已关闭，则会发生I / O错误，或者没有可用于指定录制或间隔的数据
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")

      • closeStream

        void closeStream​(long streamId)          throws IOException
        关闭具有指定ID的记录流，并释放与该流关联的所有系统资源。

        如果流已经关闭，则调用此方法无效。

        参数
        streamId - 流的ID
        异常
        IllegalArgumentException - 如果不存在具有指定ID的流
        IOException - 如果在尝试关闭流时发生I / O错误
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        openStream(long, Map)

      • readStream

        byte[] readStream​(long streamId)           throws IOException
        使用指定的ID从流中读取部分数据，如果没有更多数据，则返回null 。

        要读取记录的所有数据，请重复调用此方法，直到返回null 。

        参数
        streamId - 流的ID
        结果
        包含记录数据的字节数组，或者当没有更多数据可用时为 null
        异常
        IOException - 如果流已关闭，或者在尝试读取流时发生I / O错误
        IllegalArgumentException - 如果不存在具有流ID的记录
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")

      • getRecordingOptions

        Map<String,​String> getRecordingOptions​(long recordingId)                                      throws IllegalArgumentException
        返回一个映射，其中包含具有指定ID的记录选项（例如，目标文件或时间跨度以保留记录的数据）。

        有关可用的选项名称，请参见FlightRecorderMXBean 。

        参数
        recordingId - 要获取选项的记录的ID
        结果
        描述录制选项的地图，而不是 null
        异常
        IllegalArgumentException - 如果不存在具有指定ID的记录
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")

      • getRecordingSettings

        Map<String,​String> getRecordingSettings​(long recordingId)                                       throws IllegalArgumentException
        返回Map ，其中包含具有指定ID的记录设置（例如，事件阈值）

        如果同时运行多个记录，则可以记录的数据多于Map对象中指定的Map 。

        Map中的名称是事件名称和设置名称，由"#" （例如， "jdk.VMInfo#period" ）。 该值是设置值的文本表示形式（例如， "60 s" ）。

        参数
        recordingId - 要获取设置的录像的ID
        结果
        描述录制设置的地图，而不是 null
        异常
        IllegalArgumentException - 如果不存在具有指定ID的记录
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")

      • setConfiguration

        void setConfiguration​(long recordingId,                      String contents)               throws IllegalArgumentException
        将配置设置为具有指定ID的记录的字符串表示形式。
        参数
        recordingId - 录制的ID
        目录 - 要使用的配置文件的字符串表示形式，而不是 null
        异常
        IllegalArgumentException - 如果不存在具有指定ID的记录，或者无法解析配置。
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        Configuration.getContents()

      • setPredefinedConfiguration

        void setPredefinedConfiguration​(long recordingId,                                String configurationName)                         throws IllegalArgumentException
        为具有指定ID的记录设置预定义配置。
        参数
        recordingId - 要为其设置配置的记录的ID
        configurationName - 配置名称（例如， "profile"或 "default" ），而不是 null
        异常
        IllegalArgumentException - 如果不存在具有指定ID的记录
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        getConfigurations()

      • setRecordingSettings

        void setRecordingSettings​(long recordingId,                          Map<String,​String> settings)                   throws IllegalArgumentException
        设置并替换指定录制的所有先前设置。

        设置由名称/值对组成，其中name指定要配置的事件和设置， 值指定要将其设置为的内容。

        名称可以通过以下方式形成：

        <event-name> + "#" + <setting-name>

        要么

        <event-id> + "#" + <setting-name>

        例如，要将CPU Load事件的采样间隔设置为每秒一次，请使用名称"jdk.CPULoad#period"和值"1 s" 。 如果多个事件使用相同的名称，例如，如果在多个类加载器中加载了事件类，并且需要区分它们，则名称为"56#period" 。 事件的ID是通过调用EventType.getId()方法获得的，并且对于注册事件的Java虚拟机（JVM）实例有效。

        通过调用FlightRecorder.getEventTypes()和EventType.getName()检索可用事件名称列表。 通过调用EventType.getSettingDescriptors()和ValueDescriptor.getName()获取事件类型的可用设置列表。

        参数
        recordingId - 录制的ID
        settings - 要设置的设置的名称值映射，而不是 null
        异常
        IllegalArgumentException - 如果不存在具有指定ID的记录
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")
        另请参见：
        Recording.getId()

      • setRecordingOptions

        void setRecordingOptions​(long recordingId,                         Map<String,​String> options)                  throws IllegalArgumentException
        配置录制选项（例如，目标文件和时间跨度以保留数据）。

        有关可以使用的选项和值的说明，请参见FlightRecorderMXBean 。 将值设置为null将该值还原为默认值。

        参数
        recordingId - 要为其设置选项的记录的ID
        options - 要设置的设置的名称/值映射，而不是 null
        异常
        IllegalArgumentException - 如果不存在具有指定ID的记录
        SecurityException - 如果存在安全管理器，并且调用者没有 ManagementPermission("control")或者选项包含调用者无权操作的文件。
        另请参见：
        Recording.getId()

      • getRecordings

        List<RecordingInfo> getRecordings()
        返回可用录音的列表，不一定正在运行。

        MBeanServer访问 ：
        映射类型RecordingInfo是CompositeData ，其属性在RecordingInfo.from方法中指定。

        结果
        录音列表，而不是 null
        异常
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")
        另请参见：
        RecordingInfo ， Recording

      • getConfigurations

        List<ConfigurationInfo> getConfigurations()
        返回此Java虚拟机（JVM）的预定义配置列表。

        MBeanServer访问 ：
        映射类型ConfigurationInfo是CompositeData ，其属性在ConfigurationInfo.from方法中指定。

        结果
        预定义配置列表，而不是 null
        异常
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")
        另请参见：
        ConfigurationInfo ， Configuration

      • getEventTypes

        List<EventTypeInfo> getEventTypes()
        返回当前注册的事件类型列表。

        MBeanServer访问 ：
        映射类型EventTypeInfo是CompositeData ，其属性在EventTypeInfo.from方法中指定。

        结果
        已注册事件类型的列表，而不是 null
        异常
        SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")
        另请参见：
        EventTypeInfo ， EventType

      • copyTo

        void copyTo​(long recordingId,            String outputFile)     throws IOException,            SecurityException
        将记录数据写入指定的文件。

        如果从另一个进程远程调用此方法，则会将数据写入运行目标Java虚拟机（JVM）的计算机上名为outputFile的文件。 如果文件位置是相对路径，则它相对于启动目标JVM的工作目录。

        参数
        recordingId - 要转储数据的记录的ID
        outputFile - 写入数据的系统相关文件名，而不是 null
        异常
        IOException - 如果由于I / O错误而无法转储录制（例如，路径无效）
        IllegalArgumentException - 如果不存在具有指定ID的录制
        IllegalStateException - 如果录制尚未开始或已关闭
        SecurityException - 如果存在安全管理器且其 SecurityManager.checkWrite(java.lang.String)方法拒绝对指定文件的写访问权限，或者调用者没有 ManagmentPermission("control")
        另请参见：
        Path.toString(), Recording.dump(java.nio.file.Path)