fix: hide HTTP scrape error details (#2332)

## Summary

- return a generic HTTP 500 body instead of exposing exception details
- include a safe hint explaining how to enable better diagnostics
- avoid adding server-side logging by default
- let users explicitly opt into either detailed HTTP responses or
server-side error reporting
- verify the secure default does not expose the exception type or
message

This is the focused replacement for the #2283 portion of #2297.

Fixes #2283

## Implementation plan

1. Make `HttpErrorHandlingPolicy` builder-based and pass the built
policy through the `HTTPServer` builder to the exchange adapter.
Response verbosity and error reporting remain orthogonal choices.
2. Make the default policy return a generic HTTP 500 response with a
short hint to configure server-side error reporting for diagnostic
details. The default must not add a new log entry for the scrape
exception.
3. Let callers configure either axis independently:
- attach a caller-supplied error reporter while keeping the generic
response, so applications and Java agents can route diagnostics to an
appropriate sink; and
- enable an explicitly unsafe debug response mode that includes
exception details in the HTTP body. Avoid “legacy” naming; the API and
docs must make the disclosure risk clear.
4. Preserve the existing logging behavior for failures where the error
response itself cannot be sent or response headers were already
committed, because no useful client response remains possible in those
paths.
5. Add focused tests for the secure default, diagnostic hint,
independent verbosity/reporter configuration, reporter invocation and
isolation, reporter failure handling, and the explicitly unsafe
debug-response mode. Add user documentation for the available policies
and their security tradeoffs, plus the repository’s release-please
changelog entry linking to that documentation.

## Alternatives considered

- **Unconditional server-side logging:** rejected because it replaces
the response disclosure with a new operational regression: one stack
trace per failed scrape, with possible log-ingestion cost and
application-logging side effects for unshaded integrations.
- **Keep the detailed response as the default:** rejected because it
does not remediate #2283 unless every user discovers and enables the
secure mode.
- **Generic response with no diagnostic guidance:** rejected because it
leaves operators with a silent, unexplained HTTP 500 and no discoverable
path to better diagnostics.
- **Hard-code rate limiting or deduplication in the adapter:** deferred
in favor of a reporter abstraction. Correct suppression requires bounded
state, concurrency handling, distinct-failure classification, and
suppressed-count reporting; callers or a later reusable reporter can
implement that policy without coupling it to HTTP response handling.
- **Ambient debug/verbosity configuration:** rejected in favor of an
explicit builder option on `HttpErrorHandlingPolicy`, so re-enabling
unsafe debug responses is deliberate and carries a clear security
warning.
- **Network controls or authentication documentation alone:** rejected
as the primary fix. They remain useful defense in depth but should not
substitute for a safe default response.

## Validation

- `mise run lint:fix`
- `mise run build`
- `./mvnw test -pl prometheus-metrics-exporter-httpserver
-Dcoverage.skip=true -Dcheckstyle.skip=true`



## Release note

Release Please will use this override for the generated changelog and
GitHub release notes after a squash merge:

BEGIN_COMMIT_OVERRIDE
fix(httpserver): make scrape error responses secure and configurable

Scrape failures now return a generic HTTP 500 response by default.
Applications can configure a server-side error reporter or explicitly
enable an unsafe debug response containing exception details. See the
[HTTPServer scrape error handling
documentation](https://github.com/prometheus/client_java/blob/main/docs/content/exporters/httpserver.md#scrape-error-handling).
END_COMMIT_OVERRIDE

---------

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

docs/apidiffs/current_vs_latest/prometheus-metrics-exporter-httpserver.txt

@@ -26,6 +26,54 @@ or [inetAddress()](</client_java/api/io/prometheus/metrics/exporter/httpserver/H
 The default handler can be changed
 with [defaultHandler()](</client_java/api/io/prometheus/metrics/exporter/httpserver/HTTPServer.Builder.html#defaultHandler(com.sun.net.httpserver.HttpHandler)>).
 
+## Scrape error handling
+
+By default, scrape failures return a generic HTTP 500 response. Exception details are not
+included in the response, and are not logged when the error response can be delivered, because
+the server may run inside an application or a Java agent with its own diagnostic pipeline. If the
+error response itself cannot be delivered, the transport failure is logged because no useful
+client response remains possible.
+
+Configure a reporter to send exception details to an appropriate logging or telemetry sink:
+
+```java
+HTTPServer server = HTTPServer.builder()
+  .port(9400)
+  .errorHandlingPolicy(
+    HttpErrorHandlingPolicy.builder()
+      .errorReporter(error -> logger.log(Level.SEVERE, "Prometheus scrape failed", error))
+      .build())
+  .buildAndStart();
+```
+
+The reporter runs synchronously on the request thread and may be called concurrently. Reporter
+runtime exceptions do not prevent the generic HTTP 500 response from being sent. Rate limiting
+or deduplication can be implemented in the reporter when needed.
+
+For applications using Java Util Logging, the synchronous reporter can be enabled explicitly:
+
+```java
+HttpErrorHandlingPolicy.builder()
+  .errorReporter(HttpErrorHandlingPolicy.julReporter())
+  .build()
+```
+
+This logs scrape exceptions at `SEVERE`. It is intentionally opt-in so applications and Java
+agents do not receive an implicit logging side effect.
+
+For local debugging, an unsafe response containing the full exception stack trace can be enabled
+explicitly:
+
+```java
+HttpErrorHandlingPolicy.builder()
+  .unsafeDebugResponse(true)
+  .build()
+```
+
+This setting is independent of the error reporter, so both can be configured when needed. The
+unsafe debug response can disclose application internals and must not be enabled for an endpoint
+reachable by untrusted clients.
+
 ## Authentication and HTTPS
 
 - [authenticator()](</client_java/api/io/prometheus/metrics/exporter/httpserver/HTTPServer.Builder.html#authenticator(com.sun.net.httpserver.Authenticator)>)

docs/content/exporters/httpserver.md

@@ -157,7 +157,11 @@ void testErrorHandling() throws IOException {
     start("error");
     Response response = scrape("GET", "");
     assertThat(response.status).isEqualTo(500);
-    assertThat(response.stringBody()).contains("Simulating an error.");
+    assertErrorResponseBody(response.stringBody());
+  }
+
+  protected void assertErrorResponseBody(String body) {
+    assertThat(body).contains("Simulating an error.");
   }
 
   @Test

integration-tests/it-exporter/it-exporter-test/src/test/java/io/prometheus/metrics/it/exporter/test/ExporterIT.java

@@ -1,10 +1,21 @@
 package io.prometheus.metrics.it.exporter.test;
 
+import static org.assertj.core.api.Assertions.assertThat;
+
 import java.io.IOException;
 import java.net.URISyntaxException;
 
 class HttpServerIT extends ExporterIT {
   public HttpServerIT() throws IOException, URISyntaxException {
     super("exporter-httpserver-sample");
   }
+
+  @Override
+  protected void assertErrorResponseBody(String body) {
+    assertThat(body)
+        .isEqualTo(
+            "An internal error occurred while scraping metrics. "
+                + "Configure an HTTP error reporter for details.\n")
+        .doesNotContain("Simulating an error.");
+  }
 }

integration-tests/it-exporter/it-exporter-test/src/test/java/io/prometheus/metrics/it/exporter/test/HttpServerIT.java

@@ -61,7 +61,8 @@ private HTTPServer(
       @Nullable String authenticatedSubjectAttributeName,
       @Nullable HttpHandler defaultHandler,
       @Nullable String metricsHandlerPath,
-      @Nullable Boolean registerHealthHandler) {
+      @Nullable Boolean registerHealthHandler,
+      HttpErrorHandlingPolicy errorHandlingPolicy) {
     if (httpServer.getAddress() == null) {
       throw new IllegalArgumentException("HttpServer hasn't been bound to an address");
     }
@@ -85,7 +86,7 @@ private HTTPServer(
     }
     registerHandler(
         metricsPath,
-        new MetricsHandler(config, registry),
+        new MetricsHandler(config, registry, errorHandlingPolicy),
         authenticator,
         authenticatedSubjectAttributeName);
     if (registerHealthHandler == null || registerHealthHandler) {
@@ -211,6 +212,7 @@ public static class Builder {
     @Nullable private HttpHandler defaultHandler = null;
     @Nullable private String metricsHandlerPath = null;
     @Nullable private Boolean registerHealthHandler = null;
+    private HttpErrorHandlingPolicy errorHandlingPolicy = HttpErrorHandlingPolicy.builder().build();
 
     private Builder(PrometheusProperties config) {
       this.config = config;
@@ -295,6 +297,20 @@ public Builder registerHealthHandler(boolean registerHealthHandler) {
       return this;
     }
 
+    /**
+     * Configure how exceptions raised while scraping metrics are reported to the client and
+     * optionally to a caller-supplied diagnostic sink.
+     *
+     * <p>Default is {@code HttpErrorHandlingPolicy.builder().build()}.
+     */
+    public Builder errorHandlingPolicy(HttpErrorHandlingPolicy errorHandlingPolicy) {
+      if (errorHandlingPolicy == null) {
+        throw new NullPointerException("errorHandlingPolicy");
+      }
+      this.errorHandlingPolicy = errorHandlingPolicy;
+      return this;
+    }
+
     /** Build and start the HTTPServer. */
     public HTTPServer buildAndStart() throws IOException {
       if (registry == null) {
@@ -318,7 +334,8 @@ public HTTPServer buildAndStart() throws IOException {
           authenticatedSubjectAttributeName,
           defaultHandler,
           metricsHandlerPath,
-          registerHealthHandler);
+          registerHealthHandler,
+          errorHandlingPolicy);
     }
 
     private InetSocketAddress makeInetSocketAddress() {

prometheus-metrics-exporter-httpserver/src/main/java/io/prometheus/metrics/exporter/httpserver/HTTPServer.java

@@ -0,0 +1,120 @@
+package io.prometheus.metrics.exporter.httpserver;
+
+import io.prometheus.metrics.annotations.StableApi;
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.nio.charset.StandardCharsets;
+import java.util.function.Consumer;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import javax.annotation.Nullable;
+
+/**
+ * Controls how the {@link HTTPServer} handles exceptions raised while scraping metrics.
+ *
+ * <p>The default policy built by {@link #builder()} does not expose exception details and does not
+ * report the exception. Configure the builder to route diagnostic details to an
+ * application-appropriate sink.
+ */
+@StableApi
+public final class HttpErrorHandlingPolicy {
+
+  private static final Logger logger = Logger.getLogger(HttpErrorHandlingPolicy.class.getName());
+
+  private static final byte[] GENERIC_RESPONSE =
+      ("An internal error occurred while scraping metrics. "
+              + "Configure an HTTP error reporter for details.\n")
+          .getBytes(StandardCharsets.UTF_8);
+
+  private final boolean unsafeDebugResponse;
+  @Nullable private final Consumer<? super Exception> errorReporter;
+
+  private HttpErrorHandlingPolicy(
+      boolean unsafeDebugResponse, @Nullable Consumer<? super Exception> errorReporter) {
+    this.unsafeDebugResponse = unsafeDebugResponse;
+    this.errorReporter = errorReporter;
+  }
+
+  /**
+   * Returns a builder for configuring scrape error handling.
+   *
+   * <p>The builder defaults to a generic HTTP 500 response with no error reporter. This avoids
+   * exposing exception details to scrape clients or adding an implicit dependency on an
+   * application's logging configuration.
+   */
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  byte[] getErrorResponse(Exception exception) {
+    if (!unsafeDebugResponse) {
+      return GENERIC_RESPONSE;
+    }
+    StringWriter stringWriter = new StringWriter();
+    PrintWriter printWriter = new PrintWriter(stringWriter);
+    printWriter.write("An Exception occurred while scraping metrics: ");
+    exception.printStackTrace(printWriter);
+    return stringWriter.toString().getBytes(StandardCharsets.UTF_8);
+  }
+
+  void report(Exception error) {
+    if (errorReporter != null) {
+      errorReporter.accept(error);
+    }
+  }
+
+  boolean hasErrorReporter() {
+    return errorReporter != null;
+  }
+
+  /**
+   * Returns a synchronous reporter that logs scrape exceptions at {@link Level#SEVERE} using JUL.
+   *
+   * <p>Reporting is opt-in; the default policy does not log scrape exceptions.
+   */
+  public static Consumer<Throwable> julReporter() {
+    return error -> logger.log(Level.SEVERE, "Prometheus scrape failed", error);
+  }
+
+  /** Builder for {@link HttpErrorHandlingPolicy}. */
+  public static final class Builder {
+
+    private boolean unsafeDebugResponse = false;
+    @Nullable private Consumer<? super Exception> errorReporter;
+
+    private Builder() {}
+
+    /**
+     * Pass scrape exceptions to {@code errorReporter}.
+     *
+     * <p>The reporter runs synchronously on the HTTP request thread. It should return promptly and
+     * must be safe to call concurrently. Runtime exceptions thrown by the reporter are isolated
+     * from HTTP response handling.
+     */
+    public Builder errorReporter(Consumer<? super Exception> errorReporter) {
+      if (errorReporter == null) {
+        throw new NullPointerException("errorReporter");
+      }
+      this.errorReporter = errorReporter;
+      return this;
+    }
+
+    /**
+     * Configure whether the HTTP 500 response includes the full exception stack trace.
+     *
+     * <p><strong>Security warning:</strong> Setting this to {@code true} exposes internal exception
+     * information to scrape clients. Do not enable it for endpoints reachable by untrusted clients.
+     *
+     * <p>This setting is independent of {@link #errorReporter(Consumer)}.
+     */
+    public Builder unsafeDebugResponse(boolean unsafeDebugResponse) {
+      this.unsafeDebugResponse = unsafeDebugResponse;
+      return this;
+    }
+
+    /** Build the policy. */
+    public HttpErrorHandlingPolicy build() {
+      return new HttpErrorHandlingPolicy(unsafeDebugResponse, errorReporter);
+    }
+  }
+}