OPTIONS

--alias name

Specify an alias name for a group.

--alldevices

If no device arguments are given allow operation on all devices 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 accept 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 suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes.

--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 until 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).

--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 iterations for repeating reports. If --interval is specified but --count is not, reports will continue to repeat until interrupted.

--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 selects units of: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes.

-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 (except h and H) if processing the output.

--notimesuffix

Suppress the suffix on output time values. Histogram boundary 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 sequences of identifiers may be expressed as a hyphen separated range, for example: '1-10'.

--relative

If displaying the histogram report show relative (percentage) 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 selection 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.

--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 device.
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 display 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. 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 auxilliary data (for example, 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.

COMMANDS

ungroup [device_name] [--alldevices] [--groupid id]

Instructs the kernel to clear statistics counters for the speficied regions (with the exception of in-flight IO counters).

ungroup [device_name] [--alldevices] [--groupid 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.
Use the --group option to only display information for groups when listing and reporting.

ungroup [device_name] [--alldevices] [--groupid 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.

ungroup [device_name] [--alldevices] [--groupid id]

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.

ungroup [device_name] [--alldevices] [--groupid id]

Outputs a summary of the commands available, optionally including the list of report fields.

ungroup [device_name] [--alldevices] [--groupid id]

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.

ungroup [device_name] [--alldevices] [--groupid id]

Print raw statistics counters for the specified region or for all present regions.

ungroup [device_name] [--alldevices] [--groupid id]

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.

REGIONS, AREAS, AND GROUPS

REPORT FIELDS

Derived metrics

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 issued to the device (bandwidth utilization for the device). Device saturation occurs when this value is close to 100%.

Group, region and area meta fields

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 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.

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 values have accumulated. The value is reported as an interger expressed in units of nanoseconds.

interval

The estimated interval over which the current counter values have accumulated. The value is reported as a real number in units of seconds.

Basic counters

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_nsecs

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 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.

read_ticks

Nanoseconds spent servicing reads.

write_ticks

Nanoseconds spent servicing writes.

Histogram fields

hist_count

A list of the histogram counts for the current statistics area in order of ascending latency value. Each value represents the number of I/Os with latency times falling into that bin's time range during the sample period.

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, 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.

hist_percent_bounds

A list of the relative histogram values for the current statistics area in order of ascending latency value, expressed as a percentage and including bin boundaries. Each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period and is prefixed with the corresponding bin's lower bound.

hist_percent_ranges

A list of the relative histogram values for the current statistics area in order of ascending latency value, expressed as a percentage and including bin boundaries. Each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period and is prefixed with the corresponding bin's lower and upper bounds.

hist_bounds

A list of the histogram boundary values for the current statistics area in order of ascending latency value. The values are expressed in whole units of seconds, miliseconds, microseconds or nanoseconds with a suffix indicating the unit.

hist_ranges

A list of the histogram bin ranges for the current statistics area in order of ascending latency value. The values are expressed as "LOWER-UPPER" in whole units of seconds, miliseconds, microseconds or nanoseconds with a suffix indicating the unit.

hist_bins

The number of latency histogram bins configured for the area.

EXAMPLES

AUTHORS

SEE ALSO