Flight Recorder collects data as events. An event has a time stamp, duration and usually an application-specific payload, useful for diagnosing the running application up to the failure or crash.
To define a Flight Recorder event, extend
Event and add
fields that matches the data types of the payload. Metadata about fields,
such as labels, descriptions and units, can be added by using the annotations
available in the
jdk.jfr package, or by using a user-defined
annotation that has the
After an event class is defined, instances can be created (event objects).
Data is stored in the event by assigning data to fields. Event timing can be
explicitly controlled by using the
available in the
Gathering data to store in an event can be expensive. The
Event.shouldCommit() method can be used to verify whether an event
instance would actually be written to the system when the
Event#commit() method is invoked. If
false, then those operations can be
Sometimes the field layout of an event is not known at compile time. In that case, an event can be dynamically defined. However, dynamic events might not have the same level of performance as statically defined ones and tools might not be able to identify and visualize the data without knowing the layout.
To dynamically define an event, use the
and define fields by using the
ValueDescriptor class, and
define annotations by using the
AnnotationElement class. Use
the factory to allocate an event and the
Event.set(int, Object) method to populate it.
Controlling Flight Recorder
Flight Recorder can be controlled locally by using the
command line tool or remotely by using the
interface, registered in the platform MBeanServer. When direct programmatic
access is needed, a Flight Recorder instance can be obtained by invoking
FlightRecorder.getFlightRecorder() and a recording created by
Recording class, from which the amount of data to
record is configured.
Settings and configuration
A setting consists of a name/value pair, where name specifies the event and setting to configure, and the value specifies what to set it to.
The name can be formed in the following ways:
<event-name> + "#" + <setting-name>
<event-id> + "#" + <setting-name>
For example, to set the sample interval of the CPU Load event to once every
second, use the name
"jdk.CPULoad#period" and the value
"1 s". If multiple events use the same name, for example if an event
class is loaded in multiple class loaders, and differentiation is needed
between them, then the name is
"56#period". The ID for an event is
obtained by invoking
EventType.getId() method and is valid
for the Java Virtual Machine instance that the event is registered in.
A list of available event names is retrieved by invoking
EventType.getName(). A list of available settings for an
event type is obtained by invoking
|Name||Description||Default value||Format||Example values|
||Specifies whether the event is recorded||
||String representation of a
||Specifies the duration below which an event is not recorded||
||Specifies the interval at which the event is emitted, if it is periodic||
||Specifies whether the stack trace from the
||String representation of a
All methods define whether they accept or return
null in the Javadoc.
Typically this is expressed as
"not null". If a
parameter is used where it is not allowed, a
java.lang.NullPointerException is thrown. If a
parameters is passed to a method that throws other exceptions, such as
precedence, unless the Javadoc for the method explicitly states how
null is handled, i.e. by throwing
Interface Summary Interface Description FlightRecorderListenerCallback interface to monitor Flight Recorder's life cycle.
Class Summary Class Description AnnotationElementDescribes event metadata, such as labels, descriptions and units. ConfigurationA collection of settings and metadata describing the configuration. EventBase class for events, to be subclassed in order to define events and their fields. EventFactoryClass for defining an event at runtime. EventSettingsConvenience class for applying event settings to a recording. EventTypeDescribes an event, its fields, settings and annotations. FlightRecorderClass for accessing, controlling, and managing Flight Recorder. FlightRecorderPermissionPermission for controlling access to Flight Recorder. RecordingProvides means to configure, start, stop and dump recording data to disk. SettingControlBase class to extend to create setting controls. SettingDescriptorDescribes an event setting. ValueDescriptorDescribes the event fields and annotation elements.
Enum Summary Enum Description RecordingStateIndicates a state in the life cycle of a recording.
Annotation Types Summary Annotation Type Description BooleanFlagEvent field annotation, specifies that the value is a boolean flag, a
CategoryEvent annotation, to associate the event type with a category, in the format of a human-readable path. ContentTypeMeta annotation, specifies that an annotation represents a content type, such as a time span or a frequency. DataAmountEvent field annotation, specifies that a value represents an amount of data (for example, bytes). DescriptionAnnotation that describes an element by using a sentence or two. EnabledEvent annotation, determines if an event should be enabled by default. ExperimentalAnnotation that specifies that an element is experimental and may change without notice. FrequencyEvent field annotation, specifies that the value is a frequency, measured in Hz. LabelAnnotation that sets a human-readable name for an element (for example,
MemoryAddressEvent field annotation, specifies that the value is a memory address. MetadataDefinitionMeta annotation for defining new types of event metadata. NameAnnotation that overrides the default name for an element (for example, when the default package for an event is not appropriate). PercentageEvent field annotation to use on fractions, typically between
1.0, to specify that the value is a percentage.
PeriodEvent annotation, specifies the default setting value for a periodic event. RegisteredEvent annotation, for programmatic event registration. RelationalMeta annotation for relational annotations, to be used on an annotation. SettingDefinitionAnnotation that specifies that a method in an event class should be used to filter out events. StackTraceEvent annotation, determines whether an event by default has a stack trace or not. ThresholdEvent annotation, specifies the default duration below which an event is not recorded (for example,
TimespanEvent field annotation, specifies that the value is a duration. TimestampEvent field annotation, specifies that the value is a point in time. TransitionFromEvent field annotation, specifies that the event transitioned from a thread. TransitionToEvent field annotation, specifies that the event will soon transition to a thread. UnsignedEvent field annotation, specifies that the value is of an unsigned data type.