-
Owners:
- Chris Marchbanks @csmarchbanks
-
Implementation Status: Not implemented
-
Related Issues and PRs:
-
Other docs or links:
TL;DR: This design doc is proposing a format for exposing native histograms in the OpenMetrics text format.
Today it is only possible to export native histograms using the Protocol Buffers (protobuf) scrape format. Many users prefer the text format, and some client libraries, such as the Python client, want to avoid adding a dependency on protobuf.
During a dev summit in 2022 there was consensus we would continue to support the text format. Including native histograms as part of the text format shows commitment to that consensus.
Prometheus client libraries such as Python do not want to require a dependency on protobuf in order to expose native histograms, and in some languages protobuf is painful to use. Gating native histograms only to clients/users willing to use protobuf hurts adoption of native histograms, therefore, we would like a way to represent a native histogram in the text based format.
Goals and use cases for the solution as proposed in How:
- Support native histograms in the text format
- (Secondary) Encode/decode efficiency
- (Secondary) Ease of implementation for client libraries
- (Secondary) Human readibility of the format
Note that the goals of efficiency and human readability are commonly at odds with each other.
Client library maintainers, OpenMetrics, and Prometheus scrape maintainers.
- Requiring backwards compatability (OpenMetrics 2.0 would be ok), and especially forwards compatability (not required in the OpenMetrics spec).
Extend the OpenMetrics text format to allow structured values instead of only float values. This structured value will be used to encode a structure with the same fields as is exposed using the protobuf exposition format. Starting with an example and then breaking up the format:
# TYPE nativehistogram histogram
nativehistogram {count:24,sum:100,schema:0,zero_threshold:0.001,zero_count:4,positive_span:[0:2,1:2],negative_span:[0:2,1:2],positive_delta:[2,1,-2,3],negative_delta:[2,1,-2,3]}
The metric will have no "magic" suffixes, then the value for each series is a custom struct format with the following fields:
sum: float64- The sum of all observations for this histogram. Could be negative in cases with negative observations.count: uint64- The number of samples that were observed for this histogram.schema: int32- The schema used for this histogram, currently supported values are -4 -> 8.zero_threshold: float64- The width of the zero bucket.zero_count: uint64- The number of observations inside the zero bucket.negative_span: []BucketSpan- The buckets corresponding to negative observations, optional.negative_delta: []int64- The delta of counts compared to the previous bucket.positive_span: []BucketSpan- The buckets corresponding to negative observations, optional.positive_delta: []int64- The delta of counts compared to the previous bucket.
A bucket span is the combination of an int32 offset and a uint32 length. It is encoded as <offset>:<length>. Lists/arrays are encoded within square brackets with elements separated by commas. Compared to JSON this avoids consistently repeating keys and curly braces.
Positive infinity, negative infinity, and non number values will be represented as case insensitive versions of +Inf, -Inf, and NaN respectively in any field. This is the same behavior for values in OpenMetrics today.
Note that in this initial implementation float histograms are not supported.
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.
One valid option is to avoid this extra format and require anyone who desires to use native histograms to use protobuf for exposition. It would go against the consensus of the Prometheus team members from 2022 however.
See the alternate exposition formats proposed in the design document. The other formats generally added in additional readability/verbosity at the expense of performance.
The tasks to do in order to migrate to the new idea.
- Implement an encoder and parser in client_python
- Implement an experimental parser in the Prometheus server
- Update OpenMetrics with formalized syntax