How to get block usage summary?

Overview

The dump-wb-summary info command produces an on-demand snapshot of write block (wblock) usage for a namespace and writes it to the server log. A wblock is the fixed 8 MiB unit in which Aerospike allocates, writes, and defragments storage; every record lives inside one wblock, and the interplay between wblock occupancy, defrag-lwm-pct, and device_available_pct determines how much of the raw device the namespace can actually write to.

The command answers questions such as:

• How full are the namespace's in-use wblocks — is the data tightly packed or fragmented?
• Why is device_available_pct low, and would raising defrag-lwm-pct actually recover space, or is the device simply full of live data?
• How many wblocks would become defrag-eligible at a candidate defrag-lwm-pct value?

This article covers what the command does, how to run it on a single node with asinfo and cluster-wide with asadm, and how to read the output.

Note: The command applies to the device, memory (with backing devices or files), and pmem storage engines. It is a read-only, lock-free scan of in-memory wblock state. It performs no device I/O and is safe to run on production nodes at any time. Under heavy write load the counts are a point-in-time approximation, which is fine for diagnostic purposes.

Command syntax

dump-wb-summary:ns=<NAMESPACE>
dump-wb-summary:ns=<NAMESPACE>;verbose=true

The ns parameter is required. The optional verbose=true adds a per-device breakdown of the wblock state counts before the namespace-wide summary.

The command returns only ok over the wire, the actual data is written to the log of the node that executed it. This has two practical consequences:

• The command must be executed on every node whose data you want to see; each node reports only its own devices.
• After running it, the results are retrieved from each node's log, not from the tool that issued the command.

With security enabled, the command requires the logging-ctrl privilege (PERM_LOGGING_CTRL)  held by the sys-admin role, for example. Without it the command returns a security error.

Running on a single node with asinfo

Run against the local node (add -h, -U/-P, and TLS options as appropriate for the environment):

asinfo -v 'dump-wb-summary:ns=test'
ok

Then retrieve the output from that node's log. All lines are tagged with the WB: prefix:

# systemd journal
journalctl -u aerospike -o cat | grep 'WB:'

# or a log file
grep 'WB: ' /var/log/aerospike/aerospike.log | tail -n 20

Running cluster-wide with asadm

asadm broadcasts the command to every node in one step, which is the natural fit given the per-node execution requirement. In asadm, asinfo is a privileged command: enter enable mode first.

Interactive:

Admin> enable
Admin+> asinfo -v "dump-wb-summary:ns=test"
node1.example.com:3000 (192.168.1.1) returned:
ok

node2.example.com:3000 (192.168.1.2) returned:
ok

node3.example.com:3000 (192.168.1.3) returned:
ok

One-shot from the shell:

asadm -e 'enable; asinfo -v "dump-wb-summary:ns=test"'

To target a subset of nodes, use the with modifier (accepts node address, node ID, or substring):

Admin+> asinfo -v "dump-wb-summary:ns=test" with 192.168.1.1 192.168.1.2

Every node returns ok; the data is now sitting in each node's local log. Collect it per node (journalctl/grep as above), or gather logs from all nodes at once with asadm's collectlogs command and grep the bundle for WB:.

Reading the output

Real output from a server 8.1.2.3 node (single small device, idle namespace):

Jul 02 2026 14:00:13 GMT: INFO (drv_ssd): (drv_ssd.c:2035) WB: namespace test
Jul 02 2026 14:00:13 GMT: INFO (drv_ssd): (drv_ssd.c:2036) WB: wblocks by state - pristine:503 reserved:5 used:1 defrag:0 emptying:0 free:2
Jul 02 2026 14:00:13 GMT: INFO (drv_ssd): (drv_ssd.c:2051) WB: wblocks with zero used-sz - 4
Jul 02 2026 14:00:13 GMT: INFO (drv_ssd): (drv_ssd.c:2052) WB: wblocks by (non-zero) used-sz - units=bytes:hist-width=8388700:bucket-width=83887:buckets=0,0,...,1,1,0,...,0,2

WB: wblocks by state

Lifecycle state counts across the namespace's devices on this node. pristine wblocks have never been written; free wblocks were written and reclaimed. Together they form the pool behind device_available_pct. reserved wblocks are active write buffers (client writes, defrag destinations, etc.), used wblocks hold committed data, defrag wblocks are queued for defragmentation, and emptying wblocks are being vacated.

WB: wblocks with zero used-sz

Non-pristine wblocks whose live data is exactly zero. These bypass the defrag queue and are reclaimed directly, so they are excluded from the histogram. This count includes all free wblocks plus any reserved buffers not yet written to.

WB: wblocks by (non-zero) used-sz

A 100-bucket histogram of live bytes per wblock, covering every non-pristine wblock with nonzero used size regardless of state. Each bucket is bucket-width=83887 bytes (⌈8 MiB / 100⌉) — almost exactly 1% of a wblock — so bucket i holds wblocks that are roughly i% to (i+1)% full. hist-width=8388700 is 100 × bucket-width, the rounded-up histogram span (slightly larger than the 8 MiB wblock). buckets= is 100 comma-separated counts; anything at or beyond the last boundary is clamped into bucket 99.

With verbose=true, additional WB: device <name>: ... lines precede the namespace summary, breaking the state counts down per device. A WB: short-lived wblocks - N line appears only when nonzero.

The counts always reconcile as: (reserved + used + free + defrag + emptying) = (zero used-sz count) + (sum of all histogram buckets). In the example: 5 + 1 + 2 + 0 + 0 = 8 = 4 + (1 + 1 + 2).

Note: Because the histogram includes reserved wblocks (active write buffers) while defrag eligibility applies only to used-state wblocks, an idle or nearly empty namespace — like the example above — shows mostly write buffers in the histogram, typically in the top buckets. On a loaded cluster, reserved wblocks number a handful per device and disappear into the totals.

Interpreting what you see

A few common patterns:

• Histogram mass concentrated in high buckets (70–99): wblocks are densely packed with live data. Low device_available_pct in this state means the device is genuinely full — defrag tuning cannot recover space; the remedies are capacity, eviction/expiration, or deletes.
• Histogram mass just above the current defrag-lwm-pct: many wblocks are almost eligible. A modest LWM raise would sweep them into the defrag queue and recover their empty space. Because each bucket is ~1% of a wblock, the cumulative count of buckets below a candidate value P is the number of wblocks that would become defrag-eligible at defrag-lwm-pct = P.
• Large defrag state count: the defrag queue has a backlog, defrag throughput (governed by defrag-sleep) is not keeping up with eligibility. Lower defrag-sleep before touching defrag-lwm-pct.
• Large zero-used count that persists: normally transient; empty wblocks are reclaimed promptly. Compare snapshots a few minutes apart before reading anything into a single sample.

The command reports a moment in time. For before/after comparisons , a defrag-lwm-pct change, a delete campaign, a load test — run it on the same nodes at each point and diff the histograms.

Version notes

This article describes server 7.1 and later (including all 8.x), where the wblock size is fixed at 8 MiB. On server 7.0 and earlier, the wblock size was the configurable write-block-size (up to 8 MiB), so bucket widths scale accordingly. On the 3.x–4.x series the command logged a different format entirely — one WBH: N blocks of size X bytes line per distinct used size — rather than the fixed 100-bucket histogram.