src/database/README.md
Netdata stores detailed metrics at one-second granularity using its Database engine. This document provides an overview of the various elements of the Database, if you want to configure it, check the configuration reference page
| Mode | Description |
|---|---|
dbengine | The high performance multi-tiered time-series database of Netdata, providing superior storage efficiency (~0.5 bytes per sample on disk for high resolution per-second data), and fast long term data queries (typically 20+ times faster) by transparently utilizing all available database tiers. For details, see Database Engine. |
ram | Stores data entirely in memory without disk persistence. This is typically used in IoT devices or children that stream their metrics to Netdata parents, to avoid having any disk dependency on Netdata |
none | Operates without storage (metrics can only be streamed to a Netdata parent). |
Netdata offers a granular approach to data retention, allowing you to manage storage based on both time and disk space. This provides greater control and helps you optimize storage usage for your specific needs.
Default Retention Limits:
| Tier | Resolution | Time Limit | Size Limit (min 256 MB) |
|---|---|---|---|
| 0 | high (per second) | 14d | 1 GiB |
| 1 | middle (per minute) | 3mo | 1 GiB |
| 2 | low (per hour) | 2y | 1 GiB |
Note
If a user sets a disk space size less than 256 MB for a tier, Netdata will automatically adjust it to 256 MB.
The number of metrics collected determines how far back in time retention extends within the size limit. For expected default disk usage, per-tier size/time limits, and a practical retention example, see Disk Requirements & Retention. For how retention limits are actually enforced, see Retention Size Enforcement below.
Netdata provides a visual representation of storage utilization for both the time and space limits across all Tiers. In the dashboard, these are the dbengine space and time retention charts, found under the Netdata section → dbengine retention family — there is one chart per database tier. Each chart shows exactly how your storage space (disk space limits) and time (time limits) are used for metric retention.
Each tier has its own independent space and time lines on the chart:
disk_used / disk_max × 100. When a size limit is configured for the tier, disk_max is that limit. When no size limit is configured (set to 0), disk_max is the total available disk space at the tier's data directory (free space plus already-used space). For example, a space value of 89% means 89% of the tier's allocated or available disk space is occupied by datafiles.current_retention_duration / configured_time_limit × 100. When no time limit is configured (set to 0), this dimension shows 0% and no time-based retention is enforced. For example, a time value of 61% means 61% of the configured time retention period has elapsed since the oldest sample. This value is capped at 100%.Different tiers naturally show different percentages because they have different write volumes, compression ratios, and configured limits. When either the space or time dimension reaches 100%, the oldest datafiles are rotated out as described in the Retention Size Enforcement section below.
Retention size limits are soft caps, not hard caps. Netdata writes data unconditionally and checks limits afterwards — it does not block or reject writes when a cap is approaching.
How enforcement works:
Periodic and asynchronous checks: Netdata checks whether a tier has exceeded its configured size limit periodically and also after normal database activity (such as extent writes and rotation completions). Data continues to be written to disk without restriction between these checks.
Whole-file deletion: When the configured size limit is exceeded, Netdata schedules deletion of the oldest complete datafiles until the retention check no longer reports the tier over its limit. Multiple files may be deleted across one or more rotation passes. Datafile size is determined automatically (see Database Engine datafiles). Because entire files are removed and cannot be partially deleted, actual disk usage can overshoot the configured limit before enforcement catches up.
Why tier 0 overshoots more: Tier 0 collects per-second data, producing the highest write volume. More data accumulates between enforcement checks, and data files fill faster. Tier 1 and tier 2 have lower write volumes and their disk usage grows more predictably.
Practical guidance:
There are two cache sizes that can be used to optimize the Database: