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 <pid> 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 <pid> 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.