Allow duplicate metric names

[jaydeluca]

Resolves #696

The goal of this change is to be able to have multiple metrics with the same name but different labels, which had previously been prevented by a check during registration.

While implementing this, I operated under a few assumptions:

• We will allow metrics with different labels to have the same name, but scraping metrics with the same name and same labels results in an exception
• Metrics with the same name but different metric types will result in an exception
• Metrics with the same name but different labels should all be merged under a single HELP/TYPE heading

I originally attempted to implement the validation during metric registration, but that required doing some things that felt wrong, so I moved the validation to scrape time. This does result in a bit of a performance hit (~10% reduction in op/s in the benchmarks I ran) on the scrape operation.

The benchmarks I ran were on an apple M4. I did 4 runs total - 2 of the main branch for a baseline and 2 for this feature branch and then averaged them.

Benchmark results

TextFormatUtilBenchmark

Benchmark	Main #1	Main #2	Feature #1	Feature #2	Main Avg	Feature Avg
openMetricsWriteToByteArray	1,179,213 ± 5,959	1,170,787 ± 5,579	1,080,037 ± 5,836	1,068,906 ± 5,288	1,175,000	1,074,471
openMetricsWriteToNull	1,197,768 ± 16,513	1,191,845 ± 13,897	1,083,832 ± 3,873	1,076,979 ± 4,816	1,194,806	1,080,406
prometheusWriteToByteArray	1,281,014 ± 21,437	1,273,552 ± 26,889	1,144,375 ± 3,303	1,138,252 ± 5,744	1,277,283	1,141,313
prometheusWriteToNull	1,254,177 ± 7,513	1,308,925 ± 14,326	1,167,007 ± 6,183	1,152,662 ± 2,565	1,281,551	1,159,835

---

CounterBenchmark

Benchmark	Main #1	Main #2	Feature #1	Feature #2	Main Avg	Feature Avg
codahaleIncNoLabels	71,040 ± 1,676	81,355 ± 9,287	87,105 ± 8,193	78,829 ± 12,370	76,197	82,967
openTelemetryAdd	1,472 ± 38	1,350 ± 39	1,419 ± 57	1,350 ± 39	1,411	1,384
openTelemetryInc	1,437 ± 45	1,361 ± 82	1,389 ± 50	1,349 ± 68	1,399	1,369
openTelemetryIncNoLabels	1,521 ± 42	1,347 ± 88	1,330 ± 103	1,419 ± 74	1,434	1,375
prometheusAdd	84,285 ± 102	84,233 ± 79	84,015 ± 79	84,255 ± 28	84,259	84,135
prometheusInc	85,739 ± 160	86,172 ± 225	85,484 ± 68	86,128 ± 113	85,956	85,806
prometheusNoLabelsInc	85,586 ± 242	86,075 ± 65	85,385 ± 52	85,954 ± 57	85,830	85,669
simpleclientAdd	8,730 ± 1,429	9,114 ± 1,362	8,003 ± 733	9,200 ± 1,202	8,922	8,602
simpleclientInc	7,655 ± 798	10,469 ± 1,635	9,201 ± 1,476	9,746 ± 1,125	9,062	9,473
simpleclientNoLabelsInc	8,328 ± 908	9,124 ± 847	7,951 ± 815	9,988 ± 765	8,726	8,970

---

HistogramBenchmark

Benchmark	Main #1	Main #2	Feature #1	Feature #2	Main Avg	Feature Avg
openTelemetryClassic	780 ± 66	932 ± 75	794 ± 12	841 ± 98	856	817
openTelemetryExponential	737 ± 65	764 ± 96	732 ± 68	725 ± 51	751	729
prometheusClassic	3,844 ± 63	3,886 ± 117	4,080 ± 137	3,865 ± 62	3,865	3,973
prometheusNative	2,829 ± 245	2,933 ± 73	2,961 ± 148	2,969 ± 98	2,881	2,965
simpleclient	15,192 ± 1,914	11,926 ± 1,209	14,669 ± 395	15,781 ± 1,365	13,559	15,225

[zeitlinger]

great 😄

[Copilot]

Pull request overview

This PR enables multiple metrics with the same Prometheus name but different label sets to coexist, addressing a limitation where duplicate metric names were previously rejected at registration time. The validation has been moved from registration to scrape time, where it now checks for type consistency and unique label combinations. During exposition, metrics with the same name are merged under a single HELP/TYPE declaration.

Key changes:

• Registration no longer rejects duplicate metric names; validation occurs at scrape time
• Metrics with the same name but different types or duplicate label sets throw exceptions at scrape time
• Exposition formats merge duplicate metric names into single metric families with combined data points

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
PrometheusRegistry.java	Removed duplicate name checking at registration time and during scrape
Collector.java	Updated documentation to remove reference to registration-time name checking
MultiCollector.java	Updated documentation to remove reference to registration-time name checking
MetricSnapshots.java	Added validation logic for type consistency and duplicate label detection at construction time
TextFormatUtil.java	Added mergeDuplicates() method to combine snapshots with the same Prometheus name
PrometheusTextFormatWriter.java	Integrated mergeDuplicates() to ensure single HELP/TYPE per metric family
OpenMetricsTextFormatWriter.java	Integrated mergeDuplicates() for OpenMetrics format
PrometheusProtobufWriterImpl.java	Integrated mergeDuplicates() for protobuf format
PrometheusRegistryTest.java	Added comprehensive tests for duplicate name scenarios
TextFormatUtilTest.java	Added tests for the mergeDuplicates functionality
DuplicateNamesExpositionTest.java	New test file validating duplicate names in text formats
DuplicateNamesProtobufTest.java	New test file validating duplicate names in protobuf format
DuplicateMetricsIT.java	New integration test for end-to-end duplicate metrics validation
DuplicateMetricsSample.java	New sample application demonstrating duplicate metrics usage
pom.xml files	Added new test module to build configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jaydeluca]

closing in favor of #1800