Allow metrics with the same name different labels #1800

jaydeluca · 2026-01-24T16:09:46Z

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 <[email protected]>

zeitlinger · 2026-01-26T08:03:46Z

I still also have scrape time validation occurring along with registration time, but we can remove that if we think the registration time validation is sufficient protection.

I would opt for registration only.

What does that mean for clients that only work on snapshots like the OTel SDK?

https://github.com/open-telemetry/opentelemetry-java/blob/da310cc1fcd06e606426649f6c8db96958d9bb12/exporters/prometheus/src/main/java/io/opentelemetry/exporter/prometheus/PrometheusMetricReader.java#L104

Signed-off-by: Jay DeLuca <[email protected]>

jaydeluca · 2026-01-29T21:27:04Z

still need to incorporate checks for the help/unit

Signed-off-by: Jay DeLuca <[email protected]>

jaydeluca · 2026-01-30T17:57:42Z

What does that mean for clients that only work on snapshots like the OTel SDK?

Should be no change in behavior, I've added some tests that emulate the same type of interactions

Copilot

Pull request overview

Enables registering multiple metrics with the same name when they differ by label schema, while ensuring exposition formats emit a single metric family per name.

Changes:

Adds registration-time validation in PrometheusRegistry for metric type consistency, help/unit consistency, and duplicate label schemas (when collectors provide the new metadata methods).
Allows MetricSnapshots to contain duplicate names (same snapshot type), and merges duplicate-name snapshots during exposition writing.
Introduces integration/unit tests and sample apps covering duplicate-name behavior across text/OpenMetrics/protobuf exporters.

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
prometheus-metrics-model/src/test/java/io/prometheus/metrics/model/registry/PrometheusRegistryTest.java	Expands registry tests for duplicate names, label schemas, help/unit consistency, and unregister behavior.
prometheus-metrics-model/src/test/java/io/prometheus/metrics/model/registry/OpenTelemetryExporterRegistryCompatibilityTest.java	Adds regression tests for OTel-style `MultiCollector` usage (no names/types/labels metadata).
prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/MetricSnapshots.java	Relaxes duplicate-name constraint; only rejects conflicting snapshot types for same name.
prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/PrometheusRegistry.java	Implements registration-time validation and tracking for per-name label schemas/type/help/unit.
prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MultiCollector.java	Adds optional per-metric-name metadata methods (`getMetricType`, `getLabelNames`, `getMetadata`).
prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/MetricType.java	Introduces a metric-type enum used for registration-time validation.
prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/registry/Collector.java	Adds optional metadata methods (`getMetricType`, `getLabelNames`, `getMetadata`) for registration-time validation.
prometheus-metrics-exposition-textformats/src/test/java/io/prometheus/metrics/expositionformats/TextFormatUtilTest.java	Adds unit tests for merging duplicate-name snapshots.
prometheus-metrics-exposition-textformats/src/test/java/io/prometheus/metrics/expositionformats/DuplicateNamesExpositionTest.java	Adds text/OpenMetrics exposition tests demonstrating valid output with duplicate names.
prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/TextFormatUtil.java	Adds duplicate-name merging utility used by writers.
prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java	Merges duplicate-name snapshots before writing Prometheus text format.
prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java	Merges duplicate-name snapshots before writing OpenMetrics text format.
prometheus-metrics-exposition-formats/src/test/java/io/prometheus/metrics/expositionformats/DuplicateNamesProtobufTest.java	Adds protobuf exposition tests for duplicate-name snapshots being merged into one family.
prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/internal/PrometheusProtobufWriterImpl.java	Merges duplicate-name snapshots before protobuf serialization.
prometheus-metrics-exposition-formats/generate-protobuf.sh	Updates generation script to try to support macOS tooling and `mise`-provided protoc.
prometheus-metrics-core/src/test/java/io/prometheus/metrics/core/metrics/CounterTest.java	Adds test for label normalization affecting registration-time label schema validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/SummaryWithCallback.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Summary.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/StateSet.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/MetricWithFixedMetadata.java	Exposes metadata via `Collector.getMetadata()` and implements normalized `getLabelNames()`.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Info.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Histogram.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/GaugeWithCallback.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Gauge.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/CounterWithCallback.java	Implements `getMetricType()` for registration-time validation.
prometheus-metrics-core/src/main/java/io/prometheus/metrics/core/metrics/Counter.java	Implements `getMetricType()` for registration-time validation.
mise.toml	Adjusts Java toolchain version.
integration-tests/it-exporter/pom.xml	Adds a new integration-test sample module for duplicate metrics.
integration-tests/it-exporter/it-exporter-test/src/test/java/io/prometheus/metrics/it/exporter/test/DuplicateMetricsIT.java	Adds end-to-end exporter tests validating merged duplicate metrics output.
integration-tests/it-exporter/it-exporter-duplicate-metrics-sample/src/main/java/io/prometheus/metrics/it/exporter/duplicatemetrics/DuplicateMetricsSample.java	Adds sample app emitting same-name metrics with different label sets.
integration-tests/it-exporter/it-exporter-duplicate-metrics-sample/pom.xml	Maven module for the duplicate-metrics integration sample.
integration-tests/it-common/src/test/java/io/prometheus/client/it/common/ExporterTest.java	Makes the container field protected for reuse by new ITs.
docs/content/internals/model.md	Documents behavior for collectors that don’t provide type/label metadata.
docs/content/getting-started/registry.md	Documents registration-time-only validation and optional metadata methods.
docs/content/getting-started/metric-types.md	Adds guidance about avoiding duplicate time series for unvalidated custom collectors.
.gitignore	Ignores macOS `.DS_Store` files.

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

Copilot · 2026-01-30T18:19:09Z

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

+    List<String> prometheusNamesList = collector.getPrometheusNames();
+    List<MultiCollectorRegistration> registrations = new ArrayList<>();
+
+    for (String prometheusName : prometheusNamesList) {
+      MetricType metricType = collector.getMetricType(prometheusName);


PrometheusRegistry.register(MultiCollector) mutates shared state incrementally while iterating prometheusNamesList. If registration throws for a later name, earlier per-name updates can remain even though the MultiCollector itself was never added, leaving orphaned RegistrationInfo entries. Wrap the loop in try/catch and rollback any successful per-name registrations on failure (or pre-validate all names before mutating shared state).

Copilot · 2026-01-30T18:19:09Z

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

+    CollectorRegistration(String prometheusName, @Nullable Set<String> labelNames) {
+      this.prometheusName = prometheusName;
+      this.labelNames =
+          (labelNames == null || labelNames.isEmpty()) ? Collections.emptySet() : labelNames;
+    }


CollectorRegistration stores the Set returned by Collector.getLabelNames() directly. Because these Sets are later used as keys in labelSchemas and for unregistration, mutating the returned Set after registration can break duplicate detection and/or prevent cleanup on unregister. Consider defensively copying/normalizing to an immutable Set (e.g., Set.copyOf(normalized)) at registration time.

Copilot · 2026-01-30T18:19:09Z

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

+    MultiCollectorRegistration(String prometheusName, @Nullable Set<String> labelNames) {
+      this.prometheusName = prometheusName;
+      this.labelNames =
+          (labelNames == null || labelNames.isEmpty()) ? Collections.emptySet() : labelNames;
+    }


MultiCollectorRegistration also stores the Set returned by MultiCollector.getLabelNames(name) directly. If that Set is mutable and later changes, unregisterLabelSchema may fail to remove the schema and the registered map entry can leak. Prefer storing an immutable defensive copy (e.g., Set.copyOf(normalized)).

Copilot · 2026-01-30T18:19:10Z

prometheus-metrics-exposition-formats/generate-protobuf.sh

+if [[ "$OSTYPE" == "darwin"* ]] && command -v gsed >/dev/null 2>&1; then
+	SED='gsed'


On macOS, this script falls back to BSD sed when gsed is not installed, but later uses "$SED -i". BSD sed requires an argument for -i (e.g., -i ''), so the fallback will fail. Either hard-require gsed on macOS with a clear error message, or use a portable in-place edit strategy for both GNU/BSD sed.

Suggested change

if [[ "$OSTYPE" == "darwin"* ]] && command -v gsed >/dev/null 2>&1; then

SED='gsed'

if [[ "$OSTYPE" == "darwin"* ]]; then

if command -v gsed >/dev/null 2>&1; then

SED='gsed'

else

echo "Error: gsed (GNU sed) is required on macOS. Please install it, e.g. with 'brew install gnu-sed'." >&2

exit 1

fi

Copilot · 2026-01-30T18:19:10Z

...ormats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java

+    MetricSnapshots merged = TextFormatUtil.mergeDuplicates(metricSnapshots);
+    for (MetricSnapshot s : merged) {
      MetricSnapshot snapshot = escapeMetricSnapshot(s, scheme);
      if (!snapshot.getDataPoints().isEmpty()) {
        if (snapshot instanceof CounterSnapshot) {


PrometheusTextFormatWriter now merges duplicate metric snapshots for the main output, but the optional created-timestamp pass still uses the original MetricSnapshots. With duplicate names enabled this can emit repeated HELP/TYPE blocks and potentially duplicate _created series. Consider iterating over the merged snapshots (or otherwise merging per metric family) for the created-timestamp section too.

Copilot · 2026-01-30T18:19:11Z

prometheus-metrics-exposition-formats/generate-protobuf.sh

+if [[ "$OSTYPE" == "darwin"* ]] && command -v ggrep >/dev/null 2>&1; then
+	GREP='ggrep'
+else
+	GREP='grep'
+fi


On macOS, falling back to BSD grep will break later when using "$GREP -oP" because BSD grep does not support -P. Either hard-require ggrep on macOS with a clear error message, or replace the -P usage with a portable alternative (e.g., awk/sed/perl).

Copilot · 2026-01-30T18:19:11Z

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

+    void validateMetadata(@Nullable String newHelp, @Nullable Unit newUnit) {
+      if (help != null && newHelp != null && !Objects.equals(help, newHelp)) {
+        throw new IllegalArgumentException(
+            "Conflicting help strings. Existing: \"" + help + "\", new: \"" + newHelp + "\"");
+      }


RegistrationInfo.validateMetadata() only checks conflicts when both existing and new help/unit are non-null, but never records newly observed non-null help/unit when the stored value is null. If the first registration omits help/unit and later ones provide differing values, conflicts will never be detected and exposition output may become nondeterministic. Consider capturing the first non-null help/unit so subsequent registrations can be validated consistently.

Copilot · 2026-01-30T18:19:11Z

...sition-textformats/src/main/java/io/prometheus/metrics/expositionformats/TextFormatUtil.java

+      return new HistogramSnapshot(
+          first.getMetadata(),
+          (Collection<HistogramSnapshot.HistogramDataPointSnapshot>) (Object) allDataPoints);


TextFormatUtil.mergeSnapshots() creates a new HistogramSnapshot using the constructor that defaults isGaugeHistogram to false. This drops the gaugeHistogram flag when merging duplicate histogram snapshots (and can change OpenMetrics output from "gaugehistogram" to "histogram"). Preserve (and validate consistency of) the gaugeHistogram flag when merging HistogramSnapshot instances (e.g., use the boolean constructor and ensure all snapshots in the group agree).

Suggested change

return new HistogramSnapshot(

first.getMetadata(),

(Collection<HistogramSnapshot.HistogramDataPointSnapshot>) (Object) allDataPoints);

boolean isGaugeHistogram = ((HistogramSnapshot) first).isGaugeHistogram();

for (MetricSnapshot snapshot : snapshots) {

boolean snapshotIsGaugeHistogram = ((HistogramSnapshot) snapshot).isGaugeHistogram();

if (snapshotIsGaugeHistogram != isGaugeHistogram) {

throw new IllegalArgumentException(

"Cannot merge HistogramSnapshots with different gaugeHistogram flags");

}

}

return new HistogramSnapshot(

first.getMetadata(),

(Collection<HistogramSnapshot.HistogramDataPointSnapshot>) (Object) allDataPoints,

isGaugeHistogram);

Copilot · 2026-01-30T18:19:12Z

...ormats/src/test/java/io/prometheus/metrics/expositionformats/DuplicateNamesProtobufTest.java

+    }
+
+    assertThat(counterFamily).isNotNull();
+    assertThat(counterFamily.getType()).isEqualTo(Metrics.MetricType.COUNTER);


Variable counterFamily may be null at this access because of this assignment.

Copilot · 2026-01-30T18:19:12Z

...ormats/src/test/java/io/prometheus/metrics/expositionformats/DuplicateNamesProtobufTest.java

+    assertThat(counterFamily.getMetric(0).getCounter().getValue()).isEqualTo(100.0);
+
+    assertThat(gaugeFamily).isNotNull();
+    assertThat(gaugeFamily.getType()).isEqualTo(Metrics.MetricType.GAUGE);


Variable gaugeFamily may be null at this access because of this assignment.

jaydeluca force-pushed the duplicate-names-registration-validation branch from 7203084 to 2359244 Compare January 24, 2026 16:10

jaydeluca added 6 commits January 24, 2026 11:10

Type and label schema validation during registration

a85e35a

Signed-off-by: Jay DeLuca <[email protected]>

start adding exposition merging

58dddc8

Signed-off-by: Jay DeLuca <[email protected]>

add some additional validation checks

5acc440

Signed-off-by: Jay DeLuca <[email protected]>

optimize merge method

c8eea69

Signed-off-by: Jay DeLuca <[email protected]>

handle other exposition formats

43ab4b1

Signed-off-by: Jay DeLuca <[email protected]>

cleanups, ironing out edge cases

9289e4a

Signed-off-by: Jay DeLuca <[email protected]>

jaydeluca force-pushed the duplicate-names-registration-validation branch from 2359244 to 9289e4a Compare January 24, 2026 16:10

fix linting

6765715

Signed-off-by: Jay DeLuca <[email protected]>

jaydeluca mentioned this pull request Jan 26, 2026

Allow duplicate metric names #1728

Closed

zeitlinger mentioned this pull request Jan 29, 2026

Target release with recent improvements #1834

Open

jaydeluca added 3 commits January 29, 2026 13:32

merge main

004595f

Signed-off-by: Jay DeLuca <[email protected]>

fix merge

11efcfb

Signed-off-by: Jay DeLuca <[email protected]>

remove scrape time validation

02c0db0

Signed-off-by: Jay DeLuca <[email protected]>

jaydeluca force-pushed the duplicate-names-registration-validation branch from 62b9cbc to 02c0db0 Compare January 29, 2026 20:03

jaydeluca added 6 commits January 30, 2026 11:47

cleanup registration

8b6bf20

Signed-off-by: Jay DeLuca <[email protected]>

cleanup fallback

54f5ecb

Signed-off-by: Jay DeLuca <[email protected]>

add tests

74a46f3

Signed-off-by: Jay DeLuca <[email protected]>

test visibility

dfa2114

Signed-off-by: Jay DeLuca <[email protected]>

cleanup

cbcd1ec

Signed-off-by: Jay DeLuca <[email protected]>

add otel sdk compatibility test

1e897dc

Signed-off-by: Jay DeLuca <[email protected]>

jaydeluca force-pushed the duplicate-names-registration-validation branch from b5396a5 to 1e897dc Compare January 30, 2026 17:53

jaydeluca changed the title ~~Allow metrics with the same name (Option #2)~~ Allow metrics with the same name different labels Jan 30, 2026

jaydeluca requested a review from Copilot January 30, 2026 18:03

Copilot started reviewing on behalf of jaydeluca January 30, 2026 18:03 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

		if [[ "$OSTYPE" == "darwin"* ]] && command -v gsed >/dev/null 2>&1; then
		SED='gsed'

-      return new HistogramSnapshot(
-          first.getMetadata(),
-          (Collection<HistogramSnapshot.HistogramDataPointSnapshot>) (Object) allDataPoints);
+      boolean isGaugeHistogram = ((HistogramSnapshot) first).isGaugeHistogram();
+      for (MetricSnapshot snapshot : snapshots) {
+        boolean snapshotIsGaugeHistogram = ((HistogramSnapshot) snapshot).isGaugeHistogram();
+        if (snapshotIsGaugeHistogram != isGaugeHistogram) {
+          throw new IllegalArgumentException(
+              "Cannot merge HistogramSnapshots with different gaugeHistogram flags");
+        }
+      }
+      return new HistogramSnapshot(
+          first.getMetadata(),
+          (Collection<HistogramSnapshot.HistogramDataPointSnapshot>) (Object) allDataPoints,
+          isGaugeHistogram);

Allow metrics with the same name different labels #1800

Are you sure you want to change the base?

Allow metrics with the same name different labels #1800

Uh oh!

Conversation

jaydeluca commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeitlinger commented Jan 26, 2026

Uh oh!

jaydeluca commented Jan 29, 2026

Uh oh!

jaydeluca commented Jan 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jaydeluca commented Jan 24, 2026 •

edited

Loading