|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | REGIONS, AREAS, AND GROUPS | FILE MAPPING | REPORT FIELDS | EXAMPLES | AUTHORS | SEE ALSO | COLOPHON |
|
|
|
DMSTATS(8) MAINTENANCE COMMANDS DMSTATS(8)
dmstats — device-mapper statistics management
dmsetup stats command [OPTIONS]
dmstats command device_name | --major major --minor minor |
-u|--uuid uuid [-v|--verbose]
dmstats clear device_name [--allprograms|--programid id]
[--allregions|--regionid id]
dmstats create device_name...|file_path...|--alldevices [--areas
nr_areas|--areasize area_size] [--bounds
histogram_boundaries] [--filemap] [--follow follow_mode]
[--foreground] [--nomonitor] [--nogroup] [--precise]
[--start start_sector --length length|--segments]
[--userdata user_data] [--programid id]
dmstats delete device_name|--alldevices [--allprograms|--programid
id] [--allregions|--regionid id]
dmstats group [device_name|--alldevices] [--alias name] [--regions
regions]
dmstats help [-c|-C|--columns]
dmstats list [device_name] [--histogram]
[--allprograms|--programid id] [--units units] [--area]
[--region] [--group] [--nosuffix] [--notimesuffix]
[-v|--verbose]
dmstats print [device_name] [--clear] [--allprograms|--programid
id] [--allregions|--regionid id]
dmstats report [device_name] [--interval seconds] [--count count]
[--units units] [--histogram] [--allprograms|--programid
id] [--allregions|--regionid id] [--area] [--region]
[--group] [-O|--sort sort_fields] [-S|--select selection]
[--units units] [--nosuffix] [--notimesuffix]
dmstats ungroup [device_name|--alldevices] [--groupid id]
dmstats update_filemap file_path [--groupid id] [--follow
follow_mode] [--foreground]
The dmstats program manages IO statistics regions for devices that
use the device-mapper driver. Statistics regions may be created,
deleted, listed and reported on using the tool.
The first argument to dmstats is a command.
The second argument is the device name, uuid or major and minor
numbers.
Further options permit the selection of regions, output format
control, and reporting behaviour.
When no device argument is given dmstats will by default operate
on all device-mapper devices present. The create and delete com‐
mands require the use of --alldevices when used in this way.
--alias name
Specify an alias name for a group.
--alldevices
If no device arguments are given allow operation on all de‐
vices when creating or deleting regions.
--allprograms
Include regions from all program IDs for list and report
operations.
--allregions
Include all present regions for commands that normally ac‐
cept a single region identifier.
--area When peforming a list or report, include objects of type
area in the results.
--areas nr_areas
Specify the number of statistics areas to create within a
new region.
--areasize area_size[
b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] Specify the size of areas
into which a new region should be divided. An optional suf‐
fix selects units of: (b)ytes, (s)ectors, (k)ilobytes,
(m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
(e)xabytes. Capitalise to use multiples of 1000 (S.I.) in‐
stead of 1024.
--clear
When printing statistics counters, also atomically reset
them to zero.
--count count
Specify the iteration count for repeating reports. If the
count argument is zero reports will continue to repeat un‐
til interrupted.
--group
When peforming a list or report, include objects of type
group in the results.
--filemap
Instead of creating regions on a device as specified by
command line options, open the file found at each file_path
argument, and create regions corresponding to the locations
of the on-disk extents allocated to the file(s).
--nomonitor
Disable the dmfilemapd daemon when creating new file mapped
groups. Normally the device-mapper filemap monitoring dae‐
mon, dmfilemapd, 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.
Regions in the group may still be updated with the up‐
date_filemap command, or by starting the daemon manually.
--follow follow_mode
Specify the dmfilemapd 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.
The follow_mode argument is either "inode", for follow-in‐
ode mode, or "path", for follow-path.
If follow-inode mode is used, the daemon will hold the file
open, and continue to update regions from the same file de‐
scriptor. 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.
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.
If follow-path is used, the daemon will re-open the provid‐
ed 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 re‐
name.
In follow-path mode, the daemon will exit if the file is
removed and not replaced within a brief tolerance interval.
In either mode, the daemon exits automatically if the moni‐
tored group is removed.
--foreground
Specify that the dmfilemapd daemon should run in the fore‐
ground. The daemon will not fork into the background, and
will replace the dmstats command that started it.
--groupid id
Specify the group to operate on.
--bounds histogram_boundaries
[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 ns,us,ms, or s may be given after
each value to specify units of nanoseconds, microseconds,
miliseconds or seconds respectively.
--histogram
When used with the report and list commands select default
fields that emphasize latency histogram data.
--interval seconds
Specify the interval in seconds between successive itera‐
tions for repeating reports. If --interval is specified but
--count is not, reports will continue to repeat until in‐
terrupted.
--length length[
b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] Specify the length of a
new statistics region in sectors. An optional suffix se‐
lects units of: (b)ytes, (s)ectors, (k)ilobytes,
(m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
(e)xabytes. Capitalise to use multiples of 1000 (S.I.) in‐
stead of 1024.
-j|--major major
Specify the major number.
-m|--minor minor
Specify the minor number.
--nogroup
When creating regions mapping the extents of a file in the
file system, do not create a group or set an alias.
--nosuffix
Suppress the suffix on output sizes. Use with --units (ex‐
cept h and H) if processing the output.
--notimesuffix
Suppress the suffix on output time values. Histogram bound‐
ary values will be reported in units of nanoseconds.
-o|--options
Specify which report fields to display.
-O|--sort sort_fields
Sort output according to the list of fields given. Precede
any sort field with '-' for a reverse sort on that column.
--precise
Attempt to use nanosecond precision counters when creating
new statistics regions.
--programid id
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".
--region
When peforming a list or report, include objects of type
region in the results.
--regionid id
Specify the region to operate on.
--regions region_list
Specify a list of regions to group. The group list is a
comma-separated list of region identifiers. Continuous se‐
quences of identifiers may be expressed as a hyphen sepa‐
rated range, for example: '1-10'.
--relative
If displaying the histogram report show relative (percent‐
age) values instead of absolute counts.
-S|--select selection
Display only rows that match selection criteria. All rows
with the additional "selected" column (-o selected) showing
1 if the row matches the selection and 0 otherwise. The se‐
lection criteria are defined by specifying column names and
their valid values while making use of supported comparison
operators.
--start start[
b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] Specify the start offset
of a new statistics region in sectors. An optional suffix
selects units of: (b)ytes, (s)ectors, (k)ilobytes,
(m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
(e)xabytes. Capitalise to use multiples of 1000 (S.I.) in‐
stead of 1024.
--segments
When used with create, 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 de‐
vice.
The newly created regions are automatically placed into a
group unless the --nogroup option is given. When grouping
is enabled a group alias may be specified using the --alias
option.
--units
[units][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] Set the dis‐
play units for report output. All sizes are output in
these units: (h)uman-readable, (b)ytes, (s)ectors,
(k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes,
(p)etabytes, (e)xabytes. Capitalise to use multiples of
1000 (S.I.) instead of 1024. Can also specify custom units
e.g. --units 3M.
--userdata user_data
Specify user data (a word) to be stored with a new region.
The value is added to any internal auxiliary data (for ex‐
ample, group information), and stored with the region in
the aux_data field provided by the kernel. Whitespace is
not permitted.
-u|--uuid
Specify the uuid.
-v|--verbose [-v|--verbose]
Produce additional output.
clear device_name [--allprograms|--programid id]
[--allregions|--regionid id]
Instructs the kernel to clear statistics counters for the
speficied regions (with the exception of in-flight IO coun‐
ters).
create device_name...|file_path...|--alldevices [--areas
nr_areas|--areasize area_size] [--bounds
histogram_boundaries] [--filemap] [--follow follow_mode]
[--foreground] [--nomonitor] [--nogroup] [--precise]
[--start start_sector --length length|--segments]
[--userdata user_data] [--programid id]
Creates one or more new statistics regions on the specified
device(s).
The region will span the entire device unless --start and
--length or --segments are given. The --start an --length
options allow a region of arbitrary length to be placed at
an arbitrary offset into the device. The --segments option
causes a new region to be created for each target in the
corresponding device-mapper device's table.
If the --precise option is used the command will attempt to
create a region using nanosecond precision counters.
If --bounds is given a latency histogram will be tracked
for the new region. The boundaries of the histogram bins
are given as a comma separated list of latency values.
There is an implicit lower bound of zero on the first bin
and an implicit upper bound of infinity (or the configured
interval duration) on the final bin.
Latencies are given in nanoseconds. An optional unit suffix
of ns, us, ms, or s may be given after each value to speci‐
fy units of nanoseconds, microseconds, miliseconds or sec‐
onds 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 en‐
abled: if --precise is not given and values less than one
milisecond are used it will be enabled automatically.
An optional program_id or user_data string may be associat‐
ed with the region. A program_id may then be used to select
regions for subsequent list, print, and report operations.
The user_data stores an arbitrary string and is not used by
dmstats or the device-mapper kernel statistics subsystem.
By default dmstats creates regions with a program_id of
"dmstats".
On success the region_id of the newly created region is
printed to stdout.
If the --filemap option is given with a regular file, or
list of files, as the file_path argument, instead of creat‐
ing regions with parameters specified on the command line,
dmstats will open the files located at file_path and create
regions corresponding to the physical extents allocated to
the file. This can be used to monitor statistics for indi‐
vidual files in the file system, for example, virtual ma‐
chine images, swap areas, or large database files.
To work with the --filemap option, files must be located on
a local file system, backed by a device-mapper device, that
supports physical extent data using the FIEMAP ioctl (Ext4
and XFS for e.g.).
By default regions that map a file are placed into a group
and the group alias is set to the basename of the file.
This behaviour can be overridden with the --alias and
--nogroup options.
Creating a group that maps a file automatically starts a
daemon, dmfilemapd to monitor the file and update the map‐
ping as the extents allocated to the file change. This be‐
haviour can be disabled using the --nomonitor option.
Use the --group option to only display information for
groups when listing and reporting.
delete device_name|--alldevices [--allprograms|--programid id]
[--allregions|--regionid id]
Delete the specified statistics region. All counters and
resources used by the region are released and the region
will not appear in the output of subsequent list, print, or
report operations.
All regions registered on a device may be removed using
--allregions.
To remove all regions on all devices both --allregions and
--alldevices must be used.
If a --groupid is given instead of a --regionid the command
will attempt to delete the group and all regions that it
contains.
If a deleted region is the first member of a group of re‐
gions the group will also be removed.
group [device_name|--alldevices] [--alias name] [--regions
regions]
Combine one or more statistics regions on the specified de‐
vice into a group.
The list of regions to be grouped is specified with --re‐
gions and an optional alias may be assigned with --alias.
The set of regions is given as a comma-separated list of
region identifiers. A continuous range of identifers span‐
ning from R1 to R2 may be expressed as 'R1-R2'.
Regions that have a histogram configured can be grouped: in
this case the number of histogram bins and their bounds
must match exactly.
On success the group list and newly created group_id are
printed to stdout.
The group metadata is stored with the first (lowest num‐
bered) region_id in the group: deleting this region will
also delete the group and other group members will be re‐
turned to their prior state.
help [-c|-C|--columns]
Outputs a summary of the commands available, optionally in‐
cluding the list of report fields.
list [device_name] [--histogram] [--allprograms|--programid id]
[--units units] [--area] [--region] [--group] [--nosuffix]
[--notimesuffix] [-v|--verbose]
List the statistics regions, areas, or groups registered on
the device. If the --allprograms switch is given all re‐
gions will be listed regardless of region program ID val‐
ues.
By default only regions and groups are included in list
output. If -v or --verbose is given the report will also
include a row of information for each configured group and
for each area contained in each region displayed.
Regions that contain a single area are by default omitted
from the verbose list since their properties are identical
to the area that they contain - to view all regions regard‐
less of the number of areas present use --region). To also
view the areas contained within regions use --area.
If --histogram is given the report will include the bin
count and latency boundary values for any configured his‐
tograms.
print [device_name] [--clear] [--allprograms|--programid id]
[--allregions|--regionid id]
Print raw statistics counters for the specified region or
for all present regions.
report [device_name] [--interval seconds] [--count count] [--units
units] [--histogram] [--allprograms|--programid id]
[--allregions|--regionid id] [--area] [--region] [--group]
[-O|--sort sort_fields] [-S|--select selection] [--units
units] [--nosuffix] [--notimesuffix]
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 --interval op‐
tion. The default interval is one second.
If the --allprograms switch is given, all regions will be
listed, regardless of region program ID values.
If the --histogram is given the report will include the
histogram values and latency boundaries.
If the --relative is used the default histogram field dis‐
plays bin values as a percentage of the total number of
I/Os.
Object types (areas, regions and groups) to include in the
report are selected using the --area, --region, and --group
options.
ungroup [device_name|--alldevices] [--groupid id]
Remove an existing group and return all the group's regions
to their original state.
The group to be removed is specified using --groupid.
update_filemap file_path [--groupid id] [--follow follow_mode]
[--foreground]
Update a group of dmstats regions specified by group_id,
that were previously created with --filemap, either direct‐
ly, or by starting the monitoring daemon, dmfilemapd.
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.
Use of this command is not normally needed since the dm‐
filemapd daemon will automatically monitor filemap groups
and perform these updates when required.
If a filemapped group was created with --nomonitor, or the
daemon has been killed, the update_filemap can be used to
manually force an update or start a new daemon.
Use --nomonitor to force a direct update and disable start‐
ing the monitoring daemon.
The device-mapper statistics facility allows separate performance
counters to be maintained for arbitrary regions of devices. A re‐
gion may span any range: from a single sector to the whole device.
A region may be further sub-divided into a number of distinct ar‐
eas (one or more), each with its own counter set. In this case a
summary value for the entire region is also available for use in
reports.
In addition, one or more regions on one device can be combined in‐
to a statistics group. Groups allow several regions to be aggre‐
gated and reported as a single entity; counters for all regions
and areas are summed and used to report totals for all group mem‐
bers. Groups also permit the assignment of an optional alias, al‐
lowing meaningful names to be associated with sets of regions.
The group metadata is stored with the first (lowest numbered) re‐
gion_id in the group: deleting this region will also delete the
group and other group members will be returned to their prior
state.
By default new regions span the entire device. The --start and
--length options allows a region of any size to be placed at any
location on the device.
Using offsets it is possible to create regions that map individual
objects within a block device (for example: partitions, files in a
file system, or stripes or other structures in a RAID volume).
Groups allow several non-contiguous regions to be assembled to‐
gether for reporting and data aggregation.
A region may be either divided into the specified number of equal-
sized areas, or into areas of the given size by specifying one of
--areas or --areasize when creating a region with the create com‐
mand. Depending on the size of the areas and the device region the
final area within the region may be smaller than requested.
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 program_id values).
Depending on the sequence of create and delete operations, gaps
may exist in the sequence of region_id values for a particular de‐
vice.
The region_id should be treated as an opaque identifier used to
reference the region.
Group identifiers
Groups are also assigned an integer identifier at creation time;
like region identifiers, group identifiers are unique within the
containing device.
The group_id should be treated as an opaque identifier used to
reference the group.
Using --filemap, it is possible to create regions that correspond
to the extents of a file in the file system. This allows IO sta‐
tistics to be monitored on a per-file basis, for example to ob‐
serve large database files, virtual machine images, or other files
of interest.
To be able to use file mapping, the file must be backed by a de‐
vice-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 xfs(5) and ext4(5).
By default the regions making up a file are placed together in a
group, and the group alias is set to the basename(3) of the file.
This allows statistics to be reported for the file as a whole, ag‐
gregating values for the regions making up the group. To see only
the whole file (group) when using the list and report commands,
use --group.
Since it is possible for the file to change after the initial
group of regions is created, the update_filemap command, and dm‐
filemapd daemon are provided to update file mapped groups either
manually or automatically.
File follow modes
The file map monitoring daemon can monitor files in two distinct
ways: follow-inode mode, and follow-path mode.
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.
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 be‐
ing monitored.
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 refer‐
ence to it.
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.
In follow-path mode, the daemon will exit if the file is removed
and not replaced within a brief tolerance interval (one second).
To stop the daemon, delete the group containing the mapped re‐
gions: the daemon will automatically shut down.
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 manu‐
ally with the update_filemap command).
See the create command and --filemap, --follow, and --nomonitor
options for further information.
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 count‐
ed when a file is growing, particularly if the file is being ex‐
tended by a single thread writing beyond end-of-file (for example,
the dd program).
There is a further loss of events in that there is currently no
way to atomically resize a dmstats 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.
File mapping is currently most effective in cases where the major‐
ity of IO does not trigger extent allocation. Future updates may
address these limitations when kernel support is available.
The dmstats report provides several types of field that may be
added to the default field set, or used to create custom reports.
All performance counters and metrics are calculated per-area.
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 ba‐
sic counter values provided by the kernel for each area.
reads_merged_per_sec
Reads merged per second.
writes_merged_per_sec
Writes merged per second.
reads_per_sec
Reads completed per second.
writes_per_sec
Writes completed per second.
read_size_per_sec
Size of data read per second.
write_size_per_sec
Size of data written per second.
avg_request_size
Average request size.
queue_size
Average queue size.
await The average wait time for read and write operations.
r_await
The average wait time for read operations.
w_await
The average wait time for write operations.
throughput
The device throughput in operations per second.
service_time
The average service time (in milliseconds) for operations
issued to the device.
util Percentage of CPU time during which I/O requests were is‐
sued to the device (bandwidth utilization for the device).
Device saturation occurs when this value is close to 100%.
Group, region and area meta fields
Meta fields provide information about the groups, regions, or ar‐
eas 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.
region_id
Region identifier. This is a non-negative integer returned
by the kernel when a statistics region is created.
region_start
The region start location. Display units are selected by
the --units option.
region_len
The length of the region. Display units are selected by the
--units option.
area_id
Area identifier. Area identifiers are assigned by the de‐
vice-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 re‐
gion. 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.
area_start
The area start location. Display units are selected by the
--units option.
area_len
The length of the area. Display units are selected by the
--units option.
area_count
The number of areas in this region.
program_id
The program ID value associated with this region.
user_data
The user data value associated with this region.
group_id
Group identifier. This is a non-negative integer returned
by the dmstats group command when a statistics group is
created.
interval_ns
The estimated interval over which the current counter val‐
ues have accumulated. The value is reported as an integer
expressed in units of nanoseconds.
interval
The estimated interval over which the current counter val‐
ues have accumulated. The value is reported as a real num‐
ber in units of seconds.
Basic counters
Basic counters provide access to the raw counter data from the
kernel, allowing further processing to be carried out by another
program.
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.
read_count
Count of reads completed this interval.
reads_merged_count
Count of reads merged this interval.
read_sector_count
Count of 512 byte sectors read this interval.
read_time
Accumulated duration of all read requests (ns).
write_count
Count of writes completed this interval.
writes_merged_count
Count of writes merged this interval.
write_sector_count
Count of 512 byte sectors written this interval.
write_time
Accumulated duration of all write requests (ns).
in_progress_count
Count of requests currently in progress.
io_ticks
Nanoseconds spent servicing requests.
queue_ticks
This field is incremented at each I/O start, I/O comple‐
tion, 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.
read_ticks
Nanoseconds spent servicing reads.
write_ticks
Nanoseconds spent servicing writes.
Histogram fields
Histograms measure the frequency distribution of user specified
I/O latency intervals. Histogram bin boundaries are specified when
a region is created.
A brief representation of the histogram values and latency inter‐
vals can be included in the report using these fields.
hist_count
A list of the histogram counts for the current statistics
area in order of ascending latency value. Each value repre‐
sents the number of I/Os with latency times falling into
that bin's time range during the sample period.
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.
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.
hist_percent
A list of the relative histogram values for the current
statistics area in order of ascending latency value, ex‐
pressed as a percentage. Each value represents the propor‐
tion of I/Os with latency times falling into that bin's
time range during the sample period.
hist_percent_bounds
A list of the relative histogram values for the current
statistics area in order of ascending latency value, ex‐
pressed 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.
hist_percent_ranges
A list of the relative histogram values for the current
statistics area in order of ascending latency value, ex‐
pressed 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 up‐
per bounds.
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, milisec‐
onds, microseconds or nanoseconds with a suffix indicating
the unit.
hist_ranges
A list of the histogram bin ranges for the current statis‐
tics 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 in‐
dicating the unit.
hist_bins
The number of latency histogram bins configured for the
area.
Create a whole-device region with one area on vg00/lvol1
# dmstats create vg00/lvol1
vg00/lvol1: Created new region with 1 area(s) as region ID 0
Create a 32M region 1G into device d0
# dmstats create --start 1G --length 32M d0
d0: Created new region with 1 area(s) as region ID 0
Create a whole-device region with 8 areas on every device
# dmstats create --areas 8
vg00-lvol1: Created new region with 8 area(s) as region ID 0
vg00-lvol2: Created new region with 8 area(s) as region ID 0
vg00-lvol3: Created new region with 8 area(s) as region ID 0
vg01-lvol0: Created new region with 8 area(s) as region ID 2
vg01-lvol1: Created new region with 8 area(s) as region ID 0
vg00-lvol2: Created new region with 8 area(s) as region ID 1
Delete all regions on all devices
# dmstats delete --alldevices --allregions
Create a whole-device region with areas 10GiB in size on
vg00/lvol1 using dmsetup
# dmsetup stats create --areasize 10G vg00/lvol1
vg00-lvol1: Created new region with 5 area(s) as region ID 1
Create a 1GiB region with 16 areas at the start of vg00/lvol1
# dmstats create --start 0 --len 1G --areas=16 vg00/lvol1
vg00-lvol1: Created new region with 16 area(s) as region ID 0
List the statistics regions registered on vg00/lvol1
# dmstats list vg00/lvol1
Name RgID RStart RSize #Areas ASize ProgID
vg00-lvol1 0 0 61.00g 1 61.00g dmstats
vg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats
vg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats
Display five statistics reports for vg00/lvol1 at an interval of
one second
# dmstats report --interval 1 --count 5 vg00/lvol1
# dmstats report
Name RgID ArID AStart ASize RRqM/s WRqM/s R/s
W/s RSz/s WSz/s AvRqSz QSize Util% AWait RdAWa WrAWa
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
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
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
Create one region for reach target contained in device vg00/lvol1
# dmstats create --segments vg00/lvol1
vg00-lvol1: Created new region with 1 area(s) as region ID 0
vg00-lvol1: Created new region with 1 area(s) as region ID 1
vg00-lvol1: Created new region with 1 area(s) as region ID 2
Create regions mapping each file in the directory images/ and
place them into separate groups, each named after the correspond‐
ing file
# dmstats create --filemap images/*
images/vm1.qcow2: Created new group with 87 region(s) as group ID
0.
images/vm1-1.qcow2: Created new group with 8 region(s) as group ID
87.
images/vm2.qcow2: Created new group with 11 region(s) as group ID
95.
images/vm2-1.qcow2: Created new group with 1454 region(s) as group
ID 106.
images/vm3.img: Created new group with 2 region(s) as group ID
1560.
Print raw counters for region 4 on device d0
# dmstats print --regionid 4 d0
2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41
Bryn M. Reeves <[email protected]>
dmsetup(8)
LVM2 resource page: ⟨https://www.sourceware.org/lvm2⟩
Device-mapper resource page: ⟨http://sources.redhat.com/dm⟩
Device-mapper statistics kernel documentation
Documentation/device-mapper/statistics.txt
This page is part of the lvm2 (Logical Volume Manager 2) project.
Information about the project can be found at
⟨http://www.sourceware.org/lvm2/⟩. If you have a bug report for
this manual page, see ⟨https://github.com/lvmteam/lvm2/issues⟩.
This page was obtained from the project's upstream Git repository
⟨git://sourceware.org/git/lvm2.git⟩ on 2025-08-11. (At that time,
the date of the most recent commit that was found in the
repository was 2025-08-08.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
Linux Jun 23 2016 DMSTATS(8)
Pages that refer to this page: pmdadm(1), dmfilemapd(8), dmsetup(8), lvm(8), lvmsadc(8), lvmsar(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|