Migrate namespace capacity metrics

This page explains how to replace Database 6.x namespace capacity and index-memory statistics in dashboards and alerts with the names that Database 7.0.0 and later report.

Applies to

• Aerospike Database 6.x through Database 8.x
• Namespace data and index statistic renames in Database 7.0.0
• Combined RAM index percent of budget in Database 7.1.0
• Host versus control group memory statistics in Database 8.1.2

Audience: operators and site reliability engineers who maintain queries and alerts written for Database 6.x. If you are building alerts from scratch on Database 7.0.0 and later, start at Key metrics to monitor.

For cross-datacenter replication (XDR) statistics, see Legacy XDR parameter and metric mapping.

Outcome

Each Database 6.x capacity or index-memory statistic in scope has a current name, or an explicit statement that there is no one-to-one replacement. You know which thresholds stay the same after the upgrade to Database 7.0.0 and which you must change, and you can verify that a migrated query returns the metrics you expect.

Where to start

• You know the Database 6.x statistic name. Use Map Database 6.x statistics.
• You are updating alerts after upgrading from Database 6.x. Use Replace queries and alerts, then Verify the migrated queries.
• You need the Prometheus or OpenTelemetry/Datadog name. Find the statistic in the mapping tables, then apply the naming pattern. Aerospike Prometheus Exporter names each server statistic using the pattern aerospike_CONTEXT_STAT. By default, OpenTelemetry and Datadog names follow aerospike.server.CONTEXT.STAT. For example, the data_used_pct statistic in the namespace context is aerospike_namespace_data_used_pct in Prometheus and aerospike.server.namespace.data_used_pct in Datadog. Setting metric_name_prefix or metric_context_separator in the exporter’s OpenTelemetry configuration changes the OpenTelemetry names, as described in Configure Aerospike Prometheus Exporter. The names on the Prometheus endpoint stay the same. Each Metrics reference entry lists the exact metric names.

Map Database 6.x statistics

Status values:

• Current: the server reports this name.
• Renamed: the same concept uses a different name. The device, Persistent Memory (PMem), and in-memory variants often merge into one data_* or index name.
• Removed: there is no one-to-one replacement.
• Meaning changed: a successor exists, but it measures something different, such as used capacity instead of free capacity.

Same threshold after upgrade means you can keep the same numeric threshold after you replace the name.

Data storage

Concept	Database 6.x statistic	Current statistic	Status	Same threshold after upgrade?
Total data capacity	device_total_bytes / pmem_total_bytes	data_total_bytes	Renamed	Yes. Database 7.0.0 also reports it for memory-only namespaces, based on data-size.
Used data bytes	device_used_bytes / pmem_used_bytes / memory_used_data_bytes	data_used_bytes	Renamed	Yes for device and PMem. No for in-memory data, because data_used_bytes measures write blocks in use, not the in-memory size of records.
Used data percent	None	data_used_pct	Current	n/a
Free data percent	device_free_pct / pmem_free_pct	data_used_pct	Meaning changed	No. Convert the threshold from free to used capacity.
Minimum available write-block percent	device_available_pct / pmem_available_pct	data_avail_pct	Renamed	Yes. Both report the lowest percentage across the files, devices, or memory stripes in the namespace.
Compression ratio	device_compression_ratio / pmem_compression_ratio	data_compression_ratio	Renamed	Mostly. When compression is none, Database 7.0.0 and later report 1.000, and Database 6.x reported nothing.

The Database 7.0.0 rename list is in Aerospike Database 7.0.0 release notes.

Index memory

An index is stored in PMem or on flash when index-type (primary index) or sindex-type (secondary index) is pmem or flash. Otherwise, the index is in RAM or shared memory.

Concept	Database 6.x statistic	Current statistic	Status	Same threshold after upgrade?
Primary index bytes	memory_used_index_bytes / index_pmem_used_bytes / index_flash_used_bytes	index_used_bytes	Renamed	Partially. When the primary index is stored in PMem or on flash, memory_used_index_bytes was always 0, so a threshold on it does not apply.
Percent of primary index mounts in use	index_pmem_used_pct / index_flash_used_pct	index_mounts_used_pct	Renamed	Yes. The server reports it only when the primary index is stored in PMem or on flash. The mount budget, formerly mounts-size-limit, is now mounts-budget.
Set index bytes	memory_used_set_index_bytes	set_index_used_bytes	Renamed	Yes
Secondary index bytes	memory_used_sindex_bytes / sindex_pmem_used_bytes / sindex_flash_used_bytes	sindex_used_bytes	Renamed	Partially. When the secondary index is stored in PMem or on flash, memory_used_sindex_bytes was always 0.
Percent of secondary index mounts in use	sindex_pmem_used_pct / sindex_flash_used_pct	sindex_mounts_used_pct	Renamed	Yes. The server reports it only when the secondary index is stored in PMem or on flash.
Percent of RAM index budget in use	n/a	indexes_memory_used_pct	Current	n/a. Database 7.1.0 added this statistic, and the server reports it only when indexes-memory-budget is nonzero.

Statistics with no one-to-one replacement

Both of these statistics were based on the memory-size budget, which Database 7.0.0 removed, so no single statistic replaces either one.

Database 6.x statistic	What it measured	Current replacement	Status	Same threshold after upgrade?
memory_used_bytes	Data in memory plus RAM indexes, compared against memory-size	None. Add the index statistics instead, as described in Replace memory_used_bytes.	Removed	No
memory_free_pct	Percent of memory-size that was free. Thresholds on it often corresponded to high-water-memory-pct or stop-writes-pct.	Depends on what the alert monitors, as described in Replace memory_free_pct.	Removed	No

Replace memory_used_bytes

To get the RAM that the namespace uses for indexes, add the following statistics:

• index_used_bytes, when the primary index is in RAM or shared memory.
• set_index_used_bytes.
• sindex_used_bytes, when the secondary index is in RAM or shared memory.

If the namespace stores its data in memory, data_used_bytes reports that data as a separate total. The sum of these statistics does not match how Database 6.x counted memory against memory-size. For sizing memory-only data, see Configure namespace storage.

Replace memory_free_pct

Choose the replacement based on what the alert monitors:

• For data storage, use data_used_pct with evict-used-pct and stop-writes-used-pct.
• For RAM indexes, use indexes_memory_used_pct with evict-indexes-memory-pct. This works in Database 7.1.0 and later, and only when indexes-memory-budget is nonzero.
• For host or control group RAM, use system_free_mem_pct. It reports host memory. In Database 8.1.2 and later, it reports control group memory when you set cgroup-mem-tracking to true (default false). Also in Database 8.1.2 and later, host_free_mem_pct always reports host memory.

To choose between the host and control group statistics, see Key metrics to monitor and the cgroup-mem-tracking reference entry.

Set data bytes

Database 6.x statistic	Current statistic	Status	Same threshold after upgrade?
memory_data_bytes	set data_used_bytes	Renamed	No for in-memory sets, for the same reason as the namespace statistic memory_used_data_bytes.
device_data_bytes	set data_used_bytes	Renamed	Yes for device set data.

Set statistics belong to the sets context, so the current Prometheus name is aerospike_sets_data_used_bytes, and the Metrics reference entry is the set data_used_bytes, not the namespace data_used_bytes.

Why some replacements are not one-to-one

In Database 7.0.0 and later, the server accounts for namespace data storage and RAM indexes separately.

data_used_pct and data_avail_pct

The server reports data_used_pct and data_avail_pct as whole numbers, so 30 means 30%.

Note

Prior to Database 7.0.0, device_free_pct and pmem_free_pct reported free capacity. A converted threshold is approximately 100 minus FREE_PCT, but integer rounding can differ by one percentage point.

indexes_memory_used_pct when the budget is nonzero

When indexes-memory-budget is 0, the server does not report indexes_memory_used_pct, so dashboards show a gap, not a zero. A missing metric does not mean that metric collection failed.

Stop-writes for the index budget begins only when the RAM index size is above the budget, so an indexes_memory_used_pct value of 100 does not by itself show that stop-writes is active.

Replace queries and alerts

For the Database 7.0.0 cluster upgrade, including mixed Database 6.x and Database 7.0.0 dashboards, see Special upgrade to Database 7.0.0.

Caution

Test every changed query and alert threshold on one namespace before you use it in production.

1. List the Prometheus Query Language (PromQL), Grafana, and Datadog queries that use a Database 6.x statistic name from the mapping tables.
2. Replace each expression with the current statistic name.
3. Update each threshold that the Same threshold after upgrade? column in the mapping tables does not mark Yes.

Verify the migrated queries

Run the migrated queries against one namespace on an upgraded node, and confirm the following:

• Current metrics are present for the namespace, for example aerospike_namespace_data_used_pct{ns="test"} and aerospike_namespace_data_avail_pct{ns="test"}.
• Removed metrics are absent, not zero. aerospike_namespace_memory_free_pct and aerospike_namespace_device_available_pct must not appear for Database 7.0.0 and later nodes.
• Labels select the intended namespace and, when you filter on them, the set and storage engine.

To check the Aerospike Prometheus Exporter endpoint directly, run the following command. The exporter listens on port 9145 by default, as described in Configure Aerospike Prometheus Exporter.

Terminal

curl -s localhost:9145/metrics | grep aerospike_namespace_data_used_pct | grep 'ns="test"'

If the exporter uses TLS, start the URL with https:// and add the --cacert option with your certificate authority (CA) file. If the exporter requires mutual TLS, also add the --cert and --key options with your client certificate and private key. If the exporter uses basic authentication, add the -u option with your exporter credentials. Without these changes, the command prints nothing.

Related topics

• Metrics reference
• Key metrics to monitor
• Aerospike Database 7.0.0 release notes
• Special upgrade to Database 7.0.0
• Configure Aerospike Prometheus Exporter
• Legacy XDR parameter and metric mapping