Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8266266

JFR: Dump recording from a recording stream

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: hotspot
    • Labels:
      None
    • Subcomponent:
      jfr
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API
    • Scope:
      JDK

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              egahlin Erik Gahlin
              Reporter:
              egahlin Erik Gahlin
              Reviewed By:
              Markus Grönlund
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: