Update RecordMetadata option to take comma-separated key-value pairs

Author: DSouzaM

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/metadata/MetadataTracer.java

@@ -28,7 +28,12 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.util.HashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
 
 import org.graalvm.nativeimage.ImageSingletons;
 import org.graalvm.nativeimage.hosted.Feature;
@@ -39,6 +44,7 @@
 import com.oracle.svm.configure.UnresolvedConfigurationCondition;
 import com.oracle.svm.configure.config.ConfigurationSet;
 import com.oracle.svm.configure.config.ConfigurationType;
+import com.oracle.svm.core.SubstrateUtil;
 import com.oracle.svm.core.feature.AutomaticallyRegisteredFeature;
 import com.oracle.svm.core.feature.InternalFeature;
 import com.oracle.svm.core.jdk.RuntimeSupport;
@@ -55,34 +61,34 @@
 /**
  * Implements reachability metadata tracing during native image execution. Enabling
  * {@link Options#MetadataTracingSupport} at build time will generate code to trace all accesses of
- * reachability metadata. When {@link Options#RecordMetadata} is specified at run time, the image
- * will trace and emit metadata to the specified path.
+ * reachability metadata, and then the run-time option {@link Options#RecordMetadata} enables
+ * tracing.
  */
 public final class MetadataTracer {
 
     public static class Options {
-        @Option(help = "Enables the run-time code to trace reachability metadata accesses in the produced native image by using -XX:RecordMetadata=<path>.")//
+        @Option(help = "Generate an image that supports reachability metadata access tracing. " +
+                        "When tracing is supported, use the -XX:RecordMetadata option to enable tracing at run time.")//
         public static final HostedOptionKey<Boolean> MetadataTracingSupport = new HostedOptionKey<>(false);
 
-        @Option(help = "The path of the directory to write traced metadata to. Metadata tracing is enabled only when this option is provided.")//
-        public static final RuntimeOptionKey<String> RecordMetadata = new RuntimeOptionKey<>("");
+        @Option(help = "file:doc-files/RecordMetadataHelp.txt")//
+        public static final RuntimeOptionKey<String> RecordMetadata = new RuntimeOptionKey<>(null);
     }
 
+    private RecordOptions options;
     private volatile ConfigurationSet config;
 
-    private Path recordMetadataPath;
-
     @Fold
     public static MetadataTracer singleton() {
         return ImageSingletons.lookup(MetadataTracer.class);
     }
 
     /**
-     * Returns whether tracing is enabled at run time (using {@code -XX:RecordMetadata=path}).
+     * Returns whether tracing is enabled at run time (using {@code -XX:RecordMetadata}).
      */
     public boolean enabled() {
         VMError.guarantee(Options.MetadataTracingSupport.getValue());
-        return recordMetadataPath != null;
+        return options != null;
     }
 
     /**
@@ -159,20 +165,21 @@ public void traceSerializationType(String className) {
         }
     }
 
-    private static void initialize() {
+    private static void initialize(String recordMetadataValue) {
         assert Options.MetadataTracingSupport.getValue();
-        MetadataTracer singleton = MetadataTracer.singleton();
-        String recordMetadataValue = Options.RecordMetadata.getValue();
-        if (recordMetadataValue.isEmpty()) {
-            throw new IllegalArgumentException("Empty path provided for " + Options.RecordMetadata.getName() + ".");
-        }
-        Path recordMetadataPath = Paths.get(recordMetadataValue);
+
+        RecordOptions parsedOptions = RecordOptions.parse(recordMetadataValue);
         try {
-            Files.createDirectories(recordMetadataPath);
+            Files.createDirectories(parsedOptions.path());
         } catch (IOException ex) {
-            throw new IllegalArgumentException("Exception occurred creating the output directory for tracing (" + recordMetadataPath + ")", ex);
+            throw new IllegalArgumentException("Exception occurred creating the output directory for tracing (" + parsedOptions.path() + ")", ex);
         }
-        singleton.recordMetadataPath = recordMetadataPath;
+        if (parsedOptions.mode() != RecordMode.DEFAULT) {
+            throw new IllegalArgumentException("Mode " + parsedOptions.mode() + " is not yet supported.");
+        }
+
+        MetadataTracer singleton = MetadataTracer.singleton();
+        singleton.options = parsedOptions;
         singleton.config = new ConfigurationSet();
     }
 
@@ -183,10 +190,10 @@ private static void shutdown() {
         singleton.config = null; // clear config so that shutdown events are not traced.
         if (config != null) {
             try {
-                config.writeConfiguration(configFile -> singleton.recordMetadataPath.resolve(configFile.getFileName()));
+                config.writeConfiguration(configFile -> singleton.options.path().resolve(configFile.getFileName()));
             } catch (IOException ex) {
                 Log log = Log.log();
-                log.string("Failed to write out reachability metadata to directory ").string(singleton.recordMetadataPath.toString());
+                log.string("Failed to write out reachability metadata to directory ").string(singleton.options.path().toString());
                 log.string(":").string(ex.getMessage());
                 log.newline();
             }
@@ -200,7 +207,7 @@ static RuntimeSupport.Hook initializeMetadataTracingHook() {
             }
             VMError.guarantee(Options.MetadataTracingSupport.getValue());
             if (Options.RecordMetadata.hasBeenSet()) {
-                initialize();
+                initialize(Options.RecordMetadata.getValue());
             }
         };
     }
@@ -230,12 +237,86 @@ static RuntimeSupport.Hook checkImproperOptionUsageHook() {
                 throw new IllegalArgumentException(
                                 "The option " + Options.RecordMetadata.getName() + " can only be used if metadata tracing is enabled at build time (using " +
                                                 hostedOptionCommandArgument + ").");
-
             }
         };
     }
 }
 
+enum RecordMode {
+    DEFAULT,
+    CONDITIONAL
+}
+
+record RecordOptions(Path path, RecordMode mode) {
+
+    static RecordOptions parse(String recordMetadataValue) {
+        if (recordMetadataValue.isEmpty()) {
+            throw parseError("Option " + MetadataTracer.Options.RecordMetadata.getName() + " cannot be empty");
+        }
+
+        Map<String, String> parsedArguments = new HashMap<>();
+        Set<String> allArguments = new LinkedHashSet<>(List.of("path", "mode"));
+        for (String argument : recordMetadataValue.split(",")) {
+            String[] parts = SubstrateUtil.split(argument, "=", 2);
+            if (parts.length != 2) {
+                throw badArgumentError(argument, "Argument should be a key-value pair separated by '='");
+            } else if (!allArguments.contains(parts[0])) {
+                throw badArgumentError(argument, "Argument key should be one of " + allArguments);
+            } else if (parsedArguments.containsKey(parts[0])) {
+                throw badArgumentError(argument, "Argument '" + parts[0] + "' was already specified with value '" + parsedArguments.get(parts[0]) + "'");
+            } else if (parts[1].isEmpty()) {
+                throw badArgumentError(argument, "Argument '" + parts[0] + "' cannot be empty");
+            }
+            parsedArguments.put(parts[0], parts[1]);
+        }
+
+        String path = requiredArgument(parsedArguments, "path");
+        String mode = optionalArgument(parsedArguments, "mode", "default");
+        return new RecordOptions(Paths.get(path), parseMode(mode));
+    }
+
+    private static IllegalArgumentException parseError(String message) {
+        return new IllegalArgumentException(message + ". Sample usage: -XX:" + MetadataTracer.Options.RecordMetadata.getName() + "=path=<trace-output-directory>[,mode=<mode>]");
+    }
+
+    private static IllegalArgumentException badArgumentError(String option, String message) {
+        throw parseError("Bad argument provided for " + MetadataTracer.Options.RecordMetadata.getName() + ": '" + option + "'. " + message);
+    }
+
+    private static String requiredArgument(Map<String, String> arguments, String key) {
+        if (arguments.containsKey(key)) {
+            return arguments.get(key);
+        }
+        throw parseError(MetadataTracer.Options.RecordMetadata.getName() + " missing required argument '" + key + "'");
+    }
+
+    private static String optionalArgument(Map<String, String> options, String key, String defaultValue) {
+        if (options.containsKey(key)) {
+            return options.get(key);
+        }
+        return defaultValue;
+    }
+
+    private static RecordMode parseMode(String modeValue) {
+        try {
+            return RecordMode.valueOf(modeValue.toUpperCase(Locale.ROOT));
+        } catch (IllegalArgumentException ex) {
+            StringBuilder message = new StringBuilder("Mode should be one of [");
+            boolean first = true;
+            for (RecordMode mode : RecordMode.values()) {
+                if (first) {
+                    first = false;
+                } else {
+                    message.append(", ");
+                }
+                message.append(mode.toString().toLowerCase(Locale.ROOT));
+            }
+            message.append("]");
+            throw badArgumentError("mode=" + modeValue, message.toString());
+        }
+    }
+}
+
 @AutomaticallyRegisteredFeature
 class MetadataTracerFeature implements InternalFeature {
     @Override

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/metadata/doc-files/RecordMetadataHelp.txt

@@ -0,0 +1,9 @@
+Enables metadata tracing at run time. This option is only supported if -H:MetadataTracingSupport is enabled when building the image.
+The value of this option is a comma-separated list of arguments specified as key-value pairs. The following arguments are supported:
+
+- path=<trace-output-directory> (required): Specifies the directory to write traced metadata to.
+- mode=<tracing-mode> (optional): Specifies the tracing mode, which can be one of:
+  - default: Traces without conditions.
+  - conditional: Traces and infers conditions for each metadata element. An element (a type, resource, etc.) is only reachable in the image if the associated condition is satisfied, which can reduce image size and improve analysis results.
+
+Example usage: -H:RecordMetadata=path=tracing_output,mode=default