pr review

Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

Author: jaydeluca

docs/content/getting-started/registry.md

@@ -6,7 +6,7 @@ weight: 2
 In order to expose metrics, you need to register them with a `PrometheusRegistry`. We are using a
 counter as an example here, but the `register()` method is the same for all metric types.
 
-## Registering a Metrics with the Default Registry
+## Registering a Metric with the Default Registry
 
 ```java
 Counter eventsTotal = Counter.builder()
@@ -18,7 +18,7 @@ Counter eventsTotal = Counter.builder()
 The `register()` call above builds the counter and registers it with the global static
 `PrometheusRegistry.defaultRegistry`. Using the default registry is recommended.
 
-## Registering a Metrics with a Custom Registry
+## Registering a Metric with a Custom Registry
 
 You can also register your metric with a custom registry:
 
@@ -84,17 +84,24 @@ Validation of duplicate metric names and label schemas happens at registration t
 Built-in metrics (Counter, Gauge, Histogram, etc.) participate in this validation.
 
 Custom collectors that implement the `Collector` or `MultiCollector` interface can optionally
-implement `getMetricType()` and `getLabelNames()` (or the MultiCollector per-name variants) so the
-registry can enforce consistency. If those methods return `null`, the registry does not validate
-that collector. If two such collectors produce the same metric name and same label set at scrape
-time, the exposition output may contain duplicate time series and be invalid for Prometheus.
+implement `getPrometheusName()` and `getMetricType()` (and the MultiCollector per-name variants) so
+the registry can enforce consistency. **Validation is skipped when metric name or type is
+unavailable:** if `getPrometheusName()` or `getMetricType()` returns `null`, the registry does not
+validate that collector. If two such collectors produce the same metric name and same label set at
+scrape time, the exposition output may contain duplicate time series and be invalid for Prometheus.
+
+When validation *is* performed (name and type are non-null), **null label names are treated as an
+empty label schema:** `getLabelNames()` returning `null` is normalized to `Collections.emptySet()`
+and full label-schema validation and duplicate detection still apply. A collector that returns a
+non-null type but leaves `getLabelNames()` as `null` is still validated, with its labels treated as
+empty.
 
 ## Unregistering a Metric
 
 There is no automatic expiry of unused metrics (yet), once a metric is registered it will remain
 registered forever.
 
-However, you can programmatically unregistered an obsolete metric like this:
+However, you can programmatically unregister an obsolete metric like this:
 
 ```java
 PrometheusRegistry.defaultRegistry.unregister(eventsTotal);

mise.toml

@@ -1,7 +1,7 @@
 [tools]
 "go:github.com/gohugoio/hugo" = "v0.155.0"
 "go:github.com/grafana/oats" = "0.6.0"
-java = "temurin-25.0.1+8.0.LTS"
+java = "temurin-25.0.2+10.0.LTS"
 lychee = "0.22.0"
 protoc = "33.4"
 

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/Collector.java

@@ -109,14 +109,13 @@ default MetricType getMetricType() {
    * same metric name. Two collectors with the same name and type can coexist if they have different
    * label name sets.
    *
-   * <p>Returning {@code null} means label schema validation is skipped for this collector.
+   * <p>Returning {@code null} is treated as an empty label set: the registry normalizes it to
+   * {@code Collections.emptySet()} and performs full label-schema validation and duplicate
+   * detection. Two collectors with the same name, type, and {@code null} (or empty) label names are
+   * considered duplicate and registration of the second will fail.
    *
-   * <p>Validation is performed only at registration time. If this method returns {@code null}, no
-   * label-schema validation is performed for this collector. If such a collector produces the same
-   * metric name and label schema as another at scrape time, the exposition may contain duplicate
-   * time series, which is invalid in Prometheus.
-   *
-   * @return the set of all label names, or {@code null} to skip validation
+   * @return the set of all label names, or {@code null} (treated as empty) for a metric with no
+   *     labels
    */
   @Nullable
   default Set<String> getLabelNames() {

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MultiCollector.java

@@ -100,16 +100,14 @@ default MetricType getMetricType(String prometheusName) {
    * <p>This is used for per-name label schema validation during registration. Two collectors with
    * the same name and type can coexist if they have different label name sets.
    *
-   * <p>Returning {@code null} means label schema validation is skipped for that specific metric
-   * name.
-   *
-   * <p>Validation is performed only at registration time. If this method returns {@code null}, no
-   * label-schema validation is performed for that name. If such a collector produces the same
-   * metric name and label schema as another at scrape time, the exposition may contain duplicate
-   * time series, which is invalid in Prometheus.
+   * <p>Returning {@code null} is treated as an empty label set: the registry normalizes it to
+   * {@code Collections.emptySet()} and performs full label-schema validation and duplicate
+   * detection. Two collectors with the same name, type, and {@code null} (or empty) label names are
+   * considered duplicate and registration of the second will fail.
    *
    * @param prometheusName the Prometheus metric name
-   * @return the set of all label names for the given name, or {@code null} to skip validation
+   * @return the set of all label names for the given name, or {@code null} (treated as empty) for a
+   *     metric with no labels
    */
   @Nullable
   default Set<String> getLabelNames(String prometheusName) {

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusRegistry.java

@@ -154,63 +154,69 @@ private static Set<String> immutableLabelNames(@Nullable Set<String> labelNames)
   }
 
   public void register(Collector collector) {
-    if (collectors.contains(collector)) {
+    if (!collectors.add(collector)) {
       throw new IllegalArgumentException("Collector instance is already registered");
     }
-
-    String prometheusName = collector.getPrometheusName();
-    MetricType metricType = collector.getMetricType();
-    Set<String> normalizedLabels = immutableLabelNames(collector.getLabelNames());
-    MetricMetadata metadata = collector.getMetadata();
-    String help = metadata != null ? metadata.getHelp() : null;
-    Unit unit = metadata != null ? metadata.getUnit() : null;
-
-    // Only perform validation if collector provides sufficient metadata.
-    // Collectors that don't implement getPrometheusName()/getMetricType() will skip validation.
-    if (prometheusName != null && metricType != null) {
-      final String name = prometheusName;
-      final MetricType type = metricType;
-      final Set<String> names = normalizedLabels;
-      final String helpForValidation = help;
-      final Unit unitForValidation = unit;
-      registered.compute(
-          prometheusName,
-          (n, existingInfo) -> {
-            if (existingInfo == null) {
-              return RegistrationInfo.of(type, names, helpForValidation, unitForValidation);
-            } else {
-              if (existingInfo.getType() != type) {
-                throw new IllegalArgumentException(
-                    name
-                        + ": Conflicting metric types. Existing: "
-                        + existingInfo.getType()
-                        + ", new: "
-                        + type);
-              }
-              existingInfo.validateMetadata(helpForValidation, unitForValidation);
-              if (!existingInfo.addLabelSet(names)) {
-                throw new IllegalArgumentException(
-                    name + ": duplicate metric name with identical label schema " + names);
+    try {
+      String prometheusName = collector.getPrometheusName();
+      MetricType metricType = collector.getMetricType();
+      Set<String> normalizedLabels = immutableLabelNames(collector.getLabelNames());
+      MetricMetadata metadata = collector.getMetadata();
+      String help = metadata != null ? metadata.getHelp() : null;
+      Unit unit = metadata != null ? metadata.getUnit() : null;
+
+      // Only perform validation if collector provides sufficient metadata.
+      // Collectors that don't implement getPrometheusName()/getMetricType() will skip validation.
+      if (prometheusName != null && metricType != null) {
+        final String name = prometheusName;
+        final MetricType type = metricType;
+        final Set<String> names = normalizedLabels;
+        final String helpForValidation = help;
+        final Unit unitForValidation = unit;
+        registered.compute(
+            prometheusName,
+            (n, existingInfo) -> {
+              if (existingInfo == null) {
+                return RegistrationInfo.of(type, names, helpForValidation, unitForValidation);
+              } else {
+                if (existingInfo.getType() != type) {
+                  throw new IllegalArgumentException(
+                      name
+                          + ": Conflicting metric types. Existing: "
+                          + existingInfo.getType()
+                          + ", new: "
+                          + type);
+                }
+                existingInfo.validateMetadata(helpForValidation, unitForValidation);
+                if (!existingInfo.addLabelSet(names)) {
+                  throw new IllegalArgumentException(
+                      name + ": duplicate metric name with identical label schema " + names);
+                }
+                return existingInfo;
               }
-              return existingInfo;
-            }
-          });
+            });
 
-      collectorMetadata.put(collector, new CollectorRegistration(prometheusName, normalizedLabels));
-    }
+        collectorMetadata.put(
+            collector, new CollectorRegistration(prometheusName, normalizedLabels));
+      }
 
-    if (prometheusName != null) {
-      prometheusNames.add(prometheusName);
+      if (prometheusName != null) {
+        prometheusNames.add(prometheusName);
+      }
+    } catch (Exception e) {
+      collectors.remove(collector);
+      CollectorRegistration reg = collectorMetadata.remove(collector);
+      if (reg != null && reg.prometheusName != null) {
+        unregisterLabelSchema(reg.prometheusName, reg.labelNames);
+      }
+      throw e;
     }
-
-    collectors.add(collector);
   }
 
   public void register(MultiCollector collector) {
-    if (multiCollectors.contains(collector)) {
+    if (!multiCollectors.add(collector)) {
       throw new IllegalArgumentException("MultiCollector instance is already registered");
     }
-
     List<String> prometheusNamesList = collector.getPrometheusNames();
     List<MultiCollectorRegistration> registrations = new ArrayList<>();
     Set<String> namesOnlyInPrometheusNames = new HashSet<>();
@@ -264,8 +270,8 @@ public void register(MultiCollector collector) {
       }
 
       multiCollectorMetadata.put(collector, registrations);
-      multiCollectors.add(collector);
     } catch (Exception e) {
+      multiCollectors.remove(collector);
       for (MultiCollectorRegistration registration : registrations) {
         unregisterLabelSchema(registration.prometheusName, registration.labelNames);
       }

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/MetricSnapshots.java

@@ -29,7 +29,8 @@ public MetricSnapshots(MetricSnapshot... snapshots) {
    *
    * @param snapshots the constructor creates a sorted copy of snapshots.
    * @throws IllegalArgumentException if snapshots contain conflicting metric types (same name but
-   *     different metric types like Counter vs Gauge).
+   *     different metric types like Counter vs Gauge), or if two HistogramSnapshots share a name
+   *     but differ in gauge histogram vs classic histogram.
    */
   public MetricSnapshots(Collection<MetricSnapshot> snapshots) {
     List<MetricSnapshot> list = new ArrayList<>(snapshots);

prometheus-metrics-model/src/test/java/io/prometheus/metrics/model/registry/PrometheusRegistryTest.java

@@ -256,6 +256,68 @@ public Set<String> getLabelNames() {
         .hasMessageContaining("duplicate metric name with identical label schema");
   }
 
+  @Test
+  void register_duplicateLabelSchema_rollsBackCollectorOnFailure() {
+    PrometheusRegistry registry = new PrometheusRegistry();
+
+    Collector counter1 =
+        new Collector() {
+          @Override
+          public MetricSnapshot collect() {
+            return CounterSnapshot.builder().name("http_requests").build();
+          }
+
+          @Override
+          public String getPrometheusName() {
+            return "http_requests";
+          }
+
+          @Override
+          public MetricType getMetricType() {
+            return MetricType.COUNTER;
+          }
+
+          @Override
+          public Set<String> getLabelNames() {
+            return new HashSet<>(asList("path", "status"));
+          }
+        };
+
+    Collector counter2 =
+        new Collector() {
+          @Override
+          public MetricSnapshot collect() {
+            return CounterSnapshot.builder().name("http_requests").build();
+          }
+
+          @Override
+          public String getPrometheusName() {
+            return "http_requests";
+          }
+
+          @Override
+          public MetricType getMetricType() {
+            return MetricType.COUNTER;
+          }
+
+          @Override
+          public Set<String> getLabelNames() {
+            return new HashSet<>(asList("path", "status"));
+          }
+        };
+
+    registry.register(counter1);
+
+    // Second collector has same name and label schema - registration fails during metadata
+    // validation. The failed collector must be rolled back (not present in the registry).
+    assertThatThrownBy(() -> registry.register(counter2))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("duplicate metric name with identical label schema");
+
+    // Only the first collector should be in the registry; counter2 was removed on rollback.
+    assertThat(registry.scrape().size()).isEqualTo(1);
+  }
+
   @Test
   void register_nullType_skipsValidation() {
     PrometheusRegistry registry = new PrometheusRegistry();