Provided by: dmsetup_1.02.167-1ubuntu1_amd64 bug

NAME

       dmstats — device-mapper statistics management

SYNOPSIS

       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]

DESCRIPTION

       The dmstats program manages IO statistics regions for devices that use  the  device-mapper
       driver. Statistics regions may be created, deleted, listed and reported on using the tool.

       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 commands require the use of --alldevices when used
       in this way.

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.  Capitalise to use multiples of  1000  (S.I.)
              instead 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 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).

       --nomonitor
              Disable the dmfilemapd daemon when creating new file mapped  groups.  Normally  the
              device-mapper  filemap  monitoring  daemon,  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 update_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-inode 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 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.

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

              In either mode, the daemon exits automatically if the monitored group is removed.

       --foreground
              Specify  that  the dmfilemapd daemon should run in the foreground.  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  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.  Capitalise to use multiples of  1000  (S.I.)
              instead 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  (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.  Capitalise to use multiples of  1000  (S.I.)
              instead 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 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.  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 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

       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.

REGIONS, AREAS, AND GROUPS

       The  device-mapper  statistics  facility  allows  separate  performance  counters  to   be
       maintained  for  arbitrary  regions of devices. A region may span any range: from a single
       sector to the whole device. A region may be further sub-divided into a number of  distinct
       areas  (one  or more), each with its own counter set. In this case a summary value for the
       entire region is also available for use in reports.

       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.

       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.

       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 together 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 command. 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 device.

       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.

FILE MAPPING

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

       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 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, aggregating 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 dmfilemapd 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 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 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 regions: 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 manually 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 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 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 majority of IO does not
       trigger extent allocation. Future  updates  may  address  these  limitations  when  kernel
       support is available.

REPORT FIELDS

       The  dmstats report provides several types of field that may be added to the default field
       set, or used to create custom reports.

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

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

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

AUTHORS

       Bryn M. Reeves <bmr@redhat.com>

SEE ALSO

       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