Allow metrics with the same name different labels by jaydeluca · Pull Request #1800 · prometheus/client_java

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

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>

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 <jaydeluca4@gmail.com>

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

still need to incorporate checks for the help/unit

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

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.

…ix build order to avoid local issues Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

Copilot

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 7 comments.

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

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

Copilot

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 5 comments.

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

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

zeitlinger

great - we're almost there 😄

zeitlinger · 2026-02-05T11:46:07Z

 }
+
+ multiCollectorMetadata.put(collector, registrations);
+ } catch (Exception e) {


can this be a specific ex?

so now you have RuntimeException - can you list the specific exception that is thrown - or is this unknown?

we invoke of a handful of methods in these blocks that could potentially have buggy implementations from custom collector implementations, which could throw NPEs or other runtime exceptions. And we need to catch them so we don't end up with partial registrations.

OK, can you add that as a comment?

zeitlinger · 2026-02-05T11:51:37Z

+ * @return the metric type, or {@code null} to skip validation
+ */
+ @Nullable
+ default MetricType getMetricType() {


I like default methods over instanceof checks!

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

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

Draft validation PR for the unmodified Micrometer compatibility story. This intentionally does **not** depend on #2114. Vanilla Micrometer does not use the typed descriptor API and does not implement the #1800 registration metadata hooks, so this PR validates the patch-compatible path independently of typed descriptors. This validates upstream `micrometer-metrics/micrometer@main` against: - current `main`, which already includes #2100 and #2124 (reserved suffix stripping in `PrometheusNaming.sanitizeMetricName()`). - Micrometer compatibility test tooling/workflow from zeitlinger#1. Local validation: - `mise run lint` - `MICROMETER_DIR=/tmp/micrometer-compat-vanilla-2124 mise run micrometer:test` --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com> Co-authored-by: Jay DeLuca <jaydeluca4@gmail.com>

Adds typed metric family descriptors and typed metadata support for the model snapshots. This is the typed-descriptor branch for downstreams that want to provide registration-time metadata explicitly. The #1800 Collector/MultiCollector registration metadata hooks are already optional via default methods, so unmodified downstreams should not need this PR just to keep working. This PR now also deprecates the fragmented registration metadata API (`getPrometheusName()`, `getMetricType()`, `getLabelNames()`, and `getMetadata()` plus the `MultiCollector` variants) in favor of `getMetricFamilyDescriptor()` / `getMetricFamilyDescriptors()`. The deprecated methods remain bridged by default implementations for compatibility. Related validation: - #2121 validates unmodified Micrometer independently of #2114, against `main` + #2124. - #2123 validates a Micrometer branch that explicitly uses `MetricFamilyDescriptor` to implement the existing registration metadata hooks without invoking scrape/sample callbacks during registration. --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Draft validation PR for the unmodified Micrometer compatibility story. This intentionally does **not** depend on #2114. Vanilla Micrometer does not use the typed descriptor API and does not implement the #1800 registration metadata hooks, so this PR validates the patch-compatible path independently of typed descriptors. This validates upstream `micrometer-metrics/micrometer@main` against: - current `main`, which already includes #2100 and #2124 (reserved suffix stripping in `PrometheusNaming.sanitizeMetricName()`). - Micrometer compatibility test tooling/workflow from zeitlinger#1. Local validation: - `mise run lint` - `MICROMETER_DIR=/tmp/micrometer-compat-vanilla-2124 mise run micrometer:test` --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com> Co-authored-by: Jay DeLuca <jaydeluca4@gmail.com> Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

Adds typed metric family descriptors and typed metadata support for the model snapshots. This is the typed-descriptor branch for downstreams that want to provide registration-time metadata explicitly. The #1800 Collector/MultiCollector registration metadata hooks are already optional via default methods, so unmodified downstreams should not need this PR just to keep working. This PR now also deprecates the fragmented registration metadata API (`getPrometheusName()`, `getMetricType()`, `getLabelNames()`, and `getMetadata()` plus the `MultiCollector` variants) in favor of `getMetricFamilyDescriptor()` / `getMetricFamilyDescriptors()`. The deprecated methods remain bridged by default implementations for compatibility. Related validation: - #2121 validates unmodified Micrometer independently of #2114, against `main` + #2124. - #2123 validates a Micrometer branch that explicitly uses `MetricFamilyDescriptor` to implement the existing registration metadata hooks without invoking scrape/sample callbacks during registration. --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com> Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

jaydeluca force-pushed the duplicate-names-registration-validation branch from 7203084 to 2359244Compare 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 <jaydeluca4@gmail.com>

start adding exposition merging
58dddc8
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

add some additional validation checks
5acc440
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

optimize merge method
c8eea69
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

handle other exposition formats
43ab4b1
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

cleanups, ironing out edge cases
9289e4a
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

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

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

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
Closed

jaydeluca added 3 commits January 29, 2026 13:32

merge main
004595f
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

fix merge
11efcfb
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

remove scrape time validation
02c0db0
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

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

jaydeluca added 6 commits January 30, 2026 11:47

cleanup registration
8b6bf20
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

cleanup fallback
54f5ecb
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

add tests
74a46f3
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

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

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

add otel sdk compatibility test
1e897dc
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

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

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

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

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

CopilotAI reviewed Jan 30, 2026
View reviewed changes

make copys of labels, fix multicollector processing with try catch, f…
707e4dc
…ix build order to avoid local issues Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

Copilotstarted reviewing on behalf of jaydeluca February 3, 2026 15:53 View session

CopilotAI reviewed Feb 3, 2026
View reviewed changes

jaydeluca added 3 commits February 3, 2026 13:28

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

Merge branch 'main' into duplicate-names-registration-validation
31aebc3
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

proto update
28a8514
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

jaydeluca force-pushed the duplicate-names-registration-validation branch from c5907ce to 28a8514Compare February 3, 2026 20:18

jaydeluca requested a review from Copilot February 4, 2026 17:08

Copilotstarted reviewing on behalf of jaydeluca February 4, 2026 17:08 View session

CopilotAI reviewed Feb 4, 2026
View reviewed changes

jaydeluca added 2 commits February 4, 2026 13:06

be consistent about help/unit validation, ensure deregister labels
9bf69c8
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

Merge branch 'main' into duplicate-names-registration-validation
6ebab1b

jaydeluca marked this pull request as ready for review February 4, 2026 18:12

jaydeluca requested review from fstab and zeitlinger February 4, 2026 18:12

zeitlinger reviewed Feb 5, 2026
View reviewed changes

make exceptions more specific, undo unrelated changes to pom and gene…
831645c
…rate script Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

jaydeluca force-pushed the duplicate-names-registration-validation branch from bf4c701 to d1d4c09Compare February 5, 2026 21:01

add comments about use of RuntimeException:
d8490cd
Signed-off-by: Jay DeLuca <jaydeluca4@gmail.com>

jaydeluca force-pushed the duplicate-names-registration-validation branch from d1d4c09 to d8490cdCompare February 5, 2026 21:02

zeitlinger merged commit 0c9d5bf into mainFeb 5, 2026
14 checks passed

zeitlinger deleted the duplicate-names-registration-validation branch February 5, 2026 21:47

jaydeluca mentioned this pull request Feb 5, 2026
Same metric name, different set of label names #696
Closed

zeitlinger mentioned this pull request Feb 20, 2026
Add API compatibility linting to CI #1901
Closed
4 tasks

This was referenced May 18, 2026
feat: add opt-in typed metric family descriptors #2122
Closed
feat: add typed metric family descriptors #2114
Merged
test: validate Micrometer vanilla compatibility #2121
Merged

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!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zeitlinger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zeitlingerFeb 5, 2026

Choose a reason for hiding this comment

Uh oh!

zeitlingerFeb 5, 2026

Choose a reason for hiding this comment

Uh oh!

jaydelucaFeb 5, 2026

Choose a reason for hiding this comment

Uh oh!

zeitlingerFeb 5, 2026

Choose a reason for hiding this comment

Uh oh!

zeitlingerFeb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jaydeluca commented Jan 24, 2026•
edited
Loading