Summary

Add methods that can dump data to disk for recording streams.

Problem

The JFR API contains two classes that can stream events, jdk.jfr.consumer.RecordingStream and jdk.management.jfr.RemoteRecordingStream, both useful for application monitoring where users can listen to the stream and get a callback when an event happens. If something unexpected happens, users may want to dump the recording data to disk for further analysis in JDK Mission Control. Today, dumping is problematic because the user doesn't know the underlying recording associated with the stream.

For the in-process case, they can call FlightRecorder.getFlightRecorder().getRecordings() to get a list of all recordings and try to figure out which belongs to the event stream by some heuristic, i.e. by taking the timestamp when they start the stream and look for a timestamp that is roughly the same by invoking Recording::getStartTime(). Similar heuristics can be applied to RemoteRecordingStream by invoking FlightRecorderMXBean::getRecordings() and RecordingInfo::getStartTime(). Once they have a recording, they can invoke dump(Path) to get a dump on disk or download data using the FlightRecorderMXBean.

This is cumbersome, unreliable and hard to understand. In addition, for the remote case, the same data must be transferred to the client twice, first as part of the original stream and then again for the dump.

Solution

Add the method jdk.jfr.consumer.RecordingStream::dump(path) in the jdk.jfr module that will delegate to the underlying Recording object and its dump method.

Add the method jdk.management.RemoteRecordingStreamdump(path) in the jdk.jfr module that will wait for data to arrive from the FlightRecorderMXBean up to the time the dump was invoked and copy the contents on the local disk to a separate file.

Specification

jdk.jfr.RecordingStream

/**
  * Writes recording data to a file.
  * <p>
  * The recording stream must be started, but not closed.
  * <p>
  * It's highly recommended to set max age or max size before
  * starting the stream. Otherwise, the dump may not contain any events.
  *
  * @param destination the location where recording data is written, not
  *        {@code null}
  *
  * @throws IOException if the recording data can't be copied to the specified
  *         location, or if the stream is closed, or not started.
  *
  * @throws SecurityException if a security manager exists and the caller doesn't
  *         have {@code FilePermission} to write to the destination path
  *
  * @see RecordingStream#setMaxAge(Duration)
  * @see RecordingStream#setMaxSize(Duration)
  */
 public void dump(Path destination) throws IOException

jd.jfr.RemoteRecordingStream

/**
  * Writes recording data to a file.
  * <p>
  * The recording stream must be started, but not closed.
  * <p>
  * It's highly recommended to set max age or max size before
  * starting the stream. Otherwise, the dump may not contain any events.
  *
  * @param destination the location where recording data is written, not
  *        {@code null}
  *
  * @throws IOException if the recording data can't be copied to the specified
  *         location, or if the stream is closed, or not started.
  *
  * @throws SecurityException if a security manager exists and the caller doesn't
  *         have {@code FilePermission} to write to the destination path
  *
  * @see RemoteRecordingStream#setMaxAge(Duration)
  * @see RemoteRecordingStream#setMaxSize(Duration)
  */
 public void dump(Path destination) throws IOException