Summary

Deprecate command line option -XX:FlightRecorderOptions:samplethreads and diagnostic command JFR.configure samplethreads.

Problem

The purpose of samplethreads option was to provide a simple way for users to turn off method sampling on command line without creating custom configuration files. This was important when JFR was ported to HotSpot as it provided means to run nightly testing without crashes. The crashes were ultimately fixed by introducing crash protection, so the sampler can recover from those unlikely situations.

When JFR was open sourced in JDK 11, the mechanism to enable/disable the sampler from command line was removed, but the flag was kept. The option serves no purpose, but gives the impression that it can be used.

Solution

JDK 17 introduced the use of .jfc options on command line, which means the sampler can be enabled/disabled with the method-profiling option when using -XX:StartFlightRecording and jcmd JFR.start.

JDK 19 will allow users to specify samplethreads, but a deprecation warning is printed and the option -XX:StartFlightRecording:method-profiling= is suggested as a replacement.

JDK 20 will remove the option.

Specification

src/java.base/share/man/java.1

-.B \f[CB]samplethreads=\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]}
-Specifies whether thread sampling is enabled.
-Thread sampling occurs only if the sampling event is enabled along with
-this parameter.
-By default, this parameter is enabled.
-.RS
-.RE
-.TP

src/hotspot/share/jfr/dcmd/jfrDcmds.cpp

   out->print_cr("                     performance and is not recommended. This value cannot be changed");
   out->print_cr("                     once JFR has been initialized. (STRING, 8k)");
   out->print_cr("");
-  out->print_cr("  samplethreads      (Optional) Flag for activating thread sampling. This value cannot");
-  out->print_cr("                     be changed once JFR has been initialized. (BOOLEAN, true)");
-  out->print_cr("");
   out->print_cr("Options must be specified using the <key> or <key>=<value> syntax.");
   out->print_cr("");
   out->print_cr("Example usage:");

+  bool startup = DCmd_Source_Internal == source;
+   if (startup) {
+     log_warning(jfr,startup)("%s", "Option samplethreads is deprecated. Use -XX:StartFlightRecording:method-profiling=<off|normal|high|max>");
+   } else {
+     output()->print_cr("%s", "Option samplethreads is deprecated. Use JFR.start method-profiling=<off|normal|high|max>");
+     output()->print_cr("");
+   }