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 When peforming a list or report, include objects of type area in
73 the results.
74 --areas nr_areas
76 Specify the number of statistics areas to create within a new
77 region.
78 --areasize area_size[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
80 Specify the size of areas into which a new region should be di‐
81 vided. An optional suffix selects units of: (b)ytes, (s)ectors,
82 (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
83 (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead
84 of 1024.
85 --clear
87 When printing statistics counters, also atomically reset them to
88 zero.
89 --count count
91 Specify the iteration count for repeating reports. If the count
92 argument is zero reports will continue to repeat until inter‐
93 rupted.
94 --group
96 When peforming a list or report, include objects of type group
97 in the results.
98 --filemap
100 Instead of creating regions on a device as specified by command
101 line options, open the file found at each file_path argument,
102 and create regions corresponding to the locations of the on-disk
103 extents allocated to the file(s).
104 --nomonitor
106 Disable the dmfilemapd daemon when creating new file mapped
107 groups. Normally the device-mapper filemap monitoring daemon,
108 dmfilemapd, is started for each file mapped group to update the
109 set of regions as the file changes on-disk: use of this option
110 disables this behaviour.
111 Regions in the group may still be updated with the up‐
113 date_filemap command, or by starting the daemon manually.
114 --follow follow_mode
116 Specify the dmfilemapd file following mode. The file map moni‐
117 toring daemon can monitor files in two distinct ways: the mode
118 affects the behaviour of the daemon when a file under monitoring
119 is renamed or unlinked, and the conditions which cause the dae‐
120 mon to terminate.
121 The follow_mode argument is either "inode", for follow-inode
123 mode, or "path", for follow-path.
124 If follow-inode mode is used, the daemon will hold the file
126 open, and continue to update regions from the same file descrip‐
127 tor. This means that the mapping will follow rename, move (with‐
128 in the same file system), and unlink operations. This mode is
129 useful if the file is expected to be moved, renamed, or unlinked
130 while it is being monitored.
131 In follow-inode mode, the daemon will exit once it detects that
133 the file has been unlinked and it is the last holder of a refer‐
134 ence to it.
135 If follow-path is used, the daemon will re-open the provided
137 path on each monitoring iteration. This means that the group
138 will be updated to reflect a new file being moved to the same
139 path as the original file. This mode is useful for files that
140 are expected to be updated via unlink and rename.
141 In follow-path mode, the daemon will exit if the file is removed
143 and not replaced within a brief tolerance interval.
144 In either mode, the daemon exits automatically if the monitored
146 group is removed.
147 --foreground
149 Specify that the dmfilemapd daemon should run in the foreground.
150 The daemon will not fork into the background, and will replace
151 the dmstats command that started it.
152 --groupid id
154 Specify the group to operate on.
155 --bounds histogram_boundaries[ns|us|ms|s]
157 Specify the boundaries of a latency histogram to be tracked for
158 the region as a comma separated list of latency values. Latency
159 values are given in nanoseconds. An optional unit suffix of
160 ns,us,ms, or s may be given after each value to specify units of
161 nanoseconds, microseconds, miliseconds or seconds respectively.
162 --histogram
164 When used with the report and list commands select default
165 fields that emphasize latency histogram data.
166 --interval seconds
168 Specify the interval in seconds between successive iterations
169 for repeating reports. If --interval is specified but --count is
170 not, reports will continue to repeat until interrupted.
171 --length length[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
173 Specify the length of a new statistics region in sectors. An op‐
174 tional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes,
175 (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes.
176 Capitalise to use multiples of 1000 (S.I.) instead of 1024.
177 -j|--major major
179 Specify the major number.
180 -m|--minor minor
182 Specify the minor number.
183 --nogroup
185 When creating regions mapping the extents of a file in the file
186 system, do not create a group or set an alias.
187 --nosuffix
189 Suppress the suffix on output sizes. Use with --units (except h
190 and H) if processing the output.
191 --notimesuffix
193 Suppress the suffix on output time values. Histogram boundary
194 values will be reported in units of nanoseconds.
195 -o|--options
197 Specify which report fields to display.
198 -O|--sort sort_fields
200 Sort output according to the list of fields given. Precede any
201 sort field with '-' for a reverse sort on that column.
202 --precise
204 Attempt to use nanosecond precision counters when creating new
205 statistics regions.
206 --programid id
208 Specify a program ID string. When creating new statistics re‐
209 gions this string is stored with the region. Subsequent opera‐
210 tions may supply a program ID in order to select only regions
211 with a matching value. The default program ID for dmstats-man‐
212 aged regions is "dmstats".
213 --region
215 When peforming a list or report, include objects of type region
216 in the results.
217 --regionid id
219 Specify the region to operate on.
220 --regions region_list
222 Specify a list of regions to group. The group list is a comma-
223 separated list of region identifiers. Continuous sequences of
224 identifiers may be expressed as a hyphen separated range, for
225 example: '1-10'.
226 --relative
228 If displaying the histogram report show relative (percentage)
229 values instead of absolute counts.
230 -S|--select selection
232 Display only rows that match selection criteria. All rows with
233 the additional "selected" column (-o selected) showing 1 if the
234 row matches the selection and 0 otherwise. The selection crite‐
235 ria are defined by specifying column names and their valid val‐
236 ues while making use of supported comparison operators.
237 --start start[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
239 Specify the start offset of a new statistics region in sectors.
240 An optional suffix selects units of: (b)ytes, (s)ectors,
241 (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
242 (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead
243 of 1024.
244 --segments
246 When used with create, create a new statistics region for each
247 target contained in the given device(s). This causes a separate
248 region to be allocated for each segment of the device.
249 The newly created regions are automatically placed into a group
251 unless the --nogroup option is given. When grouping is enabled a
252 group alias may be specified using the --alias option.
253 --units [units][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
255 Set the display units for report output. All sizes are output
256 in these units: (h)uman-readable, (b)ytes, (s)ectors,
257 (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
258 (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead
259 of 1024. Can also specify custom units e.g. --units 3M.
260 --userdata user_data
262 Specify user data (a word) to be stored with a new region. The
263 value is added to any internal auxiliary data (for example,
264 group information), and stored with the region in the aux_data
265 field provided by the kernel. Whitespace is not permitted.
266 -u|--uuid
268 Specify the uuid.
269 -v|--verbose [-v|--verbose]
271 Produce additional output.
272
274 clear device_name [--allprograms|--programid id]
275 [--allregions|--regionid id]
276 Instructs the kernel to clear statistics counters for the spefi‐
277 cied regions (with the exception of in-flight IO counters).
278 create device_name...|file_path...|--alldevices [--areas
280 nr_areas|--areasize area_size] [--bounds histogram_boundaries]
281 [--filemap] [--follow follow_mode] [--foreground] [--nomonitor]
282 [--nogroup] [--precise] [--start start_sector --length
283 length|--segments] [--userdata user_data] [--programid id]
284 Creates one or more new statistics regions on the specified de‐
285 vice(s).
286 The region will span the entire device unless --start and
288 --length or --segments are given. The --start an --length op‐
289 tions allow a region of arbitrary length to be placed at an ar‐
290 bitrary offset into the device. The --segments option causes a
291 new region to be created for each target in the corresponding
292 device-mapper device's table.
293 If the --precise option is used the command will attempt to cre‐
295 ate a region using nanosecond precision counters.
296 If --bounds is given a latency histogram will be tracked for the
298 new region. The boundaries of the histogram bins are given as a
299 comma separated list of latency values. There is an implicit
300 lower bound of zero on the first bin and an implicit upper bound
301 of infinity (or the configured interval duration) on the final
302 bin.
303 Latencies are given in nanoseconds. An optional unit suffix of
305 ns, us, ms, or s may be given after each value to specify units
306 of nanoseconds, microseconds, miliseconds or seconds respective‐
307 ly, so for example, 10ms is equivalent to 10000000. Latency val‐
308 ues with a precision of less than one milisecond can only be
309 used when precise timestamps are enabled: if --precise is not
310 given and values less than one milisecond are used it will be
311 enabled automatically.
312 An optional program_id or user_data string may be associated
314 with the region. A program_id may then be used to select regions
315 for subsequent list, print, and report operations. The user_data
316 stores an arbitrary string and is not used by dmstats or the de‐
317 vice-mapper kernel statistics subsystem.
318 By default dmstats creates regions with a program_id of "dm‐
320 stats".
321 On success the region_id of the newly created region is printed
323 to stdout.
324 If the --filemap option is given with a regular file, or list of
326 files, as the file_path argument, instead of creating regions
327 with parameters specified on the command line, dmstats will open
328 the files located at file_path and create regions corresponding
329 to the physical extents allocated to the file. This can be used
330 to monitor statistics for individual files in the file system,
331 for example, virtual machine images, swap areas, or large data‐
332 base files.
333 To work with the --filemap option, files must be located on a
335 local file system, backed by a device-mapper device, that sup‐
336 ports physical extent data using the FIEMAP ioctl (Ext4 and XFS
337 for e.g.).
338 By default regions that map a file are placed into a group and
340 the group alias is set to the basename of the file. This behav‐
341 iour can be overridden with the --alias and --nogroup options.
342 Creating a group that maps a file automatically starts a daemon,
344 dmfilemapd to monitor the file and update the mapping as the ex‐
345 tents allocated to the file change. This behaviour can be dis‐
346 abled using the --nomonitor option.
347 Use the --group option to only display information for groups
349 when listing and reporting.
350 delete device_name|--alldevices [--allprograms|--programid id]
352 [--allregions|--regionid id]
353 Delete the specified statistics region. All counters and re‐
354 sources used by the region are released and the region will not
355 appear in the output of subsequent list, print, or report opera‐
356 tions.
357 All regions registered on a device may be removed using --allre‐
359 gions.
360 To remove all regions on all devices both --allregions and
362 --alldevices must be used.
363 If a --groupid is given instead of a --regionid the command will
365 attempt to delete the group and all regions that it contains.
366 If a deleted region is the first member of a group of regions
368 the group will also be removed.
369 group [device_name|--alldevices] [--alias name] [--regions regions]
371 Combine one or more statistics regions on the specified device
372 into a group.
373 The list of regions to be grouped is specified with --regions
375 and an optional alias may be assigned with --alias. The set of
376 regions is given as a comma-separated list of region identi‐
377 fiers. A continuous range of identifers spanning from R1 to R2
378 may be expressed as 'R1-R2'.
379 Regions that have a histogram configured can be grouped: in this
381 case the number of histogram bins and their bounds must match
382 exactly.
383 On success the group list and newly created group_id are printed
385 to stdout.
386 The group metadata is stored with the first (lowest numbered)
388 region_id in the group: deleting this region will also delete
389 the group and other group members will be returned to their pri‐
390 or state.
391 help [-c|-C|--columns]
393 Outputs a summary of the commands available, optionally includ‐
394 ing the list of report fields.
395 list [device_name] [--histogram] [--allprograms|--programid id]
397 [--units units] [--area] [--region] [--group] [--nosuffix]
398 [--notimesuffix] [-v|--verbose]
399 List the statistics regions, areas, or groups registered on the
400 device. If the --allprograms switch is given all regions will
401 be listed regardless of region program ID values.
402 By default only regions and groups are included in list output.
404 If -v or --verbose is given the report will also include a row
405 of information for each configured group and for each area con‐
406 tained in each region displayed.
407 Regions that contain a single area are by default omitted from
409 the verbose list since their properties are identical to the
410 area that they contain - to view all regions regardless of the
411 number of areas present use --region). To also view the areas
412 contained within regions use --area.
413 If --histogram is given the report will include the bin count
415 and latency boundary values for any configured histograms.
416 print [device_name] [--clear] [--allprograms|--programid id]
418 [--allregions|--regionid id]
419 Print raw statistics counters for the specified region or for
420 all present regions.
421 report [device_name] [--interval seconds] [--count count] [--units
423 units] [--histogram] [--allprograms|--programid id]
424 [--allregions|--regionid id] [--area] [--region] [--group]
425 [-O|--sort sort_fields] [-S|--select selection] [--units units]
426 [--nosuffix] [--notimesuffix]
427 Start a report for the specified object or for all present ob‐
428 jects. If the count argument is specified, the report will re‐
429 peat at a fixed interval set by the --interval option. The de‐
430 fault interval is one second.
431 If the --allprograms switch is given, all regions will be list‐
433 ed, regardless of region program ID values.
434 If the --histogram is given the report will include the his‐
436 togram values and latency boundaries.
437 If the --relative is used the default histogram field displays
439 bin values as a percentage of the total number of I/Os.
440 Object types (areas, regions and groups) to include in the re‐
442 port are selected using the --area, --region, and --group op‐
443 tions.
444 ungroup [device_name|--alldevices] [--groupid id]
446 Remove an existing group and return all the group's regions to
447 their original state.
448 The group to be removed is specified using --groupid.
450 update_filemap file_path [--groupid id] [--follow follow_mode]
452 [--foreground]
453 Update a group of dmstats regions specified by group_id, that
454 were previously created with --filemap, either directly, or by
455 starting the monitoring daemon, dmfilemapd.
456 This will add and remove regions to reflect changes in the allo‐
458 cated extents of the file on-disk, since the time that it was
459 crated or last updated.
460 Use of this command is not normally needed since the dmfilemapd
462 daemon will automatically monitor filemap groups and perform
463 these updates when required.
464 If a filemapped group was created with --nomonitor, or the dae‐
466 mon has been killed, the update_filemap can be used to manually
467 force an update or start a new daemon.
468 Use --nomonitor to force a direct update and disable starting
470 the monitoring daemon.
471
473 The device-mapper statistics facility allows separate performance coun‐
474 ters to be maintained for arbitrary regions of devices. A region may
475 span any range: from a single sector to the whole device. A region may
476 be further sub-divided into a number of distinct areas (one or more),
477 each with its own counter set. In this case a summary value for the en‐
478 tire region is also available for use in reports.
479 In addition, one or more regions on one device can be combined into a
481 statistics group. Groups allow several regions to be aggregated and re‐
482 ported as a single entity; counters for all regions and areas are
483 summed and used to report totals for all group members. Groups also
484 permit the assignment of an optional alias, allowing meaningful names
485 to be associated with sets of regions.
486 The group metadata is stored with the first (lowest numbered) region_id
488 in the group: deleting this region will also delete the group and other
489 group members will be returned to their prior state.
490 By default new regions span the entire device. The --start and --length
492 options allows a region of any size to be placed at any location on the
493 device.
494 Using offsets it is possible to create regions that map individual ob‐
496 jects within a block device (for example: partitions, files in a file
497 system, or stripes or other structures in a RAID volume). Groups allow
498 several non-contiguous regions to be assembled together for reporting
499 and data aggregation.
500 A region may be either divided into the specified number of equal-sized
502 areas, or into areas of the given size by specifying one of --areas or
503 --areasize when creating a region with the create command. Depending on
504 the size of the areas and the device region the final area within the
505 region may be smaller than requested.
506 Region identifiers
508 Each region is assigned an identifier when it is created that is used
509 to reference the region in subsequent operations. Region identifiers
510 are unique within a given device (including across different program_id
511 values).
512 Depending on the sequence of create and delete operations, gaps may ex‐
514 ist in the sequence of region_id values for a particular device.
515 The region_id should be treated as an opaque identifier used to refer‐
517 ence the region.
518 Group identifiers
520 Groups are also assigned an integer identifier at creation time; like
521 region identifiers, group identifiers are unique within the containing
522 device.
523 The group_id should be treated as an opaque identifier used to refer‐
525 ence the group.
526
528 Using --filemap, it is possible to create regions that correspond to
529 the extents of a file in the file system. This allows IO statistics to
530 be monitored on a per-file basis, for example to observe large database
531 files, virtual machine images, or other files of interest.
532 To be able to use file mapping, the file must be backed by a device-
534 mapper device, and in a file system that supports the FIEMAP ioctl (and
535 which returns data describing the physical location of extents). This
536 currently includes xfs(5) and ext4(5).
537 By default the regions making up a file are placed together in a group,
539 and the group alias is set to the basename(3) of the file. This allows
540 statistics to be reported for the file as a whole, aggregating values
541 for the regions making up the group. To see only the whole file (group)
542 when using the list and report commands, use --group.
543 Since it is possible for the file to change after the initial group of
545 regions is created, the update_filemap command, and dmfilemapd daemon
546 are provided to update file mapped groups either manually or automati‐
547 cally.
548 File follow modes
550 The file map monitoring daemon can monitor files in two distinct ways:
551 follow-inode mode, and follow-path mode.
552 The mode affects the behaviour of the daemon when a file under monitor‐
554 ing is renamed or unlinked, and the conditions which cause the daemon
555 to terminate.
556 If follow-inode mode is used, the daemon will hold the file open, and
558 continue to update regions from the same file descriptor. This means
559 that the mapping will follow rename, move (within the same file sys‐
560 tem), and unlink operations. This mode is useful if the file is expect‐
561 ed to be moved, renamed, or unlinked while it is being monitored.
562 In follow-inode mode, the daemon will exit once it detects that the
564 file has been unlinked and it is the last holder of a reference to it.
565 If follow-path is used, the daemon will re-open the provided path on
567 each monitoring iteration. This means that the group will be updated to
568 reflect a new file being moved to the same path as the original file.
569 This mode is useful for files that are expected to be updated via un‐
570 link and rename.
571 In follow-path mode, the daemon will exit if the file is removed and
573 not replaced within a brief tolerance interval (one second).
574 To stop the daemon, delete the group containing the mapped regions: the
576 daemon will automatically shut down.
577 The daemon can also be safely killed at any time and the group kept: if
579 the file is still being allocated the mapping will become progressively
580 out-of-date as extents are added and removed (in this case the daemon
581 can be re-started or the group updated manually with the update_filemap
582 command).
583 See the create command and --filemap, --follow, and --nomonitor options
585 for further information.
586 Limitations
588 The daemon attempts to maintain good synchronisation between the file
589 extents and the regions contained in the group, however, since it can
590 only react to new allocations once they have been written, there are
591 inevitably some IO events that cannot be counted when a file is grow‐
592 ing, particularly if the file is being extended by a single thread
593 writing beyond end-of-file (for example, the dd program).
594 There is a further loss of events in that there is currently no way to
596 atomically resize a dmstats region and preserve its current counter
597 values. This affects files when they grow by extending the final ex‐
598 tent, rather than allocating a new extent: any events that had accumu‐
599 lated in the region between any prior operation and the resize are
600 lost.
601 File mapping is currently most effective in cases where the majority of
603 IO does not trigger extent allocation. Future updates may address these
604 limitations when kernel support is available.
605
607 The dmstats report provides several types of field that may be added to
608 the default field set, or used to create custom reports.
609 All performance counters and metrics are calculated per-area.
611 Derived metrics
613 A number of metrics fields are included that provide high level perfor‐
614 mance indicators. These are based on the fields provided by the conven‐
615 tional Linux iostat program and are derived from the basic counter val‐
616 ues provided by the kernel for each area.
617 reads_merged_per_sec
619 Reads merged per second.
620 writes_merged_per_sec
622 Writes merged per second.
623 reads_per_sec
625 Reads completed per second.
626 writes_per_sec
628 Writes completed per second.
629 read_size_per_sec
631 Size of data read per second.
632 write_size_per_sec
634 Size of data written per second.
635 avg_request_size
637 Average request size.
638 queue_size
640 Average queue size.
641 await The average wait time for read and write operations.
643 r_await
645 The average wait time for read operations.
646 w_await
648 The average wait time for write operations.
649 throughput
651 The device throughput in operations per second.
652 service_time
654 The average service time (in milliseconds) for operations issued
655 to the device.
656 util Percentage of CPU time during which I/O requests were issued to
658 the device (bandwidth utilization for the device). Device satu‐
659 ration occurs when this value is close to 100%.
660 Group, region and area meta fields
662 Meta fields provide information about the groups, regions, or areas
663 that the statistics values relate to. This includes the region and area
664 identifier, start, length, and counts, as well as the program ID and
665 user data values.
666 region_id
668 Region identifier. This is a non-negative integer returned by
669 the kernel when a statistics region is created.
670 region_start
672 The region start location. Display units are selected by the
673 --units option.
674 region_len
676 The length of the region. Display units are selected by the
677 --units option.
678 area_id
680 Area identifier. Area identifiers are assigned by the device-
681 mapper statistics library and uniquely identify each area within
682 a region. Each ID corresponds to a distinct set of performance
683 counters for that area of the statistics region. Area identi‐
684 fiers are always monotonically increasing within a region so
685 that higher ID values correspond to greater sector addresses
686 within the area and no gaps in the sequence of identifiers ex‐
687 ist.
688 area_start
690 The area start location. Display units are selected by the
691 --units option.
692 area_len
694 The length of the area. Display units are selected by the
695 --units option.
696 area_count
698 The number of areas in this region.
699 program_id
701 The program ID value associated with this region.
702 user_data
704 The user data value associated with this region.
705 group_id
707 Group identifier. This is a non-negative integer returned by the
708 dmstats group command when a statistics group is created.
709 interval_ns
711 The estimated interval over which the current counter values
712 have accumulated. The value is reported as an integer expressed
713 in units of nanoseconds.
714 interval
716 The estimated interval over which the current counter values
717 have accumulated. The value is reported as a real number in
718 units of seconds.
719 Basic counters
721 Basic counters provide access to the raw counter data from the kernel,
722 allowing further processing to be carried out by another program.
723 The kernel provides thirteen separate counters for each statistics
725 area. The first eleven of these match the counters provided in
726 /proc/diskstats or /sys/block/*/*/stat. The final pair provide separate
727 counters for read and write time.
728 read_count
730 Count of reads completed this interval.
731 reads_merged_count
733 Count of reads merged this interval.
734 read_sector_count
736 Count of 512 byte sectors read this interval.
737 read_time
739 Accumulated duration of all read requests (ns).
740 write_count
742 Count of writes completed this interval.
743 writes_merged_count
745 Count of writes merged this interval.
746 write_sector_count
748 Count of 512 byte sectors written this interval.
749 write_time
751 Accumulated duration of all write requests (ns).
752 in_progress_count
754 Count of requests currently in progress.
755 io_ticks
757 Nanoseconds spent servicing requests.
758 queue_ticks
760 This field is incremented at each I/O start, I/O completion, I/O
761 merge, or read of these stats by the number of I/Os in progress
762 multiplied by the number of milliseconds spent doing I/O since
763 the last update of this field. This can provide an easy measure
764 of both I/O completion time and the backlog that may be accumu‐
765 lating.
766 read_ticks
768 Nanoseconds spent servicing reads.
769 write_ticks
771 Nanoseconds spent servicing writes.
772 Histogram fields
774 Histograms measure the frequency distribution of user specified I/O la‐
775 tency intervals. Histogram bin boundaries are specified when a region
776 is created.
777 A brief representation of the histogram values and latency intervals
779 can be included in the report using these fields.
780 hist_count
782 A list of the histogram counts for the current statistics area
783 in order of ascending latency value. Each value represents the
784 number of I/Os with latency times falling into that bin's time
785 range during the sample period.
786 hist_count_bounds
788 A list of the histogram counts for the current statistics area
789 in order of ascending latency value including bin boundaries:
790 each count is prefixed by the lower bound of the corresponding
791 histogram bin.
792 hist_count_ranges
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 both the lower and upper bounds of the
797 corresponding histogram bin.
798 hist_percent
800 A list of the relative histogram values for the current statis‐
801 tics area in order of ascending latency value, expressed as a
802 percentage. Each value represents the proportion of I/Os with
803 latency times falling into that bin's time range during the sam‐
804 ple period.
805 hist_percent_bounds
807 A list of the relative histogram values for the current statis‐
808 tics area in order of ascending latency value, expressed as a
809 percentage and including bin boundaries. Each value represents
810 the proportion of I/Os with latency times falling into that
811 bin's time range during the sample period and is prefixed with
812 the corresponding bin's lower bound.
813 hist_percent_ranges
815 A list of the relative histogram values for the current statis‐
816 tics area in order of ascending latency value, expressed as a
817 percentage and including bin boundaries. Each value represents
818 the proportion of I/Os with latency times falling into that
819 bin's time range during the sample period and is prefixed with
820 the corresponding bin's lower and upper bounds.
821 hist_bounds
823 A list of the histogram boundary values for the current statis‐
824 tics area in order of ascending latency value. The values are
825 expressed in whole units of seconds, miliseconds, microseconds
826 or nanoseconds with a suffix indicating the unit.
827 hist_ranges
829 A list of the histogram bin ranges for the current statistics
830 area in order of ascending latency value. The values are ex‐
831 pressed as "LOWER-UPPER" in whole units of seconds, miliseconds,
832 microseconds or nanoseconds with a suffix indicating the unit.
833 hist_bins
835 The number of latency histogram bins configured for the area.
836
838 Create a whole-device region with one area on vg00/lvol1
839 # dmstats create vg00/lvol1
840 vg00/lvol1: Created new region with 1 area(s) as region ID 0
841 Create a 32M region 1G into device d0
843 # dmstats create --start 1G --length 32M d0
844 d0: Created new region with 1 area(s) as region ID 0
845 Create a whole-device region with 8 areas on every device
847 # dmstats create --areas 8
848 vg00-lvol1: Created new region with 8 area(s) as region ID 0
849 vg00-lvol2: Created new region with 8 area(s) as region ID 0
850 vg00-lvol3: Created new region with 8 area(s) as region ID 0
851 vg01-lvol0: Created new region with 8 area(s) as region ID 2
852 vg01-lvol1: Created new region with 8 area(s) as region ID 0
853 vg00-lvol2: Created new region with 8 area(s) as region ID 1
854 Delete all regions on all devices
856 # dmstats delete --alldevices --allregions
857 Create a whole-device region with areas 10 GiB in size on vg00/lvol1
859 using dmsetup
860 # dmsetup stats create --areasize 10G vg00/lvol1
861 vg00-lvol1: Created new region with 5 area(s) as region ID 1
862 Create a 1 GiB region with 16 areas at the start of vg00/lvol1
864 # dmstats create --start 0 --len 1G --areas=16 vg00/lvol1
865 vg00-lvol1: Created new region with 16 area(s) as region ID 0
866 List the statistics regions registered on vg00/lvol1
868 # dmstats list vg00/lvol1
869 Name RgID RStart RSize #Areas ASize ProgID
870 vg00-lvol1 0 0 61.00g 1 61.00g dmstats
871 vg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats
872 vg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats
873 Display five statistics reports for vg00/lvol1 at an interval of one
875 second
876 # dmstats report --interval 1 --count 5 vg00/lvol1
877 # dmstats report
878 Name RgID ArID AStart ASize RRqM/s WRqM/s R/s W/s
879 RSz/s WSz/s AvRqSz QSize Util% AWait RdAWa WrAWa
880 vg_hex-lv_home 0 0 0 61.00g 0.00 0.00 0.00
881 218.00 0 1.04m 4.50k 2.97 81.70 13.62 0.00 13.62
882 vg_hex-lv_home 1 0 61.00g 19.20g 0.00 0.00 0.00
883 5.00 0 548.00k 109.50k 0.14 11.00 27.40 0.00 27.40
884 vg_hex-lv_home 2 0 80.20g 2.14g 0.00 0.00 0.00
885 14.00 0 1.15m 84.00k 0.39 18.70 27.71 0.00 27.71
886 Create one region for reach target contained in device vg00/lvol1
888 # dmstats create --segments vg00/lvol1
889 vg00-lvol1: Created new region with 1 area(s) as region ID 0
890 vg00-lvol1: Created new region with 1 area(s) as region ID 1
891 vg00-lvol1: Created new region with 1 area(s) as region ID 2
892 Create regions mapping each file in the directory images/ and place
894 them into separate groups, each named after the corresponding file
895 # dmstats create --filemap images/*
896 images/vm1.qcow2: Created new group with 87 region(s) as group ID 0.
897 images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87.
898 images/vm2.qcow2: Created new group with 11 region(s) as group ID 95.
899 images/vm2-1.qcow2: Created new group with 1454 region(s) as group ID
900 106.
901 images/vm3.img: Created new group with 2 region(s) as group ID 1560.
902 Print raw counters for region 4 on device d0
904 # dmstats print --regionid 4 d0
905 2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41
906
908 Bryn M. Reeves <bmr@redhat.com>
909
911 dmsetup(8)
912 LVM2 resource page: ⟨https://www.sourceware.org/lvm2⟩
914 Device-mapper resource page: ⟨http://sources.redhat.com/dm⟩
915 Device-mapper statistics kernel documentation
917 Documentation/device-mapper/statistics.txt
918Linux Jun 23 2016 DMSTATS(8)