Package jdk.jfr

该软件包提供了用于创建事件和控制Flight Recorder的类。

定义事件

Flight Recorder将数据收集为事件。 事件具有时间戳，持续时间以及通常是特定于应用程序的有效负载，可用于诊断运行的应用程序直至故障或崩溃。

要定义Flight Recorder事件，请扩展Event并添加与有效内容的数据类型匹配的字段。 可以使用jdk.jfr包中提供的注释或使用具有MetadataDefinition注释的用户定义注释来添加有关字段（例如标签，描述和单位）的元数据。

定义事件类后，可以创建实例（事件对象）。 通过将数据分配给字段来将数据存储在事件中。 可以使用Event类中提供的begin和end方法显式控制事件计时。

收集要存储在事件中的数据可能很昂贵。 Event.shouldCommit()方法可用于验证在调用Event#commit()方法时是否实际将事件实例写入系统。 如果Event.shouldCommit()返回false ，则可以避免这些操作。

有时，在编译时不知道事件的字段布局。 在这种情况下，可以动态定义事件。 但是，动态事件可能与静态定义的事件没有相同的性能级别，并且工具可能无法在不知道布局的情况下识别和可视化数据。

动态地定义的事件时，使用EventFactory类，并通过使用定义字段ValueDescriptor类，并通过使用定义注解AnnotationElement类。 使用工厂分配事件，使用Event.set(int, Object)方法填充它。

控制飞行记录器

可以使用jcmd命令行工具在本地控制Flight Recorder，也可以使用在平台MBeanServer中注册的FlightRecorderMXBean接口远程控制。 当需要直接编程访问时，可以通过调用FlightRecorder.getFlightRecorder()和使用Recording类创建的记录来获取Flight Recorder实例，从中配置要记录的数据量。

设置和配置

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

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

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

要么

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

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

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

预定义的设置

Event setting names and their purpose. Name Description Default value Format Example values enabled Specifies whether the event is recorded "true" String representation of a Boolean ("true" or "false") "true"
"false" threshold Specifies the duration below which an event is not recorded "0" (no limit) "0" if no threshold is used, otherwise a string representation of a positive Long followed by a space and one of the following units:

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

"0"
"10 ms"
"1 s" period Specifies the interval at which the event is emitted, if it is periodic "everyChunk" "everyChunk", if a periodic event should be emitted with every file rotation, 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)

"20 ms"
"1 s"
"everyChunk" stackTrace Specifies whether the stack trace from the Event#commit() method is recorded "true" String representation of a Boolean ("true" or "false") "true",
"false"

空操作

所有方法都定义它们是否接受或返回Javadoc中的null 。 通常，这表示为"not null" 。 如果在null情况下使用null参数，则抛出java.lang.NullPointerException 。 如果将null参数传递给抛出其他异常的方法（例如java.io.IOException ，则java.lang.NullPointerException优先，除非该方法的Javadoc明确说明null的处理方式，即抛出java.lang.IllegalArgumentException 。