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
counters).
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 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 --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
associated 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
creating 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 individual files in the file system, for
example, virtual machine 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
mapping as the extents allocated to the file change. This
behaviour 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
regions the group will also be removed.
group [device_name|--alldevices] [--alias name] [--regions
regions]
Combine one or more statistics regions on the specified
device into a group.
The list of regions to be grouped is specified with
--regions 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 spanning 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
numbered) region_id in the group: deleting this region
will also delete the group and other group members will be
returned to their prior state.
help [-c|-C|--columns]
Outputs a summary of the commands available, optionally
including 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
regions will be listed regardless of region program ID
values.
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
regardless 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
histograms.
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
option. 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
displays bin values as a percentage of the total number of
I/Os.
Object types (areas, regions and groups) to include in the
report are selected using the --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
directly, 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
dmfilemapd 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
starting the monitoring daemon.
