# man > dmstats(8) --- type: CommandReference command: dmstats mode: man section: 8 source: man-pages --- ## Quick Reference - `dmstats create ` — create a whole-device region with one area - `dmstats create --start 1G --length 32M ` — create a 32M region at offset 1G - `dmstats create --areas 8 ` — create a region with 8 areas - `dmstats delete --alldevices --allregions` — delete all regions on all devices - `dmstats list ` — list registered regions - `dmstats report --interval 1 --count 5 ` — display 5 reports at 1-second intervals - `dmstats create --segments ` — create one region per target segment - `dmstats create --filemap ` — create regions mapping file extents ## Name dmstats — device-mapper statistics management ## Synopsis `dmstats [options] [device_name | --major major --minor minor | -u uuid]` Commands: `clear`, `create`, `delete`, `group`, `help`, `list`, `print`, `report`, `ungroup`, `update_filemap` ## Options ### Global Options - `--alldevices` — operate on all devices (required for `create`/`delete` without device argument) - `-j, --major ` — specify major number - `-m, --minor ` — specify minor number - `-u, --uuid ` — specify uuid - `-v, --verbose` — produce additional output ### Create Options - `--areas ` — number of areas in new region - `--areasize [b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]` — size of each area; suffix selects units (lowercase=1024, uppercase=1000) - `--bounds [ns|us|ms|s]` — comma-separated latency histogram boundaries (nanoseconds, or with unit suffix) - `--filemap` — create regions from file extents instead of device offset/length - `--follow ` — file following mode for `dmfilemapd` daemon - `--foreground` — run `dmfilemapd` in foreground - `--length [suffix]` — length of region in sectors (or with unit suffix) - `--nogroup` — do not create a group for filemap regions - `--nomonitor` — disable automatic `dmfilemapd` daemon for filemap groups - `--precise` — attempt nanosecond precision counters - `--programid ` — program ID string (default "dmstats") - `--segments` — create one region per target segment - `--start [suffix]` — start offset of region (sectors or with unit suffix) - `--userdata ` — store arbitrary user data with region ### Delete Options - `--allprograms` — delete regions from all program IDs - `--allregions` — delete all regions on device - `--groupid ` — delete group and all contained regions - `--programid ` — select regions by program ID - `--regionid ` — select specific region ### List/Report Options - `--area` — include area objects in results - `--clear` — atomically reset counters after printing - `--count ` — iteration count for repeating reports (0 = infinite) - `--group` — include group objects in results - `--histogram` — include histogram fields in report - `--interval ` — interval between reports (default 1s) - `--nosuffix` — suppress output size suffixes - `--notimesuffix` — suppress time value suffixes (histogram in ns) - `-o, --options ` — specify report fields to display - `-O, --sort ` — sort output; prefix with `-` for reverse - `--region` — include region objects in results - `--relative` — show histogram relative percentages instead of absolute counts - `-S, --select ` — display only matching rows - `--units [h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]` — display units; `h`=human-readable, `H`=human-readable with 1000 base ### Group Options - `--alias ` — assign alias to group - `--groupid ` — specify group ID for operation - `--regions ` — comma-separated list of region IDs to group (e.g., `1-10`) ### Other - `--allprograms` — include regions from all program IDs - `--allregions` — include all regions (for commands that default to single region) - `--help, -c, -C, --columns` — show command summary with optional field list - `--update_filemap ` — update filemap group (also supports `--groupid`, `--follow`, `--foreground`) ## Examples Create a whole-device region with one area on `vg00/lvol1`: shell dmstats create vg00/lvol1 Create a 32M region 1G into device `d0`: shell dmstats create --start 1G --length 32M d0 Create a whole-device region with 8 areas on every device: shell dmstats create --areas 8 Delete all regions on all devices: shell dmstats delete --alldevices --allregions Create a whole-device region with areas 10GiB in size using `dmsetup`: shell dmsetup stats create --areasize 10G vg00/lvol1 Create a 1GiB region with 16 areas at the start of `vg00/lvol1`: shell dmstats create --start 0 --len 1G --areas=16 vg00/lvol1 List statistics regions on `vg00/lvol1`: shell dmstats list vg00/lvol1 Display five statistics reports at 1-second intervals: shell dmstats report --interval 1 --count 5 vg00/lvol1 Create one region per target segment in `vg00/lvol1`: shell dmstats create --segments vg00/lvol1 Create regions mapping files in `images/` directory: shell dmstats create --filemap images/* Print raw counters for region 4 on device `d0`: shell dmstats print --regionid 4 d0 ## See Also - [dmsetup(8)](http://localhost/phpMan.php/man/dmsetup/8/markdown) - LVM2 resource page: - Device-mapper resource page: - Device-mapper statistics kernel documentation: `Documentation/device-mapper/statistics.txt` ## Notes ### Regions, Areas, and Groups - **Regions**: arbitrary ranges of a device (sectors to whole device). Each region may be subdivided into **areas** (one or more), each with its own counter set. A summary for the whole region is also available. - **Groups**: combine one or more regions on a device for aggregated reporting. Group metadata is stored with the first region; deleting that region removes the group. - **Region identifiers**: per-device, non-negative integers, assigned at creation, unique across program IDs. - **Group identifiers**: per-device, non-negative integers, assigned at creation. ### File Mapping - Use `--filemap` to create regions from file extents (requires FIEMAP-supporting filesystem, e.g., XFS, Ext4, and device-mapper backing device). - By default, regions are placed in a group named after the file. Use `--nogroup` to disable. - The `dmfilemapd` daemon automatically updates the mapping as the file changes. Two follow modes: - `inode`: holds file open; follows rename/unlink; exits when file is unlinked and last reference is dropped. - `path`: re-opens path each iteration; updates to reflect new file at same path; exits if file is removed and not replaced within ~1 second. - Stop daemon by deleting the group. ### Report Fields The `report` command supports many fields, including: - **Derived metrics**: `reads_merged_per_sec`, `writes_merged_per_sec`, `reads_per_sec`, `writes_per_sec`, `read_size_per_sec`, `write_size_per_sec`, `avg_request_size`, `queue_size`, `await`, `r_await`, `w_await`, `throughput`, `service_time`, `util`. - **Meta fields**: `region_id`, `region_start`, `region_len`, `area_id`, `area_start`, `area_len`, `area_count`, `program_id`, `user_data`, `group_id`, `interval_ns`, `interval`. - **Basic counters**: `read_count`, `reads_merged_count`, `read_sector_count`, `read_time`, `write_count`, `writes_merged_count`, `write_sector_count`, `write_time`, `in_progress_count`, `io_ticks`, `queue_ticks`, `read_ticks`, `write_ticks`. - **Histogram fields**: `hist_count`, `hist_count_bounds`, `hist_count_ranges`, `hist_percent`, `hist_percent_bounds`, `hist_percent_ranges`, `hist_bounds`, `hist_ranges`, `hist_bins`. Use `-o` to select specific fields; default fields depend on `--histogram` and `--relative` options.