Summary

Add help option to -XX:StartFlightRecording to simplify JDK Flight Recorder configuration at startup.

Problem

JDK Flight Recorder can be started on command line using -XX:StartFlightRecording, but it's not uncommon for users struggle with the syntax. One reason is the many ways a recording can be configured.

First, there are options for the recording itself:

-XX:StartFlightRecording:name=<string>
-XX:StartFlightRecording:maxage=<timespan>
-XX:StartFlightRecording:maxsize=<bytes>
-XX:StartFlightRecording:dumponexit=<true/false>
-XX:StartFlightRecording:filename=<string>
-XX:StartFlightRecording:settings=<path>

Then, there are options which set multiple event settings at once:

-XX:StartFlightRecording:gc=<off|normal|detailed|high|all>
-XX:StartFlightRecording:allocation-profiling=<off|low|medium|high|maximum>  
-XX:StartFlightRecording:compiler=<off|normal|detailed|all> 
-XX:StartFlightRecording:method-profiling=<off|normal|high|max> 
-XX:StartFlightRecording:thread-dump=<off|once|60s|10s|1s>
-XX:StartFlightRecording:exceptions=<off|errors|all>
-XX:StartFlightRecording:memory-leaks=<off|types|stack-traces|gc-roots>  
-XX:StartFlightRecording:locking-threshold=<timespan>
-XX:StartFlightRecording:file-threshold=<timespan>
-XX:StartFlightRecording:socket-threshold=<timespan>
-XX:StartFlightRecording:class-loading=<true|false>

Finally, there are over 180 events where each event may have several settings:

-XX:StartFlightRecording:jdk.JavaMonitorEnter#enabled=true
-XX:StartFlightRecording:jdk.JavaMonitorEnter#threshold=10ms
-XX:StartFlightRecording:jdk.JavaMonitorEnter#stackTrace=true
-XX:StartFlightRecording:jdk.ExceptionStatistics#enabled=true
-XX:StartFlightRecording:jdk.ExceptionStatistics#period=5s
...

To simplify event configuration, the 'jfc configure' command was introduced in JDK 17. In the same release, the help text of 'jcmd JFR.start' was improved, but minimal effort was made to enhance the user experience of -XX:StartFlightRecording. Part of the problem is that event classes can be loaded after startup and it's not possible to know what a user may call them, so the JVM can't fail with a help message if an unknown name/option is specified.

Solution

Introduce a new help option to -XX:StartFlightRecording that prints a help text similar to what exists today for 'jcmd JFR.start'. The available options often depend on the JDK release, so this will be a convenient way to check what is supported. A help text can also point to 'jfr configure'.

If -XX:StartFlightRecording:help is specified, the JVM will exit after the help text has been printed. This is similar behavior as -Xlog:help

Specification

-XX::StartFlightRecording:help   prints -XX:StartFlightRecording usage syntax and available options
                                 along with some example command lines.