[Formal SPEC Discussion clientlibs] Same metric name, different set of label names

[incertum]

(Follow for existing community discussion here: prometheus/client_java#696).

Hi everyone,

To better support dynamic use cases, could we consider relaxing the label names rule from MUST NOT to SHOULD NOT?

And to maintain clarity, what if we added a specific clause that a metric name MUST NOT be used as both labeled and unlabeled at the same time? The idea is to let users manage aggregation of the resulting time series in PromQL (see swift-server/swift-prometheus#131 (comment)).

Does this seem like a reasonable trade-off for more flexibility?
Curious to hear your perspectives. Thank you very much in advance!

---

The ask:
prometheus/client_java#696 (comment) (example has been slightly adjusted)

# HELP app_responses_total responses
# TYPE app_responses_total counter
app_responses_total{uri="/", outcome="SUCCESS"} 10
app_responses_total{uri="/", outcome="FAILURE", error="INVALID_REQUEST"} 2
app_responses_total{uri="/", outcome="FAILURE", error="DATA_NOT_FOUND"} 3
app_responses_total{uri="/", outcome="FAILURE", error="ERROR2"} 20
app_responses_total{uri="/", outcome="FAILURE", error="ERROR3"} 30

Conforming to current guidance:
prometheus/client_java#696 (comment)

# HELP app_responses_total responses
# TYPE app_responses_total counter
app_responses_total{uri="/", outcome="SUCCESS"} 10
app_responses_total{uri="/", outcome="FAILURE"} 5
# HELP app_responses_error_total responses error
# TYPE app_responses_error_total counter
app_responses_error_total{uri="/", outcome="FAILURE", error="ERROR2"} 20
app_responses_error_total{uri="/", outcome="FAILURE", error="ERROR3"} 30

For instance, if you use vector addition, you get incorrect aggregations:

sum(app_responses_total) by (outcome) + sum(app_responses_error_total) by (outcome)

{outcome="FAILURE"} 55

Users must be cautious in selecting a correct query, such as the one provided below:

sum(app_responses_total or app_responses_error_total) by (outcome)

{outcome="SUCCESS"} 10
{outcome="FAILURE"} 55

---

Retrieved on September 22, 2025:

https://prometheus.io/docs/instrumenting/writing_clientlibs/#labels
“Client libraries MUST NOT allow users to have different label names for the same metric for Gauge/Counter/Summary/Histogram or any other Collector offered by the library.”

See also:
prometheus/client_java#696
swift-server/swift-prometheus#125
swift-server/swift-prometheus#131 (comment)

[incertum]

CC @shakuzen @brian-brazil @fstab @nhartner @stolsvik @nberkley-gp @atschabu @ktoso

[bboreham]

Hello - we discussed this at the triage call, and feel it should not require much discussion.

The docs page on writing client libs should not be considered a formal spec, but it does seem outdated in this respect.

In Go, "unchecked collectors" already permit this and OpenMetrics says:

Metrics with the same name for a given MetricFamily SHOULD have the same set of label names in their LabelSet.

So we will transfer this to the docs repo to get the wording changed.

[incertum]

Hello - we discussed this at the triage call, and feel it should not require much discussion.

The docs page on writing client libs should not be considered a formal spec, but it does seem outdated in this respect.

In Go, "unchecked collectors" already permit this and OpenMetrics says:

Metrics with the same name for a given MetricFamily SHOULD have the same set of label names in their LabelSet.

So we will transfer this to the docs repo to get the wording changed.

Greatly appreciate the clarification, and we’ll make sure to reference this in the future.
Thank you @bboreham!

I believe we can close this since everything has been clarified? Thanks again!