feat: add graceful startup error handling to Java agent

Add a `graceful:` agent argument prefix that keeps the JVM running
when the JMX exporter fails to start. The error is still logged and
any started resources are closed, but System.exit(1) is skipped.
Default behavior remains fail-fast for backward compatibility.

This only affects startup errors; scrape-time errors continue to be
reported via the jmx_scrape_error metric.

Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Jan Sykora <jan@cast.ai>

Author: jansyk13

jmx_prometheus_javaagent/src/main/java/io/prometheus/jmx/Arguments.java

@@ -55,6 +55,11 @@ public class Arguments {
      */
     private static final String DEFAULT_HOST = "0.0.0.0";
 
+    /**
+     * Prefix that enables graceful error handling for startup errors.
+     */
+    private static final String GRACEFUL_PREFIX = "graceful:";
+
     /**
      * Regular expression pattern for parsing agent arguments.
      *
@@ -102,6 +107,15 @@ public class Arguments {
      */
     private final String filename;
 
+    /**
+     * Flag indicating whether graceful error handling is enabled.
+     *
+     * <p>When {@code true}, startup errors are logged and resources are cleaned up without calling
+     * {@code System.exit(1)}. When {@code false}, the agent fails fast and exits the JVM on startup
+     * errors.
+     */
+    private final boolean gracefulErrorHandling;
+
     /**
      * Constructs an Arguments instance with the specified configuration.
      *
@@ -110,13 +124,15 @@ public class Arguments {
      *     disabled
      * @param port the port number for HTTP server, may be {@code null} when HTTP is disabled
      * @param filename the path to the configuration file, must not be {@code null}
+     * @param gracefulErrorHandling whether graceful error handling is enabled
      * @throws NullPointerException if {@code filename} is {@code null}
      */
-    private Arguments(boolean httpEnabled, String host, Integer port, String filename) {
+    private Arguments(boolean httpEnabled, String host, Integer port, String filename, boolean gracefulErrorHandling) {
         this.httpEnabled = httpEnabled;
         this.host = host;
         this.port = port;
         this.filename = Objects.requireNonNull(filename, "filename cannot be null");
+        this.gracefulErrorHandling = gracefulErrorHandling;
     }
 
     /**
@@ -169,6 +185,18 @@ public String getFilename() {
         return filename;
     }
 
+    /**
+     * Returns whether graceful error handling is enabled.
+     *
+     * <p>When {@code true}, startup errors are logged and resources are cleaned up without calling
+     * {@code System.exit(1)}.
+     *
+     * @return {@code true} if graceful error handling is enabled, {@code false} otherwise
+     */
+    public boolean isGracefulErrorHandling() {
+        return gracefulErrorHandling;
+    }
+
     /**
      * Parses the Java agent argument string into an Arguments instance.
      *
@@ -178,6 +206,9 @@ public String getFilename() {
      *   <li>{@code port:configFile} - Enables HTTP on default host (0.0.0.0) and specified port
      *   <li>{@code host:port:configFile} - Enables HTTP on specified host and port
      *   <li>{@code configFile} - Disables HTTP (only OpenTelemetry export possible via config)
+     *   <li>{@code graceful:port:configFile} - Enables HTTP and graceful error handling
+     *   <li>{@code graceful:host:port:configFile} - Enables HTTP on specified host/port and graceful error handling
+     *   <li>{@code graceful:configFile} - Disables HTTP and enables graceful error handling
      * </ul>
      *
      * <p>Host can be a hostname, IPv4 address, or IPv6 address enclosed in square brackets.
@@ -191,14 +222,64 @@ public static Arguments parse(String agentArgument) {
             throw new ConfigurationException(format("Malformed arguments [%s]", agentArgument));
         }
 
-        Pattern pattern = Pattern.compile(CONFIGURATION_REGEX);
-        Matcher matcher = pattern.matcher(agentArgument);
+        boolean gracefulErrorHandling = parseGracefulPrefix(agentArgument);
+        String remainingArgument = stripGracefulPrefix(agentArgument);
+
+        ParsedHttpArguments parsedHttpArguments = parseHttpArguments(remainingArgument);
 
+        return new Arguments(
+                parsedHttpArguments.httpEnabled,
+                parsedHttpArguments.host,
+                parsedHttpArguments.port,
+                parsedHttpArguments.filename,
+                gracefulErrorHandling);
+    }
+
+    /**
+     * Determines whether the agent argument starts with the graceful error handling prefix.
+     *
+     * @param agentArgument the agent argument string to check, must not be {@code null}
+     * @return {@code true} if the argument starts with {@code graceful:}, {@code false} otherwise
+     */
+    private static boolean parseGracefulPrefix(String agentArgument) {
+        return agentArgument.startsWith(GRACEFUL_PREFIX);
+    }
+
+    /**
+     * Strips the optional graceful error handling prefix from the agent argument.
+     *
+     * @param agentArgument the agent argument string, must not be {@code null}
+     * @return the argument string with the graceful prefix removed, if present
+     * @throws ConfigurationException if only the graceful prefix was provided
+     */
+    private static String stripGracefulPrefix(String agentArgument) {
+        if (agentArgument.startsWith(GRACEFUL_PREFIX)) {
+            String remaining = agentArgument.substring(GRACEFUL_PREFIX.length());
+            if (remaining.isEmpty()) {
+                throw new ConfigurationException(format("Malformed arguments [%s]", remaining));
+            }
+            return remaining;
+        }
+        return agentArgument;
+    }
+
+    /**
+     * Parses the host, port, and filename from the agent argument after any graceful prefix has been
+     * removed.
+     *
+     * @param agentArgument the agent argument string with graceful prefix already stripped
+     * @return a {@link ParsedHttpArguments} containing the parsed values
+     * @throws ConfigurationException if the argument is malformed
+     */
+    private static ParsedHttpArguments parseHttpArguments(String agentArgument) {
         boolean httpEnabled = false;
         String host = null;
         Integer port = null;
         String filename;
 
+        Pattern pattern = Pattern.compile(CONFIGURATION_REGEX);
+        Matcher matcher = pattern.matcher(agentArgument);
+
         if (matcher.matches()) {
             httpEnabled = true;
 
@@ -225,6 +306,24 @@ public static Arguments parse(String agentArgument) {
             filename = agentArgument;
         }
 
-        return new Arguments(httpEnabled, host, port, filename);
+        return new ParsedHttpArguments(httpEnabled, host, port, filename);
+    }
+
+    /**
+     * Simple holder for HTTP-related parsed arguments.
+     */
+    private static class ParsedHttpArguments {
+
+        final boolean httpEnabled;
+        final String host;
+        final Integer port;
+        final String filename;
+
+        ParsedHttpArguments(boolean httpEnabled, String host, Integer port, String filename) {
+            this.httpEnabled = httpEnabled;
+            this.host = host;
+            this.port = port;
+            this.filename = filename;
+        }
     }
 }

jmx_prometheus_javaagent/src/main/java/io/prometheus/jmx/JavaAgent.java

@@ -35,6 +35,7 @@
 import java.lang.instrument.Instrumentation;
 import java.lang.management.ManagementFactory;
 import java.net.InetAddress;
+import java.util.function.IntConsumer;
 
 /**
  * Java agent for the Prometheus JMX exporter.
@@ -128,8 +129,15 @@ public static void agentmain(String agentArgument, Instrumentation instrumentati
      *     invalid
      */
     public static void premain(String agentArgument, Instrumentation instrumentation) {
+        Arguments arguments;
+        try {
+            arguments = Arguments.parse(agentArgument);
+        } catch (Throwable t) {
+            handleError(t, null, null, false);
+            return;
+        }
+
         try {
-            Arguments arguments = Arguments.parse(agentArgument);
             File file = new File(arguments.getFilename());
             MapAccessor mapAccessor = MapAccessor.of(YamlSupport.loadYaml(file));
 
@@ -149,7 +157,7 @@ public static void premain(String agentArgument, Instrumentation instrumentation
                 start(arguments, file, mapAccessor);
             }
         } catch (Throwable t) {
-            handleError(t, null, null);
+            handleError(t, null, null, arguments.isGracefulErrorHandling());
         }
     }
 
@@ -174,6 +182,7 @@ public static void premain(String agentArgument, Instrumentation instrumentation
      *     {@code null}
      */
     private static void startAsync(int startDelaySeconds, Arguments arguments, File file, MapAccessor mapAccessor) {
+        boolean gracefulErrorHandling = arguments.isGracefulErrorHandling();
         Thread thread = new Thread(
                 () -> {
                     try {
@@ -183,7 +192,7 @@ private static void startAsync(int startDelaySeconds, Arguments arguments, File
                         Thread.currentThread().interrupt();
                         LOGGER.warn("Startup delay of %d seconds interrupted", startDelaySeconds);
                     } catch (Throwable t) {
-                        handleError(t, null, null);
+                        handleError(t, null, null, gracefulErrorHandling);
                     }
                 },
                 THREAD_NAME);
@@ -249,7 +258,7 @@ static void start(Arguments arguments, File file, MapAccessor mapAccessor) {
 
             LOGGER.info("Running ...");
         } catch (Throwable t) {
-            handleError(t, openTelemetryExporter, httpServer);
+            handleError(t, openTelemetryExporter, httpServer, arguments.isGracefulErrorHandling());
         }
     }
 
@@ -306,36 +315,64 @@ private static OpenTelemetryExporter startOpenTelemetryExporter(File file) throw
     }
 
     /**
-     * Handles a startup failure by logging the error and cleaning up resources.
+     * Handles a startup failure by logging the error, cleaning up resources, and optionally exiting
+     * the JVM.
      *
-     * <p>This method:
+     * <p>When {@code gracefulErrorHandling} is {@code false}, this method prints the error, closes
+     * resources, and calls {@code System.exit(1)}. When {@code gracefulErrorHandling} is {@code
+     * true}, it prints the error and closes resources but does not exit the JVM.
      *
-     * <ul>
-     *   <li>Prints the error stack trace to stderr (synchronized to prevent interleaving)
-     *   <li>Closes any started resources (OpenTelemetry exporter, HTTP server)
-     *   <li>Exits the JVM with status code 1
-     * </ul>
+     * @param t the throwable that caused the failure, may be {@code null}
+     * @param openTelemetryExporter the OpenTelemetry exporter to close, may be {@code null}
+     * @param httpServer the HTTP server to close, may be {@code null}
+     * @param gracefulErrorHandling whether to skip the JVM exit
+     */
+    private static void handleError(
+            Throwable t,
+            OpenTelemetryExporter openTelemetryExporter,
+            HTTPServer httpServer,
+            boolean gracefulErrorHandling) {
+        handleError(t, openTelemetryExporter, httpServer, gracefulErrorHandling, System::exit);
+    }
+
+    /**
+     * Handles a startup failure by logging the error, cleaning up resources, and optionally exiting
+     * the JVM.
      *
-     * <p>This method never returns; it always calls {@code System.exit(1)}.
+     * <p>This overload allows tests to inject an exit action instead of calling {@link
+     * System#exit(int)}.
      *
      * @param t the throwable that caused the failure, may be {@code null}
      * @param openTelemetryExporter the OpenTelemetry exporter to close, may be {@code null}
      * @param httpServer the HTTP server to close, may be {@code null}
+     * @param gracefulErrorHandling if {@code true}, log and clean up without exiting the JVM
+     * @param exit the exit action to invoke when not in graceful mode
      */
-    private static void handleError(Throwable t, OpenTelemetryExporter openTelemetryExporter, HTTPServer httpServer) {
+    static void handleError(
+            Throwable t,
+            OpenTelemetryExporter openTelemetryExporter,
+            HTTPServer httpServer,
+            boolean gracefulErrorHandling,
+            IntConsumer exit) {
         synchronized (System.err) {
             System.err.println("Failed to start Prometheus JMX Exporter ...");
             System.err.println();
             t.printStackTrace(System.err);
             System.err.println();
-            System.err.println("Prometheus JMX Exporter exiting");
+            if (gracefulErrorHandling) {
+                System.err.println("Prometheus JMX Exporter continuing in graceful error handling mode");
+            } else {
+                System.err.println("Prometheus JMX Exporter exiting");
+            }
             System.err.flush();
         }
 
         close(openTelemetryExporter);
         close(httpServer);
 
-        System.exit(1);
+        if (!gracefulErrorHandling) {
+            exit.accept(1);
+        }
     }
 
     /**