What Is A Bucket In Prometheus?

In Prometheus, a bucket is a concept used in histograms to organize observed values into predefined ranges. Buckets are critical for tracking and analyzing the distribution of values, such as response times or request sizes.

Key features of a bucket

1. Range-based grouping: A bucket defines a range of values (e.g., 0–100ms, 100–200ms). Observed values falling within this range are counted.

2. Cumulative counts: Buckets are cumulative, meaning each bucket includes all observations for its range and any lower ranges.

3. Used in histograms: Buckets are part of the histogram metric type, providing detailed data distribution insight.

How buckets work in histograms

Prometheus counts the number of observations that fall into each bucket range when using a histogram. For example, if you define buckets for request latency:

from prometheus_client import Histogram

# Define a histogram with buckets
request_latency = Histogram(
    'http_request_latency_seconds', 
    'Request latency in seconds',
    buckets=[0.1, 0.5, 1, 2.5, 5, 10]
)

# Observe a value
request_latency.observe(1.2)

Buckets in the above example: - 0.1: Count of requests with latency ≤ 0.1 seconds. - 0.5: Count of requests with latency ≤ 0.5 seconds. - 1: Count of requests with latency ≤ 1 second. - 2.5: Count of requests with latency ≤ 2.5 seconds. - 5: Count of requests with latency ≤ 5 seconds. - 10: Count of requests with latency ≤ 10 seconds.

Special bucket:

• Prometheus also creates a bucket labeled +Inf, which includes all observed values greater than the largest bucket.

If Prometheus scrapes the above metric, it might display something like:

http_request_latency_seconds_bucket{le="0.1"} 5
http_request_latency_seconds_bucket{le="0.5"} 15
http_request_latency_seconds_bucket{le="1"} 25
http_request_latency_seconds_bucket{le="2.5"} 35
http_request_latency_seconds_bucket{le="5"} 40
http_request_latency_seconds_bucket{le="10"} 50
http_request_latency_seconds_bucket{le="+Inf"} 60
http_request_latency_seconds_sum 75
http_request_latency_seconds_count 60

• le stands for "less than or equal to."
• Buckets track cumulative counts for each range.
• The sum and count are auxiliary metrics for calculating averages.

Choosing bucket ranges

The following are some of the factors to consider when choosing bucket ranges: - Ensure buckets match the expected range of values (e.g., typical response times). - Use fewer buckets for simplicity and better performance. - Avoid excessively wide or narrow buckets, as they can reduce the usefulness of the histogram.

Example for response times: - Buckets for a low-latency service: [0.01, 0.05, 0.1, 0.5, 1, 2.5, 5] - Buckets for a high-latency service: [0.5, 1, 5, 10, 20, 50, 100]

When to use buckets

Buckets are ideal when you need: - Insights into the distribution of values, such as latency, file sizes, or response codes. - Aggregated data for performance monitoring. - Detailed PromQL queries on percentiles, e.g., histogram_quantile().

Got an article suggestion? Let us know

Explore more

How To Manage Prometheus Counters

Questions

How to Add Custom HTTP Headers in Prometheus

Questions

What is the Difference Between a Gauge and a Counter?

Questions

How to Monitor Disk Usage in Kubernetes Persistent Volumes

Questions

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.