Add example for combined histogram with labels

Illustrate that ordering matters for this new format to aid parsing.

Signed-off-by: Chris Marchbanks <[email protected]>

proposals/2024-01-29_native_histograms_text_format.md

@@ -49,12 +49,15 @@ Client library maintainers, OpenMetrics, and Prometheus scrape maintainers.
 Extend the OpenMetrics text format to allow structured values instead of only float values for specific series of a histogram type. This structured value will be used to encode a structure with the same fields as is exposed using the [protobuf exposition format](https://github.com/prometheus/client_model/blob/master/io/prometheus/client/metrics.proto). Starting with examples and then breaking up the format:
 ```
 # TYPE nativehistogram histogram
+# HELP nativehistogram Is a basic example of a native histogram.
 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]}
 
 # TYPE hist_with_labels histogram
+# HELP hist_with_labels Is an example of a native histogram with labels.
 hist_with_labels{foo="bar",baz="qux"} {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]}
 
 # TYPE hist_with_classic_buckets histogram
+# HELP hist_with_classic_buckets Is an example of native and classic histograms together.
 hist_with_classic_buckets {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]}
 hist_with_classic_buckets_bucket{le="0.001"} 4
 hist_with_classic_buckets_bucket{le="+Inf"} 24
@@ -81,6 +84,24 @@ Positive infinity, negative infinity, and non number values will be represented
 
 Note that in this initial implementation float histograms are not supported. Float histograms are rarely used in exposition, and OpenMetrics does not support classic float histograms either. Support could be added in the future by adding fields for `count_float`, `zero_count_float`, `negative_counts`, and `positive_counts`.
 
+If native histograms and a classic histogram are exposed simultaneously the native histogram must come first for any labelset. For example:
+```
+# TYPE hist_with_classic_buckets histogram
+# HELP hist_with_classic_buckets Is an example of combining native and classic histograms for two labelsets.
+hist_with_classic_buckets{foo="bar"} {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]}
+hist_with_classic_buckets_bucket{foo="bar",le="0.001"} 4
+hist_with_classic_buckets_bucket{foo="bar",le="+Inf"} 24
+hist_with_classic_buckets_count{foo="bar"} 24
+hist_with_classic_buckets_sum{foo="bar"} 100
+hist_with_classic_buckets_created{foo="bar"} 1717536092
+hist_with_classic_buckets{foo="baz"} {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]}
+hist_with_classic_buckets_bucket{foo="baz",le="0.001"} 4
+hist_with_classic_buckets_bucket{foo="baz",le="+Inf"} 24
+hist_with_classic_buckets_count{foo="baz"} 24
+hist_with_classic_buckets_sum{foo="baz"} 100
+hist_with_classic_buckets_created{foo="baz"} 1717536098
+```
+
 ### 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).