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

JFR: Filename expansion

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: hotspot
    • Labels:
      None
    • Subcomponent:
      jfr
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      low
    • Compatibility Risk Description:
      Hide
      File pathes that today contains %t, %p or %% for -XX:StartFlightRecording:filename=<path> and the diagnostic commands JFR.start filename=<path>, JFR.stop filename=<path> and JFR.dump filename=<path> would see part of the path being replaced by the PID, a timestamp or a single percentage sign. It is unlikely that such names are in use, so the compatibility risk is deemed low.
      Show
      File pathes that today contains %t, %p or %% for -XX:StartFlightRecording:filename=<path> and the diagnostic commands JFR.start filename=<path>, JFR.stop filename=<path> and JFR.dump filename=<path> would see part of the path being replaced by the PID, a timestamp or a single percentage sign. It is unlikely that such names are in use, so the compatibility risk is deemed low.
    • Interface Kind:
      add/remove command in $JDK/bin, add/remove/modify command line option
    • Scope:
      JDK

      Description

      Summary

      Extend the filename parameter of -XX:StartFlightRecording and the diagnostic commands JFR.start, JFR.stop and JFR.dump, so PID and timestamp can be included by specifying %p and %t.

      Problem

      Today, users can create a JFR dump file like this:

      $ java -XX:StartFlightRecording:filename=test.jfr <Main Class>

      But there is no way to add the PID to the filename because it is not known until the process is started.

      Since the PID can be reused by the OS, It would also be useful to get the timestamp to avoid the same filename being used when starting multiple Java processes with the same command line arguments.

      Solution

      Unified logging allows users to specify %p and %t when using -Xlog:filename option to get the timestamp and PID.

      The same mechanism can be used with JFR, for example:

      $ java -XX:StartFlightRecording:filename=dump-%p.jfr <Main class>

      '%p' will be replaced by the PID, i.e. 'dump-12342.jfr'

      $ jcmd <pid> JFR.start filename=dump-%t.jfr

      '%t' will be repalced by the current timestamp, i.e. 'dump-2021_07_04_08_32_49.jfr'

      '%p' and '%t' can be used together, and '%%' will be replaced by '%'

      Specification

      -XX:StartFlightRecording

      -XX:StartFlightRecording=parameter=value
      ...
         filename=path
                Specifies the path and name of the file to which the recording is written when
                the recordingis stopped, for example:
      
                 · recording.jfr
      
                 · /home/user/recordings/recording.jfr
      
                 · c:\recordings\recording.jfr
      
      +         If %p and/or %t is specified in the filename, it expands to the JVM's
      +         PID and the current timestamp, respectively.

      JFR.start

                 Syntax : JFR.start [options]
      
                 Options:
      
                   filename  (Optional) Name of the file to which the flight recording data is
                             written when the recording is stopped. If no filename is given, a
                             filename is generated from the PID and the current date and is
                             placed in the directory where the process was started. The
                             filename may also be a directory in which case, the filename is
                             generated from the PID and the current date in the specified
      -                      specified directory.  (STRING, no default value)
      +                      specified directory. If %p and/or %t is specified in the filename,
      +                      it expands to the JVM's PID and the current timestamp, respectively.
      +                      (STRING, no default value)

      JFR.stop

                 Syntax : JFR.stop [options]
      
                 Options:
      
                   filename  (Optional) Name of the file to which the recording is written when the
      -                      recording is stopped. If no path is provided, the data from the recording
      +                      recording is stopped. If %p and/or %t is specified in the filename, it 
      +                      expands to the JVM's PID and the current timestamp, respectively.
      +                      If no path is provided, the data from the recording is discarded.
      +                      (STRING, no default value)

      JFR.dump

                 Syntax : JFR.dump [options]
      
                 Options:
      
                   filename  (Optional) Name of the file to which the flight recording data is
                              dumped. If no filename is given, a filename is generated from the PID
                              and the current date. The filename may also be a directory in which
                              case, the filename is generated from the PID and the current date in
      -                       the specified directory. (STRING, no default value)
      +                       the specified directory. If %p and/or %t is specified in the filename, it 
      +                       expands to the JVM's PID and the current timestamp, respectively.
      +                       (STRING, no default value)

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              ddong Denghui Dong
              Reporter:
              egahlin Erik Gahlin
              Reviewed By:
              Erik Gahlin
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: