Man Pages

dmstats(8) - phpMan dmstats(8) - phpMan

Command: man perldoc info search(apropos)  


DMSTATS(8)                   MAINTENANCE COMMANDS                   DMSTATS(8)



NAME
       dmstats -- device-mapper statistics management

SYNOPSIS
       dmsetup stats command [options]

       dmstats command [device_name |--uuid uuid|--major major --minor minor]
       dmstats clear device_name [--allprograms|--programid id] [--allregions|--regionid id]
       dmstats create device_name [--alldevices] [--areas nr_areas|--areasize area_size] [--bounds
              histogram_boundaries] [--precise] [--start start_sector --length length|--segments] [--auxdata data]
              [--programid id]
       dmstats delete [device_name] [--alldevices] [--allprograms|--programid id] [--allregions|--regionid id]
       dmstats help [-c|-C|--columns]
       dmstats list [device_name] [--histogram] [--allprograms|--programid id] [--units units] [--nosuffix] [--notime-
              suffix] [-v|--verbose[-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] [-O|--sort sort_fields] [-S|--select selec-
              tion] [--units units] [--nosuffix] [--notimesuffix]

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  the program is run using the 'dmstats' alias, the command must be the first argument and any switches and
       options should be specified following the command itself. This limitation is not present when run  as  'dmsetup
       stats'.

       When no device argument is given dmstats will by default operate on all device-mapper devices present. The cre-
       ate and delete commands require the use of --alldevices when used in this way.

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

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

       --auxdata aux_data
              Specify auxilliary data (a string) to be stored with a new region.

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

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

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

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

       --regionid id
              Specify the region to operate on.

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

       --segments
              Create a new statistics region for each target contained in the target device. This  causes  a  separate
              region to be allocated for each segment of the device.

       --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.   Capi-
              talise  to use multiples of 1000 (S.I.) instead of 1024.  Can also specify custom units e.g. --units 3M.

       -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 [--alldevices] [--areas nr_areas|--areasize area_size] [--bounds histogram_boundaries]
              [--precise] [--start start_sector --length length|--segments] [--auxdata 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 --target are  given.  The  --start
              and  --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  his-
              togram  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  exam-
              ple,  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 aux_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 aux_data stores  an  arbi-
              trary 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.

       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.

       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] [--nosuffix] [--notimesuffix]
              [-v|--verbose[-v|--verbose]]
              List  the  statistics regions registered on the device. If the --allprograms switch is given all regions
              will be listed regardless of region program ID values.

              If -v or --verbose is given the report will include a row of information for each area contained in each
              region displayed.

              If  --histogram  is given the report will include the bin count and latency boundary values for any con-
              figured 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] [-O|--sort sort_fields] [-S|--select selec-
              tion] [--units units] [--nosuffix] [--notimesuffix]
              Start a report for the specified region or for all present regions. 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  val-
              ues.

              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.

REGIONS AND AREAS
       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 fur-
       ther sub-divided into a number of distinct areas (one or more), each with its own counter set.

       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.

       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.

REPORT FIELDS
       The dmstats report provides several types of field that may be added to the default field set, or used to  cre-
       ate 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%.

   Region and area meta fields
       Meta fields provide information about the region or area that the statistics values relate  to.  This  includes
       the region and area identifier, start, length, and counts, as well as the program ID and auxiliary 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.

       aux_data
              The auxiliary data value associated with this region.

       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 car-
       ried 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_nsecs
              Accumulated duration of all write requests (ns).

       in_progress_count
              Count of requests currently in progress.

       io_ticks
              Nanoseconds spent servicing requests.

       queue_ticks
              This field is incremented at each I/O start, I/O completion, I/O merge, or read of these  stats  by  the
              number  of  I/Os  in  progress  multiplied  by the number of milliseconds spent doing I/O since the last
              update of this field.  This can provide an easy measure of both I/O completion time and the backlog that
              may be accumulating.

       read_ticks
              Nanoseconds spent servicing reads.

       write_ticks
              Nanoseconds spent servicing writes.

   Histogram fields
       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

       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 <bmrATredhat.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                             Jul 25 2015                       DMSTATS(8)