IllegalArgumentException: metric name cannot contain whitespace when registering custom metrics

Why the exception occurs

Dropwizard’s MetricRegistry.register(String name, Metric metric) validates the supplied name via MetricName.build. The builder throws IllegalArgumentException: metric name cannot contain whitespace if any character in the name satisfies Character.isWhitespace (space, tab, newline, etc.). This behavior is documented in the MetricRegistry Javadoc and is the root cause of the 400 responses from the /metrics endpoint when malformed names are registered.

Confirmed facts

• Prometheus metric names must match the regex [a-zA-Z_:][a-zA-Z0-9_:]* and therefore cannot contain spaces.
• Dropwizard does not provide a built‑in aliasing or automatic transformation for metric names; the developer must sanitize the identifier before registration.
• Dropwizard’s MetricName supports tags (labels) that are exported by the Prometheus reporter as Prometheus labels.

Steps to resolve the issue

1. Sanitize the metric identifier – replace spaces with an underscore, camelCase, or any other Prometheus‑safe pattern. Example:

String safeName = "Request Latency Seconds".replaceAll("\\s+", "_"); // request_latency_seconds

1. Register the metric using the sanitized name and attach the original, human‑readable string as a tag:

MetricName metricName = MetricName.builder()
    .name(safeName)                     // Prometheus‑safe identifier
    .tag("display_name", "Request Latency Seconds") // human‑readable label
    .build();

metricRegistry.register(metricName, new Histogram());

1. Verify the export – if you are using the Dropwizard Prometheus reporter (io.dropwizard.metrics5:metrics-prometheus), the tag will appear as a Prometheus label, e.g.:

# HELP request_latency_seconds Request Latency Seconds
# TYPE request_latency_seconds histogram
request_latency_seconds{display_name="Request Latency Seconds"} ...

Missing diagnostic detail

The above steps assume you are exposing metrics via the Dropwizard Prometheus reporter. If you are using a different reporter or a custom endpoint, the tag may not be exported. Are you using the Dropwizard Prometheus reporter to serve the /metrics endpoint? Your answer will determine whether the tag‑based approach is sufficient or if you need to adjust your reporter configuration.