From a6175ee029d9fca6e519f1f9887e00ba6c03495c Mon Sep 17 00:00:00 2001 From: neugens Date: Mon, 16 Dec 2019 16:47:30 +0100 Subject: [PATCH] 8236002: CSR for JFR backport suggests not leaving out the package-info Reviewed-by: neugens Contributed-by: marcus.hirt@datadoghq.com --- src/share/classes/jdk/jfr/package-info.java | 196 ++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 src/share/classes/jdk/jfr/package-info.java diff --git a/src/share/classes/jdk/jfr/package-info.java b/src/share/classes/jdk/jfr/package-info.java new file mode 100644 index 000000000..29acf83c3 --- /dev/null +++ b/src/share/classes/jdk/jfr/package-info.java @@ -0,0 +1,196 @@ +/* + * Copyright (c) 2016, 2019, 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 {@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 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 the + * {@code Event#commit()} method is invoked. If + * {@link Event#shouldCommit()} returns {@code 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 a 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 "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 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Event setting names and their purpose.
NameDescriptionDefault valueFormatExample 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 "ns"} (nanoseconds) + *
  • {@code "us"} (microseconds) + *
  • {@code "ms"} (milliseconds) + *
  • {@code "s"} (seconds) + *
  • {@code "m"} (minutes) + *
  • {@code "h"} (hours) + *
  • {@code "d"} (days) + *
+ * 		{@code "0"}
+ * {@code "10 ms"}
+ * "1 s"
{@code period}Specifies 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 "ns"} (nanoseconds) + *
  • {@code "us"} (microseconds) + *
  • {@code "ms"} (milliseconds) + *
  • {@code "s"} (seconds) + *
  • {@code "m"} (minutes) + *
  • {@code "h"} (hours) + *
  • {@code "d"} (days) + *
+ * 		{@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"}
+ *

+ * 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}. + * + * @since 8 + */ +package jdk.jfr; -- GitLab