Clarify default storage retention limits in docs (#21780)
* Clarify default storage retention limits in documentation The documentation presented per-sample sizes and time-based retention limits without clearly explaining that metrics storage is limited to 3 GiB by default (1 GiB per tier). This led AI assistants and users to incorrectly calculate storage as growing unbounded (e.g. "3-5 GB/day"), when in reality total disk usage is about 4 GiB under normal conditions. Updated three documentation files to consistently explain the default disk footprint, retention behavior, and that limits are configurable. * Fix terminology: use "metrics per second" instead of "unique time-series" Metrics per second (ingestion rate) is the correct term for storage calculations, not cardinality (unique time-series count). * Clarify "metrics per second" as ingestion rate
Costa Tsaousis committed
Feb 18, 2026 at 02:07 UTC
8b953fe7b084d1174a040b5c4876263637b3954f
3 files changed
+30
-8
docs/impact-on-resources.md
+7
-7
@@ -39,11 +39,11 @@ When deployed on an empty VM, Netdata collects and visualizes critical system me
39
40
#### **Data Retention**
41
42
-- **Efficient Storage:**
43
- - Two weeks of high-resolution data (per-second).
44
- - Three months of mid-resolution data (per-minute).
45
- - Two years of low-resolution data (per-hour).
46
- - Total storage required: **3 GiB**.
42
+- **Metrics storage is limited to 3 GiB by default** (configurable), using 1 GiB per tier × 3 tiers. In total, with SQLite databases, alert transitions, and other metadata, expect about **4 GiB** of disk usage under normal conditions.
43
+- Default retention limits: per-second data for 1 GiB or 14 days, per-minute data for 1 GiB or 3 months, per-hour data for 1 GiB or 2 years.
44
+- The number of metrics collected determines how far back in time retention extends within these limits.
45
+- In practice, with an ingestion rate of about 4,000 metrics per second, Netdata provides about 14 days of per-second data, 3 months of per-minute data, and more than 1 year of per-hour data.
46
+- These limits are [fully configurable](/src/database/CONFIGURATION.md#tiers).
47
48
### Resource Consumption
49
@@ -60,7 +60,7 @@ Netdata operates with an exceptionally low footprint, even under demanding condi
60
- **Disk I/O:**
61
- Reads: ~2 KiB/s without machine learning, ~9 KiB/s with machine learning.
62
- Writes: ~5 KiB/s.
63
-- **Storage:** 3 GiB total.
63
+- **Storage:** ~4 GiB total (3 GiB metrics + metadata).
64
65
## Typical Netdata Resources Usage on Production Systems
66
@@ -69,7 +69,7 @@ In production systems with more data sources and features enabled, users can exp
69
- **CPU Usage:** 5%-20% of a single core.
70
- **Memory Usage:** 250–350 MB RAM.
71
- **Disk I/O:** ~10 KiB/s reads and writes.
72
-- **Storage:** 3 GiB total.
72
+- **Storage:** ~4 GiB total (3 GiB metrics + metadata).
73
74
## Impact of Running Netdata on Cloud VMs
75
docs/netdata-agent/sizing-netdata-agents/disk-requirements-and-retention.md
+16
@@ -33,6 +33,22 @@ gantt
33
| `tier1` | 60 iterations of `tier0`, so when metrics are collected per-second, this tier is per-minute. | 16 bytes | 6 bytes |
34
| `tier2` | 60 iterations of `tier1`, so when metrics are collected per second, this tier is per-hour. | 16 bytes | 18 bytes |
35
36
+### Default Disk Footprint
37
+
38
+Netdata Agent metrics storage is limited to 3 GiB by default (configurable), using 1 GiB per tier × 3 tiers. In total, with SQLite databases, alert transitions, and other metadata, expect about 4 GiB of disk usage under normal conditions. The default retention limits are:
39
+
40
+| Tier | Resolution | Size Limit | Time Limit |
41
+|:-------:|:----------:|:----------:|:----------:|
42
+| `tier0` | per-second | 1 GiB | 14 days |
43
+| `tier1` | per-minute | 1 GiB | 3 months |
44
+| `tier2` | per-hour | 1 GiB | 2 years |
45
+
46
+Data is deleted when it reaches **either** the size limit or the time limit, whichever comes first. The number of metrics collected determines how far back in time retention extends within the size limit.
47
+
48
+In practice, with default settings and an ingestion rate of about 4,000 metrics per second, Netdata provides about 14 days of high resolution (per-second) data, 3 months of medium resolution (per-minute) data, and more than 1 year of low resolution (per-hour) data.
49
+
50
+These limits are fully configurable. See [Changing how long Netdata stores metrics](/src/database/CONFIGURATION.md#tiers).
51
+
52
**Configuring dbengine mode and retention**:
53
54
- Enable dbengine mode: The dbengine mode is already the default, so no configuration change is necessary. For reference, the dbengine mode can be configured by setting `[db].mode` to `dbengine` in `netdata.conf`.
src/database/README.md
+7
-1
@@ -26,7 +26,13 @@ Netdata offers a granular approach to data retention, allowing you to manage sto
26
>
27
> If a user sets a disk space size less than 256 MB for a tier, Netdata will automatically adjust it to 256 MB.
28
29
-With these defaults, Netdata requires approximately 4 GiB of storage space (including metadata).
29
+Netdata Agent metrics storage is limited to 3 GiB by default (configurable), using 1 GiB per tier × 3 tiers. Data is deleted when it reaches **either** the size limit or the time limit, whichever comes first. The number of metrics collected determines how far back in time retention extends within the size limit.
30
+
31
+In total, with SQLite databases, alert transitions, and other metadata, expect about 4 GiB of disk usage under normal conditions.
32
+
33
+In practice, with default settings and an ingestion rate of about 4,000 metrics per second, Netdata provides about 14 days of high resolution (per-second) data, 3 months of medium resolution (per-minute) data, and more than 1 year of low resolution (per-hour) data.
34
+
35
+These limits are fully configurable. See [Changing how long Netdata stores metrics](/src/database/CONFIGURATION.md#tiers).
36
37
### Monitoring Retention Utilization
38