1928 lines
43 KiB
HTML
1928 lines
43 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of DMSTATS</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>DMSTATS</H1>
|
|
Section: MAINTENANCE COMMANDS (8)<BR>Updated: Jun 23 2016<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
dmstats --- device-mapper statistics management
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>dmsetup</B>
|
|
|
|
<B>stats</B>
|
|
|
|
<I>command</I>
|
|
|
|
[OPTIONS]
|
|
<P>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<I>command</I>
|
|
|
|
<I>device_name</I> |
|
|
|
|
<B>--major</B>
|
|
|
|
<I>major</I>
|
|
|
|
<B>--minor</B>
|
|
|
|
<I>minor</I> |
|
|
|
|
<B>-u</B>|<B>--uuid</B>
|
|
|
|
<I>uuid</I>
|
|
|
|
[<B>-v</B>|<B>--verbose]</B>
|
|
|
|
|
|
|
|
<DT id="2">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>clear</B>
|
|
|
|
<I>device_name</I>
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
|
|
<DT id="3">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>create</B>
|
|
|
|
<I>device_name...</I>|<I>file_path...</I>|<I></I><B>--alldevices</B>
|
|
|
|
[<B>--areas</B>
|
|
|
|
<I>nr_areas</I>|<I></I><B>--areasize</B>
|
|
|
|
<I>area_size</I>]
|
|
|
|
[<B>--bounds</B>
|
|
|
|
<I>histogram_boundaries</I>]
|
|
|
|
[<B>--filemap</B>]
|
|
|
|
[<B>--follow</B>
|
|
|
|
<I>follow_mode</I>]
|
|
|
|
|
|
[<B>--foreground</B>]
|
|
|
|
|
|
[<B>--nomonitor</B>]
|
|
|
|
[<B>--nogroup</B>]
|
|
|
|
[<B>--precise</B>]
|
|
|
|
[<B>--start</B>
|
|
|
|
<I>start_sector</I>
|
|
|
|
<B>--length</B>
|
|
|
|
<I>length</I>|<I></I><B>--segments</B>]
|
|
|
|
[<B>--userdata</B>
|
|
|
|
<I>user_data</I>]
|
|
|
|
[<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
<DT id="4">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>delete</B>
|
|
|
|
<I>device_name</I>|<I></I><B>--alldevices</B>
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
|
|
<DT id="5">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>group</B>
|
|
|
|
[<I>device_name</I>|<I></I><B>--alldevices</B>]
|
|
|
|
[<B>--alias</B>
|
|
|
|
<I>name</I>]
|
|
|
|
[<B>--regions</B>
|
|
|
|
<I>regions</I>]
|
|
|
|
|
|
|
|
<DT id="6">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>help</B>
|
|
|
|
[<B>-c</B>|<B>-C</B>|<B>--columns</B>]
|
|
|
|
|
|
|
|
<DT id="7">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>list</B>
|
|
|
|
[<I>device_name</I>]
|
|
|
|
[<B>--histogram</B>]
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
[<B>--units</B>
|
|
|
|
<I>units</I>]
|
|
|
|
|
|
[<B>--area</B>]
|
|
|
|
[<B>--region</B>]
|
|
|
|
[<B>--group</B>]
|
|
|
|
|
|
[<B>--nosuffix</B>]
|
|
|
|
[<B>--notimesuffix</B>]
|
|
|
|
[<B>-v</B>|<B>--verbose]</B>
|
|
|
|
|
|
|
|
<DT id="8">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>print</B>
|
|
|
|
[<I>device_name</I>]
|
|
|
|
[<B>--clear</B>]
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
|
|
<DT id="9">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>report</B>
|
|
|
|
[<I>device_name</I>]
|
|
|
|
[<B>--interval</B>
|
|
|
|
<I>seconds</I>]
|
|
|
|
[<B>--count</B>
|
|
|
|
<I>count</I>]
|
|
|
|
[<B>--units</B>
|
|
|
|
<I>units</I>]
|
|
|
|
[<B>--histogram</B>]
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--area</B>]
|
|
|
|
[<B>--region</B>]
|
|
|
|
[<B>--group</B>]
|
|
|
|
|
|
[<B>-O</B>|<B>--sort</B>
|
|
|
|
<I>sort_fields</I>]
|
|
|
|
[<B>-S</B>|<B>--select</B>
|
|
|
|
<I>selection</I>]
|
|
|
|
[<B>--units</B>
|
|
|
|
<I>units</I>]
|
|
|
|
[<B>--nosuffix</B>]
|
|
|
|
[<B>--notimesuffix</B>]
|
|
|
|
|
|
|
|
<DT id="10">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>ungroup</B>
|
|
|
|
[<I>device_name</I>|<I></I><B>--alldevices</B>]
|
|
|
|
[<B>--groupid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
<DT id="11">
|
|
<B>dmstats</B>
|
|
|
|
|
|
|
|
|
|
<B>update_filemap</B>
|
|
|
|
<I>file_path</I>
|
|
|
|
[<B>--groupid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
[<B>--follow</B>
|
|
|
|
<I>follow_mode</I>]
|
|
|
|
|
|
[<B>--foreground</B>]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<DD>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 <I>command</I>.
|
|
<P>
|
|
The second argument is the <I>device name</I>,
|
|
<I>uuid</I> or <I>major</I> and <I>minor</I> 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 <B>create</B> and <B>delete</B>
|
|
commands require the use of <B>--alldevices</B> when used in this way.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="12">
|
|
<B>--alias</B>
|
|
|
|
<I>name</I>
|
|
|
|
<DD>
|
|
<DD>Specify an alias name for a group.
|
|
<DT id="13">
|
|
<B>--alldevices</B>
|
|
|
|
<DD>
|
|
<DD>If no device arguments are given allow operation on all devices when
|
|
creating or deleting regions.
|
|
<DT id="14">
|
|
<B>--allprograms</B>
|
|
|
|
<DD>
|
|
<DD>Include regions from all program IDs for list and report operations.
|
|
<BR>
|
|
|
|
<DT id="15">
|
|
<B>--allregions</B>
|
|
|
|
<DD>
|
|
<DD>Include all present regions for commands that normally accept a single
|
|
region identifier.
|
|
<DT id="16">
|
|
<B>--area</B>
|
|
|
|
<DD>
|
|
<DD>When peforming a list or report, include objects of type area in the
|
|
results.
|
|
<DT id="17">
|
|
<B>--areas</B>
|
|
|
|
<I>nr_areas</I>
|
|
|
|
<DD>
|
|
<DD>Specify the number of statistics areas to create within a new region.
|
|
<DT id="18">
|
|
<B>--areasize</B>
|
|
|
|
<I>area_size</I>[<B></B>
|
|
<B>b</B>|<B>B</B>|<B>s</B>|<B>S</B>|<B>k</B>|<B>K</B>|<B>m</B>|<B>M</B>|<B></B><B>g</B>|<B>G</B>|<B>t</B>|<B>T</B>|<B>p</B>|<B>P</B>|<B>e</B>|<B>E</B>]
|
|
|
|
|
|
<DD>
|
|
<DD>Specify the size of areas into which a new region should be divided. An
|
|
optional suffix selects units of:
|
|
|
|
(<B>b</B>)ytes,
|
|
|
|
(<B>s</B>)ectors,
|
|
|
|
(<B>k</B>)ilobytes,
|
|
|
|
(<B>m</B>)egabytes,
|
|
|
|
(<B>g</B>)igabytes,
|
|
|
|
(<B>t</B>)erabytes,
|
|
|
|
(<B>p</B>)etabytes,
|
|
|
|
(<B>e</B>)xabytes.
|
|
|
|
|
|
|
|
<DT id="19">
|
|
<B>--clear</B>
|
|
|
|
<DD>
|
|
<DD>When printing statistics counters, also atomically reset them to zero.
|
|
<DT id="20">
|
|
<B>--count</B>
|
|
|
|
<I>count</I>
|
|
|
|
<DD>
|
|
<DD>Specify the iteration count for repeating reports. If the count
|
|
argument is zero reports will continue to repeat until interrupted.
|
|
<DT id="21">
|
|
<B>--group</B>
|
|
|
|
<DD>
|
|
<DD>When peforming a list or report, include objects of type group in the
|
|
results.
|
|
<DT id="22">
|
|
<B>--filemap</B>
|
|
|
|
<DD>
|
|
<DD>Instead of creating regions on a device as specified by command line
|
|
options, open the file found at each <B>file_path</B> argument, and
|
|
create regions corresponding to the locations of the on-disk extents
|
|
allocated to the file(s).
|
|
<DT id="23">
|
|
<B>--nomonitor</B>
|
|
|
|
<DD>
|
|
<DD>Disable the <B>dmfilemapd</B> daemon when creating new file mapped
|
|
groups. Normally the device-mapper filemap monitoring daemon,
|
|
<B>dmfilemapd</B>, 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.
|
|
<P>
|
|
Regions in the group may still be updated with the
|
|
<B>update_filemap</B> command, or by starting the daemon manually.
|
|
<DT id="24">
|
|
<B>--follow</B>
|
|
|
|
<I>follow_mode</I>
|
|
|
|
<DD>
|
|
<DD>Specify the <B>dmfilemapd</B> 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.
|
|
<P>
|
|
The <B>follow_mode</B> argument is either "inode", for follow-inode
|
|
mode, or "path", for follow-path.
|
|
<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.
|
|
<P>
|
|
In either mode, the daemon exits automatically if the monitored group
|
|
is removed.
|
|
<DT id="25">
|
|
<B>--foreground</B>
|
|
|
|
<DD>
|
|
<DD>Specify that the <B>dmfilemapd</B> daemon should run in the foreground.
|
|
The daemon will not fork into the background, and will replace the
|
|
<B>dmstats</B> command that started it.
|
|
<DT id="26">
|
|
<B>--groupid</B>
|
|
|
|
<I>id</I>
|
|
|
|
<DD>
|
|
<DD>Specify the group to operate on.
|
|
<DT id="27">
|
|
<B>--bounds</B>
|
|
|
|
<I>histogram_boundaries</I>[<B>ns</B>|<B>us</B>|<B>ms</B>|<B>s</B>]
|
|
|
|
<DD>
|
|
<DD>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
|
|
<B>ns</B>,
|
|
|
|
<B>us</B>,
|
|
|
|
<B>ms</B>,
|
|
|
|
or <B>s</B> may be given after each value to specify units of
|
|
nanoseconds, microseconds, miliseconds or seconds respectively.
|
|
<DT id="28">
|
|
<B>--histogram</B>
|
|
|
|
<DD>
|
|
<DD>When used with the <B>report</B> and <B>list</B> commands select default
|
|
fields that emphasize latency histogram data.
|
|
<DT id="29">
|
|
<B>--interval</B>
|
|
|
|
<I>seconds</I>
|
|
|
|
<DD>
|
|
<DD>Specify the interval in seconds between successive iterations for
|
|
repeating reports. If <B>--interval</B> is specified but
|
|
<B>--count</B> is not,
|
|
reports will continue to repeat until interrupted.
|
|
<DT id="30">
|
|
<B>--length</B>
|
|
|
|
<I>length</I>[<B></B>
|
|
<B>b</B>|<B>B</B>|<B>s</B>|<B>S</B>|<B>k</B>|<B>K</B>|<B>m</B>|<B>M</B>|<B></B><B>g</B>|<B>G</B>|<B>t</B>|<B>T</B>|<B>p</B>|<B>P</B>|<B>e</B>|<B>E</B>]
|
|
|
|
|
|
<DD>
|
|
<DD>Specify the length of a new statistics region in sectors. An optional
|
|
suffix selects units of:
|
|
|
|
(<B>b</B>)ytes,
|
|
|
|
(<B>s</B>)ectors,
|
|
|
|
(<B>k</B>)ilobytes,
|
|
|
|
(<B>m</B>)egabytes,
|
|
|
|
(<B>g</B>)igabytes,
|
|
|
|
(<B>t</B>)erabytes,
|
|
|
|
(<B>p</B>)etabytes,
|
|
|
|
(<B>e</B>)xabytes.
|
|
|
|
|
|
|
|
<DT id="31">
|
|
<B>-j</B>|<B>--major</B>
|
|
|
|
<I>major</I>
|
|
|
|
<DD>
|
|
<DD>Specify the major number.
|
|
<DT id="32">
|
|
<B>-m</B>|<B>--minor</B>
|
|
|
|
<I>minor</I>
|
|
|
|
<DD>
|
|
<DD>Specify the minor number.
|
|
<DT id="33">
|
|
<B>--nogroup</B>
|
|
|
|
<DD>
|
|
<DD>When creating regions mapping the extents of a file in the file
|
|
system, do not create a group or set an alias.
|
|
<DT id="34">
|
|
<B>--nosuffix</B>
|
|
|
|
<DD>
|
|
<DD>Suppress the suffix on output sizes. Use with <B>--units</B>
|
|
(except h and H) if processing the output.
|
|
<DT id="35">
|
|
<B>--notimesuffix</B>
|
|
|
|
<DD>
|
|
<DD>Suppress the suffix on output time values. Histogram boundary values
|
|
will be reported in units of nanoseconds.
|
|
<DT id="36">
|
|
<B>-o</B>|<B>--options</B>
|
|
|
|
<DD>
|
|
<DD>Specify which report fields to display.
|
|
<DT id="37">
|
|
<B>-O</B>|<B>--sort</B>
|
|
|
|
<I>sort_fields</I>
|
|
|
|
<DD>
|
|
<DD>Sort output according to the list of fields given. Precede any
|
|
sort field with '<B>-</B>' for a reverse sort on that column.
|
|
<DT id="38">
|
|
<B>--precise</B>
|
|
|
|
<DD>
|
|
<DD>Attempt to use nanosecond precision counters when creating new
|
|
statistics regions.
|
|
<DT id="39">
|
|
<B>--programid</B>
|
|
|
|
<I>id</I>
|
|
|
|
<DD>
|
|
<DD>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".
|
|
<DT id="40">
|
|
<B>--region</B>
|
|
|
|
<DD>
|
|
<DD>When peforming a list or report, include objects of type region in the
|
|
results.
|
|
<DT id="41">
|
|
<B>--regionid</B>
|
|
|
|
<I>id</I>
|
|
|
|
<DD>
|
|
<DD>Specify the region to operate on.
|
|
<DT id="42">
|
|
<B>--regions</B>
|
|
|
|
<I>region_list</I>
|
|
|
|
<DD>
|
|
<DD>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'.
|
|
<DT id="43">
|
|
<B>--relative</B>
|
|
|
|
<DD>
|
|
<DD>If displaying the histogram report show relative (percentage) values
|
|
instead of absolute counts.
|
|
<DT id="44">
|
|
<B>-S</B>|<B>--select</B>
|
|
|
|
<I>selection</I>
|
|
|
|
<DD>
|
|
<DD>Display only rows that match <I>selection</I> criteria. All rows with the
|
|
additional "selected" column (<B>-o selected</B>) showing 1 if the row matches
|
|
the <I>selection</I> and 0 otherwise. The selection criteria are defined by
|
|
specifying column names and their valid values while making use of
|
|
supported comparison operators.
|
|
<DT id="45">
|
|
<B>--start</B>
|
|
|
|
<I>start</I>[<B></B>
|
|
<B>b</B>|<B>B</B>|<B>s</B>|<B>S</B>|<B>k</B>|<B>K</B>|<B>m</B>|<B>M</B>|<B></B><B>g</B>|<B>G</B>|<B>t</B>|<B>T</B>|<B>p</B>|<B>P</B>|<B>e</B>|<B>E</B>]
|
|
|
|
|
|
<DD>
|
|
<DD>Specify the start offset of a new statistics region in sectors. An
|
|
optional suffix selects units of:
|
|
|
|
(<B>b</B>)ytes,
|
|
|
|
(<B>s</B>)ectors,
|
|
|
|
(<B>k</B>)ilobytes,
|
|
|
|
(<B>m</B>)egabytes,
|
|
|
|
(<B>g</B>)igabytes,
|
|
|
|
(<B>t</B>)erabytes,
|
|
|
|
(<B>p</B>)etabytes,
|
|
|
|
(<B>e</B>)xabytes.
|
|
|
|
|
|
|
|
<DT id="46">
|
|
<B>--segments</B>
|
|
|
|
<DD>
|
|
<DD>When used with <B>create</B>, 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.
|
|
<P>
|
|
The newly created regions are automatically placed into a group unless
|
|
the <B>--nogroup</B> option is given. When grouping is enabled a group
|
|
alias may be specified using the <B>--alias</B> option.
|
|
<DT id="47">
|
|
<B>--units</B>
|
|
|
|
[<I>units</I>]<I></I>[<B>h</B>|<B>H</B>|<B></B>
|
|
<B>b</B>|<B>B</B>|<B>s</B>|<B>S</B>|<B>k</B>|<B>K</B>|<B>m</B>|<B>M</B>|<B></B><B>g</B>|<B>G</B>|<B>t</B>|<B>T</B>|<B>p</B>|<B>P</B>|<B>e</B>|<B>E</B>]
|
|
|
|
|
|
<DD>
|
|
<DD>Set the display units for report output.
|
|
All sizes are output in these units:
|
|
(<B>h</B>)uman-readable,
|
|
|
|
|
|
(<B>b</B>)ytes,
|
|
|
|
(<B>s</B>)ectors,
|
|
|
|
(<B>k</B>)ilobytes,
|
|
|
|
(<B>m</B>)egabytes,
|
|
|
|
(<B>g</B>)igabytes,
|
|
|
|
(<B>t</B>)erabytes,
|
|
|
|
(<B>p</B>)etabytes,
|
|
|
|
(<B>e</B>)xabytes.
|
|
|
|
|
|
|
|
Can also specify custom units e.g. <B>--units 3M</B>.
|
|
<DT id="48">
|
|
<B>--userdata</B>
|
|
|
|
<I>user_data</I>
|
|
|
|
<DD>
|
|
<DD>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.
|
|
<DT id="49">
|
|
<B>-u</B>|<B>--uuid</B>
|
|
|
|
<DD>
|
|
<DD>Specify the uuid.
|
|
<DT id="50">
|
|
<B>-v</B>|<B>--verbose</B> [<B>-v</B>|<B>--verbose</B>]
|
|
|
|
<DD>
|
|
<DD>Produce additional output.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>COMMANDS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="51">
|
|
|
|
|
|
<B>clear</B>
|
|
|
|
<I>device_name</I>
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Instructs the kernel to clear statistics counters for the speficied
|
|
regions (with the exception of in-flight IO counters).
|
|
<DT id="52">
|
|
|
|
|
|
<B>create</B>
|
|
|
|
<I>device_name...</I>|<I>file_path...</I>|<I></I><B>--alldevices</B>
|
|
|
|
[<B>--areas</B>
|
|
|
|
<I>nr_areas</I>|<I></I><B>--areasize</B>
|
|
|
|
<I>area_size</I>]
|
|
|
|
[<B>--bounds</B>
|
|
|
|
<I>histogram_boundaries</I>]
|
|
|
|
[<B>--filemap</B>]
|
|
|
|
[<B>--follow</B>
|
|
|
|
<I>follow_mode</I>]
|
|
|
|
|
|
[<B>--foreground</B>]
|
|
|
|
|
|
[<B>--nomonitor</B>]
|
|
|
|
[<B>--nogroup</B>]
|
|
|
|
[<B>--precise</B>]
|
|
|
|
[<B>--start</B>
|
|
|
|
<I>start_sector</I>
|
|
|
|
<B>--length</B>
|
|
|
|
<I>length</I>|<I></I><B>--segments</B>]
|
|
|
|
[<B>--userdata</B>
|
|
|
|
<I>user_data</I>]
|
|
|
|
[<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Creates one or more new statistics regions on the specified device(s).
|
|
<P>
|
|
The region will span the entire device unless <B>--start</B> and
|
|
<B>--length</B> or <B>--segments</B> are given. The <B>--start</B> an
|
|
<B>--length</B> options allow a region of arbitrary length to be placed
|
|
at an arbitrary offset into the device. The <B>--segments</B> option
|
|
causes a new region to be created for each target in the corresponding
|
|
device-mapper device's table.
|
|
<P>
|
|
If the <B>--precise</B> option is used the command will attempt to
|
|
create a region using nanosecond precision counters.
|
|
<P>
|
|
If <B>--bounds</B> 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.
|
|
<P>
|
|
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
|
|
<B>--precise</B> is not given and values less than one milisecond are
|
|
used it will be enabled automatically.
|
|
<P>
|
|
An optional <B>program_id</B> or <B>user_data</B> string may be associated
|
|
with the region. A <B>program_id</B> may then be used to select regions
|
|
for subsequent list, print, and report operations. The <B>user_data</B>
|
|
stores an arbitrary string and is not used by dmstats or the
|
|
device-mapper kernel statistics subsystem.
|
|
<P>
|
|
By default dmstats creates regions with a <B>program_id</B> of
|
|
"dmstats".
|
|
<P>
|
|
On success the <B>region_id</B> of the newly created region is printed
|
|
to stdout.
|
|
<P>
|
|
If the <B>--filemap</B> option is given with a regular file, or list
|
|
of files, as the <B>file_path</B> argument, instead of creating regions
|
|
with parameters specified on the command line, <B>dmstats</B> will open
|
|
the files located at <B>file_path</B> 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.
|
|
<P>
|
|
To work with the <B>--filemap</B> 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.).
|
|
<P>
|
|
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 <B>--alias</B> and <B>--nogroup</B> options.
|
|
<P>
|
|
Creating a group that maps a file automatically starts a daemon,
|
|
<B>dmfilemapd</B> to monitor the file and update the mapping as the
|
|
extents allocated to the file change. This behaviour can be disabled
|
|
using the <B>--nomonitor</B> option.
|
|
<P>
|
|
Use the <B>--group</B> option to only display information for groups
|
|
when listing and reporting.
|
|
<DT id="53">
|
|
|
|
|
|
<B>delete</B>
|
|
|
|
<I>device_name</I>|<I></I><B>--alldevices</B>
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>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.
|
|
<P>
|
|
All regions registered on a device may be removed using
|
|
<B>--allregions</B>.
|
|
<P>
|
|
To remove all regions on all devices both <B>--allregions</B> and
|
|
<B>--alldevices</B> must be used.
|
|
<P>
|
|
If a <B>--groupid</B> is given instead of a <B>--regionid</B> the
|
|
command will attempt to delete the group and all regions that it
|
|
contains.
|
|
<P>
|
|
If a deleted region is the first member of a group of regions the group
|
|
will also be removed.
|
|
<DT id="54">
|
|
|
|
|
|
<B>group</B>
|
|
|
|
[<I>device_name</I>|<I></I><B>--alldevices</B>]
|
|
|
|
[<B>--alias</B>
|
|
|
|
<I>name</I>]
|
|
|
|
[<B>--regions</B>
|
|
|
|
<I>regions</I>]
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Combine one or more statistics regions on the specified device into a
|
|
group.
|
|
<P>
|
|
The list of regions to be grouped is specified with <B>--regions</B>
|
|
and an optional alias may be assigned with <B>--alias</B>. The set of
|
|
regions is given as a comma-separated list of region identifiers. A
|
|
continuous range of identifers spanning from <B>R1</B> to <B>R2</B> may
|
|
be expressed as '<B>R1</B>-<B>R2</B>'.
|
|
<P>
|
|
Regions that have a histogram configured can be grouped: in this case
|
|
the number of histogram bins and their bounds must match exactly.
|
|
<P>
|
|
On success the group list and newly created <B>group_id</B> are
|
|
printed to stdout.
|
|
<P>
|
|
The group metadata is stored with the first (lowest numbered)
|
|
<B>region_id</B> in the group: deleting this region will also delete
|
|
the group and other group members will be returned to their prior
|
|
state.
|
|
<DT id="55">
|
|
|
|
|
|
<B>help</B>
|
|
|
|
[<B>-c</B>|<B>-C</B>|<B>--columns</B>]
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Outputs a summary of the commands available, optionally including
|
|
the list of report fields.
|
|
<DT id="56">
|
|
|
|
|
|
<B>list</B>
|
|
|
|
[<I>device_name</I>]
|
|
|
|
[<B>--histogram</B>]
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
[<B>--units</B>
|
|
|
|
<I>units</I>]
|
|
|
|
|
|
[<B>--area</B>]
|
|
|
|
[<B>--region</B>]
|
|
|
|
[<B>--group</B>]
|
|
|
|
|
|
[<B>--nosuffix</B>]
|
|
|
|
[<B>--notimesuffix</B>]
|
|
|
|
[<B>-v</B>|<B>--verbose]</B>
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>List the statistics regions, areas, or groups registered on the device.
|
|
If the <B>--allprograms</B> switch is given all regions will be listed
|
|
regardless of region program ID values.
|
|
<P>
|
|
By default only regions and groups are included in list output. If
|
|
<B>-v</B> or <B>--verbose</B> is given the report will also include a
|
|
row of information for each configured group and for each area contained
|
|
in each region displayed.
|
|
<P>
|
|
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 <B>--region</B>). To also view the areas contained within regions
|
|
use <B>--area</B>.
|
|
<P>
|
|
If <B>--histogram</B> is given the report will include the bin count
|
|
and latency boundary values for any configured histograms.
|
|
<DT id="57">
|
|
|
|
|
|
<B>print</B>
|
|
|
|
[<I>device_name</I>]
|
|
|
|
[<B>--clear</B>]
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Print raw statistics counters for the specified region or for all
|
|
present regions.
|
|
<DT id="58">
|
|
|
|
|
|
<B>report</B>
|
|
|
|
[<I>device_name</I>]
|
|
|
|
[<B>--interval</B>
|
|
|
|
<I>seconds</I>]
|
|
|
|
[<B>--count</B>
|
|
|
|
<I>count</I>]
|
|
|
|
[<B>--units</B>
|
|
|
|
<I>units</I>]
|
|
|
|
[<B>--histogram</B>]
|
|
|
|
|
|
[<B>--allprograms</B>|<B>--programid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--allregions</B>|<B>--regionid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
[<B>--area</B>]
|
|
|
|
[<B>--region</B>]
|
|
|
|
[<B>--group</B>]
|
|
|
|
|
|
[<B>-O</B>|<B>--sort</B>
|
|
|
|
<I>sort_fields</I>]
|
|
|
|
[<B>-S</B>|<B>--select</B>
|
|
|
|
<I>selection</I>]
|
|
|
|
[<B>--units</B>
|
|
|
|
<I>units</I>]
|
|
|
|
[<B>--nosuffix</B>]
|
|
|
|
[<B>--notimesuffix</B>]
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>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 <B>--interval</B> option. The default interval is
|
|
one second.
|
|
<P>
|
|
If the <B>--allprograms</B> switch is given, all regions will be
|
|
listed, regardless of region program ID values.
|
|
<P>
|
|
If the <B>--histogram</B> is given the report will include the histogram
|
|
values and latency boundaries.
|
|
<P>
|
|
If the <B>--relative</B> is used the default histogram field displays
|
|
bin values as a percentage of the total number of I/Os.
|
|
<P>
|
|
Object types (areas, regions and groups) to include in the report are
|
|
selected using the <B>--area</B>, <B>--region</B>, and <B>--group</B>
|
|
options.
|
|
<DT id="59">
|
|
|
|
|
|
<B>ungroup</B>
|
|
|
|
[<I>device_name</I>|<I></I><B>--alldevices</B>]
|
|
|
|
[<B>--groupid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Remove an existing group and return all the group's regions to their
|
|
original state.
|
|
<P>
|
|
The group to be removed is specified using <B>--groupid</B>.
|
|
<DT id="60">
|
|
|
|
|
|
<B>update_filemap</B>
|
|
|
|
<I>file_path</I>
|
|
|
|
[<B>--groupid</B>
|
|
|
|
<I>id</I>]
|
|
|
|
[<B>--follow</B>
|
|
|
|
<I>follow_mode</I>]
|
|
|
|
|
|
[<B>--foreground</B>]
|
|
|
|
|
|
|
|
|
|
<DD>
|
|
<DD>Update a group of <B>dmstats</B> regions specified by <B>group_id</B>,
|
|
that were previously created with <B>--filemap</B>, either directly,
|
|
or by starting the monitoring daemon, <B>dmfilemapd</B>.
|
|
<P>
|
|
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.
|
|
<P>
|
|
Use of this command is not normally needed since the <B>dmfilemapd</B>
|
|
daemon will automatically monitor filemap groups and perform these
|
|
updates when required.
|
|
<P>
|
|
If a filemapped group was created with <B>--nomonitor</B>, or the
|
|
daemon has been killed, the <B>update_filemap</B> can be used to
|
|
manually force an update or start a new daemon.
|
|
<P>
|
|
Use <B>--nomonitor</B> to force a direct update and disable starting
|
|
the monitoring daemon.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>REGIONS, AREAS, AND GROUPS</H2>
|
|
|
|
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)
|
|
<B>region_id</B> 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 <B>--start</B> and
|
|
<B>--length</B> 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
|
|
<B>--areas</B> or <B>--areasize</B> when creating a region with the
|
|
<B>create</B> 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</B>
|
|
|
|
<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 <B>program_id</B>
|
|
values).
|
|
<P>
|
|
Depending on the sequence of create and delete operations, gaps may
|
|
exist in the sequence of <B>region_id</B> values for a particular device.
|
|
<P>
|
|
The <B>region_id</B> should be treated as an opaque identifier used to
|
|
reference the region.
|
|
<P>
|
|
|
|
<B>Group identifiers</B>
|
|
|
|
<P>
|
|
|
|
Groups are also assigned an integer identifier at creation time;
|
|
like region identifiers, group identifiers are unique within the
|
|
containing device.
|
|
<P>
|
|
The <B>group_id</B> should be treated as an opaque identifier used to
|
|
reference the group.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>FILE MAPPING</H2>
|
|
|
|
Using <B>--filemap</B>, 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 <B><A HREF="/cgi-bin/man/man2html?5+xfs">xfs</A>(5)</B> and <B><A HREF="/cgi-bin/man/man2html?5+ext4">ext4</A>(5)</B>.
|
|
<P>
|
|
By default the regions making up a file are placed together in a
|
|
group, and the group alias is set to the <B><A HREF="/cgi-bin/man/man2html?3+basename">basename</A>(3)</B> 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 <B>list</B> and <B>report</B>
|
|
commands, use <B>--group</B>.
|
|
<P>
|
|
Since it is possible for the file to change after the initial
|
|
group of regions is created, the <B>update_filemap</B> command, and
|
|
<B>dmfilemapd</B> daemon are provided to update file mapped groups
|
|
either manually or automatically.
|
|
<P>
|
|
|
|
<B>File follow modes</B>
|
|
|
|
<P>
|
|
|
|
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 <B>update_filemap</B> command).
|
|
<P>
|
|
See the <B>create</B> command and <B>--filemap</B>, <B>--follow</B>,
|
|
and <B>--nomonitor</B> options for further information.
|
|
<P>
|
|
|
|
<B>Limitations</B>
|
|
|
|
<P>
|
|
|
|
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 <B>dd</B> program).
|
|
<P>
|
|
There is a further loss of events in that there is currently no way
|
|
to atomically resize a <B>dmstats</B> 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.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>REPORT FIELDS</H2>
|
|
|
|
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.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Derived metrics</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="61"><B>reads_merged_per_sec</B>
|
|
|
|
<DD>
|
|
Reads merged per second.
|
|
<DT id="62"><B>writes_merged_per_sec</B>
|
|
|
|
<DD>
|
|
Writes merged per second.
|
|
<DT id="63"><B>reads_per_sec</B>
|
|
|
|
<DD>
|
|
Reads completed per second.
|
|
<DT id="64"><B>writes_per_sec</B>
|
|
|
|
<DD>
|
|
Writes completed per second.
|
|
<DT id="65"><B>read_size_per_sec</B>
|
|
|
|
<DD>
|
|
Size of data read per second.
|
|
<DT id="66"><B>write_size_per_sec</B>
|
|
|
|
<DD>
|
|
Size of data written per second.
|
|
<DT id="67"><B>avg_request_size</B>
|
|
|
|
<DD>
|
|
Average request size.
|
|
<DT id="68"><B>queue_size</B>
|
|
|
|
<DD>
|
|
Average queue size.
|
|
<DT id="69"><B>await</B>
|
|
|
|
<DD>
|
|
The average wait time for read and write operations.
|
|
<DT id="70"><B>r_await</B>
|
|
|
|
<DD>
|
|
The average wait time for read operations.
|
|
<DT id="71"><B>w_await</B>
|
|
|
|
<DD>
|
|
The average wait time for write operations.
|
|
<DT id="72"><B>throughput</B>
|
|
|
|
<DD>
|
|
The device throughput in operations per second.
|
|
<DT id="73"><B>service_time</B>
|
|
|
|
<DD>
|
|
The average service time (in milliseconds) for operations issued
|
|
to the device.
|
|
<DT id="74"><B>util</B>
|
|
|
|
<DD>
|
|
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%.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Group, region and area meta fields</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="75"><B>region_id</B>
|
|
|
|
<DD>
|
|
Region identifier. This is a non-negative integer returned by the kernel
|
|
when a statistics region is created.
|
|
<DT id="76"><B>region_start</B>
|
|
|
|
<DD>
|
|
The region start location. Display units are selected by the
|
|
<B>--units</B> option.
|
|
<DT id="77"><B>region_len</B>
|
|
|
|
<DD>
|
|
The length of the region. Display units are selected by the
|
|
<B>--units</B> option.
|
|
<DT id="78"><B>area_id</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="79"><B>area_start</B>
|
|
|
|
<DD>
|
|
The area start location. Display units are selected by the
|
|
<B>--units</B> option.
|
|
<DT id="80"><B>area_len</B>
|
|
|
|
<DD>
|
|
The length of the area. Display units are selected by the
|
|
<B>--units</B> option.
|
|
<DT id="81"><B>area_count</B>
|
|
|
|
<DD>
|
|
The number of areas in this region.
|
|
<DT id="82"><B>program_id</B>
|
|
|
|
<DD>
|
|
The program ID value associated with this region.
|
|
<DT id="83"><B>user_data</B>
|
|
|
|
<DD>
|
|
The user data value associated with this region.
|
|
<DT id="84"><B>group_id</B>
|
|
|
|
<DD>
|
|
Group identifier. This is a non-negative integer returned by the dmstats
|
|
<B>group</B> command when a statistics group is created.
|
|
<DT id="85"><B>interval_ns</B>
|
|
|
|
<DD>
|
|
The estimated interval over which the current counter values have
|
|
accumulated. The value is reported as an interger expressed in units
|
|
of nanoseconds.
|
|
<DT id="86"><B>interval</B>
|
|
|
|
<DD>
|
|
The estimated interval over which the current counter values have
|
|
accumulated. The value is reported as a real number in units of
|
|
seconds.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Basic counters</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="87"><B>read_count</B>
|
|
|
|
<DD>
|
|
Count of reads completed this interval.
|
|
<DT id="88"><B>reads_merged_count</B>
|
|
|
|
<DD>
|
|
Count of reads merged this interval.
|
|
<DT id="89"><B>read_sector_count</B>
|
|
|
|
<DD>
|
|
Count of 512 byte sectors read this interval.
|
|
<DT id="90"><B>read_time</B>
|
|
|
|
<DD>
|
|
Accumulated duration of all read requests (ns).
|
|
<DT id="91"><B>write_count</B>
|
|
|
|
<DD>
|
|
Count of writes completed this interval.
|
|
<DT id="92"><B>writes_merged_count</B>
|
|
|
|
<DD>
|
|
Count of writes merged this interval.
|
|
<DT id="93"><B>write_sector_count</B>
|
|
|
|
<DD>
|
|
Count of 512 byte sectors written this interval.
|
|
<DT id="94"><B>write_time</B>
|
|
|
|
<DD>
|
|
Accumulated duration of all write requests (ns).
|
|
<DT id="95"><B>in_progress_count</B>
|
|
|
|
<DD>
|
|
Count of requests currently in progress.
|
|
<DT id="96"><B>io_ticks</B>
|
|
|
|
<DD>
|
|
Nanoseconds spent servicing requests.
|
|
<DT id="97"><B>queue_ticks</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="98"><B>read_ticks</B>
|
|
|
|
<DD>
|
|
Nanoseconds spent servicing reads.
|
|
<DT id="99"><B>write_ticks</B>
|
|
|
|
<DD>
|
|
Nanoseconds spent servicing writes.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Histogram fields</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="100"><B>hist_count</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="101"><B>hist_count_bounds</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="102"><B>hist_count_ranges</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="103"><B>hist_percent</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="104"><B>hist_percent_bounds</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="105"><B>hist_percent_ranges</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="106"><B>hist_bounds</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="107"><B>hist_ranges</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="108"><B>hist_bins</B>
|
|
|
|
<DD>
|
|
The number of latency histogram bins configured for the area.
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
Create a whole-device region with one area on vg00/lvol1
|
|
<BR>
|
|
|
|
#
|
|
<B>dmstats create vg00/lvol1</B>
|
|
|
|
<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</B>
|
|
|
|
<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</B>
|
|
|
|
<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</B>
|
|
|
|
<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</B>
|
|
|
|
<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</B>
|
|
|
|
<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</B>
|
|
|
|
<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</B>
|
|
|
|
<BR>
|
|
|
|
#
|
|
<B>dmstats report</B>
|
|
|
|
<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</B>
|
|
|
|
<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/*</B>
|
|
|
|
<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</B>
|
|
|
|
<BR>
|
|
|
|
2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41
|
|
<A NAME="lbAO"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Bryn M. Reeves <<A HREF="mailto:bmr@redhat.com">bmr@redhat.com</A>>
|
|
<A NAME="lbAP"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+dmsetup">dmsetup</A></B>(8)
|
|
|
|
<P>
|
|
LVM2 resource page: <A HREF="https://www.sourceware.org/lvm2/">https://www.sourceware.org/lvm2/</A>
|
|
<BR>
|
|
|
|
Device-mapper resource page: <A HREF="http://sources.redhat.com/dm/">http://sources.redhat.com/dm/</A>
|
|
<BR>
|
|
|
|
<P>
|
|
Device-mapper statistics kernel documentation
|
|
<BR>
|
|
|
|
<I>Documentation/device-mapper/statistics.txt</I>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="109"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="110"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="111"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="112"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="113"><A HREF="#lbAF">COMMANDS</A><DD>
|
|
<DT id="114"><A HREF="#lbAG">REGIONS, AREAS, AND GROUPS</A><DD>
|
|
<DT id="115"><A HREF="#lbAH">FILE MAPPING</A><DD>
|
|
<DT id="116"><A HREF="#lbAI">REPORT FIELDS</A><DD>
|
|
<DL>
|
|
<DT id="117"><A HREF="#lbAJ">Derived metrics</A><DD>
|
|
<DT id="118"><A HREF="#lbAK">Group, region and area meta fields</A><DD>
|
|
<DT id="119"><A HREF="#lbAL">Basic counters</A><DD>
|
|
<DT id="120"><A HREF="#lbAM">Histogram fields</A><DD>
|
|
</DL>
|
|
<DT id="121"><A HREF="#lbAN">EXAMPLES</A><DD>
|
|
<DT id="122"><A HREF="#lbAO">AUTHORS</A><DD>
|
|
<DT id="123"><A HREF="#lbAP">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:11 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|