Summary

Add support for specifying .jfc file options when starting a JFR recording from the command line or via jcmd.

Problem

Today it is possible to configure JFR by generating a custom .jfc file using JMC or the jfr tool. The tools let users discover and select available options that a specific .jfc file supports. Based on the chosen options, the tooling generates a custom.jfc file to be used as a configuration when starting JFR.

It would be very convenient if it were possible to configure JFR directly on the command line in a similar manner as the tooling, hence skipping the intermediary custom.jfc file generation step.

Solution

Currently, -XX:StartFlightRecording accepts a set of fixed options, i.e. regular options, e.g. "disk", "settings", "dumponexit" et al. and they will work just like in the past.

For example:

$ java -XX:StartFlightRecording:disk=false,dumponexit=true,settings=my.jfc ...

What will be added is a way to configure the settings/options exposed by a .jfc file, just like the "jfr configure" command https://bugs.openjdk.java.net/browse/JDK-8260863, but directly from the command line.

Instead of writing:

$ jfr configure [jfc-options] --output temp.jfc
$ java -XX:StartFlightRecording:[fixed-options],settings=temp.jfc
$ rm temp.jfc

It will be possible to do it in one step:

$ java -XX:StartFlightRecording:[fixed-options],[jfc-options] ...

If there is a name conflict between a fixed option and a .jfc option, the fixed option will take precedence. The existing option "settings" will detail the input .jfc file to use.

For example:

$ java -XX:StartFlightRecording:settings=my.jfc,[jfc-options] ...

If the "settings" option is not specified, the default.jfc file, shipped with the JDK, will be used. This is equivalent to not specifying a .jfc file using "jfr configure" and its "--input file" argument.

Since new events are added with every new release and performance improvements are made to existing events, the .jfc options are likely to change over time. For example, in JDK 16, a new allocation sampling event was introduced and turned on by default (without exceeding an overhead of 1%). That meant that the earlier .jfc option, "Memory Profiling", which enabled the TLAB and Object Count events, was removed, and the events instead placed under the control of the "gc" option. Several similar changes have happened in the past and will likely occur in future releases.

Due to the volatile nature of the .jfc options, it is desirable to apply less strict checking. If a .jfc option or event is not available, it should be sufficient to print a warning message but still allow the JVM to start. This will avoid flag days when users migrate to a new JDK release. Since .jfc files will also be created for user-defined events in third-party libraries, less strict checking will simplify and smoothen the third-party library upgrade process.

Example usage of jfc-options:

$ java -XX:StartFlightRecording:jdk.JavaMonitorEnter#threshold=1ms ...
$ java -XX:StartFlightRecording:gc=high,method-profiling=high ...
$ java -XX:StartFlightRecording:settings=netty.jfc,netty-threshold=10ms ...

The same mechanism will be available when using the diagnostic command JFR.start as well:

$ jcmd <pid> JFR.start [fixed-options] [jfc-options] ...

Example:

$ jcmd 7091 JFR.start dumponexit=true method-profiling=high

Specification

--X:StartFlightRecording

diff --git a/src/java.base/share/man/java.1 b/src/java.base/share/man/java.1
index 4f846951135..4a1ce6435d4 100644
--- a/src/java.base/share/man/java.1
+++ b/src/java.base/share/man/java.1
@@ -1756,6 +1756,22 @@ is needed.
 .PP
 You can specify values for multiple parameters by separating them with a
 comma.
+.PP
+Event settings and .jfc options can also be specified using the following
+syntax:
+.TP
+.B \f[CB]option=\f[R]\f[I]value\f[R]
+Specifies the option value to modify. To list available options, use the 
+JAVA_HOME/bin/jfr tool.
+.TP
+.B \f[CB]event-setting=\f[R]\f[I]value\f[R]
+Specifies the event setting value to modify. Use the form:
+<event-name>#<setting-name>=<value>
+To add a new event setting, prefix the event name with '+'.
+.PP
+In case of a conflict between a parameter and a .jfc option, the parameter
+will take precedence. The whitespace delimiter can be omitted for timespan values, i.e. 20ms. For
+more information about the settings syntax, see Javadoc of the jdk.jfr package.
.RE
.TP

JFR.start

diff --git a/src/jdk.jcmd/share/man/jcmd.1 b/src/jdk.jcmd/share/man/jcmd.1
index 1a3a9d7192b..914b12c63a6 100644
--- a/src/jdk.jcmd/share/man/jcmd.1
+++ b/src/jdk.jcmd/share/man/jcmd.1
@@ -562,6 +562,22 @@ is needed.
Use \f[CB]none\f[R] to start a recording without a predefined
configuration file.
(STRING, \f[CB]JAVA\-HOME\f[R]/lib/jfr/default.jfc)
+.PP
+Event settings and .jfc options can also be specified using the following
+syntax:
+.TP
+.B \f[CB]option=\f[R]\f[I]value\f[R]
+Specifies the option value to modify. To list available options, use the
+JAVA_HOME/bin/jfr tool.
+.TP
+.B \f[CB]event-setting=\f[R]\f[I]value\f[R]
+Specifies the event setting value to modify. Use the form:
+<event-name>#<setting-name>=<value>
+To add a new event setting, prefix the event name with '+'.
+.PP
+In case of a conflict between a parameter and a .jfc option, the parameter
+will take precedence. The whitespace delimiter can be omitted for timespan values, i.e. 20ms. For
+more information about the settings syntax, see Javadoc of the jdk.jfr package.
.RE
.TP