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