Prometheus Retention Storage Calculator
Estimate Prometheus local storage from series or sample rate, then account for retention and compression plus WAL reserve and disk budget.| Capacity item | Value | Basis | Copy |
|---|---|---|---|
| {{ row.item }} | {{ row.value }} | {{ row.basis }} |
| Guardrail | Reading | Operator action | Copy |
|---|---|---|---|
| {{ row.guardrail }} | {{ row.reading }} | {{ row.action }} |
Prometheus retention is a capacity decision about how much local history one server can keep without exhausting its data volume. The main driver is ingest rate: every active time series contributes samples at its scrape interval, and those samples accumulate for each retained day. Cardinality growth or a shorter scrape interval can therefore consume more disk even when the number of scrape targets stays unchanged.
Local time series database storage is not one uniform pile. Compacted blocks hold historical samples efficiently, while the current head data and write-ahead log protect recent ingestion and can consume substantial extra space. Compaction can also need temporary room for old and new blocks at the same time. A safe plan leaves operational headroom instead of setting a retention limit equal to the entire volume.
| Storage area | Planning role | Important limit |
|---|---|---|
| Persistent blocks | Compressed historical samples retained by time or size policy | Estimated mainly from samples per second, bytes per sample, and days |
| WAL and head | Recent samples and replay protection before full compaction | Does not shrink in direct proportion to the block retention limit |
| Compaction headroom | Temporary room while source and compacted blocks coexist | Needed even when steady-state blocks appear to fit |
| Remote storage | Optional long-term or centralized retention outside the local TSDB | Not included in a local Prometheus disk estimate |
There are two practical ways to establish ingest. A bottom-up estimate multiplies scrape targets by active series per target and divides by the effective scrape interval. A measured samples-per-second rate is usually stronger when it represents sustained production traffic, because it already reflects dropped targets, service discovery, relabeling, and irregular scrape patterns.
Compressed bytes per sample is an assumption, not a universal constant. Prometheus documents roughly 1 to 2 bytes per stored sample as a planning range for persistent blocks, but label churn, chunk shape, indexes, tombstones, backfill, and workload changes can move observed storage. The best estimate pairs the model with recent TSDB measurements and a forecast for cardinality growth.
Retention protects history, not durability. A single local Prometheus data directory is not replicated storage, and reducing retained days does not replace snapshots, redundant scraping, or a tested remote-storage design.
How to Use This Tool:
Choose the ingest evidence you trust most, then test the retention plan against the disk actually allocated to this Prometheus data directory.
- Set Start from to targets and active series for a bottom-up estimate, or choose measured samples/sec when sustained production telemetry is available.
- For the series path, enter Scrape targets, Active series per target, and the effective Scrape interval. Use per-server values rather than a fleet total unless one server scrapes the whole fleet.
- Enter Compressed bytes per sample and Local retention. Use observed block growth when possible; the default compression assumption is only a starting point.
- Set the WAL/head allowance and Minimum WAL reserve. The plan uses whichever reserve is larger, including at least three 128 MiB WAL segments.
- Optionally enter Allocated Prometheus disk. The persistent-block target may be set from 1% through 85% so the suggested size leaves room for WAL, head chunks, and compaction.
- Read Planned disk, Suggested retention.size, and Budget retention together. Correct the input warning before using a result; invalid fields withhold the capacity plan.
Interpreting Results:
Persistent TSDB blocks is the compressed history estimate. WAL/head allowance is added separately, so Planned disk is the better number for comparing the chosen days with available capacity. A zero disk budget means no capacity pass or fail is attempted.
When a budget is supplied, Suggested retention.size is a persistent-block cap that fits inside the selected disk target after the modeled WAL/head reserve. It is not the full data-directory allowance. Prometheus may briefly exceed the steady block cap during compaction, and actual WAL or head peaks can exceed a percentage estimate.
A review status appears when bytes per sample is outside 1 to 2, retention exceeds 90 days, or estimated active series reaches at least 1,000,000. These are planning review flags, not Prometheus hard limits.
Technical Details:
Both sizing paths resolve to a canonical samples-per-second rate. Storage then grows linearly with ingest rate, bytes per sample, and retained time. GiB, TiB, and PiB disk entries use powers of 1024.
Formula Core
In the target-and-series path, active series and scrape interval produce the ingest rate. The measured-rate path uses the supplied rate directly.
Persistent block bytes are the ingest rate multiplied by compressed bytes per sample and retention seconds.
The WAL/head reserve is the larger of the percentage allowance and the selected count of 128 MiB segments. Planned disk adds that reserve to persistent blocks.
| Symbol | Meaning | Unit |
|---|---|---|
| N | Scrape targets | count |
| C | Active series per target | count |
| S | Estimated active series | count |
| i | Scrape interval | seconds |
| r | Ingest rate | samples/second |
| b | Compressed persistent bytes per sample | bytes/sample |
| d | Local retention | days |
| a | WAL/head allowance | percent |
| n | Minimum WAL segments | count |
| B, W, D | Persistent blocks, reserve, and planned disk | bytes |
Persistent-Cap Solver and Status Rules
The disk target equals allocated disk multiplied by the selected target percentage. The suggested persistent cap is the greatest nonnegative value x for which x plus the larger of its percentage reserve and minimum WAL reserve does not exceed that target. The model solves this inequality with 80 bisection steps. If the disk target is no larger than the minimum WAL reserve, the suggested cap is zero.
Status rules run in order. Planned disk strictly above the full allocation is Over disk. If it fits the disk but strictly exceeds the percentage target, it is Over target. Otherwise the review conditions described above apply; all remaining cases are healthy. Equality stays within the relevant boundary.
The full-precision cap is converted to a Prometheus size value by choosing the largest practical MB, GB, TB, or PB unit and rounding down to a whole unit. That avoids formatting a cap above the modeled byte allowance.
Accuracy Notes:
This is a steady planning model for one local Prometheus TSDB. Validate it against real block growth and peaks from the same shard before changing production retention.
- Remote-write storage, snapshots, filesystem overhead, and storage used by other services are outside the estimate.
- Label churn, backfill, tombstones, indexes, compaction overlap, and changing scrape populations can move actual usage.
- The WAL/head percentage is repository-authored planning reserve; measured peaks should replace the default.
- Time and size retention can both apply, and Prometheus removes data when whichever policy triggers first.
Worked Examples:
Thirty days from active series
A server with 250 targets, 1,400 active series per target, and a 30-second scrape interval resolves to 350,000 active series and about 11,666.7 samples per second. At 1.8 bytes per sample for 30 days, persistent blocks need 54,432,000,000 bytes. A 15% allowance is larger than three 128 MiB WAL segments, so the modeled reserve is 8,164,800,000 bytes and planned disk is 62,596,800,000 bytes, about 58.3 GiB.
References:
- Storage, Prometheus documentation.
- How to set Prometheus retention, Simplified Guide.
- How to analyze Prometheus TSDB blocks, Simplified Guide.