Allow duplicate metric names (WIP)

.github/workflows/native-tests.yml

@@ -17,7 +17,7 @@ jobs:
         with:
           version: v2025.12.0
           sha256: 5b7b9992950b65569b4f6f1c78b05abceea2506f15b750a4b9781f33c6cc1ae4
-        env:
-          MISE_ENV: native
+          working_directory: .mise/envs/native
       - name: Run native tests
-        run: mise run test
+        working-directory: .mise/envs/native
+        run: mise native-test

.mise/envs/native/mise.toml

@@ -0,0 +1,8 @@
+[tools]
+java = "oracle-graalvm-25.0.1"
+
+[tasks.native-test]
+depends = "build"
+run = "../../mvnw test -PnativeTest"
+dir = "../../../integration-tests/it-spring-boot-smoke-test"
+

CONTRIBUTING.md

@@ -29,7 +29,7 @@ If you're getting errors when running tests:
 ### Running native tests
 
 ```shell
-mise --env native test
+mise --cd .mise/envs/native run native-test
 ```
 
 ### Avoid failures while running tests

examples/example-exporter-opentelemetry/oats-tests/agent/Dockerfile

@@ -1,4 +1,4 @@
-FROM eclipse-temurin:25.0.1_8-jre@sha256:73fe03b88c2a48ec41f9a86428c65ea5913229488ca218cd6a4f55f8cb0ece1f
+FROM eclipse-temurin:25.0.1_8-jre@sha256:f6b092537e68d9836e86f676344e94102f2be325bbc652133cd9ef85b27d3ea9
 
 COPY target/example-exporter-opentelemetry.jar ./app.jar
 # check that the resource attributes from the agent are used, epsecially the service.instance.id should be the same

examples/example-exporter-opentelemetry/oats-tests/http/Dockerfile

@@ -1,4 +1,4 @@
-FROM eclipse-temurin:25.0.1_8-jre@sha256:73fe03b88c2a48ec41f9a86428c65ea5913229488ca218cd6a4f55f8cb0ece1f
+FROM eclipse-temurin:25.0.1_8-jre@sha256:f6b092537e68d9836e86f676344e94102f2be325bbc652133cd9ef85b27d3ea9
 
 COPY target/example-exporter-opentelemetry.jar ./app.jar
 

examples/example-native-histogram/docker-compose.yaml

@@ -1,7 +1,7 @@
 version: "3"
 services:
   example-application:
-    image: eclipse-temurin:25.0.1_8-jre@sha256:73fe03b88c2a48ec41f9a86428c65ea5913229488ca218cd6a4f55f8cb0ece1f
+    image: eclipse-temurin:25.0.1_8-jre@sha256:f6b092537e68d9836e86f676344e94102f2be325bbc652133cd9ef85b27d3ea9
     network_mode: host
     volumes:
       - ./target/example-native-histogram.jar:/example-native-histogram.jar

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,89 @@
+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 < 1 || args.length > 2) {
+      System.err.println("Usage: java -jar duplicate-metrics-sample.jar <port>");
+      System.exit(1);
+    }
+
+    int port = parsePortOrExit(args[0]);
+    run(port);
+  }
+
+  private static void run(int port) 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
+  }
+}

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

@@ -0,0 +1,194 @@
+package io.prometheus.metrics.it.exporter.test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import io.prometheus.client.it.common.ExporterTest;
+import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_33_2.Metrics;
+import java.io.IOException;
+import java.net.URISyntaxException;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Integration test for duplicate metric names with different label sets.
+ *
+ * <p>This test validates that:
+ *
+ * <ul>
+ *   <li>Multiple metrics with the same Prometheus name but different labels can be registered
+ *   <li>All exposition formats (text, OpenMetrics, protobuf) correctly merge and expose them
+ *   <li>The merged output is valid and scrapeable by Prometheus
+ * </ul>
+ */
+class DuplicateMetricsIT extends ExporterTest {
+
+  public DuplicateMetricsIT() throws IOException, URISyntaxException {
+    super("exporter-duplicate-metrics-sample");
+  }
+
+  @Test
+  void testDuplicateMetricsInPrometheusTextFormat() throws IOException {
+    start();
+    Response response = scrape("GET", "");
+    assertThat(response.status).isEqualTo(200);
+    assertContentType(
+        "text/plain; version=0.0.4; charset=utf-8", response.getHeader("Content-Type"));
+
+    String expected =
+        """
+      # HELP active_connections Active connections
+      # TYPE active_connections gauge
+      active_connections{pool="primary",type="read"} 30.0
+      active_connections{pool="replica",type="write"} 10.0
+      active_connections{protocol="http",region="us-east"} 42.0
+      active_connections{protocol="http",region="us-west"} 38.0
+      active_connections{protocol="https",region="eu-west"} 55.0
+      # HELP http_requests_total Total HTTP requests by status
+      # TYPE http_requests_total counter
+      http_requests_total{endpoint="/api",status="error"} 5.0
+      http_requests_total{endpoint="/health",status="error"} 2.0
+      http_requests_total{method="GET",status="success"} 150.0
+      http_requests_total{method="POST",status="success"} 45.0
+      # HELP unique_metric_bytes_total A unique metric for reference
+      # TYPE unique_metric_bytes_total counter
+      unique_metric_bytes_total 1024.0
+      """;
+
+    assertThat(response.stringBody()).isEqualTo(expected);
+  }
+
+  @Test
+  void testDuplicateMetricsInOpenMetricsTextFormat() throws IOException {
+    start();
+    Response response =
+        scrape("GET", "", "Accept", "application/openmetrics-text; version=1.0.0; charset=utf-8");
+    assertThat(response.status).isEqualTo(200);
+    assertContentType(
+        "application/openmetrics-text; version=1.0.0; charset=utf-8",
+        response.getHeader("Content-Type"));
+
+    // OpenMetrics format should have UNIT for unique_metric_bytes (base name without _total)
+    String expected =
+        """
+      # TYPE active_connections gauge
+      # HELP active_connections Active connections
+      active_connections{pool="primary",type="read"} 30.0
+      active_connections{pool="replica",type="write"} 10.0
+      active_connections{protocol="http",region="us-east"} 42.0
+      active_connections{protocol="http",region="us-west"} 38.0
+      active_connections{protocol="https",region="eu-west"} 55.0
+      # TYPE http_requests counter
+      # HELP http_requests Total HTTP requests by status
+      http_requests_total{endpoint="/api",status="error"} 5.0
+      http_requests_total{endpoint="/health",status="error"} 2.0
+      http_requests_total{method="GET",status="success"} 150.0
+      http_requests_total{method="POST",status="success"} 45.0
+      # TYPE unique_metric_bytes counter
+      # UNIT unique_metric_bytes bytes
+      # HELP unique_metric_bytes A unique metric for reference
+      unique_metric_bytes_total 1024.0
+      # EOF
+      """;
+
+    assertThat(response.stringBody()).isEqualTo(expected);
+  }
+
+  @Test
+  void testDuplicateMetricsInPrometheusProtobufFormat() throws IOException {
+    start();
+    Response response =
+        scrape(
+            "GET",
+            "",
+            "Accept",
+            "application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily;"
+                + " encoding=delimited");
+    assertThat(response.status).isEqualTo(200);
+    assertContentType(
+        "application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily;"
+            + " encoding=delimited",
+        response.getHeader("Content-Type"));
+
+    List<Metrics.MetricFamily> metrics = response.protoBody();
+
+    // Should have exactly 3 metric families (active_connections, http_requests_total,
+    // unique_metric_bytes_total)
+    assertThat(metrics).hasSize(3);
+
+    // Metrics are sorted by name
+    assertThat(metrics.get(0).getName()).isEqualTo("active_connections");
+    assertThat(metrics.get(1).getName()).isEqualTo("http_requests_total");
+    assertThat(metrics.get(2).getName()).isEqualTo("unique_metric_bytes_total");
+
+    // Verify active_connections has all 5 data points merged
+    Metrics.MetricFamily activeConnections = metrics.get(0);
+    assertThat(activeConnections.getType()).isEqualTo(Metrics.MetricType.GAUGE);
+    assertThat(activeConnections.getHelp()).isEqualTo("Active connections");
+    assertThat(activeConnections.getMetricList()).hasSize(5);
+
+    // Verify http_requests_total has all 4 data points merged
+    Metrics.MetricFamily httpRequests = metrics.get(1);
+    assertThat(httpRequests.getType()).isEqualTo(Metrics.MetricType.COUNTER);
+    assertThat(httpRequests.getHelp()).isEqualTo("Total HTTP requests by status");
+    assertThat(httpRequests.getMetricList()).hasSize(4);
+
+    // Verify each data point has the expected labels
+    boolean foundSuccessGet = false;
+    boolean foundSuccessPost = false;
+    boolean foundErrorApi = false;
+    boolean foundErrorHealth = false;
+
+    for (Metrics.Metric metric : httpRequests.getMetricList()) {
+      List<Metrics.LabelPair> labels = metric.getLabelList();
+      if (hasLabel(labels, "status", "success") && hasLabel(labels, "method", "GET")) {
+        assertThat(metric.getCounter().getValue()).isEqualTo(150.0);
+        foundSuccessGet = true;
+      } else if (hasLabel(labels, "status", "success") && hasLabel(labels, "method", "POST")) {
+        assertThat(metric.getCounter().getValue()).isEqualTo(45.0);
+        foundSuccessPost = true;
+      } else if (hasLabel(labels, "status", "error") && hasLabel(labels, "endpoint", "/api")) {
+        assertThat(metric.getCounter().getValue()).isEqualTo(5.0);
+        foundErrorApi = true;
+      } else if (hasLabel(labels, "status", "error") && hasLabel(labels, "endpoint", "/health")) {
+        assertThat(metric.getCounter().getValue()).isEqualTo(2.0);
+        foundErrorHealth = true;
+      }
+    }
+
+    assertThat(foundSuccessGet).isTrue();
+    assertThat(foundSuccessPost).isTrue();
+    assertThat(foundErrorApi).isTrue();
+    assertThat(foundErrorHealth).isTrue();
+
+    Metrics.MetricFamily uniqueMetric = metrics.get(2);
+    assertThat(uniqueMetric.getType()).isEqualTo(Metrics.MetricType.COUNTER);
+    assertThat(uniqueMetric.getMetricList()).hasSize(1);
+    assertThat(uniqueMetric.getMetric(0).getCounter().getValue()).isEqualTo(1024.0);
+  }
+
+  @Test
+  void testDuplicateMetricsWithNameFilter() throws IOException {
+    start();
+    // Only scrape http_requests_total
+    Response response = scrape("GET", nameParam());
+    assertThat(response.status).isEqualTo(200);
+
+    String body = response.stringBody();
+
+    assertThat(body)
+        .contains("http_requests_total{method=\"GET\",status=\"success\"} 150.0")
+        .contains("http_requests_total{endpoint=\"/api\",status=\"error\"} 5.0");
+
+    // Should NOT contain active_connections or unique_metric_total
+    assertThat(body).doesNotContain("active_connections").doesNotContain("unique_metric_total");
+  }
+
+  private boolean hasLabel(List<Metrics.LabelPair> labels, String name, String value) {
+    return labels.stream()
+        .anyMatch(label -> label.getName().equals(name) && label.getValue().equals(value));
+  }
+
+  private String nameParam() {
+    return "name[]=" + "http_requests_total";
+  }
+}