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.
Regions in the group may still be updated with the update_filemap command, or by starting the daemon manually.
The follow_mode argument is either "inode", for follow-inode mode, or "path", for follow-path.
If follow-inode mode is used, the daemon will hold the file open, and continue to update regions from the same file descriptor. This means that the mapping will follow rename, move (within the same file system), and unlink operations. This mode is useful if the file is expected to be moved, renamed, or unlinked while it is being monitored.
In follow-inode mode, the daemon will exit once it detects that the file has been unlinked and it is the last holder of a reference to it.
If follow-path is used, the daemon will re-open the provided path on each monitoring iteration. This means that the group will be updated to reflect a new file being moved to the same path as the original file. This mode is useful for files that are expected to be updated via unlink and rename.
In follow-path mode, the daemon will exit if the file is removed and not replaced within a brief tolerance interval.
In either mode, the daemon exits automatically if the monitored group is removed.
The newly created regions are automatically placed into a group unless the --nogroup option is given. When grouping is enabled a group alias may be specified using the --alias option.
The region will span the entire device unless --start and --length or --segments are given. The --start an --length options allow a region of arbitrary length to be placed at an arbitrary offset into the device. The --segments option causes a new region to be created for each target in the corresponding device-mapper device's table.
If the --precise option is used the command will attempt to create a region using nanosecond precision counters.
If --bounds is given a latency histogram will be tracked for the new region. The boundaries of the histogram bins are given as a comma separated list of latency values. There is an implicit lower bound of zero on the first bin and an implicit upper bound of infinity (or the configured interval duration) on the final bin.
Latencies are given in nanoseconds. An optional unit suffix of ns, us, ms, or s may be given after each value to specify units of nanoseconds, microseconds, miliseconds or seconds respectively, so for example, 10ms is equivalent to 10000000. Latency values with a precision of less than one milisecond can only be used when precise timestamps are enabled: if --precise is not given and values less than one milisecond are used it will be enabled automatically.
An optional program_id or user_data string may be associated with the region. A program_id may then be used to select regions for subsequent list, print, and report operations. The user_data stores an arbitrary string and is not used by dmstats or the device-mapper kernel statistics subsystem.
By default dmstats creates regions with a program_id of "dmstats".
On success the region_id of the newly created region is printed to stdout.
If the --filemap option is given with a regular file, or list of files, as the file_path argument, instead of creating regions with parameters specified on the command line, dmstats will open the files located at file_path and create regions corresponding to the physical extents allocated to the file. This can be used to monitor statistics for individual files in the file system, for example, virtual machine images, swap areas, or large database files.
To work with the --filemap option, files must be located on a local file system, backed by a device-mapper device, that supports physical extent data using the FIEMAP ioctl (Ext4 and XFS for e.g.).
By default regions that map a file are placed into a group and the group alias is set to the basename of the file. This behaviour can be overridden with the --alias and --nogroup options.
Creating a group that maps a file automatically starts a daemon, dmfilemapd to monitor the file and update the mapping as the extents allocated to the file change. This behaviour can be disabled using the --nomonitor option.
Use the --group option to only display information for groups when listing and reporting.
All regions registered on a device may be removed using --allregions.
To remove all regions on all devices both --allregions and --alldevices must be used.
If a --groupid is given instead of a --regionid the command will attempt to delete the group and all regions that it contains.
If a deleted region is the first member of a group of regions the group will also be removed.
The list of regions to be grouped is specified with --regions and an optional alias may be assigned with --alias. The set of regions is given as a comma-separated list of region identifiers. A continuous range of identifers spanning from R1 to R2 may be expressed as 'R1-R2'.
Regions that have a histogram configured can be grouped: in this case the number of histogram bins and their bounds must match exactly.
On success the group list and newly created group_id are printed to stdout.
The group metadata is stored with the first (lowest numbered) region_id in the group: deleting this region will also delete the group and other group members will be returned to their prior state.
By default only regions and groups are included in list output. If -v or --verbose is given the report will also include a row of information for each configured group and for each area contained in each region displayed.
Regions that contain a single area are by default omitted from the verbose list since their properties are identical to the area that they contain - to view all regions regardless of the number of areas present use --region). To also view the areas contained within regions use --area.
If --histogram is given the report will include the bin count and latency boundary values for any configured histograms.
If the --allprograms switch is given, all regions will be listed, regardless of region program ID values.
If the --histogram is given the report will include the histogram values and latency boundaries.
If the --relative is used the default histogram field displays bin values as a percentage of the total number of I/Os.
Object types (areas, regions and groups) to include in the report are selected using the --area, --region, and --group options.
The group to be removed is specified using --groupid.
This will add and remove regions to reflect changes in the allocated extents of the file on-disk, since the time that it was crated or last updated.
Use of this command is not normally needed since the dmfilemapd daemon will automatically monitor filemap groups and perform these updates when required.
If a filemapped group was created with --nomonitor, or the daemon has been killed, the update_filemap can be used to manually force an update or start a new daemon.
Use --nomonitor to force a direct update and disable starting the monitoring daemon.
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; counters for all regions and areas are summed and used to report totals for all group members. Groups also permit the assignment of an optional alias, allowing meaningful names to be associated with sets of regions.
The group metadata is stored with the first (lowest numbered) region_id in the group: deleting this region will also delete the group and other group members will be returned to their prior state.
By default new regions span the entire device. The --start and --length options allows a region of any size to be placed at any location on the device.
Using offsets it is possible to create regions that map individual objects within a block device (for example: partitions, files in a file system, or stripes or other structures in a RAID volume). Groups allow several non-contiguous regions to be assembled together for reporting and data aggregation.
A region may be either divided into the specified number of equal-sized areas, or into areas of the given size by specifying one of --areas or --areasize when creating a region with the create command. Depending on the size of the areas and the device region the final area within the region may be smaller than requested.
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.
The region_id should be treated as an opaque identifier used to reference the region.
Group identifiers
Groups are also assigned an integer identifier at creation time; like region identifiers, group identifiers are unique within the containing device.
The group_id should be treated as an opaque identifier used to reference the group.
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 (and which returns data describing the physical location of extents). This currently includes 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(3) of the file. This allows statistics to be reported for the file as a whole, aggregating values for the regions making up the group. To see only the whole file (group) when using the list and report commands, use --group.
Since it is possible for the file to change after the initial group of regions is created, the update_filemap command, and dmfilemapd daemon are provided to update file mapped groups either manually or automatically.
File follow modes
The file map monitoring daemon can monitor files in two distinct ways: follow-inode mode, and follow-path mode.
The mode affects the behaviour of the daemon when a file under monitoring is renamed or unlinked, and the conditions which cause the daemon to terminate.
If follow-inode mode is used, the daemon will hold the file open, and continue to update regions from the same file descriptor. This means that the mapping will follow rename, move (within the same file system), and unlink operations. This mode is useful if the file is expected to be moved, renamed, or unlinked while it is being monitored.
In follow-inode mode, the daemon will exit once it detects that the file has been unlinked and it is the last holder of a reference to it.
If follow-path is used, the daemon will re-open the provided path on each monitoring iteration. This means that the group will be updated to reflect a new file being moved to the same path as the original file. This mode is useful for files that are expected to be updated via unlink and rename.
In follow-path mode, the daemon will exit if the file is removed and not replaced within a brief tolerance interval (one second).
To stop the daemon, delete the group containing the mapped regions: the daemon will automatically shut down.
The daemon can also be safely killed at any time and the group kept: if the file is still being allocated the mapping will become progressively out-of-date as extents are added and removed (in this case the daemon can be re-started or the group updated manually with the update_filemap command).
See the create command and --filemap, --follow, and --nomonitor options for further information.
Limitations
The daemon attempts to maintain good synchronisation between the file extents and the regions contained in the group, however, since it can only react to new allocations once they have been written, there are inevitably some IO events that cannot be counted when a file is growing, particularly if the file is being extended by a single thread writing beyond end-of-file (for example, the dd program).
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. This affects files when they grow by extending the final extent, rather than allocating a new extent: any events that had accumulated in the region between any prior operation and the resize are lost.
File mapping is currently most effective in cases where the majority of IO does not trigger extent allocation. Future updates may address these limitations when kernel support is available.
All performance counters and metrics are calculated per-area.
The kernel provides thirteen separate counters for each statistics area. The first eleven of these match the counters provided in /proc/diskstats or /sys/block/*/*/stat. The final pair provide separate counters for read and write time.
A brief representation of the histogram values and latency intervals can be included in the report using these fields.
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 reach 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, each named after the corresponding file
#
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
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