mirror of
git://sourceware.org/git/lvm2.git
synced 2024-12-21 13:34:40 +03:00
9164a393de
Correcting some usage of Bold and Italics (files). Adding some missing SEE ALSO. Fixing missed replaceable paths that are configurable. Be careful about .P in .TP sections - need to use .sp for space line. Use .UR/.UE for URL references.
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 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)
|
|
.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
|