+ * 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"}