man > dmstats(8)

man perldoc info pydoc3 ri search

DMSTATS(8)                                                                                                                                                                                                                                                                 MAINTENANCE COMMANDS                                                                                                                                         DMSTATS(8)

📋 NAME

dmstats — device-mapper statistics management

🚀 Quick Reference

Use Case	Command	Description
Create a whole-device region	dmstats create <device>	Creates a new statistics region spanning the entire device.
Create a region with specific size and offset	dmstats create --start <start> --length <len> <device>	Places a region of arbitrary length at an arbitrary offset.
Create a region with multiple areas	dmstats create --areas <nr> <device>	Divides the region into the specified number of equal-sized areas.
Create regions per segment	dmstats create --segments <device>	Creates a separate region for each target in the device table.
Create file-mapped regions	dmstats create --filemap <file>	Creates regions corresponding to the on-disk extents of a file.
List regions	dmstats list <device>	Lists statistics regions, areas, or groups on the device.
Report statistics	dmstats report <device>	Displays a continuous or one-shot report of counter values.
Print raw counters	dmstats print --regionid <id> <device>	Prints raw kernel counters for a specific region.
Delete all regions	dmstats delete --alldevices --allregions	Removes all regions from all devices.
Group regions	dmstats group --regions <list> <device>	Combines regions into a group for aggregated reporting.

🔍 SYNOPSIS

dmsetup stats <command> [OPTIONS]

dmstats <command> <device_name> | --major <major> --minor <minor> | -u|--uuid <uuid> [-v|--verbose]
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]

📝 DESCRIPTION

The dmstats program manages IO statistics regions for devices that use the device-mapper driver. Statistics regions may be created, deleted, listed and reported on using the tool.

The first argument to dmstats is a command.

The second argument is the device name, uuid or major and minor numbers.

Further options permit the selection of regions, output format control, and reporting behaviour.

When no device argument is given dmstats will by default operate on all device-mapper devices present. The create and delete commands require the use of --alldevices when used in this way.

⚙️ OPTIONS

• --alias <name> — Specify an alias name for a group.
• --alldevices — If no device arguments are given allow operation on all devices when creating or deleting regions.
• --allprograms — Include regions from all program IDs for list and report operations.
• --allregions — Include all present regions for commands that normally accept a single region identifier.
• --area — When performing a list or report, include objects of type area in the results.
• --areas <nr_areas> — Specify the number of statistics areas to create within a new region.
• --areasize <area_size>[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — Specify the size of areas into which a new region should be divided.
• --clear — When printing statistics counters, also atomically reset them to zero.
• --count <count> — Specify the iteration count for repeating reports. Zero means repeat until interrupted.
• --group — When performing a list or report, include objects of type group in the results.
• --filemap — Instead of creating regions on a device as specified by command line options, open the file found at each file_path argument and create regions corresponding to the locations of the on-disk extents allocated to the file(s).
• --nomonitor — Disable the dmfilemapd daemon when creating new file mapped groups.
• --follow <follow_mode> — Specify the dmfilemapd file following mode: "inode" or "path".
• --foreground — Specify that the dmfilemapd daemon should run in the foreground.
• --groupid <id> — Specify the group to operate on.
• --bounds <histogram_boundaries>[ns|us|ms|s] — Specify the boundaries of a latency histogram to be tracked for the region.
• --histogram — When used with the report and list commands select default fields that emphasize latency histogram data.
• --interval <seconds> — Specify the interval in seconds between successive iterations for repeating reports.
• --length <length>[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — Specify the length of a new statistics region in sectors.
• -j|--major <major> — Specify the major number.
• -m|--minor <minor> — Specify the minor number.
• --nogroup — When creating regions mapping the extents of a file in the file system, do not create a group or set an alias.
• --nosuffix — Suppress the suffix on output sizes.
• --notimesuffix — Suppress the suffix on output time values. Histogram boundary values will be reported in units of nanoseconds.
• -o|--options — Specify which report fields to display.
• -O|--sort <sort_fields> — Sort output according to the list of fields given. Precede any sort field with '-' for a reverse sort.
• --precise — Attempt to use nanosecond precision counters when creating new statistics regions.
• --programid <id> — Specify a program ID string. Default is "dmstats".
• --region — When performing a list or report, include objects of type region in the results.
• --regionid <id> — Specify the region to operate on.
• --regions <region_list> — Specify a list of regions to group. Comma-separated, ranges like '1-10'.
• --relative — If displaying the histogram report show relative (percentage) values instead of absolute counts.
• -S|--select <selection> — Display only rows that match selection criteria.
• --start <start>[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — Specify the start offset of a new statistics region in sectors.
• --segments — When used with create, create a new statistics region for each target contained in the given device(s).
• --units [<units>][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — Set the display units for report output.
• --userdata <user_data> — Specify user data (a word) to be stored with a new region.
• -u|--uuid — Specify the uuid.
• -v|--verbose [-v|--verbose] — Produce additional output.

📂 COMMANDS

🧹 clear

dmstats clear <device_name> [--allprograms|--programid <id>] [--allregions|--regionid <id>]

Instructs the kernel to clear statistics counters for the specified regions (with the exception of in-flight IO counters).

🆕 create

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>]

Creates one or more new statistics regions on the specified device(s). The region will span the entire device unless --start and --length or --segments are given. If --precise is used, the command will attempt to create a region using nanosecond precision counters. If --bounds is given a latency histogram will be tracked. Latency values are given in nanoseconds. An optional program_id or user_data string may be associated. If --filemap is given with a regular file, regions are created corresponding to the physical extents allocated to the file.

🗑️ delete

dmstats delete <device_name>|--alldevices [--allprograms|--programid <id>] [--allregions|--regionid <id>]

Delete the specified statistics region. All counters and resources are released. Use --allregions to remove all regions on a device. To remove all regions on all devices use both --allregions and --alldevices. If a --groupid is given, the group and all its regions are deleted.

🔗 group

dmstats group [<device_name>|--alldevices] [--alias <name>] [--regions <regions>]

Combine one or more statistics regions on the specified device into a group. The list of regions is specified with --regions and an optional alias with --alias. Regions with histograms can be grouped only if the histogram bins match exactly.

❓ help

dmstats help [-c|-C|--columns]

Outputs a summary of the commands available, optionally including the list of report fields.

📋 list

dmstats list [<device_name>] [--histogram] [--allprograms|--programid <id>] [--units <units>] [--area] [--region] [--group] [--nosuffix] [--notimesuffix] [-v|--verbose]

List the statistics regions, areas, or groups registered on the device. By default only regions and groups are included. Use -v for verbose output including areas. Use --histogram to include bin count and latency boundary values.

🖨️ print

dmstats print [<device_name>] [--clear] [--allprograms|--programid <id>] [--allregions|--regionid <id>]

Print raw statistics counters for the specified region or for all present regions.

📊 report

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]

Start a report for the specified object or for all present objects. The report can repeat at a fixed interval. Use --histogram to include histogram values. Use --relative to show bin values as percentages. Object types (areas, regions, groups) are selected using --area, --region, and --group.

🔓 ungroup

dmstats ungroup [<device_name>|--alldevices] [--groupid <id>]

Remove an existing group and return all the group's regions to their original state. The group is specified using --groupid.

🔄 update_filemap

dmstats update_filemap <file_path> [--groupid <id>] [--follow <follow_mode>] [--foreground]

Update a group of dmstats regions specified by group_id, that were previously created with --filemap. This will add and remove regions to reflect changes in the allocated extents of the file. Use --nomonitor to force a direct update and disable starting the monitoring daemon.

🏷️ REGIONS, AREAS, AND GROUPS

The device-mapper statistics facility allows separate performance counters to be maintained for arbitrary regions of devices. A region may span any range: from a single sector to the whole device. A region may be further sub-divided into a number of distinct areas (one or more), each with its own counter set. In addition, one or more regions on one device can be combined into a statistics group. Groups allow several regions to be aggregated and reported as a single entity. By default new regions span the entire device.

🔖 Region identifiers

Each region is assigned an identifier when it is created that is used to reference the region in subsequent operations. Region identifiers are unique within a given device (including across different program_id values). Depending on the sequence of create and delete operations, gaps may exist in the sequence of region_id values for a particular device.

🔖 Group identifiers

Groups are also assigned an integer identifier at creation time; like region identifiers, group identifiers are unique within the containing device.

📄 FILE MAPPING

Using --filemap, it is possible to create regions that correspond to the extents of a file in the file system. This allows IO statistics to be monitored on a per-file basis. To be able to use file mapping, the file must be backed by a device-mapper device, and in a file system that supports the FIEMAP ioctl (e.g., xfs(5) and ext4(5)). By default the regions making up a file are placed together in a group, and the group alias is set to the basename of the file. The update_filemap command and dmfilemapd daemon are provided to update file mapped groups.

📁 File follow modes

The file map monitoring daemon can monitor files in two distinct ways: follow-inode mode and follow-path mode.

• follow-inode — The daemon holds the file open and continues to update regions from the same file descriptor. The mapping follows rename, move, and unlink operations. The daemon exits once the file is unlinked and it is the last holder of a reference.
• follow-path — The daemon re-opens the provided path on each monitoring iteration. The group updates to reflect a new file moved to the same path. The daemon exits if the file is removed and not replaced within a brief tolerance interval.

To stop the daemon, delete the group containing the mapped regions. The daemon can also be safely killed at any time and the group kept.

⚠️ Limitations

The daemon attempts to maintain good synchronisation between the file extents and the regions, but there are inevitably some IO events that cannot be counted when a file is growing. There is a further loss of events in that there is currently no way to atomically resize a dmstats region and preserve its current counter values. File mapping is currently most effective in cases where the majority of IO does not trigger extent allocation.

📊 REPORT FIELDS

The dmstats report provides several types of field that may be added to the default field set, or used to create custom reports. All performance counters and metrics are calculated per-area.

📈 Derived metrics

• reads_merged_per_sec — Reads merged per second.
• writes_merged_per_sec — Writes merged per second.
• reads_per_sec — Reads completed per second.
• writes_per_sec — Writes completed per second.
• read_size_per_sec — Size of data read per second.
• write_size_per_sec — Size of data written per second.
• avg_request_size — Average request size.
• queue_size — Average queue size.
• await — The average wait time for read and write operations.
• r_await — The average wait time for read operations.
• w_await — The average wait time for write operations.
• throughput — The device throughput in operations per second.
• service_time — The average service time (in milliseconds) for operations.
• util — Percentage of CPU time during which I/O requests were issued to the device (bandwidth utilization).

🏷️ Group, region and area meta fields

• region_id — Region identifier.
• region_start — The region start location.
• region_len — The length of the region.
• area_id — Area identifier.
• area_start — The area start location.
• area_len — The length of the area.
• area_count — The number of areas in this region.
• program_id — The program ID value associated with this region.
• user_data — The user data value associated with this region.
• group_id — Group identifier.
• interval_ns — The estimated interval over which the current counter values have accumulated (nanoseconds).
• interval — The estimated interval (seconds).

🔢 Basic counters

• read_count — Count of reads completed this interval.
• reads_merged_count — Count of reads merged this interval.
• read_sector_count — Count of 512 byte sectors read this interval.
• read_time — Accumulated duration of all read requests (ns).
• write_count — Count of writes completed this interval.
• writes_merged_count — Count of writes merged this interval.
• write_sector_count — Count of 512 byte sectors written this interval.
• write_time — Accumulated duration of all write requests (ns).
• in_progress_count — Count of requests currently in progress.
• io_ticks — Nanoseconds spent servicing requests.
• queue_ticks — Incremented at each I/O start, completion, merge, or read by the number of I/Os in progress multiplied by the time spent since last update.
• read_ticks — Nanoseconds spent servicing reads.
• write_ticks — Nanoseconds spent servicing writes.

📊 Histogram fields

• hist_count — A list of histogram counts in order of ascending latency.
• hist_count_bounds — Histogram counts with bin boundaries.
• hist_count_ranges — Histogram counts with lower and upper bounds.
• hist_percent — Relative histogram values as percentages.
• hist_percent_bounds — Relative histogram values with bin boundaries.
• hist_percent_ranges — Relative histogram values with lower and upper bounds.
• hist_bounds — List of histogram boundary values.
• hist_ranges — List of histogram bin ranges (e.g., "LOWER-UPPER").
• hist_bins — The number of latency histogram bins configured.

💡 EXAMPLES

Create a whole-device region with one area on vg00/lvol1

# 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

# 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

# dmstats create --areas 8
vg00-lvol1: Created new region with 8 area(s) as region ID 0
vg00-lvol2: Created new region with 8 area(s) as region ID 0
vg00-lvol3: Created new region with 8 area(s) as region ID 0
vg01-lvol0: Created new region with 8 area(s) as region ID 2
vg01-lvol1: Created new region with 8 area(s) as region ID 0
vg00-lvol2: Created new region with 8 area(s) as region ID 1

Delete all regions on all devices

# dmstats delete --alldevices --allregions

Create a whole-device region with areas 10GiB in size on vg00/lvol1 using dmsetup

# dmsetup stats create --areasize 10G vg00/lvol1
vg00-lvol1: Created new region with 5 area(s) as region ID 1

Create a 1GiB region with 16 areas at the start of vg00/lvol1

# dmstats create --start 0 --len 1G --areas=16 vg00/lvol1
vg00-lvol1: Created new region with 16 area(s) as region ID 0

List the statistics regions registered on vg00/lvol1

# dmstats list vg00/lvol1
Name             RgID  RStart RSize  #Areas ASize  ProgID
vg00-lvol1           0      0 61.00g      1 61.00g dmstats
vg00-lvol1           1 61.00g 19.20g      1 19.20g dmstats
vg00-lvol1           2 80.20g  2.14g      1  2.14g dmstats

Display five statistics reports for vg00/lvol1 at an interval of one second

# dmstats report --interval 1 --count 5 vg00/lvol1
# dmstats report
Name              RgID   ArID   AStart  ASize   RRqM/s    WRqM/s    R/s    W/s    RSz/s WSz/s
AvRqSz  QSize Util%      AWait RdAWa WrAWa
vg_hex-lv_home       0     0      0 61.00g      0.00      0.00   0.00  218.00      0    1.04m
4.50k  2.97      81.70 13.62  0.00 13.62
vg_hex-lv_home        1      0  61.00g  19.20g      0.00      0.00  0.00   5.00     0 548.00k
109.50k  0.14      11.00 27.40  0.00 27.40
vg_hex-lv_home       2     0 80.20g  2.14g      0.00      0.00   0.00   14.00      0    1.15m
84.00k  0.39      18.70 27.71  0.00 27.71

Create one region for each target contained in device vg00/lvol1

# dmstats create --segments vg00/lvol1
vg00-lvol1: Created new region with 1 area(s) as region ID 0
vg00-lvol1: Created new region with 1 area(s) as region ID 1
vg00-lvol1: Created new region with 1 area(s) as region ID 2

Create regions mapping each file in the directory images/ and place them into separate groups

# dmstats create --filemap images/*
images/vm1.qcow2: Created new group with 87 region(s) as group ID 0.
images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87.
images/vm2.qcow2: Created new group with 11 region(s) as group ID 95.
images/vm2-1.qcow2: Created new group with 1454 region(s) as group ID 106.
images/vm3.img: Created new group with 2 region(s) as group ID 1560.

Print raw counters for region 4 on device d0

# dmstats print --regionid 4 d0
2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41

✍️ AUTHORS

Bryn M. Reeves <bmr AT redhat.com>

🔗 SEE ALSO

• dmsetup(8)
• 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

Linux                                                                                                                                                                                                                                                                 Jun 23 2016                                                                                                                                                                                                                         DMSTATS(8)

📋 NAME 🚀 Quick Reference 🔍 SYNOPSIS 📝 DESCRIPTION ⚙️ OPTIONS 📂 COMMANDS 🏷️ REGIONS, AREAS, AND GROUPS 📄 FILE MAPPING 📊 REPORT FIELDS 💡 EXAMPLES ✍️ AUTHORS 🔗 SEE ALSO