1DMSTATS(8) MAINTENANCE COMMANDS DMSTATS(8)
2
6 dmstats — device-mapper statistics management
7
9 dmsetup stats command [OPTIONS]
10 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
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 The first argument to dmstats is a command.
45 The second argument is the device name, uuid or major and minor num‐
47 bers.
48 Further options permit the selection of regions, output format control,
50 and reporting behaviour.
51 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
57 --alias name
58 Specify an alias name for a group.
59 --alldevices
61 If no device arguments are given allow operation on all devices
62 when creating or deleting regions.
63 --allprograms
65 Include regions from all program IDs for list and report opera‐
66 tions.
67 --allregions
69 Include all present regions for commands that normally accept a
70 single region identifier.
71 --area
73 When peforming a list or report, include objects of type area in
74 the results.
75 --areas nr_areas
77 Specify the number of statistics areas to create within a new
78 region.
79 --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 --clear
88 When printing statistics counters, also atomically reset them to
89 zero.
90 --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 --group
97 When peforming a list or report, include objects of type group
98 in the results.
99 --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 --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 Regions in the group may still be updated with the
114 update_filemap command, or by starting the daemon manually.
115 --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 The follow_mode argument is either "inode", for follow-inode
124 mode, or "path", for follow-path.
125 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 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 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 In follow-path mode, the daemon will exit if the file is removed
144 and not replaced within a brief tolerance interval.
145 In either mode, the daemon exits automatically if the monitored
147 group is removed.
148 --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 --groupid id
155 Specify the group to operate on.
156 --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 --histogram
165 When used with the report and list commands select default
166 fields that emphasize latency histogram data.
167 --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 --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 -j|--major major
181 Specify the major number.
182 -m|--minor minor
184 Specify the minor number.
185 --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 --nosuffix
191 Suppress the suffix on output sizes. Use with --units (except h
192 and H) if processing the output.
193 --notimesuffix
195 Suppress the suffix on output time values. Histogram boundary
196 values will be reported in units of nanoseconds.
197 -o|--options
199 Specify which report fields to display.
200 -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 --precise
206 Attempt to use nanosecond precision counters when creating new
207 statistics regions.
208 --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 --region
217 When peforming a list or report, include objects of type region
218 in the results.
219 --regionid id
221 Specify the region to operate on.
222 --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 --relative
230 If displaying the histogram report show relative (percentage)
231 values instead of absolute counts.
232 -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 --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 --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 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 --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 --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 -u|--uuid
270 Specify the uuid.
271 -v|--verbose [-v|--verbose]
273 Produce additional output.
274
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 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 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 If the --precise option is used the command will attempt to cre‐
297 ate a region using nanosecond precision counters.
298 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 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 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 By default dmstats creates regions with a program_id of
322 "dmstats".
323 On success the region_id of the newly created region is printed
325 to stdout.
326 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 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 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 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 Use the --group option to only display information for groups
351 when listing and reporting.
352 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 All regions registered on a device may be removed using --allre‐
361 gions.
362 To remove all regions on all devices both --allregions and
364 --alldevices must be used.
365 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 If a deleted region is the first member of a group of regions
370 the group will also be removed.
371 group [device_name|--alldevices] [--alias name] [--regions regions]
373 Combine one or more statistics regions on the specified device
374 into a group.
375 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 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 On success the group list and newly created group_id are printed
387 to stdout.
388 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 help [-c|-C|--columns]
395 Outputs a summary of the commands available, optionally includ‐
396 ing the list of report fields.
397 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 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 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 If --histogram is given the report will include the bin count
417 and latency boundary values for any configured histograms.
418 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 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 If the --allprograms switch is given, all regions will be
435 listed, regardless of region program ID values.
436 If the --histogram is given the report will include the his‐
438 togram values and latency boundaries.
439 If the --relative is used the default histogram field displays
441 bin values as a percentage of the total number of I/Os.
442 Object types (areas, regions and groups) to include in the
444 report are selected using the --area, --region, and --group
445 options.
446 ungroup [device_name|--alldevices] [--groupid id]
448 Remove an existing group and return all the group's regions to
449 their original state.
450 The group to be removed is specified using --groupid.
452 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 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 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 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 Use --nomonitor to force a direct update and disable starting
472 the monitoring daemon.
473
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 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 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 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 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 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 Region identifiers
510 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 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 The region_id should be treated as an opaque identifier used to refer‐
520 ence the region.
521 Group identifiers
523 Groups are also assigned an integer identifier at creation time; like
525 region identifiers, group identifiers are unique within the containing
526 device.
527 The group_id should be treated as an opaque identifier used to refer‐
529 ence the group.
530
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 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 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 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 File follow modes
554 The file map monitoring daemon can monitor files in two distinct ways:
556 follow-inode mode, and follow-path mode.
557 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 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 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 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 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 To stop the daemon, delete the group containing the mapped regions: the
581 daemon will automatically shut down.
582 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 See the create command and --filemap, --follow, and --nomonitor options
590 for further information.
591 Limitations
593 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 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 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
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 All performance counters and metrics are calculated per-area.
617 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 reads_merged_per_sec
625 Reads merged per second.
626 writes_merged_per_sec
628 Writes merged per second.
629 reads_per_sec
631 Reads completed per second.
632 writes_per_sec
634 Writes completed per second.
635 read_size_per_sec
637 Size of data read per second.
638 write_size_per_sec
640 Size of data written per second.
641 avg_request_size
643 Average request size.
644 queue_size
646 Average queue size.
647 await The average wait time for read and write operations.
649 r_await
651 The average wait time for read operations.
652 w_await
654 The average wait time for write operations.
655 throughput
657 The device throughput in operations per second.
658 service_time
660 The average service time (in milliseconds) for operations issued
661 to the device.
662 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 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 region_id
674 Region identifier. This is a non-negative integer returned by
675 the kernel when a statistics region is created.
676 region_start
678 The region start location. Display units are selected by the
679 --units option.
680 region_len
682 The length of the region. Display units are selected by the
683 --units option.
684 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 area_start
696 The area start location. Display units are selected by the
697 --units option.
698 area_len
700 The length of the area. Display units are selected by the
701 --units option.
702 area_count
704 The number of areas in this region.
705 program_id
707 The program ID value associated with this region.
708 user_data
710 The user data value associated with this region.
711 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 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 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 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 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 read_count
736 Count of reads completed this interval.
737 reads_merged_count
739 Count of reads merged this interval.
740 read_sector_count
742 Count of 512 byte sectors read this interval.
743 read_time
745 Accumulated duration of all read requests (ns).
746 write_count
748 Count of writes completed this interval.
749 writes_merged_count
751 Count of writes merged this interval.
752 write_sector_count
754 Count of 512 byte sectors written this interval.
755 write_time
757 Accumulated duration of all write requests (ns).
758 in_progress_count
760 Count of requests currently in progress.
761 io_ticks
763 Nanoseconds spent servicing requests.
764 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 read_ticks
774 Nanoseconds spent servicing reads.
775 write_ticks
777 Nanoseconds spent servicing writes.
778 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 A brief representation of the histogram values and latency intervals
785 can be included in the report using these fields.
786 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 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 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 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 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 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 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 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 hist_bins
842 The number of latency histogram bins configured for the area.
843
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 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 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 Delete all regions on all devices
863 # dmstats delete --alldevices --allregions
864 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 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 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 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 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 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 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
915 Bryn M. Reeves <bmr@redhat.com>
916
918 dmsetup(8)
919 LVM2 resource page: https://www.sourceware.org/lvm2/
921 Device-mapper resource page: http://sources.redhat.com/dm/
922 Device-mapper statistics kernel documentation
924 Documentation/device-mapper/statistics.txt
925Linux Jun 23 2016 DMSTATS(8)