mirror of
git://sourceware.org/git/lvm2.git
synced 2024-12-21 13:34:40 +03:00
fe6fb1ec52
Put space between size and SI unit. Automatically make this 'space' as fixed size by Makefile sed script.
1245 lines
36 KiB
Plaintext
1245 lines
36 KiB
Plaintext
.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 ]
|
|
..
|
|
.de OPT_FOREGROUND
|
|
. RB [ --foreground ]
|
|
..
|
|
.
|
|
.\" 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
|
|
[OPTIONS]
|
|
.sp
|
|
.
|
|
.PD 0
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_COMMAND
|
|
. ad l
|
|
. nh
|
|
. IR command
|
|
. IR device_name \ |
|
|
. BR --major
|
|
. IR major
|
|
. BR --minor
|
|
. IR minor \ |
|
|
. BR -u | --uuid
|
|
. IR uuid
|
|
. RB [ -v | --verbose ]
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_COMMAND
|
|
.
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_CLEAR
|
|
. ad l
|
|
. nh
|
|
. BR clear
|
|
. IR device_name
|
|
. OPT_PROGRAMS
|
|
. OPT_REGIONS
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_CLEAR
|
|
.
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_CREATE
|
|
. ad l
|
|
. nh
|
|
. BR create
|
|
. IR device_name ...| file_path ...| \fB--alldevices
|
|
. RB [ --areas
|
|
. IR nr_areas | \fB--areasize
|
|
. IR area_size ]
|
|
. RB [ --bounds
|
|
. IR histogram_boundaries ]
|
|
. RB [ --filemap ]
|
|
. RB [ --follow
|
|
. IR follow_mode ]
|
|
. OPT_FOREGROUND
|
|
. RB [ --nomonitor ]
|
|
. RB [ --nogroup ]
|
|
. RB [ --precise ]
|
|
. RB [ --start
|
|
. IR start_sector
|
|
. BR --length
|
|
. IR length | \fB--segments ]
|
|
. RB [ --userdata
|
|
. IR user_data ]
|
|
. RB [ --programid
|
|
. IR id ]
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_CREATE
|
|
.
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_DELETE
|
|
. ad l
|
|
. nh
|
|
. BR delete
|
|
. IR device_name | \fB--alldevices
|
|
. OPT_PROGRAMS
|
|
. OPT_REGIONS
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_DELETE
|
|
.
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_GROUP
|
|
. ad l
|
|
. nh
|
|
. BR group
|
|
. RI [ device_name | \fB--alldevices ]
|
|
. RB [ --alias
|
|
. IR name ]
|
|
. RB [ --regions
|
|
. IR regions ]
|
|
. hy
|
|
. 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
|
|
. nh
|
|
. BR list
|
|
. RI [ device_name ]
|
|
. RB [ --histogram ]
|
|
. OPT_PROGRAMS
|
|
. RB [ --units
|
|
. IR units ]
|
|
. OPT_OBJECTS
|
|
. RB [ --nosuffix ]
|
|
. RB [ --notimesuffix ]
|
|
. RB [ -v | --verbose ]
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_LIST
|
|
.
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_PRINT
|
|
. ad l
|
|
. nh
|
|
. BR print
|
|
. RI [ device_name ]
|
|
. RB [ --clear ]
|
|
. OPT_PROGRAMS
|
|
. OPT_REGIONS
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_PRINT
|
|
.
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_REPORT
|
|
. ad l
|
|
. nh
|
|
. 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 ]
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_REPORT
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_UNGROUP
|
|
. ad l
|
|
. nh
|
|
. BR ungroup
|
|
. RI [ device_name | \fB--alldevices ]
|
|
. RB [ --groupid
|
|
. IR id ]
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_UNGROUP
|
|
.HP
|
|
.B dmstats
|
|
.de CMD_UPDATE_FILEMAP
|
|
. ad l
|
|
. nh
|
|
. BR update_filemap
|
|
. IR file_path
|
|
. RB [ --groupid
|
|
. IR id ]
|
|
. RB [ --follow
|
|
. IR follow_mode ]
|
|
. OPT_FOREGROUND
|
|
. hy
|
|
. ad b
|
|
..
|
|
.CMD_UPDATE_FILEMAP
|
|
.
|
|
.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.
|
|
.P
|
|
The first argument to dmstats is a \fIcommand\fP.
|
|
.P
|
|
The second argument is the \fIdevice name\fP,
|
|
\fIuuid\fP or \fImajor\fP and \fIminor\fP numbers.
|
|
.P
|
|
Further options permit the selection of regions, output format
|
|
control, and reporting behaviour.
|
|
.P
|
|
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
|
|
.
|
|
.TP
|
|
.B --alias \fIname
|
|
Specify an alias name for a group.
|
|
.
|
|
.TP
|
|
.B --alldevices
|
|
If no device arguments are given allow operation on all devices when
|
|
creating or deleting regions.
|
|
.
|
|
.TP
|
|
.B --allprograms
|
|
Include regions from all program IDs for list and report operations.
|
|
.
|
|
.TP
|
|
.B --allregions
|
|
Include all present regions for commands that normally accept a single
|
|
region identifier.
|
|
.
|
|
.TP
|
|
.B --area
|
|
When peforming a list or report, include objects of type area in the
|
|
results.
|
|
.
|
|
.TP
|
|
.B --areas \fInr_areas
|
|
Specify the number of statistics areas to create within a new region.
|
|
.
|
|
.TP
|
|
.B --areasize \fIarea_size\fR[\c
|
|
.UNITS
|
|
Specify the size of areas into which a new region should be divided. An
|
|
optional suffix selects units of:
|
|
.HELP_UNITS
|
|
.
|
|
.TP
|
|
.B --clear
|
|
When printing statistics counters, also atomically reset them to zero.
|
|
.
|
|
.TP
|
|
.B --count \fIcount
|
|
Specify the iteration count for repeating reports. If the count
|
|
argument is zero reports will continue to repeat until interrupted.
|
|
.
|
|
.TP
|
|
.B --group
|
|
When peforming a list or report, include objects of type group in the
|
|
results.
|
|
.
|
|
.TP
|
|
.B --filemap
|
|
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).
|
|
.
|
|
.TP
|
|
.B --nomonitor
|
|
Disable the \fBdmfilemapd\fP daemon when creating new file mapped
|
|
groups. Normally the device-mapper filemap monitoring daemon,
|
|
\fBdmfilemapd\fP, is started for each file mapped group to update the
|
|
set of regions as the file changes on-disk: use of this option
|
|
disables this behaviour.
|
|
.sp
|
|
Regions in the group may still be updated with the
|
|
\fBupdate_filemap\fP command, or by starting the daemon manually.
|
|
.
|
|
.TP
|
|
.B --follow \fIfollow_mode
|
|
Specify the \fBdmfilemapd\fP file following mode. The file map
|
|
monitoring daemon can monitor files in two distinct ways: 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.
|
|
.sp
|
|
The \fBfollow_mode\fP argument is either "inode", for follow-inode
|
|
mode, or "path", for follow-path.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
In follow-path mode, the daemon will exit if the file is removed and
|
|
not replaced within a brief tolerance interval.
|
|
.sp
|
|
In either mode, the daemon exits automatically if the monitored group
|
|
is removed.
|
|
.
|
|
.TP
|
|
.B --foreground
|
|
Specify that the \fBdmfilemapd\fP daemon should run in the foreground.
|
|
The daemon will not fork into the background, and will replace the
|
|
\fBdmstats\fP command that started it.
|
|
.
|
|
.TP
|
|
.B --groupid \fIid
|
|
Specify the group to operate on.
|
|
.
|
|
.TP
|
|
.B --bounds \fIhistogram_boundaries\c
|
|
.RB [ ns | us | ms | s ]
|
|
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 , us , ms ,
|
|
or \fBs\fP may be given after each value to specify units of
|
|
nanoseconds, microseconds, miliseconds or seconds respectively.
|
|
.
|
|
.TP
|
|
.B --histogram
|
|
When used with the \fBreport\fP and \fBlist\fP commands select default
|
|
fields that emphasize latency histogram data.
|
|
.
|
|
.TP
|
|
.B --interval \fIseconds
|
|
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.
|
|
.
|
|
.TP
|
|
.B --length \fIlength\fR[\c
|
|
.UNITS
|
|
Specify the length of a new statistics region in sectors. An optional
|
|
suffix selects units of:
|
|
.HELP_UNITS
|
|
.
|
|
.TP
|
|
.BR -j | --major " " \fImajor
|
|
Specify the major number.
|
|
.
|
|
.TP
|
|
.BR -m | --minor " " \fIminor
|
|
Specify the minor number.
|
|
.
|
|
.TP
|
|
.B --nogroup
|
|
When creating regions mapping the extents of a file in the file
|
|
system, do not create a group or set an alias.
|
|
.
|
|
.TP
|
|
.B --nosuffix
|
|
Suppress the suffix on output sizes. Use with \fB--units\fP
|
|
(except h and H) if processing the output.
|
|
.
|
|
.TP
|
|
.B --notimesuffix
|
|
Suppress the suffix on output time values. Histogram boundary values
|
|
will be reported in units of nanoseconds.
|
|
.
|
|
.TP
|
|
.BR -o | --options
|
|
Specify which report fields to display.
|
|
.
|
|
.TP
|
|
.BR -O | --sort " " \fIsort_fields
|
|
Sort output according to the list of fields given. Precede any
|
|
sort field with '\fB-\fP' for a reverse sort on that column.
|
|
.
|
|
.TP
|
|
.B --precise
|
|
Attempt to use nanosecond precision counters when creating new
|
|
statistics regions.
|
|
.
|
|
.TP
|
|
.B --programid \fIid
|
|
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".
|
|
.
|
|
.TP
|
|
.B --region
|
|
When peforming a list or report, include objects of type region in the
|
|
results.
|
|
.
|
|
.TP
|
|
.B --regionid \fIid
|
|
Specify the region to operate on.
|
|
.
|
|
.TP
|
|
.B --regions \fIregion_list
|
|
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'.
|
|
.
|
|
.TP
|
|
.B --relative
|
|
If displaying the histogram report show relative (percentage) values
|
|
instead of absolute counts.
|
|
.
|
|
.TP
|
|
.BR -S | --select " " \fIselection
|
|
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.
|
|
.
|
|
.TP
|
|
.B --start \fIstart\fR[\c
|
|
.UNITS
|
|
Specify the start offset of a new statistics region in sectors. An
|
|
optional suffix selects units of:
|
|
.HELP_UNITS
|
|
.
|
|
.TP
|
|
.B --segments
|
|
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.
|
|
.sp
|
|
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.
|
|
.
|
|
.TP
|
|
.B --units \c
|
|
.RI [ units ] \c
|
|
.RB [ h | H | \c
|
|
.UNITS
|
|
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.
|
|
.
|
|
.TP
|
|
.B --userdata \fIuser_data
|
|
Specify user data (a word) to be stored with a new region. The value
|
|
is added to any internal auxiliary data (for example, group
|
|
information), and stored with the region in the aux_data field provided
|
|
by the kernel. Whitespace is not permitted.
|
|
.
|
|
.TP
|
|
.BR -u | --uuid
|
|
Specify the uuid.
|
|
.
|
|
.TP
|
|
.BR -v | --verbose \ [ -v | --verbose ]
|
|
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).
|
|
.sp
|
|
The region will span the entire device unless \fB--start\fP and
|
|
\fB--length\fP or \fB--segments\fP are given. The \fB--start\fP an
|
|
\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.
|
|
.sp
|
|
If the \fB--precise\fP option is used the command will attempt to
|
|
create a region using nanosecond precision counters.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
By default dmstats creates regions with a \fBprogram_id\fP of
|
|
"dmstats".
|
|
.sp
|
|
On success the \fBregion_id\fP of the newly created region is printed
|
|
to stdout.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.).
|
|
.sp
|
|
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.
|
|
.sp
|
|
Creating a group that maps a file automatically starts a daemon,
|
|
\fBdmfilemapd\fP to monitor the file and update the mapping as the
|
|
extents allocated to the file change. This behaviour can be disabled
|
|
using the \fB--nomonitor\fP option.
|
|
.sp
|
|
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.
|
|
.sp
|
|
All regions registered on a device may be removed using
|
|
\fB--allregions\fP.
|
|
.sp
|
|
To remove all regions on all devices both \fB--allregions\fP and
|
|
\fB--alldevices\fP must be used.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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'.
|
|
.sp
|
|
Regions that have a histogram configured can be grouped: in this case
|
|
the number of histogram bins and their bounds must match exactly.
|
|
.sp
|
|
On success the group list and newly created \fBgroup_id\fP are
|
|
printed to stdout.
|
|
.sp
|
|
The group metadata is stored with the first (lowest numbered)
|
|
\fBregion_id\fP in the group: deleting this region will also delete
|
|
the group and other group members will be returned to their prior
|
|
state.
|
|
.
|
|
.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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
If the \fB--allprograms\fP switch is given, all regions will be
|
|
listed, regardless of region program ID values.
|
|
.sp
|
|
If the \fB--histogram\fP is given the report will include the histogram
|
|
values and latency boundaries.
|
|
.sp
|
|
If the \fB--relative\fP is used the default histogram field displays
|
|
bin values as a percentage of the total number of I/Os.
|
|
.sp
|
|
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.
|
|
.sp
|
|
The group to be removed is specified using \fB--groupid\fP.
|
|
.
|
|
.HP
|
|
.CMD_UPDATE_FILEMAP
|
|
.br
|
|
Update a group of \fBdmstats\fP regions specified by \fBgroup_id\fP,
|
|
that were previously created with \fB--filemap\fP, either directly,
|
|
or by starting the monitoring daemon, \fBdmfilemapd\fP.
|
|
.sp
|
|
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.
|
|
.sp
|
|
Use of this command is not normally needed since the \fBdmfilemapd\fP
|
|
daemon will automatically monitor filemap groups and perform these
|
|
updates when required.
|
|
.sp
|
|
If a filemapped group was created with \fB--nomonitor\fP, or the
|
|
daemon has been killed, the \fBupdate_filemap\fP can be used to
|
|
manually force an update or start a new daemon.
|
|
.sp
|
|
Use \fB--nomonitor\fP to force a direct update and disable starting
|
|
the monitoring daemon.
|
|
.
|
|
.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.
|
|
.P
|
|
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.
|
|
.P
|
|
The group metadata is stored with the first (lowest numbered)
|
|
\fBregion_id\fP in the group: deleting this region will also delete
|
|
the group and other group members will be returned to their prior
|
|
state.
|
|
.P
|
|
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.
|
|
.P
|
|
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.
|
|
.P
|
|
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.
|
|
.
|
|
.SS 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 \fBprogram_id\fP
|
|
values).
|
|
.P
|
|
Depending on the sequence of create and delete operations, gaps may
|
|
exist in the sequence of \fBregion_id\fP values for a particular device.
|
|
.P
|
|
The \fBregion_id\fP should be treated as an opaque identifier used to
|
|
reference the region.
|
|
.
|
|
.SS Group identifiers
|
|
.
|
|
Groups are also assigned an integer identifier at creation time;
|
|
like region identifiers, group identifiers are unique within the
|
|
containing device.
|
|
.P
|
|
The \fBgroup_id\fP should be treated as an opaque identifier used to
|
|
reference the group.
|
|
.
|
|
.SH FILE MAPPING
|
|
.
|
|
Using \fB--filemap\fP, 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, for example to
|
|
observe large database files, virtual machine images, or other files
|
|
of interest.
|
|
.P
|
|
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 \fBxfs(5)\fP and \fBext4(5)\fP.
|
|
.P
|
|
By default the regions making up a file are placed together in a
|
|
group, and the group alias is set to the \fBbasename(3)\fP 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 \fBlist\fP and \fBreport\fP
|
|
commands, use \fB--group\fP.
|
|
.P
|
|
Since it is possible for the file to change after the initial
|
|
group of regions is created, the \fBupdate_filemap\fP command, and
|
|
\fBdmfilemapd\fP daemon are provided to update file mapped groups
|
|
either manually or automatically.
|
|
.
|
|
.SS File follow modes
|
|
.
|
|
The file map monitoring daemon can monitor files in two distinct ways:
|
|
follow-inode mode, and follow-path mode.
|
|
.P
|
|
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.
|
|
.P
|
|
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.
|
|
.P
|
|
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.
|
|
.P
|
|
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.
|
|
.P
|
|
In follow-path mode, the daemon will exit if the file is removed and
|
|
not replaced within a brief tolerance interval (one second).
|
|
.P
|
|
To stop the daemon, delete the group containing the mapped regions:
|
|
the daemon will automatically shut down.
|
|
.P
|
|
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 \fBupdate_filemap\fP command).
|
|
.P
|
|
See the \fBcreate\fP command and \fB--filemap\fP, \fB--follow\fP,
|
|
and \fB--nomonitor\fP options for further information.
|
|
.
|
|
.SS 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 \fBdd\fP program).
|
|
.P
|
|
There is a further loss of events in that there is currently no way
|
|
to atomically resize a \fBdmstats\fP 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.
|
|
.P
|
|
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.
|
|
.
|
|
.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.
|
|
.P
|
|
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 integer 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_time
|
|
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 10 GiB 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 1 GiB 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)
|
|
.P
|
|
LVM2 resource page:
|
|
.UR https://www.sourceware.org/lvm2
|
|
.UE
|
|
.br
|
|
Device-mapper resource page:
|
|
.UR http://sources.redhat.com/dm
|
|
.UE
|
|
.P
|
|
Device-mapper statistics kernel documentation
|
|
.br
|
|
.I Documentation/device-mapper/statistics.txt
|