Skip to main content
Loading

Configuring Namespace Data Retention

To ensure sufficient memory for continuous operation, you can configure Aerospike namespaces to expire or evict records.

Namespace Supervisor​

The Namespace Supervisor (NSUP) is the subsystem that removes expired records from the primary index. Any past generation version of a record will subsequently get cleaned up by the continuous defragmentation process. Records with a void-time of 0 do not expire or get evicted.

Eviction, expiration, void-time and TTL​

Aerospike records include void-time metadata - the timestamp in the future when they automatically expire. As far as applications are concerned, an expired record does not exist, but its metadata still occupies a 64 byte slot in the primary index.

Independent of expiration, if namespace storage exceeds a configurable high-water mark, NSUP deletes the records with non-zero void-time that are nearest to their expiration. This early expiration process is called eviction. Eviction continues until sufficient space has been recovered.

caution

If NSUP is not running, expired records are not removed unless they're manually deleted or replaced.

Applications optionally send a Time-to-Live (TTL) with writes, which declares the number of seconds from now until the record will expire. By default namespaces reject writes with a TTL, and NSUP does not run, but this behavior is configurable (see below). If client writes are allowed to send a TTL, the record's void-time is set according to client TTL values. In this case, you should also configure NSUP to check for expired records.

Configuration Parameters​

The following parameters are configurable per namespace. For the exact definition and use of these parameters, see the configuration reference, or click the name of a parameter. Other related parameters are shown in Examples of configuration stanzas.

Configuration parameterDescriptionDefault valueNotes
nsup-periodThe time interval in seconds between successive starts of NSUP scans of the primary index for expired records.

If NSUP takes longer to traverse the primary index than the nsup-period, it will effectively be running continuously.		0

By default, NSUP does not run (nsup-period of 0).

Once NSUP is running, it does not stop until it has traversed the entire primary index of the namespace.

When nsup-period is 0, to allow writes that have a positive integer TTL, you must set allow-ttl-without-nsup to true (see below).

Regardless of the setting of nsup-period, writes with a non-positive TTL (<= 0) are always allowed.
allow-ttl-without-nsupA parameter for testing only. Measures the impact of NSUP when running in a use case where TTL is non-zero. Allows records to be written to the namespace with positive integer TTLs, even if NSUP is disabled.falseWarning: Records that have a TTL when NSUP is not running.
default-ttlThe default TTL value to use for the namespace, whenever a client writes a record with a TTL of 0.0If the value of default-ttl is non-zero and nsup-period is 0 (its default), the Aerospike server will not start.

A default-ttl of zero sets a void-time of 0. Aerospike never expires or evicts records that have a void-time of 0.

default-ttl cannot be set higher than 10 years (3650D).
high-water-disk-pctPercentage threshold at which the eviction process starts, defined as the ratio of namespace disk consumption to its device storage capacity.0The default value of 0 disables the threshold.
high-water-memory-pctPercentage threshold at which the eviction process starts, defined as the ratio of namespace memory consumption to its memory-size.0The default value of 0 disables the threshold.
mounts-high-water-pctPercentage threshold at which the eviction process starts, defined as the ratio of index mount utilization (index_flash_used_pct or index_pmem_used_pct) to the namespace mounts-size-limit.0Only applies when the namespace primary index is configured to be stored in flash or persistent memory.
stop-writes-pctPercentage threshold at which client writes are refused, defined as the ratio of namespace memory consumption to its memory-size.90Deletions, replica writes, and migration writes are still allowed when the namespace is in stop-writes mode.
stop-writes-sys-memory-pctPercentage threshold at which client writes are refused, defined as the ratio of total memory usage (across all applications) to the system memory.90Deletions, replica writes, and migration writes are still allowed when the namespace is in stop-writes mode.
min-avail-pctStops client writes when any namespace storage device (SSD or PMem) has its reserve of write blocks drop under a minimum, defined as the ratio of free write blocks to the device storage capacity.5Deletions, replica writes, and migration writes are still allowed when the namespace is in stop-writes mode.
max-used-pctStops client writes when the ratio of used storage space to total storage space (in bytes) exceeds the given max percentage.70Deletions, replica writes, and migration writes are still allowed when the namespace is in stop-writes mode.

Client TTL values​

When a namespace is configured to allow writes with a TTL, a client may send a positive TTL value, which determines how many seconds the record has until it expires. The void-time is set to the timestamp of now plus the TTL.

Additionally, there are three special TTL values that can always be used, regardless of namespace configuration:

  • A TTL of 0 instructs the server to use the default-ttl of the namespace when setting the void-time.
  • A TTL of -1 sets the record's void-time to 0, which means that the record will not expire.
  • A TTL of -2 instructs the server not to modify the void-time if the write is an update operation. If the write creates a new record, the default-ttl is used to determine the void-time.

A durable delete from the client will create a tombstone, which always has a void-time of 0, regardless of the record's previous void-time.

caution

Writing a record with a TTL value less than the current remaining life will reduce the record's void-time to less than its current void-time. This may have undesirable side effects upon a cold restart. For further details, see Issues with cold-start resurrecting deleted records.

Warning: records that have a TTL when NSUP is not running​

The following side-effects occur when NSUP is not running:

  • Trying to write a record with a TTL gets rejected with error code 22 (AS_ERR_FORBIDDEN).
  • Expired records do not get removed from the indexes and storage.
    • An attempt to read an expired record returns error code 2 (AS_ERR_NOT_FOUND).
    • An attempt to update an expired record creates a new record with its metadata in the same primary index slot. The previous version of the record is ignored, and the generation count is reset to 1.
    • Deleting an expired record removes it from the index. The defragmentation process will reclaim its storage.

Ensuring that NSUP is keeping up​

If NSUP is not able to keep up with a node's expiration/eviction of records, it might take the node a long time to restart, as the node will first remove expired records before rejoining the cluster. Also, if a large percentage of records are removed at startup the server has to deal with a temporary large increase in its defragmentation load. As of server 6.3, if the NSUP cycle takes longer than 2 hours and deletes more than 1% of the namespace, a warning line is written to the server log. It is recommended that you tune NSUP period and nsup-threads to keep up with expirations if you see this warning.

Examples of configuration stanzas​

The following example shows the applicable namespace data retention parameters and a short comment describing how they are used.

namespace namespaceName {
    default-ttl <VALUE>             # How long (in seconds) to keep data after
                                    # it is written

    high-water-disk-pct <PERCENT>   # How full may the disk become before the
                                    # server begins eviction

    high-water-memory-pct <PERCENT> # How full may the memory become before the
                                    # server begins eviction

    stop-writes-pct <PERCENT>       # How full may the memory become before
                                    # we disallow new writes

    index-type flash/pmem {             # If applicable
        mounts-high-water-pct <PERCENT> # How full flash index storage may become
                                        # before server begins eviction
        ...
    }

    ...
}

Tuning parameters​

The following example shows additional namespace data retention parameters to tune data expiration and eviction, with comments describing usage.

namespace <namespace-name> {
    nsup-period <SECONDS>           # As of Aerospike 4.5.1 (at service level prior)
                                    # Maximum time between starting successive
                                    # rounds of expiration or eviction - a value
                                    # of zero disables expiration and eviction

    nsup-threads <NUMBER>           # As of Aerospike 4.5.1
                                    # How many threads per round of expiration
                                    # or eviction

    evict-tenths-pct <NUMBER>       # Fraction of evictable records to delete
                                    # per round of eviction. For example, 5 means
                                    # delete 0.5 percent of evictable records)

    ...
}

Disable Eviction on Sets​

A set can be protected from evictions with the config parameter disable-eviction true.

namespace <namespace-name> {
    ...
    set <set-name> {
        disable-eviction true     # Protect this set from evictions

    }
}

See how to manage the evictions on a set.

note

prior to Aerospike 5.6 this configuration parameter was called set-disable-eviction.

Set Stop Writes size​

You can define a stop-writes-size to limit the amount of storage it can occupy.

namespace <namespace-name> {
    ...
    set <set-name> {
        stop-writes-size 500M     # Limit this set's storage to 500MB
    }
}

See how to manage the set size cap.

Set Stop Writes count​

A set can have stop-writes-count to limit the number of records that can be written to it.

namespace <namespace-name> {
    ...
    set <set-name> {
        stop-writes-count 5000     # Limit the number of records that can
                                   # be written to this set to 5000.

    }
}

See how to manage the set object count cap.

note

prior to Aerospike Database 5.6 this configuration parameter was called set-stop-writes-count.

How to List Non-expirable Records​

Use the asadm command to determine the number of non-expirable records:

show stat like non_expirable_objects

To find all those records, create a backup and grep for the pattern ^+ t 0 in the backup files. Refer to asbackup command-line options and Backup File Format for more information.

Alternatively, write a user-defined function (UDF) to scan records based on the record.ttl field. Note than this could turn into an intensive operation that may affect a production system’s performance. How to Modify TTL using UDF provides some examples.

Where to Next?​

Last updated on