histograms should be histograms

[donbourne]

MP Metrics histograms don't actually provide the data expected of a histogram in their data representation or their output. Histograms are expected to summarize the count of data points that fall into a set of buckets. Currently MP Metrics histograms provide data on percentiles, but do not provide bucket counts.

I propose the following:

• Histograms should support having percentiles and/or buckets
• Histograms should output using the prometheus histogram type (currently it uses summary type)

from https://prometheus.io/docs/instrumenting/exposition_formats/#text-format-example : prometheus histogram

# A histogram, which has a pretty complex representation in the text format:
# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.2"} 100392
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320

prometheus summary

# Finally a summary, which has a complex representation, too:
# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.01"} 3102
rpc_duration_seconds{quantile="0.05"} 3272
rpc_duration_seconds{quantile="0.5"} 4773
rpc_duration_seconds{quantile="0.9"} 9001
rpc_duration_seconds{quantile="0.99"} 76656
rpc_duration_seconds_sum 1.7560473e+07
rpc_duration_seconds_count 2693

For reference, using Micrometer's DistributionSummary with serviceLevelObjectives specified and a PrometheusMeterRegistry, the PrometheusMeterRegistry.scrape output produces a Prometheus histogram:

# HELP distance_to_hole_meters Distance of golf ball to hole
# TYPE distance_to_hole_meters histogram
distance_to_hole_meters{scope="golf_stats",quantile="0.0",} 0.002685546875
distance_to_hole_meters{scope="golf_stats",quantile="0.5",} 2.8748779296875
distance_to_hole_meters{scope="golf_stats",quantile="0.75",} 4.4998779296875
distance_to_hole_meters{scope="golf_stats",quantile="0.95",} 7.9998779296875
distance_to_hole_meters{scope="golf_stats",quantile="0.98",} 9.4998779296875
distance_to_hole_meters{scope="golf_stats",quantile="0.99",} 11.9998779296875
distance_to_hole_meters{scope="golf_stats",quantile="0.999",} 12.9998779296875
distance_to_hole_meters_bucket{scope="golf_stats",le="2.0",} 165.0
distance_to_hole_meters_bucket{scope="golf_stats",le="4.0",} 332.0
distance_to_hole_meters_bucket{scope="golf_stats",le="6.0",} 432.0
distance_to_hole_meters_bucket{scope="golf_stats",le="8.0",} 464.0
distance_to_hole_meters_bucket{scope="golf_stats",le="10.0",} 482.0
distance_to_hole_meters_bucket{scope="golf_stats",le="+Inf",} 487.0
distance_to_hole_meters_count{scope="golf_stats",} 487.0
distance_to_hole_meters_sum{scope="golf_stats",} 1569.3785694223322
# HELP distance_to_hole_meters_max Distance of golf ball to hole
# TYPE distance_to_hole_meters_max gauge
distance_to_hole_meters_max{scope="golf_stats",} 12.722726616315509

[donbourne]

based on experimentation with micrometer api and prometheusMeterRegistry:

• DistributionSummary instances configured to have buckets and percentiles produce histogram type (and a gauge for max value)
• DistributionSummary instances configured to have buckets and no percentiles produce histogram type (and a gauge for max value)
• DistributionSummary instances configured to have no buckets and percentiles produce summary type (and a gauge for max value)
• DistributionSummary instances configured to have no buckets and no percentiles produce summary type (and a gauge for max value)

so effectively, if the metric has buckets a histogram is produced from PrometheusMeterRegistry.scrape() else a summary is produced.

[donbourne]

Based on the above comment, we could add histogram buckets without breaking backward compatibility. When histograms are configured to be part of the metric a histogram output type would be used. When there are no buckets, a summary would be used (same behavior for this case as in MP Metrics 5.0)