所有超级接口:: PlatformManagedObject

public interface FlightRecorderMXBean extends PlatformManagedObject

用于控制飞行记录器的管理接口。

用于在平台MBean服务器中标识MXBean的对象名称为:

jdk.management.jfr:type=FlightRecorder

飞行记录器可以通过以下方式进行配置:

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

查看包jdk.jfr文档以获取有关设置语法的描述，以及ConfigurationInfo类文档以获取配置信息。

记录选项

以下表格显示了与setRecordingOptions(long, Map)和getRecordingOptions(long)一起使用的选项名称。

记录选项
名称	描述	默认值	格式	示例值
`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运行的机器上。如果目标是相对路径，则相对于启动目标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 Summary

Fields

Modifier and Type

Field

Description

static final String

MXBEAN_NAME

FlightRecorderMXBean的ObjectName的字符串表示。
Method Summary

Modifier and Type

Method

Description

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)

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

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

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

Methods declared in interface java.lang.management.PlatformManagedObject
getObjectName

Field Details
- MXBEAN_NAME
  
  static final String MXBEAN_NAME
  
  FlightRecorderMXBean的ObjectName的字符串表示。
  参见:
  
  常量字段值

Method Details

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以获取与录制无关的数据。

录制流选项
名称	描述	默认值	格式	示例值
`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`值。将`blockSize`设置为非常高的值可能导致`OutOfMemoryError`或`IllegalArgumentException`，如果Java虚拟机（JVM）认为值过大而无法处理。	`"50000"`, `"1000000"`,
`streamVersion`	指定从运行中的录制读取数据时要使用的格式	`"1.0"`	具有主要版本和次要版本的版本号。要能够从运行中的录制中读取，必须设置该值	`"1.0"`

如果地图中省略了选项，则使用默认值。

必须在打开流之前停止具有指定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

返回:

描述录制选项的地图，不为null

抛出:

IllegalArgumentException - 如果没有具有指定ID的录制

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

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

返回一个包含具有指定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

contents - 要使用的配置文件的字符串表示形式，不能为空

抛出:

IllegalArgumentException - 如果不存在具有指定ID的记录或无法解析配置。

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

参见:
- Configuration.getContents()
setPredefinedConfiguration

void setPredefinedConfiguration(long recordingId, String configurationName) throws IllegalArgumentException

设置指定ID的记录的预定义配置。
参数:

recordingId - 要设置配置的记录的ID

configurationName - 配置的名称（例如，"profile"或"default"），不能为空

抛出:

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

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

参见:
- getConfigurations()
setRecordingSettings

void setRecordingSettings(long recordingId, Map<String,String> settings) throws IllegalArgumentException

设置并替换指定记录的所有先前设置。
设置由名称/值对组成，其中名称指定要配置的事件和设置，值指定要设置的内容。

名称可以以下列方式形成：

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

或

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

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

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

recordingId - 记录的ID

settings - 要设置的设置的名称值映射，不能为空

抛出:

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

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

参见:
- Recording.getId()
setRecordingOptions

void setRecordingOptions(long recordingId, Map<String,String> options) throws IllegalArgumentException

配置记录选项（例如，目标文件和保留数据的时间跨度）。
有关可以使用的选项和值的描述，请参阅FlightRecorderMXBean。将值设置为null将值恢复为默认值。
参数:

recordingId - 要设置选项的记录的ID

options - 要设置的设置的名称值映射，不能为空

抛出:

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

SecurityException - 如果存在安全管理器，且调用者没有ManagementPermission("control")或一个选项包含调用者无权操作的文件。

参见:
- Recording.getId()
getRecordings

List<RecordingInfo> getRecordings()

返回可用记录的列表，不一定在运行中。
MBeanServer访问:
RecordingInfo的映射类型为CompositeData，其属性如RecordingInfo.from方法中指定。
返回:

记录列表，不能为空

抛出:

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

参见:
- RecordingInfo
- Recording
getConfigurations

List<ConfigurationInfo> getConfigurations()

返回此Java虚拟机（JVM）的预定义配置列表。
MBeanServer访问:
ConfigurationInfo的映射类型为CompositeData，其属性如ConfigurationInfo.from方法中指定。
返回:

预定义配置列表，不能为空

抛出:

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

参见:
- ConfigurationInfo
- Configuration
getEventTypes

List<EventTypeInfo> getEventTypes()

返回当前注册的事件类型列表。
MBeanServer访问:
EventTypeInfo的映射类型为CompositeData，其属性如EventTypeInfo.from方法中指定。
返回:

注册的事件类型列表，不能为空

抛出:

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

参见:
- EventTypeInfo
- EventType
copyTo

void copyTo(long recordingId, String outputFile) throws IOException, SecurityException

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

recordingId - 要为其转储数据的记录的ID

outputFile - 写入数据的系统相关文件名，不能为空

抛出:

IOException - 如果由于I/O错误（例如，无效路径）无法转储记录

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

IllegalStateException - 如果记录尚未启动或已关闭

SecurityException - 如果存在安全管理器且其SecurityManager.checkWrite(java.lang.String)方法拒绝对命名文件的写访问或调用者没有ManagmentPermission("control")

参见:
- Path.toString()
- Recording.dump(java.nio.file.Path)

Interface FlightRecorderMXBean

记录选项

Field Summary

Method Summary

Methods declared in interface java.lang.management.PlatformManagedObject

Field Details

MXBEAN_NAME

Method Details

newRecording

takeSnapshot

cloneRecording

startRecording

stopRecording

closeRecording

openStream

closeStream

readStream

getRecordingOptions

getRecordingSettings

setConfiguration

setPredefinedConfiguration

setRecordingSettings

setRecordingOptions

getRecordings

getConfigurations

getEventTypes

copyTo