Package jdk.jfr
Defining events
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 MetadataDefinition annotation.
 
 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 begin and end methods
 available in the Event class.
 
 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
 Event.shouldCommit() returns false, then those operations can be
 avoided.
 
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 EventFactory class
 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 jcmd
 command line tool or remotely by using the FlightRecorderMXBean
 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
 using 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>
 
 
or
 
   <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
 FlightRecorder.getEventTypes() and
 EventType.getName(). A list of available settings for an
 event type is obtained by invoking
 EventType.getSettingDescriptors() and
 ValueDescriptor.getName().
 
Predefined settings
| 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 positiveLongfollowed by a space and one of the following units:
 | "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 positiveLongvalue followed by an empty space and one of the following units:
 | "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" | 
Null-handling
 All methods define whether they accept or return null in the Javadoc.
 Typically this is expressed as "not null". If a null
 parameter is used where it is not allowed, a
 java.lang.NullPointerException is thrown. If a null
 parameters is passed to a method that throws other exceptions, such as
 java.io.IOException, the java.lang.NullPointerException takes
 precedence, unless the Javadoc for the method explicitly states how
 null is handled, i.e. by throwing
 java.lang.IllegalArgumentException.
- Since:
- 9
- 
Interface Summary Interface Description FlightRecorderListener Callback interface to monitor Flight Recorder's life cycle.
- 
Class Summary Class Description AnnotationElement Describes event metadata, such as labels, descriptions and units.Configuration A collection of settings and metadata describing the configuration.Event Base class for events, to be subclassed in order to define events and their fields.EventFactory Class for defining an event at runtime.EventSettings Convenience class for applying event settings to a recording.EventType Describes an event, its fields, settings and annotations.FlightRecorder Class for accessing, controlling, and managing Flight Recorder.FlightRecorderPermission Permission for controlling access to Flight Recorder.Recording Provides means to configure, start, stop and dump recording data to disk.SettingControl Base class to extend to create setting controls.SettingDescriptor Describes an event setting.ValueDescriptor Describes the event fields and annotation elements.
- 
Enum Summary Enum Description RecordingState Indicates a state in the life cycle of a recording.
- 
Annotation Types Summary Annotation Type Description BooleanFlag Event field annotation, specifies that the value is a boolean flag, atrueorfalsevalueCategory Event annotation, to associate the event type with a category, in the format of a human-readable path.ContentType Meta annotation, specifies that an annotation represents a content type, such as a time span or a frequency.DataAmount Event field annotation, specifies that a value represents an amount of data (for example, bytes).Description Annotation that describes an element by using a sentence or two.Enabled Event annotation, determines if an event should be enabled by default.Experimental Annotation that specifies that an element is experimental and may change without notice.Frequency Event field annotation, specifies that the value is a frequency, measured in Hz.Label Annotation that sets a human-readable name for an element (for example,"Maximum Throughput").MemoryAddress Event field annotation, specifies that the value is a memory address.MetadataDefinition Meta annotation for defining new types of event metadata.Name Annotation that overrides the default name for an element (for example, when the default package for an event is not appropriate).Percentage Event field annotation to use on fractions, typically between0.0and1.0, to specify that the value is a percentage.Period Event annotation, specifies the default setting value for a periodic event.Registered Event annotation, for programmatic event registration.Relational Meta annotation for relational annotations, to be used on an annotation.SettingDefinition Annotation that specifies that a method in an event class should be used to filter out events.StackTrace Event annotation, determines whether an event by default has a stack trace or not.Threshold Event annotation, specifies the default duration below which an event is not recorded (for example,"20 ms").Timespan Event field annotation, specifies that the value is a duration.Timestamp Event field annotation, specifies that the value is a point in time.TransitionFrom Event field annotation, specifies that the event transitioned from a thread.TransitionTo Event field annotation, specifies that the event will soon transition to a thread.Unsigned Event field annotation, specifies that the value is of an unsigned data type.