Prometheus Retention Storage Calculator

{{ result.statusText }} {{ result.sampleRateBadge }} {{ result.retentionBadge }} {{ result.bytesBadge }} {{ result.reserveBadge }}

Sizing input:

Choose whether the ingest rate comes from active series math or a measured samples-per-second counter.

Scrape targets:

Use the target count for one Prometheus server or shard, not the whole fleet unless one server scrapes all of it.

Series per target:

Use active series, not metric names; high-cardinality labels can make this much larger than expected.

Samples per second:

Use a sustained average append rate for the Prometheus shard being sized.

samples/sec

Scrape interval:

Use the effective interval for most targets in this shard.

seconds

Scrape interval tuning {{ scrapeIntervalRangeLabel }}

Bytes per sample:

Use 1-2 for a first pass, or your measured chunk bytes per compacted sample.

bytes/sample

Compression assumption {{ bytesPerSampleRangeLabel }}

Retention period:

Enter the planned local retention window before remote storage or archive tiers.

days

Local retention window {{ retentionRangeLabel }}

WAL/head allowance:

Adds a planning reserve on top of persistent blocks; the minimum WAL segment reserve still applies.

Reserve tuning {{ reserveRangeLabel }}

Prometheus storage inputs need review

{{ message }}

Export label:

Optional label for handoff exports; it does not change storage math.

Disk budget:

Set 0 to skip fixed-disk guardrails.

Retention size target:

Used only when disk budget is set; 80-90% leaves safer room for WAL/head peaks and filesystem overhead.

Disk target share {{ retentionSizeTargetRangeLabel }}

Minimum WAL segments:

Raise this only when observed WAL/head peaks are larger than the percentage allowance.

Metric	Value	Detail	Copy
{{ row.metric }}	{{ row.value }}	{{ row.detail }}

Guardrail	Setting	Reading	Operator action	Copy
{{ row.guardrail }}	{{ row.setting }}	{{ row.reading }}	{{ row.action }}

Embed:

Customize

Include current inputs

Size

Advanced

Width

Height

Aspect ratio

Max height

Collapsible embed

Allow fullscreen

Referrer policy

Sandbox tokens

Local Prometheus retention is the promise that recent high-resolution metrics will still be queryable when an incident, capacity review, or rollback investigation needs them. That promise is paid for with disk on one Prometheus server or shard. If the data directory fills, the problem is no longer just historical visibility; scraping, compaction, restarts, and recovery can all become fragile.

Storage does not scale with host count alone. Prometheus stores a separate time series for every metric name and label set, so one noisy target with unbounded labels can create more samples than a larger but cleaner fleet. Shorter scrape intervals raise the append rate because active series are sampled more often. Longer retention keeps the resulting blocks on local disk for more days.

The storage estimate has to include more than compacted historical blocks. Recent samples live in head data and the write-ahead log before they are compacted, and Prometheus keeps a minimum number of WAL segments. A disk plan that fits only the block formula can still fail during churn, compaction, or a restart-heavy period.

Active series: Distinct metric-and-label sets that are currently producing samples.
Samples/sec: The sustained rate at which samples are appended to one Prometheus server or shard.
Retention window: The planned number of days kept in local TSDB blocks before old data is removed.
WAL/head reserve: Extra disk space for recent un-compacted data, write-ahead log files, and short-term peaks.

Diagram showing targets and active series becoming samples per second, retained TSDB blocks, WAL and head reserve, and a disk headroom check.

Prometheus retention storage planning factors
Planning question	Why it matters	Common mistake
How many samples arrive each second?	Append rate drives block growth for every retained day.	Counting targets without checking active series.
How long should local history stay?	Retention multiplies the daily sample footprint.	Keeping months locally when a remote tier should hold old data.
How much WAL/head reserve is needed?	Recent un-compacted data can exceed a simple percentage on small or busy shards.	Treating persistent blocks as the whole data directory.
What disk share should retention use?	A size cap needs room for WAL, head chunks, filesystem behavior, and emergencies.	Setting `retention.size` equal to the raw disk size.

Two mistakes make retention plans look safer than they are. One is sizing a whole estate as though one server scrapes it all, when the real capacity question belongs to one Prometheus server, shard, or persistent volume. The other is treating retention.size as a complete data-directory cap. Size retention removes old persistent blocks, but WAL and head data still need space, and cleanup does not make an overfull filesystem safe after the fact.

Local Prometheus storage is useful for recent operational detail, not a full durability design by itself. A storage estimate can tell you whether a retention window is plausible for one node. Long-term history, replication, downsampling, backups, and disaster recovery still depend on the monitoring architecture around that node.

How to Use This Tool:

Start from the best ingest-rate evidence you have, then check the disk plan against the retention and reserve rules for one Prometheus shard.

Choose Sizing input. Pick Targets and active series for planning from scrape inventory, or Measured samples/sec when you already have a sustained append rate such as rate(prometheus_tsdb_head_samples_appended_total[5m]).
In series mode, enter Scrape targets and Series per target. Keep the scope to one Prometheus server or shard, then confirm the Active series estimate and Ingest rate rows before trusting the disk total.
In measured mode, enter Samples per second directly. The Scrape interval field remains useful for handoff context, but the measured append rate drives the storage calculation.
Set Scrape interval, Bytes per sample, and Retention period. A 1 to 2 bytes/sample value is a common first pass; replace it with measured compacted bytes per sample when you have production data.
Tune WAL/head allowance and Minimum WAL segments. The reserve uses the larger of the percentage allowance or the configured count of 128 MiB WAL segments, with three segments as the minimum.
Open Advanced when a real volume or persistent disk limit matters. Disk budget and Retention size target produce disk headroom readings and a suggested retention.size value.
If Prometheus storage inputs need review appears, fix the listed field first. Zero sample rates, zero bytes per sample, retention below one day, negative disk budget, and fewer than three WAL segments cannot produce a useful capacity plan.

Use TSDB Footprint for the main capacity rows, Retention Size Guardrails for operator checks, Retention Runway Curve for day-by-day growth, and Storage Layer Mix to see how much of the plan is persistent blocks versus WAL/head reserve.

Interpreting Results:

Planned local disk is the capacity number to compare with the volume that holds Prometheus data. It combines Persistent TSDB blocks with WAL/head allowance, so it is more useful than a block-only estimate when deciding whether a retention window can fit.

When Disk budget is set, read the status before copying the GiB number. Over disk means the modeled footprint is larger than the configured disk. Over target means the plan is below raw disk size but exceeds the selected retention-size target. Headroom watch means usage is at least 80% of the modeled target, leaving little room for cardinality growth, compaction peaks, or filesystem overhead.

Treat the suggested retention.size as a guardrail for persistent blocks, not a promise that every byte under the data directory is capped. Before changing production flags, compare the estimate with live active-series count, sustained append rate, observed WAL/head peaks, and available disk space on the Prometheus data volume.

Technical Details:

A Prometheus time series is identified by a metric name plus its labels. Changing any label value creates a different series, so high-cardinality labels such as user IDs, request IDs, raw paths, or other unbounded values can multiply storage even when target count stays flat. Storage planning starts with append rate, either measured directly or derived from active series and scrape interval.

Persistent TSDB blocks are modeled from samples per second, bytes per sample, and retention seconds. WAL/head reserve is modeled separately because recent data is not yet compacted into the same shape as older blocks. Prometheus stores WAL files in 128 MB segments and retains at least three of them, so a percentage reserve alone can understate the minimum footprint for small shards.

Formula Core:

The calculator uses binary storage units for GiB, TiB, and PiB output. Retention days become seconds by multiplying by 86,400.

\begin{array}{lcl} S_{active} & = & targets \times series per target \\ R_{samples} & = & \frac{S_{active}}{scrape interval seconds} \\ B_{persistent} & = & R_{samples} \times bytes per sample \times retention days \times 86400 \\ B_{reserve} & = & max (B_{persistent} \times \frac{reserve percent}{100}, WAL segments \times 128 MiB) \\ B_{planned} & = & B_{persistent} + B_{reserve} \end{array}

Prometheus retention storage variables and units
Quantity	Meaning	Unit or rule
Active series	Estimated metric-and-label sets contributing samples in series mode.	Targets multiplied by series per target.
Ingest rate	Sustained append rate used for storage math.	Samples/sec, derived or entered directly.
Persistent TSDB blocks	Compacted block estimate for the retention window.	Bytes, displayed in binary units.
WAL/head allowance	Reserve for recent un-compacted data and peaks.	Greater of percent reserve or WAL segment minimum.
Suggested retention.size	Modeled persistent-block cap from disk budget and target share.	Rounded down to a whole MB, GB, TB, or PB-style flag value.

Default substitution: 250 targets and 1,400 series per target produce 350,000 active series. At a 30 second scrape interval, the ingest rate is about 11,666.67 samples/sec. A 30 day retention window at 1.8 bytes/sample produces about 50.69 GiB of persistent blocks. A 15% WAL/head allowance is larger than the three-segment minimum, so the reserve is about 7.60 GiB and planned local disk is about 58.30 GiB.

Prometheus retention storage validation and guardrail rules
Check	Rule	Capacity meaning
Series mode inputs	Targets and series per target must be greater than zero.	They multiply into active series before scrape interval is applied.
Measured mode input	Samples/sec must be greater than zero.	It replaces active-series math as the ingest rate.
WAL/head allowance	Allowed range is 0% to 300%.	Low values may miss write-ahead log, head chunk, and churn peaks.
Minimum WAL segments	At least 3 segments of 128 MiB each.	This creates a reserve floor even when persistent blocks are small.
Retention size target	Allowed range is 1% to 100% of disk budget.	It determines the modeled target used for the suggested size cap.

The size-cap calculation works backward from the selected percentage of disk budget. It finds the largest persistent block allowance whose persistent bytes plus modeled WAL/head reserve fit under that target. Prometheus itself may remove blocks only after they are fully expired, and time and size retention can both apply, so production rollouts should keep extra filesystem headroom beyond the modeled value.

Accuracy Notes:

The estimate is a planning model, not a replacement for observing the running server. The inputs should be checked against Prometheus metrics and the actual data directory before changing retention flags.

Bytes per sample is workload-dependent. The common 1 to 2 bytes/sample range is a starting assumption, not a guarantee.
WAL/head allowance may need to be higher during churn, restarts, compaction pressure, or sudden cardinality growth.
Disk budget use does not include every filesystem concern. Leave space for operating-system behavior, monitoring agent overhead, and emergency access.
Long local retention should be compared with remote storage or downsampled long-term tiers before keeping months of high-resolution data on one node.

Worked Examples:

Series-based shard plan

A shard with 250 scrape targets, 1,400 active series per target, a 30 second scrape interval, 1.8 bytes/sample, and 30 retention days shows an Ingest rate near 11,666.67 samples/sec. Planned local disk is about 58.30 GiB including WAL/head allowance.

Measured append rate near a volume limit

A busy shard measured at 50,000 samples/sec for 14 retention days at 1.5 bytes/sample has about 84.49 GiB of Persistent TSDB blocks. With a 20% allowance, Planned local disk is about 101.39 GiB, so a 100 GiB Disk budget should show an over-disk condition.

Size target warning

The default series example on a 64 GiB disk budget with an 85% Retention size target stays below raw disk size but rises above the target share. Read that as Over target: the disk is not mathematically exhausted, but the proposed retention leaves less buffer than the target allows.

Invalid capacity input

If Bytes per sample is set to 0 or Minimum WAL segments is set below 3, the validation message appears before capacity results are meaningful. Fix the field, then check Retention Size Guardrails again before copying a size flag.

FAQ:

Should I use active series or measured samples/sec?

Use Measured samples/sec when you have a reliable sustained append rate for the same shard. Use Targets and active series when you are planning a new scrape layout or do not yet have production append-rate data.

Why is 1 to 2 bytes per sample only a starting point?

Prometheus documentation uses 1 to 2 bytes/sample for rough capacity planning, but real compression depends on the metrics, labels, churn, and compaction behavior. The Bytes/sample assumption guardrail flags values outside that range for review.

Does retention.size protect the whole Prometheus data directory?

No. Size retention is a persistent-block cap, while WAL and head data still need disk. Use the suggested retention.size together with WAL/head allowance and real disk-availability monitoring.

Why does the result add a WAL/head allowance?

Recent samples are not immediately compacted into historical blocks. The allowance accounts for write-ahead log files, head chunks, churn, and peaks, with a minimum of three 128 MiB WAL segments.

What should I do when local retention is more than 90 days?

Read the Long local retention horizon guardrail and compare the plan with remote storage or downsampled long-term tiers. Long local retention can be valid, but it concentrates capacity and durability risk on one Prometheus server.

Glossary:

Active series: Distinct metric and label sets currently producing samples in a Prometheus shard.
Samples/sec: The sustained rate at which samples are appended to local storage.
Scrape interval: How often Prometheus collects samples from targets, measured in seconds.
TSDB block: A compacted local storage block containing historical samples and index data.
WAL: The write-ahead log that protects recent samples before compaction.
Head chunks: Recent in-progress sample data that has not yet become a fully compacted block.
retention.size: A Prometheus storage cap for retained blocks, separate from raw disk capacity.

References:

Storage, Prometheus Authors.
Data model, Prometheus Authors.
Metric and label naming, Prometheus Authors.