所有父级接口：: PlatformManagedObject

public interface FlightRecorderMXBean extends PlatformManagedObject

控制飞行记录仪的管理接口。

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

jdk.management.jfr:type=FlightRecorder

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

录音选项
指定记录应持续多长时间，以及应在何处和何时转储数据。
设置
指定应启用哪些事件以及每个事件应捕获哪种信息。
配置
预定义的设置集，通常来自设置文件，同时指定多个事件的配置。

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

录音选项

下表显示了用于 setRecordingOptions(long, Map) 和 getRecordingOptions(long) 的选项名称。

录音选项
Name	说明	默认值	Format	示例值
`name`	设置人类可读的录音名称	录音 ID 的字符串表示	`String`	`"My Recording"` , `"profiling"`
`maxAge`	指定数据在磁盘存储库中保留的时间长度，直到最旧的数据可能被删除。仅在 `disk=true` 时有效，否则忽略此参数。	`"0"`（无限制）	`"0"` 如果没有施加限制，否则为正 `Long` 值的字符串表示形式，后跟一个空格和以下单位之一， `"ns"`（纳秒） `"us"`（微秒） `"ms"`（毫秒） `"s"`（秒） `"m"`（分钟） `"h"`（小时） `"d"`（天）	`"2 h"` , `"24 h"` , `"2 d"` , `"0"`
`maxSize`	指定数据在磁盘存储库中保存的大小（以字节为单位）。仅在 `disk=true` 时有效，否则忽略此参数。	`"0"`（无限制）	`Long` 值的字符串表示形式，必须为正数	`"0"` , `"1000000000"`
`dumpOnExit`	在 Java 虚拟机 (JVM) 退出时将记录数据转储到磁盘	`"false"`	`Boolean` 值、`"true"` 或 `"false"` 的字符串表示	`"true"` , `"false"`
`destination`	指定录音停止时写入录音数据的路径。	`"false"`	有关格式，请参阅 `Paths#getPath`。如果从另一个进程调用此方法，则数据将写入运行目标 JVM 的机器上。如果 destination 是相对路径，则它是相对于目标 JVM 启动的工作目录的。}	`"c:\recording\recotding.jfr"` , `"/recordings/recording.jfr"` , `"recording.jfr"`
`disk`	按原样存储记录的数据	`"false"`	`Boolean` 值、`"true"` 或 `"false"` 的字符串表示	`"true"` , `"false"`
`duration`	设置录音应该运行多长时间	`"0"`（无限制，连续）	`"0"` 如果不应施加限制，否则为正 `Long` 后跟空格和以下单位之一的字符串表示形式： `"ns"`（纳秒） `"us"`（微秒） `"ms"`（毫秒） `"s"`（秒） `"m"`（分钟） `"h"`（小时） `"d"`（天）	`"60 s"` , `"10 m"` , `"4 h"` , `"0"`

自从：: 9

字段摘要

字段

修饰符和类型

Field

描述

static final String

MXBEAN_NAME

FlightRecorderMXBean 的 ObjectName 的字符串表示。
方法总结

修饰符和类型

方法

描述

long

cloneRecording(long recordingId, boolean stop)

创建现有录音的副本，对于提取部分录音很有用。

void

closeRecording(long recordingId)

关闭具有指定 ID 的记录并释放与该记录关联的所有系统资源。

void

closeStream(long streamId)

关闭具有指定 ID 的录制流并释放与该流关联的所有系统资源。

void

copyTo(long recordingId, String outputFile)

将录音数据写入指定文件。

List<ConfigurationInfo>

getConfigurations()

返回此 Java 虚拟机 (JVM) 的预定义配置列表。

List<EventTypeInfo>

getEventTypes()

返回当前注册的事件类型列表。

Map<String,String>

getRecordingOptions(long recordingId)

返回包含具有指定 ID 的记录选项的映射（例如，目标文件或保留记录数据的时间跨度）。

List<RecordingInfo>

getRecordings()

返回可用记录的列表，不一定是正在运行的。

Map<String,String>

getRecordingSettings(long recordingId)

返回一个 Map，其中包含具有指定 ID 的记录的设置（例如，事件阈值）

long

newRecording()

创建录音，但不启动它。

long

openStream(long recordingId, Map<String,String> streamOptions)

为具有指定 ID 的记录打开数据流，或 0 以获取与记录无关的数据。

byte[]

readStream(long streamId)

从具有指定 ID 的流中读取部分数据，如果没有更多数据可用，则返回 null。

void

setConfiguration(long recordingId, String contents)

将配置设置为具有指定 ID 的记录的字符串表示形式。

void

setPredefinedConfiguration(long recordingId, String configurationName)

为具有指定 ID 的录制设置预定义配置。

void

setRecordingOptions(long recordingId, Map<String,String> options)

配置记录选项（例如，目标文件和保留数据的时间跨度）。

void

setRecordingSettings(long recordingId, Map<String,String> settings)

设置并替换指定记录的所有先前设置。

void

startRecording(long recordingId)

使用指定的 ID 开始录制。

boolean

stopRecording(long recordingId)

停止具有指定 ID 的正在运行的记录。

long

takeSnapshot()

创建所有可用记录数据的快照记录。

在接口 java.lang.management.PlatformManagedObject 中声明的方法
getObjectName

字段详细信息
- MXBEAN_NAME
  
  static final String MXBEAN_NAME
  
  FlightRecorderMXBean 的 ObjectName 的字符串表示。
  参见：
  
  常量字段值

方法详情

newRecording

long newRecording() throws IllegalStateException , SecurityException

创建录音，但不启动它。
返回：

可用于启动、停止、关闭和配置录制的唯一 ID

抛出：

IllegalStateException - 如果无法创建飞行记录器（例如，如果 Java 虚拟机 (JVM) 缺少飞行记录器支持，或者无法创建或访问文件存储库）

SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")

参见：
- Recording
takeSnapshot

long takeSnapshot()

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

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

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

可用于读取记录数据的唯一 ID

抛出：

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
startRecording

void startRecording(long recordingId) throws IllegalStateException , SecurityException

使用指定的 ID 开始录制。
停止的录制无法重新开始。
参数：

recordingId - 要开始的记录的 ID

抛出：

IllegalArgumentException - 如果不存在具有指定 ID 的记录

SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")

IllegalStateException

参见：
- Recording
stopRecording

boolean stopRecording(long recordingId) throws IllegalArgumentException , IllegalStateException , SecurityException

停止具有指定 ID 的正在运行的记录。
参数：

recordingId - 停止录制的 ID

返回：

true 如果录制停止，false 否则

抛出：

IllegalArgumentException - 如果不存在具有指定 ID 的记录

IllegalStateException - 如果记录没有运行

SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("control")

参见：
- newRecording()
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 以获取与记录无关的数据。

录制流选项
Name	说明	默认值	Format	示例值
`startTime`	指定开始录制流的时间点。由于数据的存储方式，可能会包含一些在开始时间之前开始或结束的事件。	`Instant.MIN_VALUE.toString()`	ISO-8601。见`Instant.toString()` 或自纪元以来的毫秒数	`"2015-11-03T00:00"` , `"1446508800000"`
`endTime`	指定结束录制流的时间点。由于数据的存储方式，可能会包含一些在结束时间之后开始或结束的事件。	`Instant.MAX_VALUE.toString()`	ISO-8601。见`Instant.toString()` 或自纪元以来的毫秒数	`"2015-11-03T01:00"` , `"1446512400000"`
`blockSize`	指定通过调用 `readStream` 读取的最大字节数	`"50000"`	一个正的 `long` 值。如果 Java 虚拟机 (JVM) 认为该值太大而无法处理，则将 `blockSize` 设置为非常高的值可能会导致 `OutOfMemoryError` 或 `IllegalArgumentException` 。	`"50000"` , `"1000000"` ,
`streamVersion`	指定从正在运行的记录中读取数据时要使用的格式	`"1.0"`	带有主要版本和次要版本的版本号。为了能够从正在运行的记录中读取，必须设置该值	`"1.0"`

如果map中省略了一个选项，则使用默认值。

在打开流之前必须停止具有指定 ID 的记录，除非指定了选项 "streamVersion"。

参数：: 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

返回：

描述记录选项的map，而不是null

抛出：

IllegalArgumentException - 如果不存在具有指定 ID 的记录

SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")
getRecordingSettings

Map <String ,String > getRecordingSettings(long recordingId) throws IllegalArgumentException

返回一个 Map，其中包含具有指定 ID 的记录的设置（例如，事件阈值）
如果同时运行多个记录，则记录的数据可能多于 Map 对象中指定的数据。

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

参数：

recordingId - 要获取设置的录音 ID

返回：

一张描述录音设置的map，而不是null

抛出：

IllegalArgumentException - 如果不存在具有指定 ID 的记录

SecurityException - 如果存在安全管理器且调用者没有 ManagementPermission("monitor")
setConfiguration

void setConfiguration(long recordingId, String contents) throws IllegalArgumentException

将配置设置为具有指定 ID 的记录的字符串表示形式。
参数：

recordingId - 录音的 ID

contents - 要使用的配置文件的字符串表示，而不是 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 指定要配置的事件和设置，value 指定将其设置为什么。

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

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

or

<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)

接口 FlightRecorderMXBean

录音选项

字段摘要

方法总结

在接口 java.lang.management.PlatformManagedObject 中声明的方法

字段详细信息

MXBEAN_NAME

方法详情

newRecording

takeSnapshot

cloneRecording

startRecording

stopRecording

closeRecording

openStream

closeStream

readStream

getRecordingOptions

getRecordingSettings

setConfiguration

setPredefinedConfiguration

setRecordingSettings

setRecordingOptions

getRecordings

getConfigurations

getEventTypes

copyTo