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 <arianna.vespri@yahoo.it>

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 <arianna.vespri@yahoo.it>

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 <arianna.vespri@yahoo.it>

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?

I see your point. However, as things stand, the flag is necessary because prometheus/common's expfmt encoder requires explicit opt-in via WithUnit() to output units. Without it, units are silently ignored even if set in the MetricFamily. I think this was to avoid potential changes to metric names to happen automatically. In fact, because of this logic

if we:

Opt in with WithUnit()

Have a metric foo_total with Unit: "seconds"

The metric name doesn't already end with _seconds

The metric name becomes foo_seconds_total. I believe the consensus back then was this should be the result of a very explicit decision by the user.
Of course, if - for example - we decide we’re allowed not to enforce the unit suffix anymore or that we deem acceptable to silently add unit suffixes, then the flag becomes superfluous, and can be removed as soon as the related code in common gets modified accordingly. I’ll be happy to do that myself, if consensus is ever reached in that sense.

I think we agree it's a bit toxic to change name depending on the unit, even though it's what OM 1.0 kind of requires (but there tons of other way to handle this e.g. return error on registration e.g. using pedantic registry).

To proceed I think we need to simplify this for users and make sure there's a mode in expfmt that do not change metric names, perhaps even to _total. Then we also need to reduce risk this mode will be not alter.

The problem with adding a feature flag "for now", it's because it's for forever (v1) and it's also adding a flag with something that we don't recommend and can have consequences. So let's try to alter common then?

Sure thing. Opened the corresponding PR on common today.

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 <bwplotka@gmail.com> Signed-off-by: Arianna Vespri <36129782+vesari@users.noreply.github.com>

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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 :)

…t is given Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

…c argument in V2 NewDesc Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

vesari · 2026-01-11T10:14:44Z

This is now ready for review :)

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 <arianna.vespri@yahoo.it>

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 <arianna.vespri@yahoo.it>

again, do not assume units

f78b666

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

assume the units

e876012

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

add units in more places

b1f5a86

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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 <arianna.vespri@yahoo.it>

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 <arianna.vespri@yahoo.it>

Update version of common in go.mod

5971215

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Start modifying handler

efb64f3

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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

fafe45b

Use different common

51861d5

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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

1362436

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Use the newly named func for OM encoding

a2bfd3a

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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

7900714

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Fix examples and comments

19d7102

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Fix go.mod

031e0d3

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Adapt go.mod as much as possible

fd60a57

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

vesari added 5 commits March 15, 2024 13:33

Use go 1.20

f7e2848

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Use go 1.21

5f58996

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Upgrade github workflows to go 1.21 needed for common

ac9d1d8

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Delete test funcs which are unused according to lint

3db440e

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Upgrade to Go 1.21 in Makefile and workflows for tests

7752d37

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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 <arianna.vespri@yahoo.it>

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

e5f8851

Make desc funcs variadic

9eac68e

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Adjust http to have unit and test accordingly

3441cb0

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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

52eb82d

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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 <bwplotka@gmail.com> Signed-off-by: Arianna Vespri <36129782+vesari@users.noreply.github.com>

Update prometheus/promhttp/http.go

1d93cb8

Co-authored-by: Bartlomiej Plotka <bwplotka@gmail.com> Signed-off-by: Arianna Vespri <36129782+vesari@users.noreply.github.com>

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

00d2201

Fix formatting

5a07918

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

vesari added 5 commits January 4, 2026 15:53

Add tests for unit edge cases, ensure unit field is skipped if no uni…

7b8aec9

…t is given Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Restore original NewDesc signature, replace unit with DescOpt variadi…

2efe1b8

…c argument in V2 NewDesc Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

Eval unit asap

38444fe

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

test runtime metrics unit extraction

3dac913

Signed-off-by: Arianna Vespri <arianna.vespri@yahoo.it>

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

410798a

vesari requested a review from bwplotka January 11, 2026 10:14

vesari mentioned this pull request Jan 27, 2026

Remove logic adding unit to metrics name prometheus/common#877

Open

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!

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!

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!

vesari commented Jan 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vesari commented Nov 26, 2023 •

edited

Loading