Summary

Extend the 'jfr' tool with an additional command to help users configure event settings more easily from the command line.

Problem

The JDK comes with more than 150 JFR event types, with multiple settings for each type.

To make configuration easier, JFR configuration files (.jfc files) come with options that can modify settings for a set of event types. To use these options today, users must start JDK Mission Control (JMC) and navigate to the template manager. There they will find a combo box where they can select the values "Off", "Normal", or "All". Users must then click the "Export File" button to save the configuration into a new .jfc file.

Having convenient access to these options only in a GUI application makes JFR unnecessarily restrictive and cumbersome to use and does not work well when working in a shell, especially against a remote computer.

Solution

Extend the 'jfr' tool with a 'configure' command where options can be specified and modified events settings written to a generated custom .jfc file:

$ jfr configure gc=all method-profiling=high

By default, the tool will use the options in the default.jfc file that is shipped with the JDK and write the result to a file called custom.jfc. For more advanced use cases, it is possible to specify both input files and and output file:

$ jfr configure --input profile.jfc gc=all --output my.jfc

There will also be an interactive mode that prompts the user for each option in the input .jfc file(s), similar to the graphical user interface in JDK Mission Control today:

$ jfr configure --interactive

Garbage Collector: Normal (default)
1. Off
2. Normal
3. All
> 3
Using: All

Exceptions: Off (default)
1. Off
2. Errors Only
3. All Exceptions, including Errors
> 2 
Using: Errors Only
... 

Once users have created a customized .jfc file, they can use it to start a recording:

 $ java -XX:StartFlightRecording:settings=custom.jfc ...

 $ jcmd <pid> JFR.start settings=custom.jfc

The command can also combine several .jfc files:

 $ jfr configure --input default.jfc,netty.jfc --output combined.jfc

A --verbose switch helps understand the impact of changing an option and to debug which settings are modified:

$ jfr configure --verbose method-profiling=high
Setting:
"jdk.ExecutionSample#enabled=true"
"jdk.ExecutionSample#period=10 ms"
"jdk.NativeMethodSample#enabled=true"
"jdk.NativeMethodSample#period=20 ms"

If the user wants to start from an empty configuration and not use the default shipped with JDK, they can specify 'none'. This option is similar to how user can specify -XX:StartFlightRecording:settings=none on the command-line:

$ jfr configure --input none ...

Sometimes users may want to modify only a single event setting and specify its name directly:

$ jfr configure jdk.ThreadDump#enabled=true jdk.ThreadDump#period=5s

The syntax, event name + "#" + setting name, is the same as is used today in the Flight Recorder API. To make it less cumbersome and error-prone to specify periods and thresholds that may include whitespaces, i.e. "20 ms", it will be possible to omit them, i.e. "20ms". The command will add the space when it generates the new .jfc file.

By default, if the user tries to modify a setting for an event type that does not exist in the .jfc file, the command will abort with an error. For cases where users like to add a setting for an event type that is not part of the .jfc files, for example, a custom event they have made themselves, the syntax supports a '+' prefix to override the default:

$ jfr configure  +com.example.HelloWorld#enabled=true

Specification

jfr configure [--interactive] [--verbose]
              [--input <files>] [--output <file>]
              [option=value]* [event-setting=value]*

  --interactive           Interactive mode where the configuration
                          is determined by a set of questions.

  --verbose               Displays the modified settings.

  --input <files>         A comma-separated list of .jfc files from which
                          the new configuration is based. If no file is
                          specified, the default file in the JDK is used
                          (default.jfc). If 'none' is specified, the new
                          configuration starts empty.

  --ouput <file>          The filename of the generated output file. If not
                          specified, the filename custom.jfc will be used.

  option=value            The option value to modify. For available options,
                          see listed input files below.

  event-setting=value     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 '+'.

The whitespace character can be omitted for timespan values, i.e. 20ms. For
more information about the settings syntax, see Javadoc of the jdk.jfr package.