* 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 {@link jdk.jfr.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.annotation package, or by using a
* user-defined annotation that has the {@link jdk.jfr.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 {@code end} methods
* available in the Event class.
*
* Gathering data to store in an event can be expensive. The * {@link Event#shouldCommit()} method can be used to verify whether an event * instance would actually be written to the system when commit is invoked. If * {@link 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 {@link jdk.jfr.EventFactory} class * and define fields by using the {@link jdk.jfr.ValueDescriptor} class, and * define annotations by using the {@link jdk.jfr.AnnotationElement} class. Use * the factory to allocate an event and the * {@link jdk.jfr.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
* {@link jdk.jfr.FlightRecorder#getFlightRecorder()} and recording created by
* using {@link jdk.jfr.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: *
* {@code
*
* or
*
* {@code
*
* For example, to set the sample interval of the CPU Load event to once every
* second, use the name {@code "com.oracle.jdk.CPULoad#period"} and the value
* {@code "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 {@code "56#period"}. The id for an event is
* obtained by invoking {@link jdk.jfr.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
* {@link jdk.jfr.FlightRecorder#getEventTypes()} and
* {@link jdk.jfr.EventType#getName()}. A list of available settings for an
* event type is obtained by invoking
* {@link jdk.jfr.EventType#getSettingDescriptors()} and
* {@link jdk.jfr.ValueDescriptor#getName()}.
*
* Predefined settings
*
*
* Null-handling
*
* All methods define whether they accept or return {@code null} in the Javadoc.
* Typically this is expressed as {@code "not null"}. If a {@code null}
* parameter is used where it is not allowed, a
* {@code java.lang.NullPointerException} is thrown. If a {@code null}
* parameters is passed to a method that throws other exceptions, such as
* {@code java.io.IOException}, the {@code java.lang.NullPointerException} takes
* precedence, unless the Javadoc for the method explicitly states how
* {@code null} is handled, i.e. by throwing
* {@code java.lang.IllegalArgumentException}.
*
* @commercialFeature
* @since 9
*/
package jdk.jfr;
*
*
*
*
* Name
* Description
* Default value
* Format
* Example values
*
*
* {@code enabled}
* Specifies whether the event is recorded
* {@code "true"}
* String representation of a {@code Boolean} ({@code "true"} or
* {@code "false"})
* {@code "true"}
*
* {@code "false"}
*
* {@code threshold}
* Specifies the duration below which an event is not recorded
* {@code "0"} (no limit)
* {@code "0"} if no threshold is used, otherwise a string representation of
* a positive {@code Long} followed by a space and one of the following units:
*
*
* {@code "0"}
*
* {@code "10 ms"}
* "1 s"
*
* {@code period}
* ISpecifies the interval at which the event is emitted, if it is
* periodic
* {@code "everyChunk"}
* {@code "everyChunk"}, if a periodic event should be emitted with every
* file rotation, otherwise a string representation of a positive {@code Long}
* value followed by an empty space and one of the following units:
*
*
*
* {@code "20 ms"}
*
*
* {@code "1 s"}
* {@code "everyChunk"}
*
*
* {@code stackTrace}
* Specifies whether the stack trace from the {@code Event#commit()} method
* is recorded
* {@code "true"}
* String representation of a {@code Boolean} ({@code "true"} or
* {@code "false"})
* {@code "true"},
*
* {@code "false"}