From 7af982722f6e06f49cf4e19a44361a983388db91 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Thu, 6 Jun 2024 15:04:55 -0600 Subject: [PATCH] Include support for multiple exemplars Provide a paragraph describing support for multiple exemplars as part of this proposal. Currently it is left ambiguous if a list of exemplars can be included on more than native histograms, we can define that explicitly when writing the new OpenMetrics spec. Signed-off-by: Chris Marchbanks --- proposals/2024-01-29_native_histograms_text_format.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/proposals/2024-01-29_native_histograms_text_format.md b/proposals/2024-01-29_native_histograms_text_format.md index ba85209..4807283 100644 --- a/proposals/2024-01-29_native_histograms_text_format.md +++ b/proposals/2024-01-29_native_histograms_text_format.md @@ -42,7 +42,6 @@ Client library maintainers, OpenMetrics, and Prometheus scrape maintainers. ## Non-Goals * Requiring backwards compatability (OpenMetrics 2.0 would be ok), and especially forwards compatability (not required in the OpenMetrics spec). -* Support for multiple exemplars (this will be done in a future proposal). ## How @@ -102,6 +101,13 @@ hist_with_classic_buckets_sum{foo="baz"} 100 hist_with_classic_buckets_created{foo="baz"} 1717536098 ``` +Finally, multiple exemplars will also be supported in the exposition format by providing a list of exemplars at the end of any line, separated by `#`. Note that having spaces around the hashes is required and matches the [ABNF specification in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#abnf). For example: +``` +# TYPE exemplar_example histogram +# HELP exemplar_example Is an example of a native histogram with exemplars. +nativehistogram {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,positive_spans:[0:2,1:2],negative_spans:[0:2,1:2],positive_deltas:[2,1,-2,3],negative_deltas:[2,1,-2,3]} # {trace_id="KOO5S4vxi0o"} 0.67 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789 +``` + ### Backwards compatibility and semantic versioning After discussions with a few people it is believed that these changes can be made in a 1.x release of OpenMetrics. OpenMetrics 1.x parsers that support native histograms will still be able to read OpenMetrics 1.0 responses, therefore this change is backwards compatible. However, this change is not forwards compatible, i.e. an OpenMetrics 1.0 parser will not be able to read an OpenMetrics >= 1.1 response. Any producers implementing native histograms MUST also implement content negotiation and fall back to OpenMetrics 1.0.0, and therefore not expose native histograms, if a supported version cannot be negotiated. Note that the behavior to fall back to 1.0.0 is already part of the [OpenMetrics spec](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#protocol-negotiation).