[GR-42964] Deprecate --enable-monitoring without argument.

PullRequest: graal/13447

Author: LesiaChaban

docs/reference-manual/native-image/BuildOptions.md

@@ -26,7 +26,7 @@ The following options are supported across both GraalVM Community and Enterprise
 * `--enable-all-security-services`: add all security service classes to a native executable
 * `--enable-http`: enable HTTP support in a native executable
 * `--enable-https`: enable HTTPS support in a native executable
-* `--enable-monitoring`: enable monitoring features that allow the VM to be inspected at run time. Comma-separated list can contain `heapdump`, `jfr`, `jvmstat`, or `all` (defaults to `all` if no argument is provided). For example: `--enable-monitoring=heapdump,jvmstat`.
+* `--enable-monitoring`: enable monitoring features that allow the VM to be inspected at run time. Comma-separated list can contain `heapdump`, `jfr`, `jvmstat`, or `all` (deprecated behavior: defaults to `all` if no argument is provided). For example: `--enable-monitoring=heapdump,jfr`.
 * `--enable-sbom`:  embed a Software Bill of Materials (SBOM) in the executable or shared library for passive inspection. Comma-separated list can contain `cyclonedx` or `strict` (defaults to `cyclonedx` if no argument is provided).  The optional `strict` flag aborts the build if any class cannot be matched to a library in the SBOM. For example: `--enable-sbom=cyclonedx,strict`. **GraalVM Enterprise only**
 * `--enable-preview`: allow classes to depend on preview features of this release
 * `--enable-url-protocols`: list comma-separated URL protocols to enable

substratevm/CHANGELOG.md

@@ -14,6 +14,7 @@ This changelog summarizes major changes to GraalVM Native Image.
 * (GR-41096) Support services loaded through the `java.util.ServiceLoader.ModuleServicesLookupIterator`. An example of such service is the `com.sun.jndi.rmi.registry.RegistryContextFactory`.
 * (GR-41912) The builder now generated reports for internal errors, which users can share when creating issues. By default, error reports follow the `svm_err_b_<timestamp>_pid<pid>.md` pattern and are created in the working directory. Use `-H:ErrorFile` to adjust the path or filename.
 * (GR-36951) Add [RISC-V support](https://medium.com/p/899be38eddd9) for Native Image through the LLVM backend.
+* (GR-42964) Deprecate `--enable-monitoring` without an argument. The option will no longer default to `all` in a future release. Instead, please always explicitly specify the list of monitoring features to be enabled (for example, `--enable-monitoring=heapdump,jfr,jvmstat`").
 
 ## Version 22.3.0
 * (GR-35721) Remove old build output style and the `-H:±BuildOutputUseNewStyle` option.

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/VMInspectionOptions.java

@@ -44,27 +44,39 @@
 
 public final class VMInspectionOptions {
     private static final String ENABLE_MONITORING_OPTION = "enable-monitoring";
+    private static final String MONITORING_DEFAULT_NAME = "<deprecated-default>";
     private static final String MONITORING_ALL_NAME = "all";
     private static final String MONITORING_HEAPDUMP_NAME = "heapdump";
     private static final String MONITORING_JFR_NAME = "jfr";
     private static final String MONITORING_JVMSTAT_NAME = "jvmstat";
-    private static final String MONITORING_ALLOWED_VALUES = "'" + MONITORING_HEAPDUMP_NAME + "', '" + MONITORING_JFR_NAME + "', '" + MONITORING_JVMSTAT_NAME + "', or '" + MONITORING_ALL_NAME +
-                    "' (defaults to '" + MONITORING_ALL_NAME + "' if no argument is provided)";
+    private static final String MONITORING_ALLOWED_VALUES = "`" + MONITORING_HEAPDUMP_NAME + "`, `" + MONITORING_JFR_NAME + "`, `" + MONITORING_JVMSTAT_NAME + "`, or `" + MONITORING_ALL_NAME +
+                    "` (deprecated behavior: defaults to `" + MONITORING_ALL_NAME + "` if no argument is provided)";
 
-    @APIOption(name = ENABLE_MONITORING_OPTION, defaultValue = MONITORING_ALL_NAME) //
+    @APIOption(name = ENABLE_MONITORING_OPTION, defaultValue = MONITORING_DEFAULT_NAME) //
     @Option(help = "Enable monitoring features that allow the VM to be inspected at run time. Comma-separated list can contain " + MONITORING_ALLOWED_VALUES + ". " +
-                    "For example: `--" + ENABLE_MONITORING_OPTION + "=" + MONITORING_HEAPDUMP_NAME + "," + MONITORING_JVMSTAT_NAME + "`.", type = OptionType.User) //
+                    "For example: `--" + ENABLE_MONITORING_OPTION + "=" + MONITORING_HEAPDUMP_NAME + "," + MONITORING_JFR_NAME + "`.", type = OptionType.User) //
     public static final HostedOptionKey<LocatableMultiOptionValue.Strings> EnableMonitoringFeatures = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.commaSeparated(),
                     VMInspectionOptions::validateEnableMonitoringFeatures);
 
-    public static void validateEnableMonitoringFeatures(OptionKey<?> optionKey) {
+    public static void validateEnableMonitoringFeatures(@SuppressWarnings("unused") OptionKey<?> optionKey) {
         Set<String> enabledFeatures = getEnabledMonitoringFeatures();
-        enabledFeatures.removeAll(List.of(MONITORING_HEAPDUMP_NAME, MONITORING_JFR_NAME, MONITORING_JVMSTAT_NAME, MONITORING_ALL_NAME));
+        if (enabledFeatures.contains(MONITORING_DEFAULT_NAME)) {
+            System.out.printf(
+                            "Warning: `%s` without an argument is deprecated. Please always explicitly specify the list of monitoring features to be enabled (for example, `%s`).%n",
+                            getDefaultMonitoringCommandArgument(),
+                            SubstrateOptionsParser.commandArgument(EnableMonitoringFeatures, String.join(",", List.of(MONITORING_HEAPDUMP_NAME, MONITORING_JFR_NAME))));
+        }
+        enabledFeatures.removeAll(List.of(MONITORING_HEAPDUMP_NAME, MONITORING_JFR_NAME, MONITORING_JVMSTAT_NAME, MONITORING_ALL_NAME, MONITORING_DEFAULT_NAME));
         if (!enabledFeatures.isEmpty()) {
-            throw UserError.abort("The option %s contains invalid value(s): %s. It can only contain %s.", optionKey.getName(), String.join(", ", enabledFeatures), MONITORING_ALLOWED_VALUES);
+            throw UserError.abort("The `%s` option contains invalid value(s): %s. It can only contain %s.", getDefaultMonitoringCommandArgument(), String.join(", ", enabledFeatures),
+                            MONITORING_ALLOWED_VALUES);
         }
     }
 
+    private static String getDefaultMonitoringCommandArgument() {
+        return SubstrateOptionsParser.commandArgument(EnableMonitoringFeatures, MONITORING_DEFAULT_NAME);
+    }
+
     @Fold
     public static String getHeapdumpsCommandArgument() {
         return SubstrateOptionsParser.commandArgument(EnableMonitoringFeatures, MONITORING_HEAPDUMP_NAME);
@@ -76,7 +88,7 @@ public static Set<String> getEnabledMonitoringFeatures() {
 
     private static boolean hasAllOrKeywordMonitoringSupport(String keyword) {
         Set<String> enabledFeatures = getEnabledMonitoringFeatures();
-        return enabledFeatures.contains(MONITORING_ALL_NAME) || enabledFeatures.contains(keyword);
+        return enabledFeatures.contains(MONITORING_ALL_NAME) || enabledFeatures.contains(MONITORING_DEFAULT_NAME) || enabledFeatures.contains(keyword);
     }
 
     @Fold