.TH DMSTATS 8 "Jul 25 2015" "Linux" "MAINTENANCE COMMANDS" .de OPT_PROGRAMS . RB \%[ \-\-allprograms | \-\-programid . IR id ] .. . .de OPT_REGIONS . RB \%[ \-\-allregions | \-\-regionid . IR id ] .. . .\" Print units suffix, use with arg to print human .\" man2html can't handle too many changes per command .de UNITS . BR b | B | s | S | k | K | m | M | \c . BR g | G | t | T | p | P | e | E ] .. . .\" Print help text for units, use with arg to print human .de HELP_UNITS . RB ( b )ytes, . RB ( s )ectors, . RB ( k )ilobytes, . RB ( m )egabytes, . RB ( g )igabytes, . RB ( t )erabytes, . RB ( p )etabytes, . RB ( e )xabytes. . nop Capitalise to use multiples of 1000 (S.I.) instead of 1024. .. . .SH NAME . dmstats \(em device-mapper statistics management . .SH SYNOPSIS . .B dmsetup .B stats .I command .RB [ options ] .sp . .PD 0 .HP .B dmstats .de CMD_COMMAND . ad l . IR command . RI [ device_name . RB | \-\-uuid . IR uuid | \fB\-\-major . IR major . BR \-\-minor . IR minor ] . ad b .. .CMD_COMMAND . .HP .B dmstats .de CMD_CLEAR . ad l . BR clear . IR device_name . OPT_PROGRAMS . OPT_REGIONS . ad b .. .CMD_CLEAR . .HP .B dmstats .de CMD_CREATE . ad l . BR create . IR device_name . RB [ \-\-alldevices ] . RB [ \-\-areas . IR nr_areas | \fB\-\-areasize . IR area_size ] . RB [ \-\-bounds . IR \%histogram_boundaries ] . RB [ \-\-precise ] . RB [ \-\-start . IR start_sector . BR \-\-length . IR length | \fB\-\-segments ] . RB \%[ \-\-auxdata . IR data ] . RB [ \-\-programid . IR id ] . ad b .. .CMD_CREATE . .HP .B dmstats .de CMD_DELETE . ad l . BR delete . RI [ device_name ] . RB [ \-\-alldevices ] . OPT_PROGRAMS . OPT_REGIONS . ad b .. .CMD_DELETE . .HP .B dmstats .de CMD_HELP . ad l . BR help . RB [ \-c | \-C | \-\-columns ] . ad b .. .CMD_HELP . .HP .B dmstats .de CMD_LIST . ad l . BR list . RI [ device_name ] . RB [ \-\-histogram ] . OPT_PROGRAMS . RB [ \-\-units . IR units ] . RB \%[ \-\-nosuffix ] . RB [ \-\-notimesuffix ] . RB \%[ \-v | \-\-verbose [ \-v | \-\-verbose ]] . ad b .. .CMD_LIST . .HP .B dmstats .de CMD_PRINT . ad l . BR print . RI [ device_name ] . RB [ \-\-clear ] . OPT_PROGRAMS . OPT_REGIONS . ad b .. .CMD_PRINT . .HP .B dmstats .de CMD_REPORT . ad l . BR report . RI [ device_name ] . RB [ \-\-interval . IR seconds ] . RB [ \-\-count . IR count ] . RB [ \-\-units . IR units ] . RB [ \-\-histogram ] . OPT_PROGRAMS . OPT_REGIONS . RB [ \-O | \-\-sort . IR sort_fields ] . RB [ \-S | \-\-select . IR selection ] . RB [ \-\-units . IR units ] . RB [ \-\-nosuffix ] . RB \%[ \-\-notimesuffix ] . ad b .. .CMD_REPORT . .PD .ad b . .SH 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 \fIcommand\fP. The second argument is the \fIdevice name\fP, \fIuuid\fP or \fImajor\fP and \fIminor\fP numbers. Further options permit the selection of regions, output format control, and reporting behaviour. When the program is run using the '\fBdmstats\fP' alias, the command \fBmust\fP be the first argument and any switches and options should be specified following the command itself. This limitation is not present when run as '\fBdmsetup stats\fP'. When no device argument is given dmstats will by default operate on all device-mapper devices present. The \fBcreate\fP and \fBdelete\fP commands require the use of \fB\-\-alldevices\fP when used in this way. . .SH OPTIONS . .HP .BR \-\-alldevices .br If no device arguments are given allow operation on all devices when creating or deleting regions. . .HP .BR \-\-allprograms .br Include regions from all program IDs for list and report operations. .br .HP .BR \-\-allregions .br Include all present regions for commands that normally accept a single region identifier. . .HP .BR \-\-areas .IR nr_areas .br Specify the number of statistics areas to create within a new region. . .HP .BR \-\-areasize .IR area_size \c .RB [ \c .UNITS .br Specify the size of areas into which a new region should be divided. An optional suffix selects units of: .HELP_UNITS . .HP .BR \-\-auxdata .IR aux_data .br Specify auxilliary data (a string) to be stored with a new region. . .HP .BR \-\-clear .br When printing statistics counters, also atomically reset them to zero. . .HP .BR \-\-count .IR count .br Specify the iteration count for repeating reports. If the count argument is zero reports will continue to repeat until interrupted. . .HP .BR \-\-bounds .IR histogram_boundaries \c .RB [ ns | us | ms | s ] .br Specify the boundaries of a latency histogram to be tracked for the region as a comma separated list of latency values. Latency values are given in nanoseconds. An optional unit suffix of .BR ns , .BR us , .BR ms , or \fBs\fP may be given after each value to specify units of nanoseconds, microseconds, miliseconds or seconds respectively. . .HP .BR \-\-histogram .br When used with the \fBreport\fP and \fBlist\fP commands select default fields that emphasize latency histogram data. . .HP .BR \-\-interval .IR seconds .br Specify the interval in seconds between successive iterations for repeating reports. If \fB\-\-interval\fP is specified but \fB\-\-count\fP is not, reports will continue to repeat until interrupted. . .HP .BR \-\-length .IR length \c .RB [ \c .UNITS .br Specify the length of a new statistics region in sectors. An optional suffix selects units of: .HELP_UNITS . .HP .BR \-j | \-\-major .IR major .br Specify the major number. . .HP .BR \-m | \-\-minor .IR minor .br Specify the minor number. . .HP .BR \-\-nosuffix .br Suppress the suffix on output sizes. Use with \fB\-\-units\fP (except h and H) if processing the output. . .HP .BR \-\-notimesuffix .br Suppress the suffix on output time values. Histogram boundary values will be reported in units of nanoseconds. . .HP .BR \-o | \-\-options .br Specify which report fields to display. . .HP .BR \-O | \-\-sort .IR sort_fields .br Sort output according to the list of fields given. Precede any sort field with '\fB-\fP' for a reverse sort on that column. . .HP .BR \-\-precise .br Attempt to use nanosecond precision counters when creating new statistics regions. . .HP .BR \-\-programid .IR id .br 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". . .HP .BR \-\-regionid .IR id .br Specify the region to operate on. . .HP .BR \-\-relative .br If displaying the histogram report show relative (percentage) values instead of absolute counts. . .HP .BR \-S | \-\-select .IR selection .br Display only rows that match \fIselection\fP criteria. All rows with the additional "selected" column (\fB\-o selected\fP) showing 1 if the row matches the \fIselection\fP and 0 otherwise. The selection criteria are defined by specifying column names and their valid values while making use of supported comparison operators. . .HP .BR \-\-start .IR start \c .RB [ \c .UNITS .br Specify the start offset of a new statistics region in sectors. An optional suffix selects units of: .HELP_UNITS . .HP .BR \-\-segments .br 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. . .HP .BR \-\-units .RI [ units ] \c .RB [ h | H | \c .UNITS .br Set the display units for report output. All sizes are output in these units: .RB ( h )uman-readable, .HELP_UNITS Can also specify custom units e.g. \fB\-\-units\ 3M\fP. . .HP .BR \-u | \-\-uuid .br Specify the uuid. . .HP .BR \-v | \-\-verbose " [" \-v | \-\-verbose ] .br Produce additional output. . .SH COMMANDS . .HP .CMD_CLEAR .br Instructs the kernel to clear statistics counters for the speficied regions (with the exception of in-flight IO counters). . .HP .CMD_CREATE .br Creates one or more new statistics regions on the specified device(s). The region will span the entire device unless \fB\-\-start\fP and \fB\-\-length\fP or \fB\-\-target\fP are given. The \fB\-\-start\fP and \fB\-\-length\fP options allow a region of arbitrary length to be placed at an arbitrary offset into the device. The \fB\-\-segments\fP option causes a new region to be created for each target in the corresponding device-mapper device's table. If the \fB\-\-precise\fP option is used the command will attempt to create a region using nanosecond precision counters. If \fB\-\-bounds\fP 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 \fB\-\-precise\fP is not given and values less than one milisecond are used it will be enabled automatically. An optional \fBprogram_id\fP or \fBaux_data\fP string may be associated with the region. A \fBprogram_id\fP may then be used to select regions for subsequent list, print, and report operations. The \fBaux_data\fP stores an arbitrary string and is not used by dmstats or the device-mapper kernel statistics subsystem. By default dmstats creates regions with a \fBprogram_id\fP of "dmstats". On success the \fBregion_id\fP of the newly created region is printed to stdout. . .HP .CMD_DELETE .br 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 \fB\-\-allregions\fP. To remove all regions on all devices both \fB\-\-allregions\fP and \fB\-\-alldevices\fP must be used. . .HP .CMD_HELP .br Outputs a summary of the commands available, optionally including the list of report fields. . .HP .CMD_LIST .br List the statistics regions registered on the device. If the \fB\-\-allprograms\fP switch is given all regions will be listed regardless of region program ID values. If \fB\-v\fP or \fB\-\-verbose\fP is given the report will include a row of information for each area contained in each region displayed. If \fB\-\-histogram\fP is given the report will include the bin count and latency boundary values for any configured histograms. . .HP .CMD_PRINT .br Print raw statistics counters for the specified region or for all present regions. . .HP .CMD_REPORT .br 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 \fB\-\-interval\fP option. The default interval is one second. If the \fB\-\-allprograms\fP switch is given, all regions will be listed, regardless of region program ID values. If the \fB\-\-histogram\fP is given the report will include the histogram values and latency boundaries. If the \fB\-\-relative\fP is used the default histogram field displays bin values as a percentage of the total number of I/Os. . .SH 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 \fB\-\-start\fP and \fB\-\-length\fP 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 \fB\-\-areas\fP or \fB\-\-areasize\fP when creating a region with the \fBcreate\fP command. Depending on the size of the areas and the device region the final area within the region may be smaller than requested. .P .B Region identifiers .P 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 \fBprogram_id\fP values). Depending on the sequence of create and delete operations, gaps may exist in the sequence of \fBregion_id\fP values for a particular device. . .SH 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. . .SS 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. .TP .B reads_merged_per_sec Reads merged per second. .TP .B writes_merged_per_sec Writes merged per second. .TP .B reads_per_sec Reads completed per second. .TP .B writes_per_sec Writes completed per second. .TP .B read_size_per_sec Size of data read per second. .TP .B write_size_per_sec Size of data written per second. .TP .B avg_request_size Average request size. .TP .B queue_size Average queue size. .TP .B await The average wait time for read and write operations. .TP .B r_await The average wait time for read operations. .TP .B w_await The average wait time for write operations. .TP .B throughput The device throughput in operations per second. .TP .B service_time The average service time (in milliseconds) for operations issued to the device. .TP .B 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%. . .SS 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. .TP .B region_id Region identifier. This is a non-negative integer returned by the kernel when a statistics region is created. .TP .B region_start The region start location. Display units are selected by the \fB\-\-units\fP option. .TP .B region_len The length of the region. Display units are selected by the \fB\-\-units\fP option. .TP .B 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 area and no gaps in the sequence of identifiers exist. .TP .B area_start The area start location. Display units are selected by the \fB\-\-units\fP option. .TP .B area_len The length of the area. Display units are selected by the \fB\-\-units\fP option. .TP .B area_count The number of areas in this region. .TP .B program_id The program ID value associated with this region. .TP .B aux_data The auxiliary data value associated with this region. .TP .B interval_ns The estimated interval over which the current counter values have accumulated. The value is reported as an interger expressed in units of nanoseconds. .TP .B interval The estimated interval over which the current counter values have accumulated. The value is reported as a real number in units of seconds. . .SS Basic counters . Basic counters provide access to the raw counter data from the kernel, allowing further processing to be carried out by another program. .P 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. .TP .B read_count Count of reads completed this interval. .TP .B reads_merged_count Count of reads merged this interval. .TP .B read_sector_count Count of 512 byte sectors read this interval. .TP .B read_time Accumulated duration of all read requests (ns). .TP .B write_count Count of writes completed this interval. .TP .B writes_merged_count Count of writes merged this interval. .TP .B write_sector_count Count of 512 byte sectors written this interval. .TP .B write_nsecs Accumulated duration of all write requests (ns). .TP .B in_progress_count Count of requests currently in progress. .TP .B io_ticks Nanoseconds spent servicing requests. .TP .B queue_ticks 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. .TP .B read_ticks Nanoseconds spent servicing reads. .TP .B write_ticks Nanoseconds spent servicing writes. . .SS Histogram fields . Histograms measure the frequency distribution of user specified I/O latency intervals. Histogram bin boundaries are specified when a region is created. .P A brief representation of the histogram values and latency intervals can be included in the report using these fields. .TP .B hist_count A list of the histogram counts for the current statistics area in order of ascending latency value. Each value represents the number of I/Os with latency times falling into that bin's time range during the sample period. .TP .B hist_count_bounds A list of the histogram counts for the current statistics area in order of ascending latency value including bin boundaries: each count is prefixed by the lower bound of the corresponding histogram bin. .TP .B hist_count_ranges A list of the histogram counts for the current statistics area in order of ascending latency value including bin boundaries: each count is prefixed by both the lower and upper bounds of the corresponding histogram bin. .TP .B hist_percent A list of the relative histogram values for the current statistics area in order of ascending latency value, expressed as a percentage. Each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period. .TP .B hist_percent_bounds A list of the relative histogram values for the current statistics area in order of ascending latency value, expressed as a percentage and including bin boundaries. Each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period and is prefixed with the corresponding bin's lower bound. .TP .B hist_percent_ranges A list of the relative histogram values for the current statistics area in order of ascending latency value, expressed as a percentage and including bin boundaries. Each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period and is prefixed with the corresponding bin's lower and upper bounds. .TP .B hist_bounds A list of the histogram boundary values for the current statistics area in order of ascending latency value. The values are expressed in whole units of seconds, miliseconds, microseconds or nanoseconds with a suffix indicating the unit. .TP .B hist_ranges A list of the histogram bin ranges for the current statistics area in order of ascending latency value. The values are expressed as "LOWER-UPPER" in whole units of seconds, miliseconds, microseconds or nanoseconds with a suffix indicating the unit. .TP .B hist_bins The number of latency histogram bins configured for the area. . .SH EXAMPLES . Create a whole-device region with one area on vg00/lvol1 .br # .B dmstats create vg00/lvol1 .br vg00/lvol1: Created new region with 1 area(s) as region ID 0 .P Create a 32M region 1G into device d0 .br # .B dmstats create \-\-start 1G \-\-length 32M d0 .br d0: Created new region with 1 area(s) as region ID 0 .P Create a whole-device region with 8 areas on every device .br .br # .B dmstats create \-\-areas 8 .br vg00-lvol1: Created new region with 8 area(s) as region ID 0 .br vg00-lvol2: Created new region with 8 area(s) as region ID 0 .br vg00-lvol3: Created new region with 8 area(s) as region ID 0 .br vg01-lvol0: Created new region with 8 area(s) as region ID 2 .br vg01-lvol1: Created new region with 8 area(s) as region ID 0 .br vg00-lvol2: Created new region with 8 area(s) as region ID 1 .P Delete all regions on all devices .br .br # .B dmstats delete \-\-alldevices \-\-allregions .P Create a whole-device region with areas 10GiB in size on vg00/lvol1 using dmsetup .br .br # .B dmsetup stats create \-\-areasize 10G vg00/lvol1 .br vg00-lvol1: Created new region with 5 area(s) as region ID 1 .P Create a 1GiB region with 16 areas at the start of vg00/lvol1 .br # .B dmstats create \-\-start 0 \-\-len 1G \-\-areas=16 vg00/lvol1 .br vg00-lvol1: Created new region with 16 area(s) as region ID 0 .P List the statistics regions registered on vg00/lvol1 .br # .B dmstats list vg00/lvol1 .br Name RgID RStart RSize #Areas ASize ProgID .br vg00-lvol1 0 0 61.00g 1 61.00g dmstats .br vg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats .br vg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats .P Display five statistics reports for vg00/lvol1 at an interval of one second .br .br # .B dmstats report \-\-interval 1 \-\-count 5 vg00/lvol1 .br # .B dmstats report .br Name RgID ArID AStart ASize RRqM/s WRqM/s R/s W/s RSz/s WSz/s AvRqSz QSize Util% AWait RdAWa WrAWa .br 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 .br 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 .br 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 .P Create one region for reach target contained in device vg00/lvol1 .br .br # .B dmstats create \-\-segments vg00/lvol1 .br vg00-lvol1: Created new region with 1 area(s) as region ID 0 .br vg00-lvol1: Created new region with 1 area(s) as region ID 1 .br vg00-lvol1: Created new region with 1 area(s) as region ID 2 .P Print raw counters for region 4 on device d0 .br # .B dmstats print \-\-regionid 4 d0 .br 2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41 . .SH AUTHORS . Bryn M. Reeves . .SH SEE ALSO . .BR dmsetup (8) LVM2 resource page: https://www.sourceware.org/lvm2/ .br Device-mapper resource page: http://sources.redhat.com/dm/ .br Device-mapper statistics kernel documentation .br .I Documentation/device-mapper/statistics.txt