Allow metrics with the same name different labels (#1800)

Closes #696

Alternate approach to #1728 

Validation occurs at registration time:

- Metrics with the same name, type, unit, and help - but different
labels, are allowed to be registered
- Custom Collectors that do not implement the required fields
(prometheus name, metric type) will skip validation and could risk
creating duplicate series that will cause issues at scrape time.
- I looked into adding a fallback, but it requires calling `collect()`
at registration in order to introspect existing metadata and that seemed
not great due to potential side effects

---------

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

Author: jaydeluca

.gitignore

@@ -24,3 +24,5 @@ docs/public
 benchmark-results/
 benchmark-results.json
 benchmark-output.log
+
+*.DS_Store

docs/content/getting-started/metric-types.md

@@ -364,3 +364,6 @@ in the `prometheus-metrics-core` API.
 However, `prometheus-metrics-model` implements the underlying data model for these types.
 To use these types, you need to implement your own `Collector` where the `collect()` method returns
 an `UnknownSnapshot` or a `HistogramSnapshot` with `.gaugeHistogram(true)`.
+If your custom collector does not implement `getMetricType()` and `getLabelNames()`, ensure it does
+not produce the same metric name and label set as another collector, or the exposition may contain
+duplicate time series.

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:
 
@@ -78,12 +78,30 @@ Counter eventsTotal2 = Counter.builder()
     .register(); // IllegalArgumentException, because a metric with that name is already registered
 ```
 
+## Validation at registration only
+
+Validation of duplicate metric names and label schemas happens at registration time only.
+Built-in metrics (Counter, Gauge, Histogram, etc.) participate in this validation.
+
+Custom collectors that implement the `Collector` or `MultiCollector` interface can optionally
+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);

docs/content/internals/model.md

@@ -19,7 +19,10 @@ All metric types implement
 the [Collector](/client_java/api/io/prometheus/metrics/model/registry/Collector.html) interface,
 i.e. they provide
 a [collect()](</client_java/api/io/prometheus/metrics/model/registry/Collector.html#collect()>)
-method to produce snapshots.
+method to produce snapshots. Implementers that do not provide metric type or label names (returning
+null from `getMetricType()` and `getLabelNames()`) are not validated at registration; they must
+avoid producing the same metric name and label schema as another collector, or exposition may be
+invalid.
 
 ## prometheus-metrics-model
 

integration-tests/it-common/src/test/java/io/prometheus/client/it/common/ExporterTest.java

@@ -24,7 +24,7 @@
 import org.testcontainers.containers.GenericContainer;
 
 public abstract class ExporterTest {
-  private final GenericContainer<?> sampleAppContainer;
+  protected final GenericContainer<?> sampleAppContainer;
   private final Volume sampleAppVolume;
   protected final String sampleApp;
 

integration-tests/it-exporter/it-exporter-duplicate-metrics-sample/pom.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>io.prometheus</groupId>
+    <artifactId>it-exporter</artifactId>
+    <version>1.5.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>it-exporter-duplicate-metrics-sample</artifactId>
+
+  <name>Integration Tests - Duplicate Metrics Sample</name>
+  <description>
+    HTTPServer Sample demonstrating duplicate metric names with different label sets
+  </description>
+
+  <dependencies>
+    <dependency>
+      <groupId>io.prometheus</groupId>
+      <artifactId>prometheus-metrics-exporter-httpserver</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>io.prometheus</groupId>
+      <artifactId>prometheus-metrics-core</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <finalName>exporter-duplicate-metrics-sample</finalName>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-shade-plugin</artifactId>
+        <executions>
+          <execution>
+            <phase>package</phase>
+            <goals>
+              <goal>shade</goal>
+            </goals>
+            <configuration>
+              <transformers>
+                <transformer
+                  implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                  <mainClass>
+                    io.prometheus.metrics.it.exporter.duplicatemetrics.DuplicateMetricsSample
+                  </mainClass>
+                </transformer>
+              </transformers>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>

integration-tests/it-exporter/it-exporter-duplicate-metrics-sample/src/main/java/io/prometheus/metrics/it/exporter/duplicatemetrics/DuplicateMetricsSample.java

@@ -0,0 +1,91 @@
+package io.prometheus.metrics.it.exporter.duplicatemetrics;
+
+import io.prometheus.metrics.core.metrics.Counter;
+import io.prometheus.metrics.core.metrics.Gauge;
+import io.prometheus.metrics.exporter.httpserver.HTTPServer;
+import io.prometheus.metrics.model.snapshots.Unit;
+import java.io.IOException;
+
+/** Integration test sample demonstrating metrics with duplicate names but different label sets. */
+public class DuplicateMetricsSample {
+
+  public static void main(String[] args) throws IOException, InterruptedException {
+    if (args.length != 2) {
+      System.err.println("Usage: java -jar duplicate-metrics-sample.jar <port> <outcome>");
+      System.err.println("Where outcome is \"success\" or \"error\".");
+      System.exit(1);
+    }
+
+    int port = parsePortOrExit(args[0]);
+    String outcome = args[1];
+    run(port, outcome);
+  }
+
+  private static void run(int port, String outcome) throws IOException, InterruptedException {
+    // Register multiple counters with the same Prometheus name "http_requests_total"
+    // but different label sets
+    Counter requestsSuccess =
+        Counter.builder()
+            .name("http_requests_total")
+            .help("Total HTTP requests by status")
+            .labelNames("status", "method")
+            .register();
+    requestsSuccess.labelValues("success", "GET").inc(150);
+    requestsSuccess.labelValues("success", "POST").inc(45);
+
+    Counter requestsError =
+        Counter.builder()
+            .name("http_requests_total")
+            .help("Total HTTP requests by status")
+            .labelNames("status", "endpoint")
+            .register();
+    requestsError.labelValues("error", "/api").inc(5);
+    requestsError.labelValues("error", "/health").inc(2);
+
+    // Register multiple gauges with the same Prometheus name "active_connections"
+    // but different label sets
+    Gauge connectionsByRegion =
+        Gauge.builder()
+            .name("active_connections")
+            .help("Active connections")
+            .labelNames("region", "protocol")
+            .register();
+    connectionsByRegion.labelValues("us-east", "http").set(42);
+    connectionsByRegion.labelValues("us-west", "http").set(38);
+    connectionsByRegion.labelValues("eu-west", "https").set(55);
+
+    Gauge connectionsByPool =
+        Gauge.builder()
+            .name("active_connections")
+            .help("Active connections")
+            .labelNames("pool", "type")
+            .register();
+    connectionsByPool.labelValues("primary", "read").set(30);
+    connectionsByPool.labelValues("replica", "write").set(10);
+
+    // Also add a regular metric without duplicates for reference
+    Counter uniqueMetric =
+        Counter.builder()
+            .name("unique_metric_total")
+            .help("A unique metric for reference")
+            .unit(Unit.BYTES)
+            .register();
+    uniqueMetric.inc(1024);
+
+    HTTPServer server = HTTPServer.builder().port(port).buildAndStart();
+
+    System.out.println(
+        "DuplicateMetricsSample listening on http://localhost:" + server.getPort() + "/metrics");
+    Thread.currentThread().join(); // wait forever
+  }
+
+  private static int parsePortOrExit(String port) {
+    try {
+      return Integer.parseInt(port);
+    } catch (NumberFormatException e) {
+      System.err.println("\"" + port + "\": Invalid port number.");
+      System.exit(1);
+    }
+    return 0; // this won't happen
+  }
+}