/*
 * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

This package provides classes to create events and control Flight Recorder.

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

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"




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/**
 * This package provides classes to create events and control Flight Recorder.
 * <p>
 * <b>Defining events</b>
 * <p>
 * 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.
 * <p>
 * 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 <code>jdk.jfr</code> package, or by using a user-defined
 * annotation that has the {@link jdk.jfr.MetadataDefinition} annotation.
 * <p>
 * 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 <code>begin</code> and {@code end} methods
 * available in the <code>Event</code> class.
 * <p>
 * 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 the
 * {@code Event#commit()} method is invoked. If
 * {@link Event#shouldCommit()} returns {@code false}, then those operations can be
 * avoided.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * <b>Controlling Flight Recorder</b>
 * <p>
 * Flight Recorder can be controlled locally by using the <code>jcmd</code>
 * command line tool or remotely by using the <code>FlightRecorderMXBean</code>
 * 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 a recording created by
 * using {@link jdk.jfr.Recording} class, from which the amount of data to
 * record is configured.
 * <p>
 * <b>Settings and configuration</b>
 * <p>
 * A setting consists of a name/value pair, where <em>name</em> specifies the
 * event and setting to configure, and the <em>value</em> specifies what to set
 * it to.
 * <p>
 * The name can be formed in the following ways:
 * <p>
 * {@code
 *   <event-name> + "#" + <setting-name>
 * }
 * <p>
 * or
 * <p>
 * {@code
 *   <event-id> + "#" + <setting-name>
 * }
 * <p>
 * For example, to set the sample interval of the CPU Load event to once every
 * second, use the name {@code "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.
 * <p>
 * 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()}.
 * <p>
 * <b>Predefined settings</b>
 * <table class="striped">
 * <caption>Event setting names and their purpose.</caption> <thead>
 * <tr>
 * <th scope="col">Name</th>
 * <th scope="col">Description</th>
 * <th scope="col">Default value</th>
 * <th scope="col">Format</th>
 * <th scope="col">Example values</th>
 * </tr>
 * </thead> <tbody>
 * <tr>
 * <th scope="row">{@code enabled}</th>
 * <td>Specifies whether the event is recorded</td>
 * <td>{@code "true"}</td>
 * <td>String representation of a {@code Boolean} ({@code "true"} or
 * {@code "false"})</td>
 * <td>{@code "true"}<br>
 * {@code "false"}</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code threshold}</th>
 * <td>Specifies the duration below which an event is not recorded</td>
 * <td>{@code "0"} (no limit)</td>
 * <td>{@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:
 * <ul style="list-style-type:none">
 * <li>{@code "ns"} (nanoseconds)
 * <li>{@code "us"} (microseconds)
 * <li>{@code "ms"} (milliseconds)
 * <li>{@code "s"} (seconds)
 * <li>{@code "m"} (minutes)
 * <li>{@code "h"} (hours)
 * <li>{@code "d"} (days)
 * </ul>
 * <td>{@code "0"}<br>
 * {@code "10 ms"}<br>
 * "1 s"</td>
 * </tr>
 * <tr>
 * <th scope="row">{@code period}</th>
 * <td>Specifies the interval at which the event is emitted, if it is
 * periodic</td>
 * <td>{@code "everyChunk"}</td>
 * <td>{@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:
 * <ul style="list-style-type:none">
 * <li>{@code "ns"} (nanoseconds)
 * <li>{@code "us"} (microseconds)
 * <li>{@code "ms"} (milliseconds)
 * <li>{@code "s"} (seconds)
 * <li>{@code "m"} (minutes)
 * <li>{@code "h"} (hours)
 * <li>{@code "d"} (days)
 * </ul>
 * </td>
 * <td>{@code "20 ms"}<br>
 * {@code "1 s"}<br>
 * {@code "everyChunk"}</td>
 *
 * </tr>
 * <tr>
 * <th scope="row">{@code stackTrace}</th>
 * <td>Specifies whether the stack trace from the {@code Event#commit()} method
 * is recorded</td>
 * <td>{@code "true"}</td>
 * <td>String representation of a {@code Boolean} ({@code "true"} or
 * {@code "false"})</td>
 * <td>{@code "true"},<br>
 * {@code "false"}</td>
 * </tr>
 * </tbody>
 * </table>
 * <p>
 * <b>Null-handling</b>
 * <p>
 * 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}.
 *
 * @since 9
 */
package jdk.jfr;