DMSTATS(8)

NAME
dmstats — device-mapper statistics management

SYNOPSIS
dmsetup stats command [options]
dmstats <command> [[ device_name] |[--uuid uuid] |[--major major --minor minor]]
dmstats clear device_name [--allregions |--regionid id]
dmstats create device_name [--alldevices] [[--areas nr_areas] |[--areasize area_size]] [--precise] [[--start start_sector] [--length length] |[--segments]] [--auxdata data] [--programid id]
dmstats delete device_name [--alldevices] [--allregions |--regionid id] [--allprograms |--programid id]
dmstats help [-c|-C|--columns]
dmstats list [device_name] [--allprograms |--programid id] [--units units] [--nosuffix] [--nosuffix] [-v|--verbose [-v|--verbose]
dmstats print [device_name] [--clear] [--allprograms |--programid id] [--allregions |--regionid id]
dmstats report [device_name] [--interval seconds] [--count count] [--units units] [--allprograms] [--programid id] [--regionid id] [-O|--sort sort_fields] [-S|--select Selection] [--units units] [--nosuffix]

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 the program is run using the 'dmstats' alias, the command must be the first argument and any switches and options should be specified following the command itself. This limitation is not present when run as 'dmsetup stats'. 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

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

--areas nr_areas
    Specify the number of statistics areas to create within a new region.

--areasize area_size
    Specify the size of areas into which a new region should be divided. An optional suffix selects units of bBsSkKmMgGtTpPeE: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead of 1024.

--auxdata aux_data
    Specify auxilliary data (a string) to be stored with a new region.

--clear
    When printing statistics counters, also atomically reset them to zero.

--count count
    Specify the iteration count for repeating reports. If the count argument is zero reports will continue to repeat until interrupted.

--interval seconds
    Specify the interval in seconds between successive iterations for repeating reports. If --interval is specified but --count is not, reports will continue to repeat until interrupted.

--length length
    Specify the length of a new statistics region in sectors. An optional suffix selects units of bBsSkKmMgGtTpPeE: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead of 1024.

-j|--major major
    Specify the major number.

-m|--minor minor
    Specify the minor number.

--nosuffix
    Suppress the suffix on output sizes. Use with --units (except h and H) if processing the output.

-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 on that column.

--precise
    Attempt to use nanosecond precision counters when creating new statistics regions.

--programid id
    Specify a program ID string. When creating new statistics regions this string is stored with the region. Subsequent operations may supply a program ID in order to select only regions with a matching value. The default program ID for dmstats-managed regions is "dmstats".

-S|--select selection
    Display only rows that match selection criteria. All rows with the additional "selected" column (-o selected) showing 1 if the row matches the selection and 0 otherwise. The selection criteria are defined by specifying column names and their valid values while making use of supported comparison operators.

--start start
    Specify the start offset of a new statistics region in sectors. An optional suffix selects units of bBsSkKmMgGtTpPeE: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead of 1024.

--segments
    Create a new statistics region for each target contained in the target device. This causes a separate region to be allocated for each segment of the device.

--units hHbBsSkKmMgGtTpPeE
    Set the display units for report output. All sizes are output in these units: (h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead of 1024. Can also specify custom units e.g. --units 3M

-u|--uuid
    Specify the uuid.

-v|--verbose [-v|--verbose]
    Produce additional output.

COMMANDS

clear
    device_name [--allregions |--regionid id] [--allprograms |--programid id]
    Instructs the kernel to clear statistics counters for the speficied regions (with the exception of in-flight IO counters).

create
    device_name [--areas nr_areas] [--areasize area_size] [--precise] [[--start start_sector] [--length length] |[--segments]] [--auxdata 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 --target are given. The --start and --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. An optional program_id or aux_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 aux_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.

delete
    [ device_name ] [--alldevices] [--allregions |--regionid id] [--allprograms |--programid id]
    Delete the specified statistics region. All counters and resources used by the region are released and the region will not appear in the output of subsequent list, print, or report operations. 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.

help
    [-c|-C|--columns]
    Outputs a summary of the commands available, optionally including the list of report fields.

list
    [device_name] [--allprograms] [--programid [-v|--verbose [-v|--verbose]] id]
    List the statistics regions registered on the device. If the --allprograms switch is given all regions will be listed regardless of region program ID values. If -v or --verbose is given the report will include a row of information for each area contained in each region displayed.

print
    [--clear] [--allregions |--regionid id] [--allprograms |--programid id]
    Print raw statistics counters for the specified region or for all present regions.

report
    [--allprograms] [--interval seconds] [--count count] [--units unit] [--regionid id] [--programid id] [-O|--sort sort_fields] [-S|--select Selection] [--units units]
    Start a report for the specified region or for all present regions. If the count argument is specified, the report will repeat at a fixed interval set by the --interval option. The default interval is one second. If the --allprograms switch is given, all regions will be listed, regardless of region program ID values.

REGIONS AND AREAS
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. 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. 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.

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
A number of metrics fields are included that provide high level performance indicators. These are based on the fields provided by the conventional Linux iostat program and are derived from the basic counter values provided by the kernel for each area.

rrqm
Read requests merged per second.

wrqm
Write requests merged per second.

rs
Read requests per second.

ws
Write requests per second.

rsec
Sectors read per second.

wsec
Sectors written per second.

arqsz
The average size of requests submitted to the area.

qusz
The average queue length.

await
The average wait time for read and write requests.

r_await
The average wait time for read requests.

w_await
The average wait time for write requests.

tput
The device throughput in requests per second.

svctm
The average service time (in milliseconds) for I/O requests that were issued to the device.

util
Percentage of CPU time during which I/O requests were issued to the device (bandwidth utilization for the device). Device saturation occurs when this value is close to 100%.

  Region and area meta fields
Meta fields provide information about the region or area that the statistics values relate to. This includes the region and area identifier, start, length, and counts, as well as the program ID and auxiliary data values.

region_id
Region identifier. This is a non-negative integer returned by the kernel when a statistics region is created.

region_start
The region start sector in units of 512 byte sectors.

region_len
The length of the region in units of 512 byte sectors.

area_id
Area identifier. Area identifiers are assigned by the device-mapper statistics library and uniquely identify each area within a region. Each ID corresponds to a distinct set of performance counters for that area of the statistics region. Area identifiers are always monotonically increasing within a region so that higher ID values correspond to greater sector addresses within the region and no gaps in the sequence of identifiers exist. Sorting a report by device, region start, and area ID (the default) will then produce rows in order of ascending region and area address.

area_start
The area start sector in units of 512 byte sectors.

area_len
The length of the area in units of 512 byte sectors.

area_count
The number of areas in this region.

program_id
The program ID value associated with this region.

aux_data
The auxiliary data value associated with this region.

interval_ns
The estimated interval over which the current counter values have accumulated. The vaulue is reported as an interger expressed in units of nanoseconds.

interval
The estimated interval over which the current counter values have accumulated. The value is reported as a real number in units of seconds.

  Basic counters
Basic counters provide access to the raw counter data from the kernel, allowing further processing to be carried out by another program. 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.

reads
The number of reads successfully completed this interval.

read_merges
The number of read requests merged this interval. This field is incremented every time a pair of requests are merged to create a single request to be issued to the device.

read_sectors
The number of 512 byte sectors read this interval.

read_nsecs
The number of nanoseconds spent reading during this interval.

writes
The number of writes successfully completed this interval.

write_merges
The number of write requests merged this interval. This field is incremented every time a pair of requests are merged to create a single request to be issued to the device.

write_sectors
The number of 512 byte sectors written this interval.

write_nsecs
The number of nanoseconds spent writing during this interval.

in_progress
The number of reads and writes currently in progress.

io_nsecs
The number of nanoseconds spent reading and writing.

weighted_io_nsecs
This field is incremented at each I/O start, I/O completion, I/O merge, or read of these stats by the number of I/Os in progress multiplied by the number of milliseconds spent doing I/O since the last update of this field. This can provide an easy measure of both I/O completion time and the backlog that may be accumulating.

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 reach target contained in device vg00/lvol1
# dmstats create --segments vg00/lvol1
Created new region with 1 area(s) as region ID 0
Created new region with 1 area(s) as region ID 1
Created new region with 1 area(s) as region ID 2
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@redhat.com>

SEE ALSO
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