Database Configuration Reference

You can configure the Agent's Database through the database settings. For a deeper understanding of the Database components, see the Database overview.

Modes

Use edit-config to open netdata.conf and set your preferred mode:

[db]
  # dbengine, ram, none
  mode = dbengine

Tiers

Retention Settings

note

In a Parent-Child setup, these settings control the Parent's total storage for metrics collected locally and metrics received from Children.

Child and Parent storage are independent:

• A Child can keep local history based on its own [db].mode.
• Streamed metrics can also be persisted on the Parent, in the Parent's own dbengine files.

Retention size is enforced per-tier, not per Child, so all streaming Children share the Parent's tier quota. For Parent sizing guidance, see Parent Retention Sizing.

You can fine-tune retention for each tier by setting a time limit or size limit. Setting a limit to 0 disables it. This enables the following retention strategies:

Setting	Retention Behavior
Size Limit = 0, Time Limit > 0	Time based: data is stored for a specific duration regardless of disk usage
Time Limit = 0, Size Limit > 0	Space based: data is stored with a disk space limit, regardless of time
Time Limit > 0, Size Limit > 0	Combined time and space limits: data is deleted once it reaches either the time limit or the disk space limit, whichever comes first

note

Retention size limits are soft targets, not hard caps enforced at write time. Actual disk usage can temporarily exceed the configured limit. For the detailed enforcement behavior, see Retention Size Enforcement.

You can change these limits using edit-config to open netdata.conf:

[db]
    mode = dbengine
    storage tiers = 3

    # Tier 0, per second data. Set to 0 for no limit.
    dbengine tier 0 retention size = 1GiB
    dbengine tier 0 retention time = 14d

    # Tier 1, per minute data. Set to 0 for no limit.
    dbengine tier 1 retention size = 1GiB
    dbengine tier 1 retention time = 3mo

    # Tier 2, per hour data. Set to 0 for no limit.
    dbengine tier 2 retention size = 1GiB
    dbengine tier 2 retention time = 2y

Legacy Configuration

v1.99.0 and prior

Netdata prior to v2 supports the following configuration options in netdata.conf. They have the same defaults as the latest v2, but the unit of each value is given in the option name, not at the value.

storage tiers = 3
# Tier 0, per second data. Set to 0 for no limit.
dbengine tier 0 disk space MB = 1024
dbengine tier 0 retention days = 14
# Tier 1, per minute data. Set to 0 for no limit.
dbengine tier 1 disk space MB = 1024
dbengine tier 1 retention days = 90
# Tier 2, per hour data. Set to 0 for no limit.
dbengine tier 2 disk space MB = 1024
dbengine tier 2 retention days = 730

v1.45.6 and prior

Netdata versions prior to v1.46.0 relied on disk space-based retention.

Default Retention Limits:

Tier	Resolution	Size Limit
0	high (per second)	256 MB
1	middle (per minute)	128 MB
2	low (per hour)	64 GiB

You can change these limits in netdata.conf:

[db]
    mode = dbengine
    storage tiers = 3
    # Tier 0, per second data
    dbengine multihost disk space MB = 256
    # Tier 1, per minute data
    dbengine tier 1 multihost disk space MB = 1024
    # Tier 2, per hour data
    dbengine tier 2 multihost disk space MB = 1024

Cache Sizes

There are two cache sizes that you can configure in netdata.conf to better optimize the Database:

1. [db].dbengine page cache size: controls the size of the cache that keeps metric data on memory.
2. [db].dbengine extent cache size: controls the size of the cache that keeps in memory compressed data blocks.

info

Both of them are dynamically adjusted to use some of the total memory computed above. The configuration in netdata.conf allows providing additional memory to them, increasing their caching efficiency.

Monitoring Cache Memory Usage

You can check how much memory the dbengine caches are currently consuming directly from the dashboard.

The total memory used by the database always appears as the dbengine dimension in the Netdata Memory chart (under the Netdata section → Memory Usage family). This gives a quick view of the database's overall memory footprint without any extra configuration.

For a detailed breakdown into individual caches, the dedicated dbengine cache charts require extended pulse statistics, which are disabled by default. To enable them, use edit-config to open netdata.conf and set:

[pulse]
    extended = yes

Restart the Agent for the change to take effect. Once enabled, the following charts appear under the Netdata section:

• In the dbengine memory family, the Netdata DB Memory chart breaks total database memory down by component: main cache, open cache, extent cache, metrics registry, buffers, and allocator bookkeeping (aral structures, aral padding, pgd padding).
• In the dbengine main cache, dbengine open cache, and dbengine extent cache families:
  • Netdata main Cache Memory, Netdata open Cache Memory, and Netdata extent Cache Memory show how each cache's memory is distributed across its states — hot, dirty, clean, free, index, evicting, and flushing.
  • Netdata main Target Cache Memory, Netdata open Target Cache Memory, and Netdata extent Target Cache Memory show each cache's current memory size alongside its target (wanted) size.

To check whether your configured cache sizes provide enough headroom, compare the current value against the wanted value in the Target Cache Memory charts. When a cache consistently operates at its target, increasing dbengine page cache size or dbengine extent cache size may improve caching efficiency.