Optionally add OM unit #1392

vesari · 2023-11-26T13:42:55Z

This PR adds support for unit for Open Metrics. It is ready for review, but not ready to merge (see my long comment below). Fixes #684.

Signed-off-by: Arianna Vespri <[email protected]>

ArthurSens · 2024-03-15T10:56:26Z

Hey @vesari , just passing by to ask if there is anything we could do to unblock you 👋

vesari · 2024-03-15T11:30:14Z

Hey @vesari , just passing by to ask if there is anything we could do to unblock you 👋

@ArthurSens hello! I think I'm just using a Go version which is too new, I plan on fixing that later today. Thanks a lot for checking on me, much appreciated! :)

Signed-off-by: Arianna Vespri <[email protected]>

ArthurSens

If we decide to support units, let's think of alternative that isn't breaking changes to downstream projects :)

ArthurSens · 2024-05-10T17:34:46Z

prometheus/example_metricvec_test.go

-func NewInfoVec(name, help string, labelNames []string) *InfoVec {
-	desc := prometheus.NewDesc(name, help, labelNames, nil)
+func NewInfoVec(name, help, unit string, labelNames []string) *InfoVec {
+	desc := prometheus.NewDesc(name, help, unit, labelNames, nil)


Similar problem here, we can't change Public function's signatures

ArthurSens · 2024-05-10T17:35:20Z

tutorial/whatsup/go.mod

 module github.com/prometheus/client_golang/tutorial

-go 1.20
+go 1.21


I believe we want to keep 1.20 until the next go release

Oops. Yes, absolutely. Just a leftover from when I reverted the changes I had made before common was fixed in this sense.

vesari · 2024-05-11T08:28:46Z

If we decide to support units, let's think of alternative that isn't breaking changes to downstream projects :)

Of course! I'll await your decision whether to support them and, if so, I'll be happy to continue working on it the way you suggested :)

beorn7 · 2024-05-14T16:27:44Z

I realized we already kind of agreed to supporting this... #684 so probably too late to challenge it cc @beorn7 @ArthurSens - do you remember what's the benefit other than "compatibility"?

It's hard for me to give a fair judgement here (because of my difficult history with OM). Having said that, the OM approach to units strikes me as weird.

I understand the historical Prometheus approach of "including the unit in the metric name" as a pragmatic solution to the lack of proper metadata support in Prometheus. It should be noted that it always has been just a convention.

OM added the unit metadata field, presumably because others asked for it (the OTel data model didn't exist back then, but I assume that the presence of a unit field in OTel comes from the same school of thinking). Now you might think, if OM has it as an explicit field, you don't have to include it in the metric name anymore. But OM did the opposite: If there is a unit field, the same string MUST be in the metric name, otherwise it is not valid OM. Personally, I think it should be possible to include the unit in the metric name (for those that like that for all the situation where you do not want to lookup the metadata even if you could), but given that others want to live in a world where metadata is always available at your fingertips, enforcing it in the metric name feels redundant.

Sadly, OTel took its guidance for Prometheus compatibility from OM, so the way the OTel data model is converted to Prometheus is already following the OM requirements, although there was never a Prometheus consensus about it.

Looping back to the question: How should we deal with the situation in client_golang? Given how far unit support has already seeped into various parts of the wider ecosystem, it's tough to say "this is all f*** up, let's just ignore it".
I think we should make it possible to expose the unit field for those that want it, but I would, for now, not enforce that the unit is also in the metric name (therefore accepting that we might generate invalid OM 1.0, but anticipating that this requirement is lifted in OM 2.0). It could be a note in the doc comment, like: "If you want to create valid OM 1.0, include the unit in the metric name, but this is not enforced." (I guess the OM vision was that you specify the name without the unit in instrumentation, then specify the unit separately (but only once), and then the actually exposed metric name includes the metric?)

How "1st class" adding the unit should be, is up to debate. I definitely wouldn't require all users to now add a unit. It should be an option for those that want it.

WRT to NewDesc: I once had an ambitious plan to get rid of (user-visible) Desc, see also #222 for issues with Desc. Not sure how to add unit without making everything even worse. Maybe NewDescWithUnit is OK for now.

vesari · 2024-05-16T10:00:59Z

Thank you all very much for your considerations and suggestions! In order not to enforce that the unit is also in the metric name when the unit field is populated, the logic in common has to be modified accordingly, by reverting some of the most recent changes that enforce exactly that. Of course, I'll be happy to do so. After that, I can work on the NewDescWithUnit approach for NewDesc. Let me know if I can proceed @ArthurSens @bwplotka @beorn7 :)

beorn7 · 2024-05-16T10:54:35Z

To be clear: @ArthurSens @bwplotka @kakkoyun should make the call here. I'm just providing my personal context.

ArthurSens · 2024-05-19T14:45:38Z

Hi @vesari!

The team met recently and one of the things we discussed was whether we accept OpenMetrics units or not.
A TL;DR; is: We won't accept this until Prometheus has a clear use case for unit metadata.

Reading the OpenMetrics specification, we can read[1][2]:

A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, HELP, TYPE, and UNIT metadata. Every Metric within a MetricFamily MUST have a unique LabelSet.
.
.
.
Unit specifies MetricFamily units. If non-empty, it MUST be a suffix of the MetricFamily name separated by an underscore. Be aware that further generation rules might make it an infix in the text format.

We clearly understand that units are required by OpenMetrics 1.0, and we clearly understand that units must be used as metric name suffixes. However, at this point, if we accept this the only benefit would be to say "We're OpenMetrics 1.0 compatible". Being OpenMetrics 1.0 compatible is not a bad thing per se, but Prometheus hasn't used the Unit metadata for anything yet, so it brings Client_golang users little benefit while making our API a bit more complex.

If in the future Prometheus introduces the usage of Unit metadata, e.g. to properly sum metrics with different but compatible units (one in seconds and the other in milliseconds), we'd be happy to resurrect this.

In the name of the team, we apologize for taking this long to make a decision. Your work was quite involved, spreading contributions across multiple repositories and communicating with several stakeholders. We'd be happy to continue working with you if that's also of your interest :)

ArthurSens · 2024-05-19T14:48:34Z

Maybe we could start brainstorming how to use the unit metadata in Prometheus? Although this would be a high-complexity project that I would also need a lot of time to understand properly😬

vesari · 2024-05-20T05:27:31Z

Hi @vesari!

The team met recently and one of the things we discussed was whether we accept OpenMetrics units or not. A TL;DR; is: We won't accept this until Prometheus has a clear use case for unit metadata.

Reading the OpenMetrics specification, we can read[1][2]:
A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, HELP, TYPE, and UNIT metadata. Every Metric within a MetricFamily MUST have a unique LabelSet.
.
.
.
Unit specifies MetricFamily units. If non-empty, it MUST be a suffix of the MetricFamily name separated by an underscore. Be aware that further generation rules might make it an infix in the text format.
We clearly understand that units are required by OpenMetrics 1.0, and we clearly understand that units must be used as metric name suffixes. However, at this point, if we accept this the only benefit would be to say "We're OpenMetrics 1.0 compatible". Being OpenMetrics 1.0 compatible is not a bad thing per se, but Prometheus hasn't used the Unit metadata for anything yet, so it brings Client_golang users little benefit while making our API a bit more complex.

If in the future Prometheus introduces the usage of Unit metadata, e.g. to properly sum metrics with different but compatible units (one in seconds and the other in milliseconds), we'd be happy to resurrect this.

In the name of the team, we apologize for taking this long to make a decision. Your work was quite involved, spreading contributions across multiple repositories and communicating with several stakeholders. We'd be happy to continue working with you if that's also of your interest :)

@ArthurSens, no worries at all, I totally understand. Of course I’d be delighted to continue working with the team, thanks for suggesting that!

vesari · 2024-05-20T05:30:04Z

Maybe we could start brainstorming how to use the unit metadata in Prometheus? Although this would be a high-complexity project that I would also need a lot of time to understand properly😬

Either this or anything the team deem useful. Whatever you think needs attention, I’ll be happy to work on :) Feel free to DM me on Slack if necessary. Thank you!

vesari · 2024-07-31T10:53:51Z

As agreed with @bwplotka, we want to add units eventually, but this needs more thought on how to avoid adding significant boilerplate to all users for that; help wanted, closing for now.

ArthurSens · 2025-06-09T21:33:34Z

We might want to ressurect this PR now that prometheus/proposals#39 adds a purpose to units in Prometheus :)

vesari · 2025-06-10T11:28:44Z

I'll be happy to do so

vesari · 2025-06-10T11:31:05Z

@kakkoyun ignore the request for review for now, as it was sent automatically once I reopened the PR. There's still a lot to catch up on here and work to do.

Signed-off-by: Arianna Vespri <[email protected]>

bwplotka

This is amazing. Solid work, thanks for finding way to not break compatibility.

Added a few suggestions and ideas, hope those help! Overall this goes in a good direction 👍🏽

bwplotka · 2025-12-02T10:42:29Z

prometheus/promhttp/http.go

-			enc = expfmt.NewEncoder(w, contentType)
+			encOpts = append(encOpts, expfmt.WithCreatedLines())
+		}
+		if opts.EnableOpenMetricsUnit {


Do we need this manual flag?

Why can't we simply add UNIT line if someone enabled OM? Shouldn't this be safe?

We added flag for EnableOpenMetricsTextCreatedSamples because we believe CT line is potentially breaking to the ecosystem (lot's of problems). But with UNIT metadata, I'd expect OM compatible parsers to either ignore it or parse. Even TEXT formats should work, because it's just a # .. comment.

The only potential risk is the slight increase of payload size, but this is actually limited by the user who need to manually add Unit: <....> fields to their metric definitions, no?

bwplotka · 2025-12-02T10:45:35Z

prometheus/promhttp/http.go

+			encOpts = append(encOpts, expfmt.WithCreatedLines())
+		}
+		if opts.EnableOpenMetricsUnit {
+			encOpts = append(encOpts, expfmt.WithUnit())


I wonder, does this print UNIT line if UNIT is unknown (empty string?)

Can we ensure this does NOT add UNIT if it's unknown? Just to safe space and limit the risks mentioned in https://github.com/prometheus/client_golang/pull/1392/files#r2580622660

prometheus/promhttp/http.go

bwplotka · 2025-12-02T10:47:12Z

prometheus/promhttp/http.go

 	EnableOpenMetricsTextCreatedSamples bool
+	// EnableOpenMetricsUnit enables unit metadata in the OpenMetrics output format.
+	// This is only applicable when OpenMetrics format is negotiated.
+	EnableOpenMetricsUnit bool


again, I wonder if we could skip this (reduce complexity and effort for everyone, users already need to manually add Unit field).

bwplotka · 2025-12-02T10:48:17Z

prometheus/promhttp/http_test.go

 	}

-	wantMsg := `error gathering metrics: error collecting metric Desc{fqName: "invalid_metric", help: "not helpful", constLabels: {}, variableLabels: {}}: collect error
+	wantMsg := `error gathering metrics: error collecting metric Desc{fqName: "invalid_metric", help: "not helpful", unit: "", constLabels: {}, variableLabels: {}}: collect error


Can we ensure everywhere we don't print empty string? (and just skip it?). It does not give a lot of info in an empty string form

bwplotka · 2025-12-02T10:58:39Z

prometheus/desc.go

 // For constLabels, the label values are constant. Therefore, they are fully
 // specified in the Desc. See the Collector example for a usage pattern.
-func (v2) NewDesc(fqName, help string, variableLabels ConstrainableLabels, constLabels Labels) *Desc {
+func (v2) NewDesc(fqName, help string, variableLabels ConstrainableLabels, constLabels Labels, unit ...string) *Desc {


Here, I wonder if we don't want to break compatibility. 🤔 It's V2 and I wished we marked it as experimental somewhere visibility (it was meant to experiment on a new API). However, I bet downstream ecosystem already started using it.

I'd suggest, (see A, B options in https://github.com/prometheus/client_golang/pull/1392/files#r2580668173)

For NewDesc we do (B)

For V2 we do (A) ?

bwplotka · 2025-12-02T10:59:29Z

prometheus/desc.go

 	// label names.
 	xxh.Reset()
 	xxh.WriteString(help)
+	xxh.WriteString(optionalUnitValue(unit...))


let's eval unit as soon as we have it from descV2Opts or something

bwplotka · 2025-12-02T10:59:44Z

prometheus/desc.go

 	}
 	return fmt.Sprintf(
-		"Desc{fqName: %q, help: %q, constLabels: {%s}, variableLabels: {%s}}",
+		"Desc{fqName: %q, help: %q, unit: %q, constLabels: {%s}, variableLabels: {%s}}",


ditto, optionally print it?

bwplotka · 2025-12-02T11:00:23Z

prometheus/go_collector_latest.go

 		sampleBuf = append(sampleBuf, metrics.Sample{Name: d.Name})
 		sampleMap[d.Name] = &sampleBuf[len(sampleBuf)-1]

+		// Extract unit from the runtime/metrics name (e.g., "/gc/heap/allocs:bytes" -> "bytes")


That's nice!

prometheus/metric.go

Co-authored-by: Bartlomiej Plotka <[email protected]> Signed-off-by: Arianna Vespri <[email protected]>

Signed-off-by: Arianna Vespri <[email protected]>

vesari · 2025-12-14T09:32:20Z

This is amazing. Solid work, thanks for finding way to not break compatibility.

Added a few suggestions and ideas, hope those help! Overall this goes in a good direction 👍🏽

Thank you very much, I'm working on addressing your requests for changes and your observations. I'll get back to you once I'm done :)

vesari force-pushed the add-unit branch from df2dcf4 to 6349728 Compare November 26, 2023 13:51

start adding support for units

d74a7fb

Signed-off-by: Arianna Vespri <[email protected]>

vesari force-pushed the add-unit branch from 6349728 to d74a7fb Compare November 26, 2023 14:01

vesari added 4 commits November 30, 2023 14:47

do not assume units for now

5d8c6de

Signed-off-by: Arianna Vespri <[email protected]>

again, do not assume units

f78b666

Signed-off-by: Arianna Vespri <[email protected]>

assume the units

e876012

Signed-off-by: Arianna Vespri <[email protected]>

add units in more places

b1f5a86

Signed-off-by: Arianna Vespri <[email protected]>

This was referenced Dec 2, 2023

Add unit field to MetricFamily proto message prometheus/client_model#75

Merged

Add OpenMetrics unit support prometheus/common#544

Merged

fix dependencies in go.mod

788d53b

Signed-off-by: Arianna Vespri <[email protected]>

vesari mentioned this pull request Dec 7, 2023

protobuf: add unit to metric family message prometheus/prometheus#13259

Merged

vesari mentioned this pull request Dec 17, 2023

protobuf: add unit parser prometheus/prometheus#13299

Merged

vesari added 11 commits January 19, 2024 14:22

Merge remote-tracking branch 'prometheus/main' into add-unit

1692495

Signed-off-by: Arianna Vespri <[email protected]>

Update version of common in go.mod

5971215

Signed-off-by: Arianna Vespri <[email protected]>

Start modifying handler

efb64f3

Signed-off-by: Arianna Vespri <[email protected]>

Merge remote-tracking branch 'prometheus/main' into add-unit

fafe45b

Use different common

51861d5

Signed-off-by: Arianna Vespri <[email protected]>

Merge remote-tracking branch 'prometheus/main' into add-unit

1362436

Signed-off-by: Arianna Vespri <[email protected]>

Use the newly named func for OM encoding

a2bfd3a

Signed-off-by: Arianna Vespri <[email protected]>

Merge remote-tracking branch 'prometheus/main' into add-unit

7900714

Signed-off-by: Arianna Vespri <[email protected]>

Fix examples and comments

19d7102

Signed-off-by: Arianna Vespri <[email protected]>

Fix go.mod

031e0d3

Signed-off-by: Arianna Vespri <[email protected]>

Adapt go.mod as much as possible

fd60a57

Signed-off-by: Arianna Vespri <[email protected]>

vesari added 5 commits March 15, 2024 13:33

Use go 1.20

f7e2848

Signed-off-by: Arianna Vespri <[email protected]>

Use go 1.21

5f58996

Signed-off-by: Arianna Vespri <[email protected]>

Upgrade github workflows to go 1.21 needed for common

ac9d1d8

Signed-off-by: Arianna Vespri <[email protected]>

Delete test funcs which are unused according to lint

3db440e

Signed-off-by: Arianna Vespri <[email protected]>

Upgrade to Go 1.21 in Makefile and workflows for tests

7752d37

Signed-off-by: Arianna Vespri <[email protected]>

ArthurSens reviewed May 10, 2024

View reviewed changes

vesari closed this Jul 31, 2024

ArthurSens mentioned this pull request Jun 3, 2025

feat: UnitNamer API prometheus/otlptranslator#35

Merged

vesari reopened this Jun 10, 2025

vesari requested a review from kakkoyun as a code owner June 10, 2025 11:28

vesari mentioned this pull request Oct 15, 2025

OpenMetrics unit support (in v1) #684

Open

vesari added 6 commits October 17, 2025 12:49

Merge remote-tracking branch 'prometheus/main' into add-unit

5b5c4be

small cleanup

a635a5a

Signed-off-by: Arianna Vespri <[email protected]>

Merge remote-tracking branch 'prometheus/main' into add-unit

e5f8851

Make desc funcs variadic

9eac68e

Signed-off-by: Arianna Vespri <[email protected]>

Adjust http to have unit and test accordingly

3441cb0

Signed-off-by: Arianna Vespri <[email protected]>

Merge remote-tracking branch 'prometheus/main' into add-unit

52eb82d

Signed-off-by: Arianna Vespri <[email protected]>

bwplotka reviewed Dec 2, 2025

View reviewed changes

vesari and others added 4 commits December 14, 2025 09:53

Update prometheus/metric.go

99ae579

Co-authored-by: Bartlomiej Plotka <[email protected]> Signed-off-by: Arianna Vespri <[email protected]>

Update prometheus/promhttp/http.go

1d93cb8

Co-authored-by: Bartlomiej Plotka <[email protected]> Signed-off-by: Arianna Vespri <[email protected]>

Merge remote-tracking branch 'prometheus/main' into add-unit

00d2201

Fix formatting

5a07918

Signed-off-by: Arianna Vespri <[email protected]>

Optionally add OM unit #1392

Are you sure you want to change the base?

Optionally add OM unit #1392

Uh oh!

Conversation

vesari commented Nov 26, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ArthurSens commented Mar 15, 2024

Uh oh!

vesari commented Mar 15, 2024

Uh oh!

ArthurSens left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vesari commented May 11, 2024

Uh oh!

beorn7 commented May 14, 2024

Uh oh!

vesari commented May 16, 2024

Uh oh!

beorn7 commented May 16, 2024

Uh oh!

ArthurSens commented May 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ArthurSens commented May 19, 2024

Uh oh!

vesari commented May 20, 2024

Uh oh!

vesari commented May 20, 2024

Uh oh!

vesari commented Jul 31, 2024

Uh oh!

ArthurSens commented Jun 9, 2025

Uh oh!

vesari commented Jun 10, 2025

Uh oh!

vesari commented Jun 10, 2025

Uh oh!

bwplotka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vesari commented Dec 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vesari commented Nov 26, 2023 •

edited

Loading

ArthurSens commented May 19, 2024 •

edited

Loading