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.annotation</code> package, or by using a
39 * user-defined annotation that has the {@link jdk.jfr.MetadataDefinition}
40 * annotation).
41 * <p>
42 * After an event class is defined, instances can be created (event objects).
43 * Data is stored in the event by assigning data to fields. Event timing can be
44 * explicitly controlled by using the <code>begin</code> and {@code end} methods
45 * available in the <code>Event</code> class.
46 * <p>
47 * Gathering data to store in an event can be expensive. The
48 * {@link Event#shouldCommit()} method can be used to verify whether an event
49 * instance would actually be written to the system when commit is invoked. If
50 * {@link Event#shouldCommit()} returns 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 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 "com.oracle.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 * <p>
109 * <table class="striped">
110 * <caption>Event setting names and their purpose.</caption> <thead>
111 * <tr>
112 * <th scope="col">Name</th>
113 * <th scope="col">Description</th>
114 * <th scope="col">Default value</th>
115 * <th scope="col">Format</th>
116 * <th scope="col">Example values</th>
117 * </tr>
118 * </thead> <tbody>
119 * <tr>
120 * <th scope="row">{@code enabled}</th>
121 * <td>Specifies whether the event is recorded</td>
122 * <td>{@code "true"}</td>
123 * <td>String representation of a {@code Boolean} ({@code "true"} or
124 * {@code "false"})</td>
125 * <td>{@code "true"}<br>
126 * {@code "false"}</td>
127 * </tr>
128 * <tr>
129 * <th scope="row">{@code threshold}</th>
130 * <td>Specifies the duration below which an event is not recorded</td>
131 * <td>{@code "0"} (no limit)</td>
132 * <td>{@code "0"} if no threshold is used, otherwise a string representation of
133 * a positive {@code Long} followed by a space and one of the following units:
134 * <ul style="list-style-type:none">
135 * <li>{@code "ns"} (nanoseconds)
136 * <li>{@code "us"} (microseconds)
137 * <li>{@code "ms"} (milliseconds)
138 * <li>{@code "s"} (seconds)
139 * <li>{@code "m"} (minutes)
140 * <li>{@code "h"} (hours)
141 * <li>{@code "d"} (days)
142 * </ul>
143 * <td>{@code "0"}<br>
144 * {@code "10 ms"}<br>
145 * "1 s"</td>
146 * </tr>
147 * <tr>
148 * <th scope="row">{@code period}</th>
149 * <td>ISpecifies the interval at which the event is emitted, if it is
150 * periodic</td>
151 * <td>{@code "everyChunk"}</td>
152 * <td>{@code "everyChunk"}, if a periodic event should be emitted with every
153 * file rotation, otherwise a string representation of a positive {@code Long}
154 * value followed by an empty space and one of the following units:
155 * <ul style="list-style-type:none">
156 * <li>{@code "ns"} (nanoseconds)
157 * <li>{@code "us"} (microseconds)
158 * <li>{@code "ms"} (milliseconds)
159 * <li>{@code "s"} (seconds)
160 * <li>{@code "m"} (minutes)
161 * <li>{@code "h"} (hours)
162 * <li>{@code "d"} (days)
163 * </ul>
164 * </td>
165 * <td>{@code "20 ms"}<br>
166 * {@code "1 s"}<br>
167 * {@code "everyChunk"}</td>
168 *
169 * </tr>
170 * <tr>
171 * <th scope="row">{@code stackTrace}</th>
172 * <td>Specifies whether the stack trace from the {@code Event#commit()} method
173 * is recorded</td>
174 * <td>{@code "true"}</td>
175 * <td>String representation of a {@code Boolean} ({@code "true"} or
176 * {@code "false"})</td>
177 * <td>{@code "true"},<br>
178 * {@code "false"}</td>
179 * </tr>
180 * </tbody>
181 * </table>
182 * <p>
183 * <b>Null-handling</b>
184 * <p>
185 * All methods define whether they accept or return {@code null} in the Javadoc.
186 * Typically this is expressed as {@code "not null"}. If a {@code null}
187 * parameter is used where it is not allowed, a
188 * {@code java.lang.NullPointerException} is thrown. If a {@code null}
189 * parameters is passed to a method that throws other exceptions, such as
190 * {@code java.io.IOException}, the {@code java.lang.NullPointerException} takes
191 * precedence, unless the Javadoc for the method explicitly states how
192 * {@code null} is handled, i.e. by throwing
193 * {@code java.lang.IllegalArgumentException}.
194 *
195 * @commercialFeature
196 * @since 9
197 */
198 package jdk.jfr;