1 /* 2 * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * This package provides classes to create events and control Flight Recorder. 28 * <p> 29 * <b>Defining events</b> 30 * <p> 31 * Flight Recorder collects data as events. An event has a time stamp, duration 32 * and usually an application-specific payload, useful for diagnosing the 33 * running application up to the failure or crash. 34 * <p> 35 * To define a Flight Recorder event, extend {@link jdk.jfr.Event} and add 36 * fields that matches the data types of the payload. Metadata about fields, 37 * such as labels, descriptions and units, can be added by using the annotations 38 * available in the <code>jdk.jfr</code> package, or by using a user-defined 39 * annotation that has the {@link jdk.jfr.MetadataDefinition} annotation. 40 * <p> 41 * After an event class is defined, instances can be created (event objects). 42 * Data is stored in the event by assigning data to fields. Event timing can be 43 * explicitly controlled by using the <code>begin</code> and {@code end} methods 44 * available in the <code>Event</code> class. 45 * <p> 46 * Gathering data to store in an event can be expensive. The 47 * {@link Event#shouldCommit()} method can be used to verify whether an event 48 * instance would actually be written to the system when the 49 * {@code Event#commit()} method is invoked. If 50 * {@link Event#shouldCommit()} returns {@code false}, then those operations can be 51 * avoided. 52 * <p> 53 * Sometimes the field layout of an event is not known at compile time. In that 54 * case, an event can be dynamically defined. However, dynamic events might not 55 * have the same level of performance as statically defined ones and tools might 56 * not be able to identify and visualize the data without knowing the layout. 57 * <p> 58 * To dynamically define an event, use the {@link jdk.jfr.EventFactory} class 59 * and define fields by using the {@link jdk.jfr.ValueDescriptor} class, and 60 * define annotations by using the {@link jdk.jfr.AnnotationElement} class. Use 61 * the factory to allocate an event and the 62 * {@link jdk.jfr.Event#set(int, Object)} method to populate it. 63 * <p> 64 * <b>Controlling Flight Recorder</b> 65 * <p> 66 * Flight Recorder can be controlled locally by using the <code>jcmd</code> 67 * command line tool or remotely by using the <code>FlightRecorderMXBean</code> 68 * interface, registered in the platform MBeanServer. When direct programmatic 69 * access is needed, a Flight Recorder instance can be obtained by invoking 70 * {@link jdk.jfr.FlightRecorder#getFlightRecorder()} and a recording created by 71 * using {@link jdk.jfr.Recording} class, from which the amount of data to 72 * record is configured. 73 * <p> 74 * <b>Settings and configuration</b> 75 * <p> 76 * A setting consists of a name/value pair, where <em>name</em> specifies the 77 * event and setting to configure, and the <em>value</em> specifies what to set 78 * it to. 79 * <p> 80 * The name can be formed in the following ways: 81 * <p> 82 * {@code 83 * <event-name> + "#" + <setting-name> 84 * } 85 * <p> 86 * or 87 * <p> 88 * {@code 89 * <event-id> + "#" + <setting-name> 90 * } 91 * <p> 92 * For example, to set the sample interval of the CPU Load event to once every 93 * second, use the name {@code "jdk.CPULoad#period"} and the value 94 * {@code "1 s"}. If multiple events use the same name, for example if an event 95 * class is loaded in multiple class loaders, and differentiation is needed 96 * between them, then the name is {@code "56#period"}. The ID for an event is 97 * obtained by invoking {@link jdk.jfr.EventType#getId()} method and is valid 98 * for the Java Virtual Machine instance that the event is registered in. 99 * <p> 100 * A list of available event names is retrieved by invoking 101 * {@link jdk.jfr.FlightRecorder#getEventTypes()} and 102 * {@link jdk.jfr.EventType#getName()}. A list of available settings for an 103 * event type is obtained by invoking 104 * {@link jdk.jfr.EventType#getSettingDescriptors()} and 105 * {@link jdk.jfr.ValueDescriptor#getName()}. 106 * <p> 107 * <b>Predefined settings</b> 108 * <table class="striped"> 109 * <caption>Event setting names and their purpose.</caption> <thead> 110 * <tr> 111 * <th scope="col">Name</th> 112 * <th scope="col">Description</th> 113 * <th scope="col">Default value</th> 114 * <th scope="col">Format</th> 115 * <th scope="col">Example values</th> 116 * </tr> 117 * </thead> <tbody> 118 * <tr> 119 * <th scope="row">{@code enabled}</th> 120 * <td>Specifies whether the event is recorded</td> 121 * <td>{@code "true"}</td> 122 * <td>String representation of a {@code Boolean} ({@code "true"} or 123 * {@code "false"})</td> 124 * <td>{@code "true"}<br> 125 * {@code "false"}</td> 126 * </tr> 127 * <tr> 128 * <th scope="row">{@code threshold}</th> 129 * <td>Specifies the duration below which an event is not recorded</td> 130 * <td>{@code "0"} (no limit)</td> 131 * <td>{@code "0"} if no threshold is used, otherwise a string representation of 132 * a positive {@code Long} followed by a space and one of the following units: 133 * <ul style="list-style-type:none"> 134 * <li>{@code "ns"} (nanoseconds) 135 * <li>{@code "us"} (microseconds) 136 * <li>{@code "ms"} (milliseconds) 137 * <li>{@code "s"} (seconds) 138 * <li>{@code "m"} (minutes) 139 * <li>{@code "h"} (hours) 140 * <li>{@code "d"} (days) 141 * </ul> 142 * <td>{@code "0"}<br> 143 * {@code "10 ms"}<br> 144 * "1 s"</td> 145 * </tr> 146 * <tr> 147 * <th scope="row">{@code period}</th> 148 * <td>Specifies the interval at which the event is emitted, if it is 149 * periodic</td> 150 * <td>{@code "everyChunk"}</td> 151 * <td>{@code "everyChunk"}, if a periodic event should be emitted with every 152 * file rotation, otherwise a string representation of a positive {@code Long} 153 * value followed by an empty space and one of the following units: 154 * <ul style="list-style-type:none"> 155 * <li>{@code "ns"} (nanoseconds) 156 * <li>{@code "us"} (microseconds) 157 * <li>{@code "ms"} (milliseconds) 158 * <li>{@code "s"} (seconds) 159 * <li>{@code "m"} (minutes) 160 * <li>{@code "h"} (hours) 161 * <li>{@code "d"} (days) 162 * </ul> 163 * </td> 164 * <td>{@code "20 ms"}<br> 165 * {@code "1 s"}<br> 166 * {@code "everyChunk"}</td> 167 * 168 * </tr> 169 * <tr> 170 * <th scope="row">{@code stackTrace}</th> 171 * <td>Specifies whether the stack trace from the {@code Event#commit()} method 172 * is recorded</td> 173 * <td>{@code "true"}</td> 174 * <td>String representation of a {@code Boolean} ({@code "true"} or 175 * {@code "false"})</td> 176 * <td>{@code "true"},<br> 177 * {@code "false"}</td> 178 * </tr> 179 * </tbody> 180 * </table> 181 * <p> 182 * <b>Null-handling</b> 183 * <p> 184 * All methods define whether they accept or return {@code null} in the Javadoc. 185 * Typically this is expressed as {@code "not null"}. If a {@code null} 186 * parameter is used where it is not allowed, a 187 * {@code java.lang.NullPointerException} is thrown. If a {@code null} 188 * parameters is passed to a method that throws other exceptions, such as 189 * {@code java.io.IOException}, the {@code java.lang.NullPointerException} takes 190 * precedence, unless the Javadoc for the method explicitly states how 191 * {@code null} is handled, i.e. by throwing 192 * {@code java.lang.IllegalArgumentException}. 193 * 194 * @since 9 195 */ 196 package jdk.jfr; 197