What is a Prometheus histogram bucket?

In a classic Prometheus histogram, a bucket counts observations less than or equal to a boundary identified by the le label. For example, request_duration_seconds_bucket{le="0.5"} counts requests taking no more than half a second.

The instrumented application or exporter maintains these counts and exposes them for Prometheus to scrape. Native histograms use a different representation; the separate _bucket series described here are the classic form.

Buckets are cumulative

For configured boundaries of 0.1, 0.5, 1, and 5 seconds, an exporter might expose:

request_duration_seconds_bucket{le="0.1"} 105
request_duration_seconds_bucket{le="0.5"} 480
request_duration_seconds_bucket{le="1"} 760
request_duration_seconds_bucket{le="5"} 799
request_duration_seconds_bucket{le="+Inf"} 800

The 480 observations in the 0.5-second bucket already include the 105 observations in the 0.1-second bucket. The +Inf bucket includes every observation and equals the histogram's count. Do not add cumulative buckets together to obtain a total.

Estimate a percentile

histogram_quantile(
  0.95,
  sum by (le) (rate(request_duration_seconds_bucket[5m]))
)

rate converts each bucket counter into a rate before aggregation. Keeping le allows histogram_quantile to locate the bucket containing the percentile and estimate a value within it. Classic histograms generally use linear interpolation within finite buckets, so a wide bucket can produce a coarse estimate.

Aggregate only compatible bucket layouts for the population being measured. Retain a service label in the grouping when you need a separate percentile per service.

Choose meaningful boundaries

Place a boundary exactly at an SLO threshold when you need to count observations meeting it. Add finer boundaries around a decision-sensitive region, such as 0.3, 0.4, 0.5, 0.6, and 0.8 seconds around a 500 ms threshold.

Choose finite buckets that cover the useful latency range. Outliers still enter +Inf, but a percentile falling beyond the last finite boundary cannot be located precisely. Every classic bucket adds a series per label combination, in addition to sum and count; balance useful resolution against cardinality rather than adopting a universal bucket count.

FAQ

Can I change bucket boundaries later? Yes, but earlier samples retain their earlier layout. During a rolling change, different instances may expose different boundaries. Plan the migration and query windows so mixed layouts do not silently distort aggregation.

Can I graph bucket series directly? Yes, but remember that they are cumulative counters. Rates can show threshold traffic; a histogram-aware heatmap can convert cumulative buckets into intervals. For a percentile trend, use histogram_quantile.

Sources

This guide is based on the documentation below; the examples have not been tested against a live deployment.

• Prometheus histograms and summaries
• Prometheus query functions