| .TH DMSTATS 8 "Jun 23 2016" "Linux" "MAINTENANCE COMMANDS" |
| |
| .de OPT_PROGRAMS |
| . RB \%[ \-\-allprograms | \-\-programid |
| . IR id ] |
| .. |
| . |
| .de OPT_REGIONS |
| . RB \%[ \-\-allregions | \-\-regionid |
| . IR id ] |
| .. |
| .de OPT_OBJECTS |
| . RB [ \-\-area ] |
| . RB [ \-\-region ] |
| . RB [ \-\-group ] |
| .. |
| . |
| .\" 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 |
| . RB [ device_name... |
| . RB | file_path... ] |
| . RB [ \-\-alldevices ] |
| . RB [ \-\-areas |
| . IR nr_areas | \fB\-\-areasize |
| . IR area_size ] |
| . RB [ \-\-bounds |
| . IR \%histogram_boundaries ] |
| . RB [ \-\-filemap ] |
| . RB [ \-\-nogroup ] |
| . RB [ \-\-precise ] |
| . RB [ \-\-start |
| . IR start_sector |
| . BR \-\-length |
| . IR length | \fB\-\-segments ] |
| . RB \%[ \-\-userdata |
| . IR user_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_GROUP |
| . ad l |
| . BR group |
| . RI [ device_name ] |
| . RB [ \-\-alias |
| . IR name ] |
| . RB [ \-\-alldevices ] |
| . RB [ \-\-regions |
| . IR regions ] |
| . ad b |
| .. |
| .CMD_GROUP |
| .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 ] |
| . OPT_OBJECTS |
| . 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 |
| . OPT_OBJECTS |
| . RB [ \-O | \-\-sort |
| . IR sort_fields ] |
| . RB [ \-S | \-\-select |
| . IR selection ] |
| . RB [ \-\-units |
| . IR units ] |
| . RB [ \-\-nosuffix ] |
| . RB \%[ \-\-notimesuffix ] |
| . ad b |
| .. |
| .CMD_REPORT |
| .HP |
| .B dmstats |
| .de CMD_UNGROUP |
| . ad l |
| . BR ungroup |
| . RI [ device_name ] |
| . RB [ \-\-alldevices ] |
| . RB [ \-\-groupid |
| . IR id ] |
| . ad b |
| .. |
| .CMD_UNGROUP |
| . |
| .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 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 \-\-alias |
| .IR name |
| .br |
| Specify an alias name for a group. |
| . |
| .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 \-\-area |
| .br |
| When peforming a list or report, include objects of type area in the |
| results. |
| . |
| .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 \-\-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 \-\-group |
| .br |
| When peforming a list or report, include objects of type group in the |
| results. |
| . |
| .HP |
| .BR \-\-filemap |
| .br |
| Instead of creating regions on a device as specified by command line |
| options, open the file found at each \fBfile_path\fP argument, and |
| create regions corresponding to the locations of the on-disk extents |
| allocated to the file(s). |
| . |
| .HP |
| .BR \-\-groupid |
| .IR id |
| .br |
| Specify the group to operate on. |
| . |
| .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 \-\-nogroup |
| .br |
| When creating regions mapping the extents of a file in the file |
| system, do not create a group or set an alias. |
| . |
| .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 \-\-region |
| .br |
| When peforming a list or report, include objects of type region in the |
| results. |
| . |
| .HP |
| .BR \-\-regionid |
| .IR id |
| .br |
| Specify the region to operate on. |
| . |
| .HP |
| .BR \-\-regions |
| .IR region_list |
| .br |
| Specify a list of regions to group. The group list is a comma-separated |
| list of region identifiers. Continuous sequences of identifiers may be |
| expressed as a hyphen separated range, for example: '1-10'. |
| . |
| .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 |
| When used with \fBcreate\fP, create a new statistics region for each |
| target contained in the given device(s). This causes a separate region |
| to be allocated for each segment of the device. |
| |
| The newly created regions are automatically placed into a group unless |
| the \fB\-\-nogroup\fP option is given. When grouping is enabled a group |
| alias may be specified using the \fB\-\-alias\fP option. |
| . |
| .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 \-\-userdata |
| .IR user_data |
| .br |
| Specify user data (a word) to be stored with a new region. The value |
| is added to any internal auxilliary data (for example, group |
| information), and stored with the region in the aux_data field provided |
| by the kernel. Whitespace is not permitted. |
| . |
| .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 \fBuser_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 \fBuser_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. |
| |
| If the \fB\-\-filemap\fP option is given with a regular file, or list |
| of files, as the \fBfile_path\fP argument, instead of creating regions |
| with parameters specified on the command line, \fBdmstats\fP will open |
| the files located at \fBfile_path\fP 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 \fB\-\-filemap\fP 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 \fB\-\-alias\fP and \fB\-\-nogroup\fP options. |
| |
| Use the \fB\-\-group\fP option to only display information for groups |
| when listing and reporting. |
| . |
| .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. |
| |
| If a \fB\-\-groupid\fP is given instead of a \fB\-\-regionid\fP 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. |
| . |
| .HP |
| .CMD_GROUP |
| .br |
| Combine one or more statistics regions on the specified device into a |
| group. |
| |
| The list of regions to be grouped is specified with \fB\-\-regions\fP |
| and an optional alias may be assigned with \fB\-\-alias\fP. The set of |
| regions is given as a comma-separated list of region identifiers. A |
| continuous range of identifers spanning from \fBR1\fP to \fBR2\fP may |
| be expressed as '\fBR1\fP-\fBR2\fP'. |
| |
| 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 \fBgroup_id\fP are |
| printed to stdout. |
| . |
| .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, areas, or groups registered on the device. |
| If the \fB\-\-allprograms\fP switch is given all regions will be listed |
| regardless of region program ID values. |
| |
| By default only regions and groups are included in list output. If |
| \fB\-v\fP or \fB\-\-verbose\fP 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 \fB\-\-region\fP). To also view the areas contained within regions |
| use \fB\-\-area\fP. |
| |
| 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 object or for all present objects. 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. |
| |
| Object types (areas, regions and groups) to include in the report are |
| selected using the \fB\-\-area\fP, \fB\-\-region\fP, and \fB\-\-group\fP |
| options. |
| . |
| .HP |
| .CMD_UNGROUP |
| .br |
| Remove an existing group and return all the group's regions to their |
| original state. |
| |
| The group to be removed is specified using \fB\-\-groupid\fP. |
| . |
| .SH 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 this case a summary value for the |
| entire region is also available for use in reports. |
| |
| In addition, one or more regions on one device can be combined into |
| a statistics group allowing reporting of aggregate values for all |
| regions and areas making up the group. |
| |
| 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. |
| |
| 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 |
| \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. |
| |
| The \fBregion_id\fP should be treated as an opaque identifier used to |
| reference the region. |
| . |
| .P |
| .B Group identifiers |
| .P |
| Groups are also assigned an integer identifier at creation time; |
| like region identifiers, group identifiers are unique within the |
| containing device. |
| |
| The \fBgroup_id\fP should be treated as an opaque identifier used to |
| reference the group. |
| . |
| .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 Group, region and area meta fields |
| . |
| Meta fields provide information about the groups, regions, or areas that |
| the statistics values relate to. This includes the region and area |
| identifier, start, length, and counts, as well as the program ID and |
| user 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 user_data |
| The user data value associated with this region. |
| .TP |
| .B group_id |
| Group identifier. This is a non-negative integer returned by the dmstats |
| \fBgroup\fP command when a statistics group is created. |
| .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 |
| Create regions mapping each file in the directory images/ and place |
| them into separate groups, each named after the corresponding file |
| .br |
| # |
| .B dmstats create --filemap images/* |
| .br |
| images/vm1.qcow2: Created new group with 87 region(s) as group ID 0. |
| .br |
| images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87. |
| .br |
| images/vm2.qcow2: Created new group with 11 region(s) as group ID 95. |
| .br |
| images/vm2-1.qcow2: Created new group with 1454 region(s) as group ID 106. |
| .br |
| images/vm3.img: Created new group with 2 region(s) as group ID 1560. |
| .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 <bmr@redhat.com> |
| . |
| .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 |