---
title: "Migrate namespace capacity metrics"
description: "Replace Database 6.x namespace capacity and index-memory statistics in dashboards and alerts with their Database 7.0.0 and later names."
---

# Migrate namespace capacity metrics

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

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](https://aerospike.com/docs/database/observe/key-metrics).

For cross-datacenter replication (XDR) statistics, see [Legacy XDR parameter and metric mapping](https://aerospike.com/docs/database/manage/xdr/parameters).

## 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](#map-database-6x-statistics).
-   You are updating alerts after upgrading from Database 6.x. Use [Replace queries and alerts](#replace-queries-and-alerts), then [Verify the migrated queries](#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](https://aerospike.com/docs/database/observe/monitor/configure/exporter). The names on the Prometheus endpoint stay the same. Each [Metrics reference entry](https://aerospike.com/docs/database/reference/metrics) 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`](https://aerospike.com/docs/database/reference/metrics#namespace__device_total_bytes) / [`pmem_total_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__pmem_total_bytes) | [`data_total_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__device_used_bytes) / [`pmem_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__pmem_used_bytes) / [`memory_used_data_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__memory_used_data_bytes) | [`data_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__data_used_pct) | Current | n/a |
| Free data percent | [`device_free_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__device_free_pct) / [`pmem_free_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__pmem_free_pct) | [`data_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__data_used_pct) | Meaning changed | No. Convert the threshold from free to used capacity. |
| Minimum available write-block percent | [`device_available_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__device_available_pct) / [`pmem_available_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__pmem_available_pct) | [`data_avail_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__device_compression_ratio) / [`pmem_compression_ratio`](https://aerospike.com/docs/database/reference/metrics#namespace__pmem_compression_ratio) | [`data_compression_ratio`](https://aerospike.com/docs/database/reference/metrics#namespace__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](https://aerospike.com/docs/database/release/7-0#metrics-changes).

### Index memory

An index is stored in PMem or on flash when [`index-type`](https://aerospike.com/docs/database/reference/config#namespace__index-type) (primary index) or [`sindex-type`](https://aerospike.com/docs/database/reference/config#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__memory_used_index_bytes) / [`index_pmem_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__index_pmem_used_bytes) / [`index_flash_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__index_flash_used_bytes) | [`index_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__index_pmem_used_pct) / [`index_flash_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__index_flash_used_pct) | [`index_mounts_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/config#namespace__mounts-budget). |
| Set index bytes | [`memory_used_set_index_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__memory_used_set_index_bytes) | [`set_index_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__set_index_used_bytes) | Renamed | Yes |
| Secondary index bytes | [`memory_used_sindex_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__memory_used_sindex_bytes) / [`sindex_pmem_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__sindex_pmem_used_bytes) / [`sindex_flash_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__sindex_flash_used_bytes) | [`sindex_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__sindex_pmem_used_pct) / [`sindex_flash_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__sindex_flash_used_pct) | [`sindex_mounts_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__indexes_memory_used_pct) | Current | n/a. Database 7.1.0 added this statistic, and the server reports it only when [`indexes-memory-budget`](https://aerospike.com/docs/database/reference/config#namespace__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`](https://aerospike.com/docs/database/reference/metrics#namespace__memory_used_bytes) | Data in memory plus RAM indexes, compared against [`memory-size`](https://aerospike.com/docs/database/reference/config#namespace__memory-size) | None. Add the index statistics instead, as described in [Replace `memory_used_bytes`](#replace-memory_used_bytes). | Removed | No |
| [`memory_free_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__memory_free_pct) | Percent of `memory-size` that was free. Thresholds on it often corresponded to [`high-water-memory-pct`](https://aerospike.com/docs/database/reference/config#namespace__high-water-memory-pct) or [`stop-writes-pct`](https://aerospike.com/docs/database/reference/config#namespace__stop-writes-pct). | Depends on what the alert monitors, as described in [Replace `memory_free_pct`](#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`](https://aerospike.com/docs/database/reference/metrics#namespace__index_used_bytes), when the primary index is in RAM or shared memory.
-   [`set_index_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__set_index_used_bytes).
-   [`sindex_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__sindex_used_bytes), when the secondary index is in RAM or shared memory.

If the namespace stores its data in memory, [`data_used_bytes`](https://aerospike.com/docs/database/reference/metrics#namespace__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](https://aerospike.com/docs/database/manage/namespace/storage/config#in-memory-data-storage-and-stripes).

#### Replace `memory_free_pct`

Choose the replacement based on what the alert monitors:

-   For data storage, use [`data_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__data_used_pct) with [`evict-used-pct`](https://aerospike.com/docs/database/reference/config#namespace__evict-used-pct) and [`stop-writes-used-pct`](https://aerospike.com/docs/database/reference/config#namespace__stop-writes-used-pct).
-   For RAM indexes, use [`indexes_memory_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__indexes_memory_used_pct) with [`evict-indexes-memory-pct`](https://aerospike.com/docs/database/reference/config#namespace__evict-indexes-memory-pct). This works in Database 7.1.0 and later, and only when [`indexes-memory-budget`](https://aerospike.com/docs/database/reference/config#namespace__indexes-memory-budget) is nonzero.
-   For host or control group RAM, use [`system_free_mem_pct`](https://aerospike.com/docs/database/reference/metrics#node_stats__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`](https://aerospike.com/docs/database/reference/metrics#node_stats__host_free_mem_pct) always reports host memory.

To choose between the host and control group statistics, see [Key metrics to monitor](https://aerospike.com/docs/database/observe/key-metrics) and the [`cgroup-mem-tracking`](https://aerospike.com/docs/database/reference/config#service__cgroup-mem-tracking) reference entry.

### Set data bytes

| Database 6.x statistic | Current statistic | Status | Same threshold after upgrade? |
| --- | --- | --- | --- |
| [`memory_data_bytes`](https://aerospike.com/docs/database/reference/metrics#sets__memory_data_bytes) | set [`data_used_bytes`](https://aerospike.com/docs/database/reference/metrics#sets__data_used_bytes) | Renamed | No for in-memory sets, for the same reason as the namespace statistic `memory_used_data_bytes`. |
| [`device_data_bytes`](https://aerospike.com/docs/database/reference/metrics#sets__device_data_bytes) | set [`data_used_bytes`](https://aerospike.com/docs/database/reference/metrics#sets__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`](https://aerospike.com/docs/database/reference/metrics#sets__data_used_bytes), not the namespace [`data_used_bytes`](https://aerospike.com/docs/database/reference/metrics#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`](https://aerospike.com/docs/database/reference/metrics#namespace__device_free_pct) and [`pmem_free_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__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`](https://aerospike.com/docs/database/reference/config#namespace__indexes-memory-budget) is 0, the server does not report [`indexes_memory_used_pct`](https://aerospike.com/docs/database/reference/metrics#namespace__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](https://aerospike.com/docs/database/advanced/special-upgrades/700-upgrade).

::: 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](https://aerospike.com/docs/database/observe/monitor/configure/exporter).

Terminal

```bash
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](https://aerospike.com/docs/database/reference/metrics)
-   [Key metrics to monitor](https://aerospike.com/docs/database/observe/key-metrics)
-   [Aerospike Database 7.0.0 release notes](https://aerospike.com/docs/database/release/7-0)
-   [Special upgrade to Database 7.0.0](https://aerospike.com/docs/database/advanced/special-upgrades/700-upgrade)
-   [Configure Aerospike Prometheus Exporter](https://aerospike.com/docs/database/observe/monitor/configure/exporter)
-   [Legacy XDR parameter and metric mapping](https://aerospike.com/docs/database/manage/xdr/parameters)