# info > DMSTATS

yaml
---
type: CommandReference
command: dmstats
mode: man
section: 8
source: man-pages
---

## Quick Reference

- `dmstats create device_name` — create a whole-device region with one area
- `dmstats create --start 1G --length 32M device` — create a region at offset
- `dmstats create --areas 8` — create a region with 8 areas on all devices
- `dmstats delete --alldevices --allregions` — delete all regions on all devices
- `dmstats list device` — list regions registered on device
- `dmstats report --interval 1 --count 5 device` — repeat a report 5 times at 1s intervals
- `dmstats create --segments device` — create one region per target segment
- `dmstats create --filemap file_path` — create regions mapping file extents

## Name

`dmstats` — device-mapper statistics management

## Synopsis

shell
dmstats command [OPTIONS]
dmstats clear device_name [--allprograms|--programid id] [--allregions|--regionid id]
dmstats create device_name...|file_path...|--alldevices [--areas nr_areas|--areasize area_size] [--bounds histogram_boundaries] [--filemap] [--follow follow_mode] [--foreground] [--nomonitor] [--nogroup] [--precise] [--start start_sector --length length|--segments] [--userdata user_data] [--programid id]
dmstats delete device_name|--alldevices [--allprograms|--programid id] [--allregions|--regionid id]
dmstats group [device_name|--alldevices] [--alias name] [--regions regions]
dmstats help [-c|-C|--columns]
dmstats list [device_name] [--histogram] [--allprograms|--programid id] [--units units] [--area] [--region] [--group] [--nosuffix] [--notimesuffix] [-v|--verbose]
dmstats print [device_name] [--clear] [--allprograms|--programid id] [--allregions|--regionid id]
dmstats report [device_name] [--interval seconds] [--count count] [--units units] [--histogram] [--allprograms|--programid id] [--allregions|--regionid id] [--area] [--region] [--group] [-O|--sort sort_fields] [-S|--select selection] [--units units] [--nosuffix] [--notimesuffix]
dmstats ungroup [device_name|--alldevices] [--groupid id]
dmstats update_filemap file_path [--groupid id] [--follow follow_mode] [--foreground]
## Options

### Device selection

- `-j, --major major` — specify major number
- `-m, --minor minor` — specify minor number
- `-u, --uuid uuid` — specify device UUID
- `--alldevices` — operate on all devices when no device argument given
- `--allprograms` — include regions from all program IDs
- `--allregions` — include all regions for commands that accept a single region ID
- `--programid id` — select regions with matching program ID (default: "dmstats")
- `--regionid id` — specify a region to operate on
- `--groupid id` — specify a group to operate on

### Region creation

- `--start start[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]` — start offset of region (default: 0)
- `--length length[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]` — length of region (default: whole device)
- `--areas nr_areas` — number of equal-sized areas to create within region
- `--areasize area_size[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]` — size of each area
- `--segments` — create one region per target segment of device
- `--precise` — use nanosecond precision counters
- `--bounds histogram_boundaries[ns|us|ms|s]` — comma-separated list of latency histogram bin boundaries
- `--userdata user_data` — arbitrary string stored with region
- `--nogroup` — do not create a group when using `--segments` or `--filemap`
- `--alias name` — alias name for a group (used with `--segments` or `--filemap`)

### File mapping

- `--filemap` — create regions from file extents instead of command-line parameters
- `--follow follow_mode` — file monitoring mode: `inode` or `path`
- `--foreground` — run `dmfilemapd` daemon in foreground
- `--nomonitor` — disable automatic `dmfilemapd` daemon

### Output and reporting

- `--units [units][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]` — display units for sizes
- `--nosuffix` — suppress suffix on output sizes
- `--notimesuffix` — suppress suffix on output time values
- `--histogram` — select default fields emphasizing histogram data
- `--relative` — show histogram bins as percentages instead of absolute counts
- `-o, --options` — specify which report fields to display
- `-O, --sort sort_fields` — sort output by field list (precede with `-` for reverse)
- `-S, --select selection` — display only rows matching criteria
- `--interval seconds` — interval between report iterations (default: 1)
- `--count count` — number of report iterations (0 = until interrupted)
- `--clear` — when printing counters, atomically reset to zero
- `--area` — include objects of type area in list/report
- `--region` — include objects of type region
- `--group` — include objects of type group
- `-v, --verbose` — produce additional output

### Grouping

- `--regions region_list` — comma-separated list of region IDs (ranges with hyphen)
- `--groupid id` — specify group to operate on
- `--alias name` — assign alias to a group

## Commands

- **clear** — zero statistics counters for specified regions (except in-flight IO)
- **create** — create one or more new statistics regions. If `--filemap` is used, regions correspond to file extents. On success, prints region ID(s) or group ID.
- **delete** — remove a region or group. Use `--allregions` and `--alldevices` to delete all.
- **group** — combine multiple regions into a group; metadata stored with first (lowest numbered) region.
- **help** — output command summary; `-c` or `-C` includes report fields.
- **list** — list regions, areas, or groups. Use `--verbose` for detailed output.
- **print** — print raw statistics counters for a region.
- **report** — display a formatted report; supports repeating and histogram modes.
- **ungroup** — remove an existing group, returning regions to original state.
- **update_filemap** — update a file-mapped group to reflect current file extents; can start `dmfilemapd` daemon.

## Examples

**Create a whole-device region with one area on vg00/lvol1**
shell
# dmstats create vg00/lvol1
vg00/lvol1: Created new region with 1 area(s) as region ID 0
**Create a 32M region 1G into device d0**
shell
# dmstats create --start 1G --length 32M d0
d0: Created new region with 1 area(s) as region ID 0
**Create a whole-device region with 8 areas on every device**
shell
# dmstats create --areas 8
vg00-lvol1: Created new region with 8 area(s) as region ID 0
...
**Delete all regions on all devices**
shell
# dmstats delete --alldevices --allregions
**List the statistics regions registered on vg00/lvol1**
shell
# dmstats list vg00/lvol1
Name             RgID  RStart RSize  #Areas ASize  ProgID
vg00-lvol1           0      0 61.00g      1 61.00g dmstats
...
**Display five statistics reports at one-second intervals**
shell
# dmstats report --interval 1 --count 5 vg00/lvol1
**Create one region for each target segment in device vg00/lvol1**
shell
# dmstats create --segments vg00/lvol1
vg00-lvol1: Created new region with 1 area(s) as region ID 0
...
**Create file-mapped regions for files in images/ directory**
shell
# dmstats create --filemap images/*
images/vm1.qcow2: Created new group with 87 region(s) as group ID 0.
...
## See Also

- [dmsetup(8)](http://localhost/phpMan.php/man/dmsetup/8/markdown)
- LVM2 resource page: <https://www.sourceware.org/lvm2/>
- Device-mapper resource page: <http://sources.redhat.com/dm/>
- Device-mapper statistics kernel documentation: `Documentation/device-mapper/statistics.txt`