feat: implement gauge and counter support for OpenMetrics 2.0 by dashpole · Pull Request #894 · prometheus/common

dashpole · 2026-04-07T02:24:55Z

Part 1 of #893

Histograms and summaries are left for follow-ups.

Open Questions:

How do we indicate that OM 2.0 support is experimental?

bwplotka

For common, given v0 I would just comment on the method. If we want to be fancy we can generate comment in the exposition format too (:

Looks good so far, good start (see comments) - only question is do we iterate on this on main or some feature branch - no strong opinion, assuming commentary is clear.

Thanks

ywwg

looks good to me so far. My general opinion is that if some scraper asks for openmetrics 2.0, they should get it... Hypothetically I could see requiring the version number "2.0.0rc" or "1.9.9" just in case?

dashpole · 2026-05-13T14:12:52Z

Lots of discussion at the OM wg. We will add a NegotiateIncluding() function that takes a list of supported protocols so we don't end up with NegotiateIncludingOpenMetricsAndOpenMetrics2 ... 😆 . Then the client can decide when it wants to add support, and how it wants to gate it (behind HandlerOpts.EnableOpenMetrics?).

dashpole · 2026-05-27T14:28:22Z

I added a NegotiateIncluding function. I didn't deprecate the old functions (e.g. NegotiateIncludingOpenMetrics), but we can do that in a follow-up if we want to.

bwplotka · 2026-06-24T13:15:25Z

I think that's great, the experimental factor at this level should be a commentary.

As per discussion on Slack I think we decided to follow:

Exposer should eventually switch to OM2 default, but only once ready (which means we recommend opt-in "exposed protocol" option)
Scrapers should be opt-in for now, while OM2 is experimental

dashpole · 2026-07-07T18:26:22Z

In the spirit of @krajorama's feedback, i've updated the implementation to perform some additional validation. It checks for newline characters, NaN and negative counter values, valid timestamps, empty exemplar label keys. It does not validate UTF-8 for strings, or duplicate label keys or duplicate label sets because those are expensive to validate. This does more validation than OM 1.0, but still leaves some things not validated. I also ended up writing benchmarks as part of that work, which i've split into #943.

The benchmark results from #943 run against this PR are:

goos: linux
goarch: amd64
pkg: github.com/prometheus/common/expfmt
cpu: Intel(R) Xeon(R) CPU @ 2.20GHz
                                             │ /tmp/bench.txt │
                                             │     sec/op     │
ConvertMetricFamily/TEXT/COUNTER-24               775.5n ± 1%
ConvertMetricFamily/OM1.0/COUNTER-24              1.664µ ± 1%
ConvertMetricFamily/OM2.0/COUNTER-24              1.617µ ± 1%
ConvertMetricFamily/TEXT/GAUGE-24                 761.5n ± 1%
ConvertMetricFamily/OM1.0/GAUGE-24                1.091µ ± 6%
ConvertMetricFamily/OM2.0/GAUGE-24                1.003µ ± 3%
ConvertMetricFamily/TEXT/UNTYPED-24               680.6n ± 1%
ConvertMetricFamily/OM1.0/UNTYPED-24              923.8n ± 3%
ConvertMetricFamily/OM2.0/UNTYPED-24              883.1n ± 1%
ConvertMetricFamily/TEXT/SUMMARY-24               3.207µ ± 1%
ConvertMetricFamily/OM1.0/SUMMARY-24              3.965µ ± 1%
ConvertMetricFamily/TEXT/HISTOGRAM-24             4.532µ ± 2%
ConvertMetricFamily/OM1.0/HISTOGRAM-24            5.582µ ± 2%
ConvertMetricFamily/TEXT/GAUGE_HISTOGRAM-24       3.414µ ± 1%
ConvertMetricFamily/OM1.0/GAUGE_HISTOGRAM-24      3.852µ ± 1%
geomean                                           1.741µ

                                             │ /tmp/bench.txt │
                                             │      B/op      │
ConvertMetricFamily/TEXT/COUNTER-24              0.000 ± 0%
ConvertMetricFamily/OM1.0/COUNTER-24             33.00 ± 0%
ConvertMetricFamily/OM2.0/COUNTER-24             0.000 ± 0%
ConvertMetricFamily/TEXT/GAUGE-24                0.000 ± 0%
ConvertMetricFamily/OM1.0/GAUGE-24               1.000 ± 0%
ConvertMetricFamily/OM2.0/GAUGE-24               0.000 ± 0%
ConvertMetricFamily/TEXT/UNTYPED-24              0.000 ± 0%
ConvertMetricFamily/OM1.0/UNTYPED-24             1.000 ± 0%
ConvertMetricFamily/OM2.0/UNTYPED-24             0.000 ± 0%
ConvertMetricFamily/TEXT/SUMMARY-24              56.00 ± 0%
ConvertMetricFamily/OM1.0/SUMMARY-24             57.00 ± 0%
ConvertMetricFamily/TEXT/HISTOGRAM-24            288.0 ± 0%
ConvertMetricFamily/OM1.0/HISTOGRAM-24           289.0 ± 0%
ConvertMetricFamily/TEXT/GAUGE_HISTOGRAM-24      160.0 ± 0%
ConvertMetricFamily/OM1.0/GAUGE_HISTOGRAM-24     161.0 ± 0%
geomean                                                     ¹
¹ summaries must be >0 to compute geomean

                                             │ /tmp/bench.txt │
                                             │   allocs/op    │
ConvertMetricFamily/TEXT/COUNTER-24              0.000 ± 0%
ConvertMetricFamily/OM1.0/COUNTER-24             2.000 ± 0%
ConvertMetricFamily/OM2.0/COUNTER-24             0.000 ± 0%
ConvertMetricFamily/TEXT/GAUGE-24                0.000 ± 0%
ConvertMetricFamily/OM1.0/GAUGE-24               1.000 ± 0%
ConvertMetricFamily/OM2.0/GAUGE-24               0.000 ± 0%
ConvertMetricFamily/TEXT/UNTYPED-24              0.000 ± 0%
ConvertMetricFamily/OM1.0/UNTYPED-24             1.000 ± 0%
ConvertMetricFamily/OM2.0/UNTYPED-24             0.000 ± 0%
ConvertMetricFamily/TEXT/SUMMARY-24              2.000 ± 0%
ConvertMetricFamily/OM1.0/SUMMARY-24             3.000 ± 0%
ConvertMetricFamily/TEXT/HISTOGRAM-24            6.000 ± 0%
ConvertMetricFamily/OM1.0/HISTOGRAM-24           7.000 ± 0%
ConvertMetricFamily/TEXT/GAUGE_HISTOGRAM-24      5.000 ± 0%
ConvertMetricFamily/OM1.0/GAUGE_HISTOGRAM-24     6.000 ± 0%
geomean                                                     ¹
¹ summaries must be >0 to compute geomean

Signed-off-by: David Ashpole <dashpole@google.com>

…rt timestamps Signed-off-by: David Ashpole <dashpole@google.com>

Signed-off-by: David Ashpole <dashpole@google.com>

…ion loss Signed-off-by: David Ashpole <dashpole@google.com>

…sion loss Signed-off-by: David Ashpole <dashpole@google.com>

…cision Signed-off-by: David Ashpole <dashpole@google.com>

bwplotka

Looks good, just one last API question

bwplotka · 2026-08-11T13:23:46Z

 	//nolint:revive // Allow for underscores.
 	FmtOpenMetrics_1_0_0 Format = OpenMetricsType + `; version=` + OpenMetricsVersion_1_0_0 + `; charset=utf-8`
+	//nolint:revive // Allow for underscores.
+	FmtOpenMetrics_2_0_0 Format = OpenMetricsType + `; version=` + OpenMetricsVersion_2_0_0 + `; charset=utf-8`


The PR introduces FmtOpenMetrics_2_0_0 as an exported constant. Adjacent older formats are explicitly marked as // Deprecated: Use expfmt.NewFormat(expfmt.TypeOpenMetrics) instead.. Introducing a new format-specific exported constant reproduces the very API footprint that maintainers actively deprecated. Consider changing to unexported fmtOpenMetrics_2_0_0.

bwplotka · 2026-08-11T13:23:48Z

+	}
+}
+
+func TestCreateOpenMetrics20_Errors(t *testing.T) {


Missing test for Counter CreatedTimestamp validation (Edge case coverage). Add a test case in TestCreateOpenMetrics20_Errors where Metric.Counter.CreatedTimestamp is mathematically invalid (e.g., negative seconds or out-of-bounds) to assert it cleanly returns the validation error message.

bwplotka · 2026-08-11T13:23:49Z

+	return strings.IndexByte(s, '\n') >= 0 || strings.IndexByte(s, '\r') >= 0
+}
+
+func validateExemplar20(e *dto.Exemplar) error {


Missing test for Exemplar Timestamp validation (Edge case coverage). Add a test case with an invalid Exemplar Timestamp (e.g. invalid protobuf timestamp values) to ensure validateExemplar20 correctly captures and bubbles up the CheckValid() error.

bwplotka · 2026-08-11T13:23:51Z

+		t.Run(tc.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			_, err := MetricFamilyToOpenMetrics20(&buf, tc.in)
+			if err == nil {


Update the err == nil logic to strictly check if the actual err.Error() matches the exact expected error message or a substring representing it. Currently, the test blindly accepts any generic non-nil error, masking regressions.

bwplotka · 2026-08-11T13:23:51Z

+	for _, scenario := range scenarios {
+		t.Run(scenario.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			_, err := MetricFamilyToOpenMetrics20(&buf, scenario.in)


Weak Unit Test Assertions on Written Bytes count. The functions return the number of bytes written, but this test suppresses it with _, err := ... . Verify that the returned byte count equals len(buf.String()) / len(expected) to ensure the returned byte counting arithmetic functions properly.

bwplotka · 2026-08-11T13:56:24Z

 // FmtOpenMetrics as an option for the result. Note that this function is
 // temporary and will disappear once FmtOpenMetrics is fully supported and as
 // such may be negotiated by the normal Negotiate function.
 func NegotiateIncludingOpenMetrics(h http.Header) Format {


Can we deprecate this in favor of the new function?

bwplotka · 2026-08-11T13:58:50Z

+// Additional formats provided in the arguments are also included as options,
+// and are checked in the order they are provided, respecting the preference
+// order in the Accept header.
+func NegotiateIncluding(h http.Header, additionalFormats ...Format) Format {


nit: Since we bake new API, what about something more explicit like: NegotiateAccept(h http.Header, accepted ...Format) Format { that would allow us to provide full list vs speculating what's default what's not (especially when default change?)

bwplotka · 2026-08-12T12:32:31Z

+		return false
+	}
+
+	// Default OpenMetrics version to OpenMetricsVersion_0_0_1


Suggested change

// Default OpenMetrics version to OpenMetricsVersion_0_0_1

// Default OpenMetrics version to OpenMetricsVersion_0_0_1.

bwplotka · 2026-08-12T12:32:35Z

+		acVersion = OpenMetricsVersion_0_0_1
+	}
+
+	// General param matching


Suggested change

// General param matching

// General param matching.

dashpole force-pushed the om2_1 branch from 394d565 to ce10d25 Compare April 7, 2026 02:28

bwplotka reviewed Apr 7, 2026

View reviewed changes

dashpole marked this pull request as ready for review April 7, 2026 19:09

ywwg reviewed Apr 16, 2026

View reviewed changes

dashpole force-pushed the om2_1 branch 2 times, most recently from 873bb38 to 1bcdef1 Compare May 27, 2026 15:39

dashpole requested review from bwplotka and ywwg June 4, 2026 13:21

bwplotka reviewed Jun 24, 2026

View reviewed changes

Comment thread expfmt/encode.go

krajorama self-requested a review June 24, 2026 13:33

krajorama requested changes Jun 24, 2026

View reviewed changes

Comment thread expfmt/openmetrics_2_0_create_test.go

Comment thread expfmt/openmetrics_2_0_create.go Outdated

Comment thread expfmt/openmetrics_2_0_create_test.go

Comment thread expfmt/openmetrics_2_0_create_test.go Outdated

Comment thread expfmt/encode.go

dashpole force-pushed the om2_1 branch 16 times, most recently from ab106e7 to 2f87680 Compare July 7, 2026 17:13

dashpole force-pushed the om2_1 branch 4 times, most recently from 46773f6 to 42ca72f Compare July 7, 2026 18:20

dashpole mentioned this pull request Jul 7, 2026

Combine and extend Prometheus text and OpenMetrics 1.0 encoder benchmarks #943

Merged

dashpole force-pushed the om2_1 branch from 42ca72f to 9cd7607 Compare July 8, 2026 15:42

dashpole added 5 commits July 31, 2026 20:32

feat: implement gauge and counter support for OpenMetrics 2.0

fb162d2

Signed-off-by: David Ashpole <dashpole@google.com>

address code review comments

ebb1df5

Signed-off-by: David Ashpole <dashpole@google.com>

Add NegotiateIncluding and refactor negotiation functions

202fd75

Signed-off-by: David Ashpole <dashpole@google.com>

Address review feedback for OpenMetrics 2.0 exemplars and counter sta…

ea0cc50

…rt timestamps Signed-off-by: David Ashpole <dashpole@google.com>

Add strict validation to OpenMetrics 2.0 encoder to reject invalid input

ab3f86d

Signed-off-by: David Ashpole <dashpole@google.com>

dashpole force-pushed the om2_1 branch from 9cd7607 to 000a829 Compare July 31, 2026 20:33

dashpole added 4 commits July 31, 2026 20:36

Add writeProtoTimestamp helper to avoid float64 precision loss

84f713c

Signed-off-by: David Ashpole <dashpole@google.com>

Use writeProtoTimestamp for created timestamp to avoid float64 precis…

33a9d90

…ion loss Signed-off-by: David Ashpole <dashpole@google.com>

Use writeProtoTimestamp for exemplar timestamp to avoid float64 preci…

4bbe8e5

…sion loss Signed-off-by: David Ashpole <dashpole@google.com>

Update subsecond created timestamp test output to full nanosecond pre…

5eb738f

…cision Signed-off-by: David Ashpole <dashpole@google.com>

dashpole force-pushed the om2_1 branch from 000a829 to 5eb738f Compare July 31, 2026 20:36

bwplotka approved these changes Aug 12, 2026

View reviewed changes

	// Default OpenMetrics version to OpenMetricsVersion_0_0_1
	// Default OpenMetrics version to OpenMetricsVersion_0_0_1.

Uh oh!

Conversation

dashpole commented Apr 7, 2026

Uh oh!

bwplotka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ywwg left a comment

Choose a reason for hiding this comment

Uh oh!

dashpole commented May 13, 2026

Uh oh!

dashpole commented May 27, 2026

Uh oh!

bwplotka commented Jun 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dashpole commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dashpole commented Jul 7, 2026 •

edited

Loading