dmstats man page on Kali

Man page or keyword search:  
man Server   9211 pages
apropos Keyword Search (all sections)
Output format
Kali logo
[printable version]

DMSTATS(8)		     MAINTENANCE COMMANDS		    DMSTATS(8)

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 num‐
       bers.

       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	opera‐
	      tions.

       --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	inter‐
	      rupted.

       --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	 moni‐
	      toring  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 dae‐
	      mon 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 descrip‐
	      tor.  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 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.

	      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 opera‐
	      tions may supply a program ID in order to	 select	 only  regions
	      with  a  matching value. The default program ID for dmstats-man‐
	      aged 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 crite‐
	      ria are defined by specifying column names and their valid  val‐
	      ues 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 spefi‐
	      cied 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 cre‐
	      ate 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  respec‐
	      tively,  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 data‐
	      base files.

	      To work with the --filemap option, files must be	located	 on  a
	      local  file  system, backed by a device-mapper device, that sup‐
	      ports 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	behav‐
	      iour 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 dis‐
	      abled 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 --allre‐
	      gions.

	      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  identi‐
	      fiers.  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  includ‐
	      ing 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 con‐
	      tained 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 his‐
	      togram 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] [--fore‐
	      ground]
	      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 allo‐
	      cated 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 dae‐
	      mon 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 coun‐
       ters  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	refer‐
       ence 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 refer‐
       ence 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  automati‐
       cally.

       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 monitor‐
       ing  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  sys‐
       tem),  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 grow‐
       ing, 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	 accu‐
       mulated	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 perfor‐
       mance indicators. These are based on the fields provided by the conven‐
       tional Linux iostat program and are derived from the basic counter val‐
       ues 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	 satu‐
	      ration 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  identi‐
	      fiers  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 accumu‐
	      lating.

       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  statis‐
	      tics  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 sam‐
	      ple period.

       hist_percent_bounds
	      A list of the relative histogram values for the current  statis‐
	      tics  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 statis‐
	      tics 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  statis‐
	      tics  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, milisec‐
	      onds, 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

Linux				  Jun 23 2016			    DMSTATS(8)
[top]

List of man pages available for Kali

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net