# dmstats

## 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** com‐
           mands 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 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.
    


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


## REGIONS, AREAS, AND GROUPS



           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.
    


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


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


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


* * *