# 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.

[ad-logs-small]

## 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:

```python
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()`.

[ad-uptime]