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)