1 /*
2 * Copyright (c) 2016, 2019, 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 package jdk.management.jfr;
27
28 import java.io.IOException;
29 import java.lang.management.PlatformManagedObject;
30 import java.time.Instant;
31 import java.util.List;
32 import java.util.Map;
33
34 import jdk.jfr.Configuration;
35 import jdk.jfr.EventType;
36 import jdk.jfr.Recording;
37
38 /**
39 * Management interface for controlling Flight Recorder.
40 * <p>
41 * The object name for identifying the MXBean in the platform MBean
42 * server is: <blockquote> {@code jdk.management.jfr:type=FlightRecorder} </blockquote>
43 * <p>
44 * Flight Recorder can be configured in the following ways:
45 * <ul>
46 * <li><b>Recording options</b><br>
47 * Specify how long a recording should last, and where and when data
48 * should be dumped.</li>
49 * <li><b>Settings</b><br>
50 * Specify which events should be enabled and what kind information each
51 * event should capture.</li>
52 * <li><b>Configurations</b><br>
53 * Predefined sets of settings, typically derived from a settings file,
54 * that specify the configuration of multiple events simultaneously.</li>
55 * </ul>
56 * <p>
57 * See the package {@code jdk.jfr} documentation for descriptions of the settings
58 * syntax and the {@link ConfigurationInfo} class documentation for configuration information.
59 *
60 * <h3>Recording options</h3>
61 * <p>
62 * The following table shows the options names to use with {@link #setRecordingOptions(long, Map)}
63 * and {@link #getRecordingOptions(long)}.
64 *
65 * <table class="striped">
66 * <caption>Recording options</caption>
67 * <thead>
68 * <tr>
69 * <th scope="col">Name</th>
70 * <th scope="col">Descripion</th>
71 * <th scope="col">Default value</th>
72 * <th scope="col">Format</th>
73 * <th scope="col">Example values</th>
74 * </tr>
75 * </thead>
76 * <tbody>
77 * <tr>
78 * <th scope="row">{@code name}</th>
79 * <td>Sets a human-readable recording name</td>
80 * <td>String representation of the recording id</td>
81 * <td>{@code String}</td>
82 * <td>{@code "My Recording"}, <br>
83 * {@code "profiling"}</td>
84 * </tr>
85 * <tr>
86 * <th scope="row">{@code maxAge}</th>
87 * <td>Specify the length of time that the data is kept in the disk repository until the
88 * oldest data may be deleted. Only works if {@code disk=true}, otherwise
89 * this parameter is ignored.</td>
90 * <td>{@code "0"} (no limit)</td>
91 * <td>{@code "0"} if no limit is imposed, otherwise a string
92 * representation of a positive {@code Long} value followed by an empty space
93 * and one of the following units,<br>
94 * <br>
95 * {@code "ns"} (nanoseconds)<br>
96 * {@code "us"} (microseconds)<br>
97 * {@code "ms"} (milliseconds)<br>
98 * {@code "s"} (seconds)<br>
99 * {@code "m"} (minutes)<br>
100 * {@code "h"} (hours)<br>
101 * {@code "d"} (days)<br>
102 * </td>
103 * <td>{@code "2 h"},<br>
104 * {@code "24 h"},<br>
105 * {@code "2 d"},<br>
106 * {@code "0"}</td>
107 * </tr>
108 * <tr>
109 * <th scope="row">{@code maxSize}</th>
110 * <td>Specifies the size, measured in bytes, at which data is kept in disk
111 * repository. Only works if
112 * {@code disk=true}, otherwise this parameter is ignored.</td>
113 * <td>{@code "0"} (no limit)</td>
114 * <td>String representation of a {@code Long} value, must be positive</td>
115 * <td>{@code "0"}, <br>
116 * {@code "1000000000"}</td>
117 * </tr>
118 * <tr>
119 * <th scope="row">{@code dumpOnExit}</th>
120 * <td>Dumps recording data to disk on Java Virtual Machine (JVM) exit</td>
121 * <td>{@code "false"}</td>
122 * <td>String representation of a {@code Boolean} value, {@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 destination}</th>
129 * <td>Specifies the path where recording data is written when the recording stops.</td>
130 * <td>{@code "false"}</td>
131 * <td>See {@code Paths#getPath} for format. <br>
132 * If this method is invoked from another process, the data is written on the
133 * machine where the target JVM is running. If destination is a relative path, it
134 * is relative to the working directory where the target JVM was started.}</td>
135 * <td>{@code "c:\recording\recotding.jfr"},<br>
136 * {@code "/recordings/recording.jfr"}, {@code "recording.jfr"}</td>
137 * </tr>
138 * <tr>
139 * <th scope="row">{@code disk}</th>
140 * <td>Stores recorded data as it is recorded</td>
141 * <td><code>"false"</code></td>
142 * <td>String representation of a {@code Boolean} value, {@code "true"} or
143 * {@code "false"}</td>
144 * <td>{@code "true"},<br>
145 * {@code "false"}</td>
146 * <tr>
147 * <th scope="row">{@code duration}</th>
148 * <td>Sets how long the recording should be running</td>
149 * <td>{@code "0"} (no limit, continuous)</td>
150 * <td>{@code "0"} if no limit should be imposed, otherwise a string
151 * representation of a positive {@code Long} followed by an empty space and one
152 * of the following units:<br>
153 * <br>
154 * {@code "ns"} (nanoseconds)<br>
155 * {@code "us"} (microseconds)<br>
156 * {@code "ms"} (milliseconds)<br>
157 * {@code "s"} (seconds)<br>
158 * {@code "m"} (minutes)<br>
159 * {@code "h"} (hours)<br>
160 * {@code "d"} (days)<br>
161 * </td>
162 * <td>{@code "60 s"},<br>
163 * {@code "10 m"},<br>
164 * {@code "4 h"},<br>
165 * {@code "0"}</td>
166 * </tr>
167 * </tbody>
168 * </table>
169 *
170 * @since 8
171 */
172 public interface FlightRecorderMXBean extends PlatformManagedObject {
173 /**
174 * String representation of the {@code ObjectName} for the
175 * {@code FlightRecorderMXBean}.
176 */
177 public static final String MXBEAN_NAME = "jdk.management.jfr:type=FlightRecorder";
178
179 /**
180 * Creates a recording, but doesn't start it.
181 *
182 * @return a unique ID that can be used to start, stop, close and
183 * configure the recording
184 *
185 * @throws IllegalStateException if Flight Recorder can't be created (for
186 * example, if the Java Virtual Machine (JVM) lacks Flight Recorder
187 * support, or if the file repository can't be created or accessed)
188 *
189 * @throws java.lang.SecurityException if a security manager exists and the
190 * caller does not have {@code ManagementPermission("control")}
191 *
192 * @see Recording
193 */
194 long newRecording() throws IllegalStateException, SecurityException;
195
196 /**
197 * Creates a snapshot recording of all available recorded data.
198 * <p>
199 * A snapshot is a synthesized recording in a stopped state. If no data is
200 * available, a recording with size {@code 0} is returned.
201 * <p>
202 * A snapshot provides stable access to data for later operations (for example,
203 * operations to change the time interval or to reduce the data size).
204 * <p>
205 * The caller must close the recording when access to the data is no longer
206 * needed.
207 *
208 * @return a snapshot of all available recording data, not {@code null}
209 *
210 * @throws java.lang.SecurityException if a security manager exists and the
211 * caller does not have {@code ManagementPermission("control")}
212 *
213 * @return a unique ID that can be used for reading recording data.
214 *
215 * @see Recording
216 */
217 public long takeSnapshot();
218
219 /**
220 * Creates a copy of an existing recording, useful for extracting parts of a
221 * recording.
222 * <p>
223 * The cloned recording contains the same recording data as the
224 * original, but it has a new ID and a name prefixed with
225 * {@code "Clone of recording"}. If the original recording is running, then
226 * the clone is also running.
227 *
228 * @param recordingId the recording ID of the recording to create a clone
229 * from
230 *
231 * @param stop if the newly created clone is stopped before
232 * returning.
233 *
234 * @return a unique ID that can be used to start, stop,
235 * close and configure the recording
236 *
237 * @throws IllegalArgumentException if a recording with the specified ID
238 * doesn't exist
239 *
240 * @throws java.lang.SecurityException if a security manager exists and the
241 * caller does not have {@code ManagementPermission("control")}
242 *
243 * @see Recording
244 */
245 long cloneRecording(long recordingId, boolean stop) throws IllegalArgumentException, SecurityException;
246
247 /**
248 * Starts the recording with the specified ID.
249 * <p>
250 * A recording that is stopped can't be restarted.
251 *
252 * @param recordingId ID of the recording to start
253 *
254 * @throws IllegalArgumentException if a recording with the specified ID
255 * doesn't exist
256 *
257 * @throws java.lang.SecurityException if a security manager exists and the
258 * caller does not have {@code ManagementPermission("control")}
259 *
260 * @see Recording
261 */
262 void startRecording(long recordingId) throws IllegalStateException, SecurityException;
263
264 /**
265 * Stops the running recording with the specified ID.
266 *
267 * @param recordingId the ID of the recording to stop
268 *
269 * @return {@code true} if the recording is stopped, {@code false}
270 * otherwise
271 *
272 * @throws IllegalArgumentException if a recording with the specified ID
273 * doesn't exist
274 * @throws IllegalStateException if the recording is not running
275 * @throws java.lang.SecurityException if a security manager exists and the
276 * caller does not have {@code ManagementPermission("control")}
277 *
278 * @see #newRecording()
279 */
280 boolean stopRecording(long recordingId) throws IllegalArgumentException, IllegalStateException, SecurityException;
281
282 /**
283 * Closes the recording with the specified ID and releases any system
284 * resources that are associated with the recording.
285 * <p>
286 * If the recording is already closed, invoking this method has no effect.
287 *
288 * @param recordingId the ID of the recording to close
289 *
290 * @throws IllegalArgumentException if a recording with the specified ID
291 * doesn't exist
292 * @throws IOException if an I/O error occurs
293 * @throws java.lang.SecurityException if a security manager exists and the
294 * caller does not have {@code ManagementPermission("control")}
295 *
296 * @see #newRecording()
297 */
298 void closeRecording(long recordingId) throws IOException;
299
300 /**
301 * Opens a data stream for the recording with the specified ID, or {@code 0}
302 * to get data irrespective of recording.
303 * <table class="striped">
304 * <caption>Recording stream options</caption>
305 * <thead>
306 * <tr>
307 * <th scope="col">Name</th>
308 * <th scope="col">Descripion</th>
309 * <th scope="col">Default value</th>
310 * <th scope="col">Format</th>
311 * <th scope="col">Example values</th>
312 * </tr>
313 * </thead>
314 * <tbody>
315 * <tr>
316 * <th scope="row">{@code startTime}</th>
317 * <td>Specifies the point in time to start a recording stream. Due to
318 * how data is stored, some events that start or end prior to the
319 * start time may be included.</td>
320 * <td>{@code Instant.MIN_VALUE.toString()}</td>
321 * <td>ISO-8601. See {@link Instant#toString}<br>
322 * or milliseconds since epoch</td>
323 * <td>{@code "2015-11-03T00:00"},<br>
324 * {@code "1446508800000"}</td>
325 * </tr>
326 * <tr>
327 * <th scope="row">{@code endTime}</th>
328 * <td>Specifies the point in time to end a recording stream. Due to how
329 * data is stored, some events that start or end after the end time may
330 * be included.</td>
331 * <td>{@code Instant.MAX_VALUE.toString()}</td>
332 * <td>ISO-8601. See {@link Instant#toString} <br>
333 * or milliseconds since epoch</td>
334 * <td>{@code "2015-11-03T01:00"}, <br>
335 * {@code "1446512400000"}</td>
336 * </tr>
337 *
338 * <tr>
339 * <th scope="row">{@code blockSize}</th>
340 * <td>Specifies the maximum number of bytes to read with a call to {@code readStream}
341 * </td>
342 * <td>{@code "50000"}</td>
343 * <td>A positive {@code long} value. <br>
344 * <br>
345 * Setting {@code blockSize} to a very high value may result in
346 * {@link OutOfMemoryError} or an {@link IllegalArgumentException}, if the
347 * Java Virtual Machine (JVM) deems the value too large to handle.</td>
348 * <td>{@code "50000"},<br>
349 * {@code "1000000"},<br>
350 * </tr>
351 * </tbody>
352 * </table>
353 * If an option is omitted from the map the default value is used.
354 * <p>
355 * The recording with the specified ID must be stopped before a stream can
356 * be opened. This restriction might be lifted in future releases.
357 *
358 * @param recordingId ID of the recording to open the stream for
359 *
360 * @param streamOptions a map that contains the options that controls the amount of data
361 * and how it is read, or {@code null} to get all data for the
362 * recording with the default block size
363 *
364 * @return a unique ID for the stream.
365 *
366 * @throws IllegalArgumentException if a recording with the iD doesn't
367 * exist, or if {@code options} contains invalid values
368 *
369 * @throws IOException if the recording is closed, an I/O error occurs, or
370 * no data is available for the specified recording or
371 * interval
372 *
373 * @throws java.lang.SecurityException if a security manager exists and the
374 * caller does not have {@code ManagementPermission("control")}
375 */
376 long openStream(long recordingId, Map<String, String> streamOptions) throws IOException;
377
378 /**
379 * Closes the recording stream with the specified ID and releases any system
380 * resources that are associated with the stream.
381 * <p>
382 * If the stream is already closed, invoking this method has no effect.
383 *
384 * @param streamId the ID of the stream
385 *
386 * @throws IllegalArgumentException if a stream with the specified ID doesn't
387 * exist
388 * @throws IOException if an I/O error occurs while trying to close the stream
389 * @throws java.lang.SecurityException if a security manager exists and the
390 * caller does not have {@code ManagementPermission("control")}
391 *
392 * @see #openStream(long, Map)
393 */
394 void closeStream(long streamId) throws IOException;
395
396 /**
397 * Reads a portion of data from the stream with the specified ID, or returns
398 * {@code null} if no more data is available.
399 * <p>
400 * To read all data for a recording, invoke this method repeatedly until
401 * {@code null} is returned.
402 *
403 * @param streamId the ID of the stream
404 *
405 * @return byte array that contains recording data, or {@code null} when no more
406 * data is available
407 * @throws IOException if the stream is closed, or an I/O error occurred while
408 * trying to read the stream
409 * @throws IllegalArgumentException if no recording with the stream ID exists
410 * @throws java.lang.SecurityException if a security manager exists and the
411 * caller does not have {@code ManagementPermission("monitor")}
412 */
413 byte[] readStream(long streamId) throws IOException;
414
415 /**
416 * Returns a map that contains the options for the recording with the
417 * specified ID (for example, the destination file or time span to keep
418 * recorded data).
419 * <p>
420 * See {@link FlightRecorderMXBean} for available option names.
421 *
422 * @param recordingId the ID of the recording to get options for
423 *
424 * @return a map describing the recording options, not {@code null}
425 *
426 * @throws IllegalArgumentException if no recording with the
427 * specified ID exists
428 * @throws java.lang.SecurityException if a security manager exists and the
429 * caller does not have {@code ManagementPermission("monitor")}
430 *
431 */
432 Map<String, String> getRecordingOptions(long recordingId) throws IllegalArgumentException;
433
434 /**
435 * Returns a {@code Map} that contains the settings for the recording with the specified ID,
436 * (for example, the event thresholds)
437 * <p>
438 * If multiple recordings are running at the same time, more data could be
439 * recorded than what is specified in the {@code Map} object.
440 * <p>
441 * The name in the {@code Map} is the event name and the setting name separated by
442 * {@code "#"} (for example, {@code "jdk.VMInfo#period"}). The value
443 * is a textual representation of the settings value (for example,
444 * {@code "60 s"}).
445 *
446 * @param recordingId the ID of the recordings to get settings for
447 *
448 * @return a map that describes the recording settings, not {@code null}
449 *
450 * @throws IllegalArgumentException if no recording with the specified ID exists
451 * @throws java.lang.SecurityException if a security manager exists and the
452 * caller does not have {@code ManagementPermission("monitor")}
453 */
454 Map<String, String> getRecordingSettings(long recordingId) throws IllegalArgumentException;
455
456 /**
457 * Sets a configuration as a string representation for the recording with the
458 * specified ID.
459 *
460 * @param recordingId ID of the recording
461 * @param contents a string representation of the configuration file to use,
462 * not {@code null}
463 * @throws IllegalArgumentException if no recording with the
464 * specified ID exists or if the configuration could not be parsed.
465 * @throws java.lang.SecurityException if a security manager exists and the
466 * caller does not have {@code ManagementPermission("control")}
467 *
468 * @see Configuration#getContents()
469 */
470 void setConfiguration(long recordingId, String contents) throws IllegalArgumentException;
471
472 /**
473 * Sets a predefined configuration for the recording with the specified ID.
474 *
475 * @param recordingId ID of the recording to set the configuration for
476 * @param configurationName the name of the configuration (for example,
477 * {@code "profile"} or {@code "default"}), not {@code null}
478 * @throws IllegalArgumentException if no recording with the
479 * specified ID exists
480 * @throws java.lang.SecurityException if a security manager exists and the
481 * caller does not have {@code ManagementPermission("control")}
482 *
483 * @see #getConfigurations()
484 */
485 void setPredefinedConfiguration(long recordingId, String configurationName) throws IllegalArgumentException;
486
487 /**
488 * Sets and replaces all previous settings for the specified recording.
489 * <p>
490 * A setting consists of a name/value pair, where <em>name</em> specifies the
491 * event and setting to configure, and the <em>value</em> specifies what to set
492 * it to.
493 * <p>
494 * The name can be formed in the following ways:
495 * <p>
496 * {@code
497 * <event-name> + "#" + <setting-name>
498 * }
499 * <p>
500 * or
501 * <p>
502 * {@code
503 * <event-id> + "#" + <setting-name>
504 * }
505 * <p>
506 * For example, to set the sample interval of the CPU Load event to once every
507 * second, use the name {@code "jdk.CPULoad#period"} and the value
508 * {@code "1 s"}. If multiple events use the same name, for example if an event
509 * class is loaded in multiple class loaders, and differentiation is needed
510 * between them, then the name is {@code "56#period"}. The ID for an event is
511 * obtained by invoking {@link jdk.jfr.EventType#getId()} method and is valid
512 * for the Java Virtual Machine (JVM) instance that the event is registered in.
513 * <p>
514 * A list of available event names is retrieved by invoking
515 * {@link jdk.jfr.FlightRecorder#getEventTypes()} and
516 * {@link jdk.jfr.EventType#getName()}. A list of available settings for an
517 * event type is obtained by invoking
518 * {@link jdk.jfr.EventType#getSettingDescriptors()} and
519 * {@link jdk.jfr.ValueDescriptor#getName()}.
520 *
521 * @param recordingId ID of the recording
522 *
523 * @param settings name value map of the settings to set, not {@code null}
524 *
525 * @throws IllegalArgumentException if no recording with the specified ID exists
526 * @throws java.lang.SecurityException if a security manager exists and the
527 * caller does not have {@code ManagementPermission("control")}
528 *
529 * @see Recording#getId()
530 */
531 void setRecordingSettings(long recordingId, Map<String, String> settings) throws IllegalArgumentException;
532
533 /**
534 * Configures the recording options (for example, destination file and time span
535 * to keep data).
536 * <p>
537 * See {@link FlightRecorderMXBean} for a description of the options and values
538 * that can be used. Setting a value to {@code null} restores the value to the
539 * default value.
540 *
541 * @param recordingId the ID of the recording to set options for
542 *
543 * @param options name/value map of the settings to set, not {@code null}
544 *
545 * @throws IllegalArgumentException if no recording with the specified ID exists
546 * @throws java.lang.SecurityException if a security manager exists, and the
547 * caller does not have {@code ManagementPermission("control")} or an
548 * option contains a file that the caller does not have permission to
549 * operate on.
550 * @see Recording#getId()
551 */
552 void setRecordingOptions(long recordingId, Map<String, String> options) throws IllegalArgumentException;
553
554 /**
555 * Returns the list of the available recordings, not necessarily running.
556 * <p>
557 * <b>MBeanServer access</b>:<br>
558 * The mapped type of {@code RecordingInfo} is {@code CompositeData} with
559 * attributes as specified in the {@link RecordingInfo#from
560 * RecordingInfo.from} method.
561 *
562 * @return list of recordings, not {@code null}
563 *
564 * @throws java.lang.SecurityException if a security manager exists and the
565 * caller does not have {@code ManagementPermission("monitor")}
566 *
567 * @see RecordingInfo
568 * @see Recording
569 */
570 List<RecordingInfo> getRecordings();
571
572 /**
573 * Returns the list of predefined configurations for this Java Virtual Machine (JVM).
574 * <p>
575 * <b>MBeanServer access</b>:<br>
576 * The mapped type of {@code ConfigurationInfo} is {@code CompositeData}
577 * with attributes as specified in the {@link ConfigurationInfo#from
578 * ConfigurationInfo.from} method.
579 *
580 * @return the list of predefined configurations, not {@code null}
581 *
582 * @throws java.lang.SecurityException if a security manager exists and the
583 * caller does not have {@code ManagementPermission("monitor")}
584 *
585 * @see ConfigurationInfo
586 * @see Configuration
587 */
588 List<ConfigurationInfo> getConfigurations();
589
590 /**
591 * Returns the list of currently registered event types.
592 * <p>
593 * <b>MBeanServer access</b>:<br>
594 * The mapped type of {@code EventTypeInfo} is {@code CompositeData} with
595 * attributes as specified in the {@link EventTypeInfo#from
596 * EventTypeInfo.from} method.
597 *
598 * @return the list of registered event types, not {@code null}
599 *
600 * @throws java.lang.SecurityException if a security manager exists and the
601 * caller does not have {@code ManagementPermission("monitor")}
602 *
603 * @see EventTypeInfo
604 * @see EventType
605 */
606 List<EventTypeInfo> getEventTypes();
607
608 /**
609 * Writes recording data to the specified file.
610 * <p>
611 * If this method is invoked remotely from another process, the data is written
612 * to a file named {@code outputFile} on the machine where the target Java
613 * Virtual Machine (JVM) is running. If the file location is a relative path, it
614 * is relative to the working directory where the target JVM was started.
615 *
616 * @param recordingId the ID of the recording to dump data for
617 *
618 * @param outputFile the system-dependent file name where data is written, not
619 * {@code null}
620 *
621 * @throws IOException if the recording can't be dumped due to an I/O error (for
622 * example, an invalid path)
623 *
624 * @throws IllegalArgumentException if a recording with the specified ID doesn't
625 * exist
626 *
627 * @throws IllegalStateException if the recording is not yet started or if it is
628 * already closed
629 *
630 * @throws SecurityException if a security manager exists and its
631 * {@code SecurityManager.checkWrite(java.lang.String)} method denies
632 * write access to the named file or the caller does not have
633 * {@code ManagmentPermission("control")}
634 *
635 * @see java.nio.file.Path#toString()
636 * @see Recording#dump(java.nio.file.Path)
637 */
638 void copyTo(long recordingId, String outputFile) throws IOException, SecurityException;
639 }