Measure Device-Mapper I/O with dmstats Safely

dmstats pulls real I/O counters off a device-mapper target when you cannot tell if the disk, the mapping or the workload is to blame. You will create a statistics region, inspect its counters, take a short repeated report, and remove the region cleanly when finished. The examples use dmstats from dmsetup version 2:1.02.185-3ubuntu3.2. Allow about fifteen minutes, plus time to identify a disposable or approved device-mapper target.

You need a shell, the dmsetup package, and a device-mapper device that your change window permits you to instrument. Creating and deleting regions changes kernel accounting state, so use an account with the required privileges, normally sudo. Do not experiment on a production mapping without recording the owner, device name and rollback plan first.

1. Check the installed command

Start with read-only checks. These do not need elevated privileges unless your host restricts access to the device-mapper control device:

$ command -v dmstats
/usr/sbin/dmstats
$ dpkg-query -W -f='${Package} ${Version}\n' dmsetup
dmsetup 2:1.02.185-3ubuntu3.2
$ dmstats help

The command reports statistics regions for device-mapper devices. Its broad form is dmstats COMMAND DEVICE, although the installed help also exposes the same functionality through dmsetup stats. Keep the command and device separate, and quote a name if it came from a variable.

Checkpoint: identify the exact mapping rather than guessing from a filesystem label.

$ sudo dmsetup ls --tree
# choose an approved mapped device name, for example: example-lv
$ DEVICE='example-lv'

Replace example-lv with a real name from your own output. Everything from here on is state-changing unless marked otherwise.

2. Inspect existing statistics before adding anything

List the regions currently visible for the selected device:

$ sudo dmstats list "$DEVICE"
name             region_id  ...
# the exact columns and rows depend on the device

By default, list shows regions and groups selected for the default program ID. Use --allprograms when an earlier tool may have created regions under another program ID, and --verbose to include group and area information, or --area and --region when you need those object types explicitly. An empty list does not mean the device has no I/O, only that no matching dmstats regions are registered.

If this is an existing monitoring setup, record its region IDs and program IDs before continuing. That record is your protection against deleting someone else's counters later.

3. Create one region for the whole device

Creating a region changes device-mapper accounting, but it does not resize or rewrite the mapped device. The default region spans the whole device. Create one with an explicit program ID so it is easy to select and remove:

$ sudo dmstats create "$DEVICE" --programid dmstats-howto --userdata baseline-check
0

On success, the final line is the new region ID. Save it immediately:

$ REGION_ID=0
$ sudo dmstats list "$DEVICE" --programid dmstats-howto
name       region_id  ...
example-lv 0           ...

The ID above is a placeholder: use the number your own command printed. --userdata is stored with the region and cannot contain whitespace; it is metadata, not a filter by itself. The default program ID is dmstats, so setting your own value stops your test hiding among unrelated regions.

To divide a region into several statistics areas, use either --areas NUMBER or --areasize SIZE. To monitor only part of a device, supply --start OFFSET --length LENGTH. These values use sectors by default, with documented suffixes for other units. Check the target's layout before choosing offsets: a wrong range makes the measurements misleading, not just wrong.

4. Read counters without resetting them

Print the raw counters for the region:

$ sudo dmstats print "$DEVICE" --programid dmstats-howto --regionid "$REGION_ID"
0 0 0 0 ...

The exact fields and values vary with kernel activity, and a newly created region may show zeros. print does not reset counters unless you add --clear. Treat --clear as a measurement boundary: it atomically resets the selected statistics except for in-flight I/O counters. Capture the current output and tell anyone consuming the baseline before you use it.

For named, human-readable columns, use a report instead:

$ sudo dmstats report "$DEVICE" --programid dmstats-howto --regionid "$REGION_ID" --units h
name       region_id  read_count  write_count  ...
example-lv 0           ...         ...          ...

Column selection and formatting can be refined with -o, --sort and --select. Run dmstats help -c on the installed system first to see the available report fields; do not copy a field list from a different release into a script without checking it.

5. Watch a short interval

A report normally runs once. Add --interval and --count for a bounded sample. The interval is in seconds, and the default interval is one second when repetition is requested:

$ sudo dmstats report "$DEVICE" --programid dmstats-howto --regionid "$REGION_ID" --interval 5 --count 3 --units h
name       region_id  read_count  write_count  ...
example-lv 0           ...         ...          ...
example-lv 0           ...         ...          ...
example-lv 0           ...         ...          ...

Here, --count 3 bounds the command to three reports. Give it an interval without a count and reporting continues until interrupted. A count of zero means the same thing, so do not use either form in unattended work unless you have deliberately arranged supervision.

For latency histograms, create the region with --bounds, optionally using values such as 1ms,10ms,100ms, then add --histogram to list or report. Sub-millisecond boundaries require precise timestamps: the tool enables precision automatically when such boundaries are requested, but --precise makes that intention explicit. Histogram bins cannot be retrofitted to an ordinary region.

6. Remove only the region you created

Deleting a region releases its statistics resources and removes it from later reports. It does not delete the underlying device, but it is irreversible for the counters:

$ sudo dmstats delete "$DEVICE" --programid dmstats-howto --regionid "$REGION_ID"
$ sudo dmstats list "$DEVICE" --programid dmstats-howto
# the test region should no longer appear

If the region belongs to a group, deleting the first member can also remove the group. For a grouped setup, inspect with list --verbose --group first and use ungroup --groupid GROUP_ID when you only intend to remove the grouping. Never jump straight to --allregions or --alldevices: combined, those options can remove every matching statistics region across every device.

Warning: if a delete fails, stop and re-run the read-only list with --allprograms rather than widening the command to all devices as a troubleshooting shortcut. Check the device name, program ID and region ID instead.

Done means