| /* |
| * 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. |
| * <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> |
| * <p> |
| * <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; |
