1DMSTATS(8)                   MAINTENANCE COMMANDS                   DMSTATS(8)
2
3
4

NAME

6       dmstats — device-mapper statistics management
7

SYNOPSIS

9       dmsetup stats command [OPTIONS]
10
11       dmstats command device_name | --major major --minor minor | -u|--uuid
12              uuid [-v|--verbose]
13       dmstats clear device_name [--allprograms|--programid id]
14              [--allregions|--regionid id]
15       dmstats create device_name...|file_path...|--alldevices [--areas
16              nr_areas|--areasize area_size] [--bounds histogram_boundaries]
17              [--filemap] [--follow follow_mode] [--foreground] [--nomonitor]
18              [--nogroup] [--precise] [--start start_sector --length
19              length|--segments] [--userdata user_data] [--programid id]
20       dmstats delete device_name|--alldevices [--allprograms|--programid id]
21              [--allregions|--regionid id]
22       dmstats group [device_name|--alldevices] [--alias name] [--regions
23              regions]
24       dmstats help [-c|-C|--columns]
25       dmstats list [device_name] [--histogram] [--allprograms|--programid id]
26              [--units units] [--area] [--region] [--group] [--nosuffix]
27              [--notimesuffix] [-v|--verbose]
28       dmstats print [device_name] [--clear] [--allprograms|--programid id]
29              [--allregions|--regionid id]
30       dmstats report [device_name] [--interval seconds] [--count count]
31              [--units units] [--histogram] [--allprograms|--programid id]
32              [--allregions|--regionid id] [--area] [--region] [--group]
33              [-O|--sort sort_fields] [-S|--select selection] [--units units]
34              [--nosuffix] [--notimesuffix]
35       dmstats ungroup [device_name|--alldevices] [--groupid id]
36       dmstats update_filemap file_path [--groupid id] [--follow follow_mode]
37              [--foreground]
38

DESCRIPTION

40       The  dmstats program manages IO statistics regions for devices that use
41       the device-mapper driver. Statistics regions may be  created,  deleted,
42       listed and reported on using the tool.
43
44       The first argument to dmstats is a command.
45
46       The  second  argument  is the device name, uuid or major and minor num‐
47       bers.
48
49       Further options permit the selection of regions, output format control,
50       and reporting behaviour.
51
52       When no device argument is given dmstats will by default operate on all
53       device-mapper devices present. The create and delete  commands  require
54       the use of --alldevices when used in this way.
55

OPTIONS

57       --alias name
58              Specify an alias name for a group.
59
60       --alldevices
61              If  no device arguments are given allow operation on all devices
62              when creating or deleting regions.
63
64       --allprograms
65              Include regions from all program IDs for list and report  opera‐
66              tions.
67
68       --allregions
69              Include  all present regions for commands that normally accept a
70              single region identifier.
71
72       --area
73              When peforming a list or report, include objects of type area in
74              the results.
75
76       --areas nr_areas
77              Specify  the  number  of statistics areas to create within a new
78              region.
79
80       --areasize area_size[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
81              Specify the size of areas into which  a  new  region  should  be
82              divided.   An   optional   suffix  selects  units  of:  (b)ytes,
83              (s)ectors, (k)ilobytes, (m)egabytes,  (g)igabytes,  (t)erabytes,
84              (p)etabytes,  (e)xabytes.   Capitalise  to use multiples of 1000
85              (S.I.) instead of 1024.
86
87       --clear
88              When printing statistics counters, also atomically reset them to
89              zero.
90
91       --count count
92              Specify  the iteration count for repeating reports. If the count
93              argument is zero reports will continue to  repeat  until  inter‐
94              rupted.
95
96       --group
97              When  peforming  a list or report, include objects of type group
98              in the results.
99
100       --filemap
101              Instead of creating regions on a device as specified by  command
102              line  options,  open  the file found at each file_path argument,
103              and create regions corresponding to the locations of the on-disk
104              extents allocated to the file(s).
105
106       --nomonitor
107              Disable  the  dmfilemapd  daemon  when  creating new file mapped
108              groups. Normally the device-mapper  filemap  monitoring  daemon,
109              dmfilemapd,  is started for each file mapped group to update the
110              set of regions as the file changes on-disk: use of  this  option
111              disables this behaviour.
112
113              Regions   in   the   group   may   still  be  updated  with  the
114              update_filemap command, or by starting the daemon manually.
115
116       --follow follow_mode
117              Specify the dmfilemapd file following mode. The file  map  moni‐
118              toring  daemon  can monitor files in two distinct ways: the mode
119              affects the behaviour of the daemon when a file under monitoring
120              is  renamed or unlinked, and the conditions which cause the dae‐
121              mon to terminate.
122
123              The follow_mode argument is  either  "inode",  for  follow-inode
124              mode, or "path", for follow-path.
125
126              If  follow-inode  mode  is  used,  the daemon will hold the file
127              open, and continue to update regions from the same file descrip‐
128              tor.  This  means  that  the  mapping  will  follow rename, move
129              (within the same file system), and unlink operations. This  mode
130              is  useful  if  the  file  is  expected to be moved, renamed, or
131              unlinked while it is being monitored.
132
133              In follow-inode mode, the daemon will exit once it detects  that
134              the file has been unlinked and it is the last holder of a refer‐
135              ence to it.
136
137              If follow-path is used, the daemon  will  re-open  the  provided
138              path  on  each  monitoring  iteration. This means that the group
139              will be updated to reflect a new file being moved  to  the  same
140              path  as  the  original file. This mode is useful for files that
141              are expected to be updated via unlink and rename.
142
143              In follow-path mode, the daemon will exit if the file is removed
144              and not replaced within a brief tolerance interval.
145
146              In  either mode, the daemon exits automatically if the monitored
147              group is removed.
148
149       --foreground
150              Specify that the dmfilemapd daemon should run in the foreground.
151              The  daemon  will not fork into the background, and will replace
152              the dmstats command that started it.
153
154       --groupid id
155              Specify the group to operate on.
156
157       --bounds histogram_boundaries[ns|us|ms|s]
158              Specify the boundaries of a latency histogram to be tracked  for
159              the  region as a comma separated list of latency values. Latency
160              values are given in nanoseconds. An optional unit suffix of  ns,
161              us,  ms,  or s may be given after each value to specify units of
162              nanoseconds, microseconds, miliseconds or seconds respectively.
163
164       --histogram
165              When used with the  report  and  list  commands  select  default
166              fields that emphasize latency histogram data.
167
168       --interval seconds
169              Specify  the  interval  in seconds between successive iterations
170              for repeating reports. If --interval is specified but --count is
171              not, reports will continue to repeat until interrupted.
172
173       --length length[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
174              Specify  the  length  of  a new statistics region in sectors. An
175              optional  suffix   selects   units   of:   (b)ytes,   (s)ectors,
176              (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
177              (e)xabytes.  Capitalise to use multiples of 1000 (S.I.)  instead
178              of 1024.
179
180       -j|--major major
181              Specify the major number.
182
183       -m|--minor minor
184              Specify the minor number.
185
186       --nogroup
187              When  creating regions mapping the extents of a file in the file
188              system, do not create a group or set an alias.
189
190       --nosuffix
191              Suppress the suffix on output sizes.  Use with --units (except h
192              and H) if processing the output.
193
194       --notimesuffix
195              Suppress  the  suffix  on output time values. Histogram boundary
196              values will be reported in units of nanoseconds.
197
198       -o|--options
199              Specify which report fields to display.
200
201       -O|--sort sort_fields
202              Sort output according to the list of fields given.  Precede  any
203              sort field with '-' for a reverse sort on that column.
204
205       --precise
206              Attempt  to  use nanosecond precision counters when creating new
207              statistics regions.
208
209       --programid id
210              Specify a  program  ID  string.  When  creating  new  statistics
211              regions this string is stored with the region. Subsequent opera‐
212              tions may supply a program ID in order to  select  only  regions
213              with  a  matching value. The default program ID for dmstats-man‐
214              aged regions is "dmstats".
215
216       --region
217              When peforming a list or report, include objects of type  region
218              in the results.
219
220       --regionid id
221              Specify the region to operate on.
222
223       --regions region_list
224              Specify  a  list of regions to group. The group list is a comma-
225              separated list of region identifiers.  Continuous  sequences  of
226              identifiers  may  be  expressed as a hyphen separated range, for
227              example: '1-10'.
228
229       --relative
230              If displaying the histogram report  show  relative  (percentage)
231              values instead of absolute counts.
232
233       -S|--select selection
234              Display  only  rows that match selection criteria. All rows with
235              the additional "selected" column (-o selected) showing 1 if  the
236              row  matches the selection and 0 otherwise. The selection crite‐
237              ria are defined by specifying column names and their valid  val‐
238              ues while making use of supported comparison operators.
239
240       --start start[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
241              Specify  the start offset of a new statistics region in sectors.
242              An  optional  suffix  selects  units  of:  (b)ytes,   (s)ectors,
243              (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
244              (e)xabytes.  Capitalise to use multiples of 1000 (S.I.)  instead
245              of 1024.
246
247       --segments
248              When  used  with create, create a new statistics region for each
249              target contained in the given device(s). This causes a  separate
250              region to be allocated for each segment of the device.
251
252              The  newly created regions are automatically placed into a group
253              unless the --nogroup option is given. When grouping is enabled a
254              group alias may be specified using the --alias option.
255
256       --units [units][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
257              Set  the  display units for report output.  All sizes are output
258              in   these   units:   (h)uman-readable,   (b)ytes,    (s)ectors,
259              (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
260              (e)xabytes.  Capitalise to use multiples of 1000 (S.I.)  instead
261              of 1024.  Can also specify custom units e.g. --units 3M.
262
263       --userdata user_data
264              Specify  user  data (a word) to be stored with a new region. The
265              value is added to any internal  auxilliary  data  (for  example,
266              group  information),  and stored with the region in the aux_data
267              field provided by the kernel. Whitespace is not permitted.
268
269       -u|--uuid
270              Specify the uuid.
271
272       -v|--verbose [-v|--verbose]
273              Produce additional output.
274

COMMANDS

276       clear device_name [--allprograms|--programid id]
277              [--allregions|--regionid id]
278              Instructs the kernel to clear statistics counters for the spefi‐
279              cied regions (with the exception of in-flight IO counters).
280
281       create device_name...|file_path...|--alldevices [--areas
282              nr_areas|--areasize area_size] [--bounds histogram_boundaries]
283              [--filemap] [--follow follow_mode] [--foreground] [--nomonitor]
284              [--nogroup] [--precise] [--start start_sector --length
285              length|--segments] [--userdata user_data] [--programid id]
286              Creates one or more new  statistics  regions  on  the  specified
287              device(s).
288
289              The  region  will  span  the  entire  device  unless --start and
290              --length or  --segments  are  given.  The  --start  an  --length
291              options  allow  a  region of arbitrary length to be placed at an
292              arbitrary offset into the device. The --segments option causes a
293              new  region  to  be created for each target in the corresponding
294              device-mapper device's table.
295
296              If the --precise option is used the command will attempt to cre‐
297              ate a region using nanosecond precision counters.
298
299              If --bounds is given a latency histogram will be tracked for the
300              new region. The boundaries of the histogram bins are given as  a
301              comma  separated  list  of  latency values. There is an implicit
302              lower bound of zero on the first bin and an implicit upper bound
303              of  infinity  (or the configured interval duration) on the final
304              bin.
305
306              Latencies are given in nanoseconds. An optional unit  suffix  of
307              ns,  us, ms, or s may be given after each value to specify units
308              of nanoseconds, microseconds,  miliseconds  or  seconds  respec‐
309              tively,  so for example, 10ms is equivalent to 10000000. Latency
310              values with a precision of less than one milisecond can only  be
311              used  when  precise  timestamps are enabled: if --precise is not
312              given and values less than one milisecond are used  it  will  be
313              enabled automatically.
314
315              An  optional  program_id  or  user_data string may be associated
316              with the region. A program_id may then be used to select regions
317              for subsequent list, print, and report operations. The user_data
318              stores an arbitrary string and is not used  by  dmstats  or  the
319              device-mapper kernel statistics subsystem.
320
321              By   default  dmstats  creates  regions  with  a  program_id  of
322              "dmstats".
323
324              On success the region_id of the newly created region is  printed
325              to stdout.
326
327              If the --filemap option is given with a regular file, or list of
328              files, as the file_path argument, instead  of  creating  regions
329              with parameters specified on the command line, dmstats will open
330              the files located at file_path and create regions  corresponding
331              to  the physical extents allocated to the file. This can be used
332              to monitor statistics for individual files in the  file  system,
333              for  example, virtual machine images, swap areas, or large data‐
334              base files.
335
336              To work with the --filemap option, files must be  located  on  a
337              local  file  system, backed by a device-mapper device, that sup‐
338              ports physical extent data using the FIEMAP ioctl (Ext4 and  XFS
339              for e.g.).
340
341              By  default  regions that map a file are placed into a group and
342              the group alias is set to the basename of the file. This  behav‐
343              iour can be overridden with the --alias and --nogroup options.
344
345              Creating a group that maps a file automatically starts a daemon,
346              dmfilemapd to monitor the file and update  the  mapping  as  the
347              extents allocated to the file change. This behaviour can be dis‐
348              abled using the --nomonitor option.
349
350              Use the --group option to only display  information  for  groups
351              when listing and reporting.
352
353       delete device_name|--alldevices [--allprograms|--programid id]
354              [--allregions|--regionid id]
355              Delete  the  specified  statistics  region.  All  counters   and
356              resources  used  by  the region are released and the region will
357              not appear in the output of subsequent list,  print,  or  report
358              operations.
359
360              All regions registered on a device may be removed using --allre‐
361              gions.
362
363              To remove all regions  on  all  devices  both  --allregions  and
364              --alldevices must be used.
365
366              If a --groupid is given instead of a --regionid the command will
367              attempt to delete the group and all regions that it contains.
368
369              If a deleted region is the first member of a  group  of  regions
370              the group will also be removed.
371
372       group [device_name|--alldevices] [--alias name] [--regions regions]
373              Combine  one  or more statistics regions on the specified device
374              into a group.
375
376              The list of regions to be grouped is  specified  with  --regions
377              and  an  optional alias may be assigned with --alias. The set of
378              regions is given as a comma-separated  list  of  region  identi‐
379              fiers.  A  continuous range of identifers spanning from R1 to R2
380              may be expressed as 'R1-R2'.
381
382              Regions that have a histogram configured can be grouped: in this
383              case  the  number  of histogram bins and their bounds must match
384              exactly.
385
386              On success the group list and newly created group_id are printed
387              to stdout.
388
389              The  group  metadata  is stored with the first (lowest numbered)
390              region_id in the group: deleting this region  will  also  delete
391              the  group  and  other  group  members will be returned to their
392              prior state.
393
394       help [-c|-C|--columns]
395              Outputs a summary of the commands available, optionally  includ‐
396              ing the list of report fields.
397
398       list [device_name] [--histogram] [--allprograms|--programid id]
399              [--units units] [--area] [--region] [--group] [--nosuffix]
400              [--notimesuffix] [-v|--verbose]
401              List  the statistics regions, areas, or groups registered on the
402              device.  If the --allprograms switch is given all  regions  will
403              be listed regardless of region program ID values.
404
405              By  default only regions and groups are included in list output.
406              If -v or --verbose is given the report will also include  a  row
407              of  information for each configured group and for each area con‐
408              tained in each region displayed.
409
410              Regions that contain a single area are by default  omitted  from
411              the  verbose  list  since  their properties are identical to the
412              area that they contain - to view all regions regardless  of  the
413              number  of  areas  present use --region). To also view the areas
414              contained within regions use --area.
415
416              If --histogram is given the report will include  the  bin  count
417              and latency boundary values for any configured histograms.
418
419       print [device_name] [--clear] [--allprograms|--programid id]
420              [--allregions|--regionid id]
421              Print raw statistics counters for the specified  region  or  for
422              all present regions.
423
424       report [device_name] [--interval seconds] [--count count] [--units
425              units] [--histogram] [--allprograms|--programid id]
426              [--allregions|--regionid id] [--area] [--region] [--group]
427              [-O|--sort sort_fields] [-S|--select selection] [--units units]
428              [--nosuffix] [--notimesuffix]
429              Start  a  report  for  the  specified  object or for all present
430              objects. If the count argument is  specified,  the  report  will
431              repeat  at  a  fixed  interval set by the --interval option. The
432              default interval is one second.
433
434              If the --allprograms  switch  is  given,  all  regions  will  be
435              listed, regardless of region program ID values.
436
437              If  the  --histogram  is  given the report will include the his‐
438              togram values and latency boundaries.
439
440              If the --relative is used the default histogram  field  displays
441              bin values as a percentage of the total number of I/Os.
442
443              Object  types  (areas,  regions  and  groups)  to include in the
444              report are selected using  the  --area,  --region,  and  --group
445              options.
446
447       ungroup [device_name|--alldevices] [--groupid id]
448              Remove  an  existing group and return all the group's regions to
449              their original state.
450
451              The group to be removed is specified using --groupid.
452
453       update_filemap file_path [--groupid id] [--follow follow_mode] [--fore‐
454              ground]
455              Update  a  group  of dmstats regions specified by group_id, that
456              were previously created with --filemap, either directly,  or  by
457              starting the monitoring daemon, dmfilemapd.
458
459              This will add and remove regions to reflect changes in the allo‐
460              cated extents of the file on-disk, since the time  that  it  was
461              crated or last updated.
462
463              Use  of this command is not normally needed since the dmfilemapd
464              daemon will automatically monitor  filemap  groups  and  perform
465              these updates when required.
466
467              If  a filemapped group was created with --nomonitor, or the dae‐
468              mon has been killed, the update_filemap can be used to  manually
469              force an update or start a new daemon.
470
471              Use  --nomonitor  to  force a direct update and disable starting
472              the monitoring daemon.
473

REGIONS, AREAS, AND GROUPS

475       The device-mapper statistics facility allows separate performance coun‐
476       ters  to  be  maintained for arbitrary regions of devices. A region may
477       span any range: from a single sector to the whole device. A region  may
478       be  further  sub-divided into a number of distinct areas (one or more),
479       each with its own counter set. In this case a  summary  value  for  the
480       entire region is also available for use in reports.
481
482       In  addition,  one or more regions on one device can be combined into a
483       statistics group. Groups allow several regions  to  be  aggregated  and
484       reported  as  a  single  entity; counters for all regions and areas are
485       summed and used to report totals for all  group  members.  Groups  also
486       permit  the  assignment of an optional alias, allowing meaningful names
487       to be associated with sets of regions.
488
489       The group metadata is stored with the first (lowest numbered) region_id
490       in the group: deleting this region will also delete the group and other
491       group members will be returned to their prior state.
492
493       By default new regions span the entire device. The --start and --length
494       options allows a region of any size to be placed at any location on the
495       device.
496
497       Using offsets it is possible to  create  regions  that  map  individual
498       objects within a block device (for example: partitions, files in a file
499       system, or stripes or other structures in a RAID volume). Groups  allow
500       several  non-contiguous  regions to be assembled together for reporting
501       and data aggregation.
502
503       A region may be either divided into the specified number of equal-sized
504       areas,  or into areas of the given size by specifying one of --areas or
505       --areasize when creating a region with the create command. Depending on
506       the  size  of the areas and the device region the final area within the
507       region may be smaller than requested.
508
509       Region identifiers
510
511       Each region is assigned an identifier when it is created that  is  used
512       to  reference  the  region in subsequent operations. Region identifiers
513       are unique within a given device (including across different program_id
514       values).
515
516       Depending  on  the  sequence  of create and delete operations, gaps may
517       exist in the sequence of region_id values for a particular device.
518
519       The region_id should be treated as an opaque identifier used to  refer‐
520       ence the region.
521
522       Group identifiers
523
524       Groups  are  also assigned an integer identifier at creation time; like
525       region identifiers, group identifiers are unique within the  containing
526       device.
527
528       The  group_id  should be treated as an opaque identifier used to refer‐
529       ence the group.
530

FILE MAPPING

532       Using --filemap, it is possible to create regions  that  correspond  to
533       the  extents of a file in the file system. This allows IO statistics to
534       be monitored on a per-file basis, for example to observe large database
535       files, virtual machine images, or other files of interest.
536
537       To  be  able  to use file mapping, the file must be backed by a device-
538       mapper device, and in a file system that supports the FIEMAP ioctl (and
539       which  returns  data describing the physical location of extents). This
540       currently includes xfs(5) and ext4(5).
541
542       By default the regions making up a file are placed together in a group,
543       and  the group alias is set to the basename(3) of the file. This allows
544       statistics to be reported for the file as a whole,  aggregating  values
545       for the regions making up the group. To see only the whole file (group)
546       when using the list and report commands, use --group.
547
548       Since it is possible for the file to change after the initial group  of
549       regions  is  created, the update_filemap command, and dmfilemapd daemon
550       are provided to update file mapped groups either manually or  automati‐
551       cally.
552
553       File follow modes
554
555       The  file map monitoring daemon can monitor files in two distinct ways:
556       follow-inode mode, and follow-path mode.
557
558       The mode affects the behaviour of the daemon when a file under monitor‐
559       ing  is  renamed or unlinked, and the conditions which cause the daemon
560       to terminate.
561
562       If follow-inode mode is used, the daemon will hold the file  open,  and
563       continue  to  update  regions from the same file descriptor. This means
564       that the mapping will follow rename, move (within the  same  file  sys‐
565       tem),  and  unlink  operations.  This  mode  is  useful  if the file is
566       expected to be moved, renamed, or unlinked while it is being monitored.
567
568       In follow-inode mode, the daemon will exit once  it  detects  that  the
569       file has been unlinked and it is the last holder of a reference to it.
570
571       If  follow-path  is  used, the daemon will re-open the provided path on
572       each monitoring iteration. This means that the group will be updated to
573       reflect  a  new file being moved to the same path as the original file.
574       This mode is useful for files that  are  expected  to  be  updated  via
575       unlink and rename.
576
577       In  follow-path  mode,  the daemon will exit if the file is removed and
578       not replaced within a brief tolerance interval (one second).
579
580       To stop the daemon, delete the group containing the mapped regions: the
581       daemon will automatically shut down.
582
583       The daemon can also be safely killed at any time and the group kept: if
584       the file is still being allocated the mapping will become progressively
585       out-of-date  as  extents are added and removed (in this case the daemon
586       can be re-started or the group updated manually with the update_filemap
587       command).
588
589       See the create command and --filemap, --follow, and --nomonitor options
590       for further information.
591
592       Limitations
593
594       The daemon attempts to maintain good synchronisation between  the  file
595       extents  and  the regions contained in the group, however, since it can
596       only react to new allocations once they have been  written,  there  are
597       inevitably  some  IO events that cannot be counted when a file is grow‐
598       ing, particularly if the file is being  extended  by  a  single  thread
599       writing beyond end-of-file (for example, the dd program).
600
601       There  is a further loss of events in that there is currently no way to
602       atomically resize a dmstats region and  preserve  its  current  counter
603       values.  This  affects  files  when  they  grow  by extending the final
604       extent, rather than allocating a new extent: any events that had  accu‐
605       mulated  in  the  region between any prior operation and the resize are
606       lost.
607
608       File mapping is currently most effective in cases where the majority of
609       IO does not trigger extent allocation. Future updates may address these
610       limitations when kernel support is available.
611

REPORT FIELDS

613       The dmstats report provides several types of field that may be added to
614       the default field set, or used to create custom reports.
615
616       All performance counters and metrics are calculated per-area.
617
618   Derived metrics
619       A number of metrics fields are included that provide high level perfor‐
620       mance indicators. These are based on the fields provided by the conven‐
621       tional Linux iostat program and are derived from the basic counter val‐
622       ues provided by the kernel for each area.
623
624       reads_merged_per_sec
625              Reads merged per second.
626
627       writes_merged_per_sec
628              Writes merged per second.
629
630       reads_per_sec
631              Reads completed per second.
632
633       writes_per_sec
634              Writes completed per second.
635
636       read_size_per_sec
637              Size of data read per second.
638
639       write_size_per_sec
640              Size of data written per second.
641
642       avg_request_size
643              Average request size.
644
645       queue_size
646              Average queue size.
647
648       await  The average wait time for read and write operations.
649
650       r_await
651              The average wait time for read operations.
652
653       w_await
654              The average wait time for write operations.
655
656       throughput
657              The device throughput in operations per second.
658
659       service_time
660              The average service time (in milliseconds) for operations issued
661              to the device.
662
663       util   Percentage  of CPU time during which I/O requests were issued to
664              the device (bandwidth utilization for the device). Device  satu‐
665              ration occurs when this value is close to 100%.
666
667   Group, region and area meta fields
668       Meta  fields  provide  information  about the groups, regions, or areas
669       that the statistics values relate to. This includes the region and area
670       identifier,  start,  length,  and counts, as well as the program ID and
671       user data values.
672
673       region_id
674              Region identifier. This is a non-negative  integer  returned  by
675              the kernel when a statistics region is created.
676
677       region_start
678              The  region  start  location.  Display units are selected by the
679              --units option.
680
681       region_len
682              The length of the region. Display  units  are  selected  by  the
683              --units option.
684
685       area_id
686              Area  identifier.  Area  identifiers are assigned by the device-
687              mapper statistics library and uniquely identify each area within
688              a  region.  Each ID corresponds to a distinct set of performance
689              counters for that area of the statistics  region.  Area  identi‐
690              fiers  are  always  monotonically  increasing within a region so
691              that higher ID values correspond  to  greater  sector  addresses
692              within  the  area  and  no  gaps  in the sequence of identifiers
693              exist.
694
695       area_start
696              The area start location.  Display  units  are  selected  by  the
697              --units option.
698
699       area_len
700              The  length  of  the  area.  Display  units  are selected by the
701              --units option.
702
703       area_count
704              The number of areas in this region.
705
706       program_id
707              The program ID value associated with this region.
708
709       user_data
710              The user data value associated with this region.
711
712       group_id
713              Group identifier. This is a non-negative integer returned by the
714              dmstats group command when a statistics group is created.
715
716       interval_ns
717              The  estimated  interval  over  which the current counter values
718              have accumulated. The value is reported as an interger expressed
719              in units of nanoseconds.
720
721       interval
722              The  estimated  interval  over  which the current counter values
723              have accumulated. The value is reported  as  a  real  number  in
724              units of seconds.
725
726   Basic counters
727       Basic  counters provide access to the raw counter data from the kernel,
728       allowing further processing to be carried out by another program.
729
730       The kernel provides thirteen  separate  counters  for  each  statistics
731       area.  The  first  eleven  of  these  match  the  counters  provided in
732       /proc/diskstats or /sys/block/*/*/stat. The final pair provide separate
733       counters for read and write time.
734
735       read_count
736              Count of reads completed this interval.
737
738       reads_merged_count
739              Count of reads merged this interval.
740
741       read_sector_count
742              Count of 512 byte sectors read this interval.
743
744       read_time
745              Accumulated duration of all read requests (ns).
746
747       write_count
748              Count of writes completed this interval.
749
750       writes_merged_count
751              Count of writes merged this interval.
752
753       write_sector_count
754              Count of 512 byte sectors written this interval.
755
756       write_time
757              Accumulated duration of all write requests (ns).
758
759       in_progress_count
760              Count of requests currently in progress.
761
762       io_ticks
763              Nanoseconds spent servicing requests.
764
765       queue_ticks
766              This field is incremented at each I/O start, I/O completion, I/O
767              merge, or read of these stats by the number of I/Os in  progress
768              multiplied  by  the number of milliseconds spent doing I/O since
769              the last update of this field.  This can provide an easy measure
770              of  both I/O completion time and the backlog that may be accumu‐
771              lating.
772
773       read_ticks
774              Nanoseconds spent servicing reads.
775
776       write_ticks
777              Nanoseconds spent servicing writes.
778
779   Histogram fields
780       Histograms measure the frequency distribution  of  user  specified  I/O
781       latency intervals. Histogram bin boundaries are specified when a region
782       is created.
783
784       A brief representation of the histogram values  and  latency  intervals
785       can be included in the report using these fields.
786
787       hist_count
788              A  list  of the histogram counts for the current statistics area
789              in order of ascending latency value. Each value  represents  the
790              number  of  I/Os with latency times falling into that bin's time
791              range during the sample period.
792
793       hist_count_bounds
794              A list of the histogram counts for the current  statistics  area
795              in  order  of  ascending latency value including bin boundaries:
796              each count is prefixed by the lower bound of  the  corresponding
797              histogram bin.
798
799       hist_count_ranges
800              A  list  of the histogram counts for the current statistics area
801              in order of ascending latency value  including  bin  boundaries:
802              each count is prefixed by both the lower and upper bounds of the
803              corresponding histogram bin.
804
805       hist_percent
806              A list of the relative histogram values for the current  statis‐
807              tics  area  in  order of ascending latency value, expressed as a
808              percentage. Each value represents the proportion  of  I/Os  with
809              latency times falling into that bin's time range during the sam‐
810              ple period.
811
812       hist_percent_bounds
813              A list of the relative histogram values for the current  statis‐
814              tics  area  in  order of ascending latency value, expressed as a
815              percentage and including bin boundaries. Each  value  represents
816              the  proportion  of  I/Os  with  latency times falling into that
817              bin's time range during the sample period and is  prefixed  with
818              the corresponding bin's lower bound.
819
820       hist_percent_ranges
821              A  list of the relative histogram values for the current statis‐
822              tics area in order of ascending latency value,  expressed  as  a
823              percentage  and  including bin boundaries. Each value represents
824              the proportion of I/Os with  latency  times  falling  into  that
825              bin's  time  range during the sample period and is prefixed with
826              the corresponding bin's lower and upper bounds.
827
828       hist_bounds
829              A list of the histogram boundary values for the current  statis‐
830              tics  area  in order of ascending latency value.  The values are
831              expressed in whole units of seconds,  miliseconds,  microseconds
832              or nanoseconds with a suffix indicating the unit.
833
834       hist_ranges
835              A  list  of  the histogram bin ranges for the current statistics
836              area in order  of  ascending  latency  value.   The  values  are
837              expressed  as  "LOWER-UPPER" in whole units of seconds, milisec‐
838              onds, microseconds or nanoseconds with a suffix  indicating  the
839              unit.
840
841       hist_bins
842              The number of latency histogram bins configured for the area.
843

EXAMPLES

845       Create a whole-device region with one area on vg00/lvol1
846       # dmstats create vg00/lvol1
847       vg00/lvol1: Created new region with 1 area(s) as region ID 0
848
849       Create a 32M region 1G into device d0
850       # dmstats create --start 1G --length 32M d0
851       d0: Created new region with 1 area(s) as region ID 0
852
853       Create a whole-device region with 8 areas on every device
854       # dmstats create --areas 8
855       vg00-lvol1: Created new region with 8 area(s) as region ID 0
856       vg00-lvol2: Created new region with 8 area(s) as region ID 0
857       vg00-lvol3: Created new region with 8 area(s) as region ID 0
858       vg01-lvol0: Created new region with 8 area(s) as region ID 2
859       vg01-lvol1: Created new region with 8 area(s) as region ID 0
860       vg00-lvol2: Created new region with 8 area(s) as region ID 1
861
862       Delete all regions on all devices
863       # dmstats delete --alldevices --allregions
864
865       Create  a  whole-device  region  with areas 10GiB in size on vg00/lvol1
866       using dmsetup
867       # dmsetup stats create --areasize 10G vg00/lvol1
868       vg00-lvol1: Created new region with 5 area(s) as region ID 1
869
870       Create a 1GiB region with 16 areas at the start of vg00/lvol1
871       # dmstats create --start 0 --len 1G --areas=16 vg00/lvol1
872       vg00-lvol1: Created new region with 16 area(s) as region ID 0
873
874       List the statistics regions registered on vg00/lvol1
875       # dmstats list vg00/lvol1
876       Name             RgID  RStart RSize  #Areas ASize  ProgID
877       vg00-lvol1           0      0 61.00g      1 61.00g dmstats
878       vg00-lvol1           1 61.00g 19.20g      1 19.20g dmstats
879       vg00-lvol1           2 80.20g  2.14g      1  2.14g dmstats
880
881       Display five statistics reports for vg00/lvol1 at an  interval  of  one
882       second
883       # dmstats report --interval 1 --count 5 vg00/lvol1
884       # dmstats report
885       Name              RgID  ArID  AStart ASize  RRqM/s   WRqM/s   R/s   W/s
886       RSz/s WSz/s   AvRqSz  QSize Util%      AWait RdAWa WrAWa
887       vg_hex-lv_home       0     0       0  61.00g      0.00      0.00   0.00
888       218.00     0   1.04m   4.50k  2.97      81.70 13.62  0.00 13.62
889       vg_hex-lv_home        1      0  61.00g  19.20g      0.00     0.00  0.00
890       5.00     0 548.00k 109.50k  0.14      11.00 27.40  0.00 27.40
891       vg_hex-lv_home       2     0  80.20g   2.14g      0.00      0.00   0.00
892       14.00     0   1.15m  84.00k  0.39      18.70 27.71  0.00 27.71
893
894       Create one region for reach target contained in device vg00/lvol1
895       # dmstats create --segments vg00/lvol1
896       vg00-lvol1: Created new region with 1 area(s) as region ID 0
897       vg00-lvol1: Created new region with 1 area(s) as region ID 1
898       vg00-lvol1: Created new region with 1 area(s) as region ID 2
899
900       Create  regions  mapping  each  file in the directory images/ and place
901       them into separate groups, each named after the corresponding file
902       # dmstats create --filemap images/*
903       images/vm1.qcow2: Created new group with 87 region(s) as group ID 0.
904       images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87.
905       images/vm2.qcow2: Created new group with 11 region(s) as group ID 95.
906       images/vm2-1.qcow2: Created new group with 1454 region(s) as  group  ID
907       106.
908       images/vm3.img: Created new group with 2 region(s) as group ID 1560.
909
910       Print raw counters for region 4 on device d0
911       # dmstats print --regionid 4 d0
912       2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41
913

AUTHORS

915       Bryn M. Reeves <bmr@redhat.com>
916

SEE ALSO

918       dmsetup(8)
919
920       LVM2 resource page: https://www.sourceware.org/lvm2/
921       Device-mapper resource page: http://sources.redhat.com/dm/
922
923       Device-mapper statistics kernel documentation
924       Documentation/device-mapper/statistics.txt
925
926
927
928Linux                             Jun 23 2016                       DMSTATS(8)
Impressum