1DMSTATS(8) MAINTENANCE COMMANDS DMSTATS(8)
2
3
4
6 dmstats — device-mapper statistics management
7
9 dmsetup stats command [options]
10
11 dmstats command [device_name |--uuid uuid|--major major --minor minor]
12 dmstats clear device_name [--allprograms|--programid id]
13 [--allregions|--regionid id]
14 dmstats create device_name [--alldevices] [--areas nr_areas|--areasize
15 area_size] [--bounds histogram_boundaries] [--precise] [--start
16 start_sector --length length|--segments] [--auxdata data]
17 [--programid id]
18 dmstats delete [device_name] [--alldevices] [--allprograms|--programid
19 id] [--allregions|--regionid id]
20 dmstats help [-c|-C|--columns]
21 dmstats list [device_name] [--histogram] [--allprograms|--programid id]
22 [--units units] [--nosuffix] [--notimesuffix]
23 [-v|--verbose[-v|--verbose]]
24 dmstats print [device_name] [--clear] [--allprograms|--programid id]
25 [--allregions|--regionid id]
26 dmstats report [device_name] [--interval seconds] [--count count]
27 [--units units] [--histogram] [--allprograms|--programid id]
28 [--allregions|--regionid id] [-O|--sort sort_fields]
29 [-S|--select selection] [--units units] [--nosuffix]
30 [--notimesuffix]
31
33 The dmstats program manages IO statistics regions for devices that use
34 the device-mapper driver. Statistics regions may be created, deleted,
35 listed and reported on using the tool.
36
37 The first argument to dmstats is a command.
38
39 The second argument is the device name, uuid or major and minor num‐
40 bers.
41
42 Further options permit the selection of regions, output format control,
43 and reporting behaviour.
44
45 When the program is run using the 'dmstats' alias, the command must be
46 the first argument and any switches and options should be specified
47 following the command itself. This limitation is not present when run
48 as 'dmsetup stats'.
49
50 When no device argument is given dmstats will by default operate on all
51 device-mapper devices present. The create and delete commands require
52 the use of --alldevices when used in this way.
53
55 --alldevices
56 If no device arguments are given allow operation on all devices
57 when creating or deleting regions.
58
59 --allprograms
60 Include regions from all program IDs for list and report opera‐
61 tions.
62
63 --allregions
64 Include all present regions for commands that normally accept a
65 single region identifier.
66
67 --areas nr_areas
68 Specify the number of statistics areas to create within a new
69 region.
70
71 --areasize area_size[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
72 Specify the size of areas into which a new region should be
73 divided. An optional suffix selects units of: (b)ytes,
74 (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes,
75 (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000
76 (S.I.) instead of 1024.
77
78 --auxdata aux_data
79 Specify auxilliary data (a string) to be stored with a new
80 region.
81
82 --clear
83 When printing statistics counters, also atomically reset them to
84 zero.
85
86 --count count
87 Specify the iteration count for repeating reports. If the count
88 argument is zero reports will continue to repeat until inter‐
89 rupted.
90
91 --bounds histogram_boundaries[ns|us|ms|s]
92 Specify the boundaries of a latency histogram to be tracked for
93 the region as a comma separated list of latency values. Latency
94 values are given in nanoseconds. An optional unit suffix of ns,
95 us, ms, or s may be given after each value to specify units of
96 nanoseconds, microseconds, miliseconds or seconds respectively.
97
98 --histogram
99 When used with the report and list commands select default
100 fields that emphasize latency histogram data.
101
102 --interval seconds
103 Specify the interval in seconds between successive iterations
104 for repeating reports. If --interval is specified but --count is
105 not, reports will continue to repeat until interrupted.
106
107 --length length[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
108 Specify the length of a new statistics region in sectors. An
109 optional suffix selects units of: (b)ytes, (s)ectors,
110 (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
111 (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead
112 of 1024.
113
114 -j|--major major
115 Specify the major number.
116
117 -m|--minor minor
118 Specify the minor number.
119
120 --nosuffix
121 Suppress the suffix on output sizes. Use with --units (except h
122 and H) if processing the output.
123
124 --notimesuffix
125 Suppress the suffix on output time values. Histogram boundary
126 values will be reported in units of nanoseconds.
127
128 -o|--options
129 Specify which report fields to display.
130
131 -O|--sort sort_fields
132 Sort output according to the list of fields given. Precede any
133 sort field with '-' for a reverse sort on that column.
134
135 --precise
136 Attempt to use nanosecond precision counters when creating new
137 statistics regions.
138
139 --programid id
140 Specify a program ID string. When creating new statistics
141 regions this string is stored with the region. Subsequent opera‐
142 tions may supply a program ID in order to select only regions
143 with a matching value. The default program ID for dmstats-man‐
144 aged regions is "dmstats".
145
146 --regionid id
147 Specify the region to operate on.
148
149 --relative
150 If displaying the histogram report show relative (percentage)
151 values instead of absolute counts.
152
153 -S|--select selection
154 Display only rows that match selection criteria. All rows with
155 the additional "selected" column (-o selected) showing 1 if the
156 row matches the selection and 0 otherwise. The selection crite‐
157 ria are defined by specifying column names and their valid val‐
158 ues while making use of supported comparison operators.
159
160 --start start[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
161 Specify the start offset of a new statistics region in sectors.
162 An optional suffix selects units of: (b)ytes, (s)ectors,
163 (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
164 (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead
165 of 1024.
166
167 --segments
168 Create a new statistics region for each target contained in the
169 target device. This causes a separate region to be allocated for
170 each segment of the device.
171
172 --units [units][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E]
173 Set the display units for report output. All sizes are output
174 in these units: (h)uman-readable, (b)ytes, (s)ectors,
175 (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes,
176 (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead
177 of 1024. Can also specify custom units e.g. --units 3M.
178
179 -u|--uuid
180 Specify the uuid.
181
182 -v|--verbose [-v|--verbose]
183 Produce additional output.
184
186 clear device_name [--allprograms|--programid id]
187 [--allregions|--regionid id]
188 Instructs the kernel to clear statistics counters for the spefi‐
189 cied regions (with the exception of in-flight IO counters).
190
191 create device_name [--alldevices] [--areas nr_areas|--areasize
192 area_size] [--bounds histogram_boundaries] [--precise] [--start
193 start_sector --length length|--segments] [--auxdata data]
194 [--programid id]
195 Creates one or more new statistics regions on the specified
196 device(s).
197
198 The region will span the entire device unless --start and
199 --length or --target are given. The --start and --length options
200 allow a region of arbitrary length to be placed at an arbitrary
201 offset into the device. The --segments option causes a new
202 region to be created for each target in the corresponding
203 device-mapper device's table.
204
205 If the --precise option is used the command will attempt to cre‐
206 ate a region using nanosecond precision counters.
207
208 If --bounds is given a latency histogram will be tracked for the
209 new region. The boundaries of the histogram bins are given as a
210 comma separated list of latency values. There is an implicit
211 lower bound of zero on the first bin and an implicit upper bound
212 of infinity (or the configured interval duration) on the final
213 bin.
214
215 Latencies are given in nanoseconds. An optional unit suffix of
216 ns, us, ms, or s may be given after each value to specify units
217 of nanoseconds, microseconds, miliseconds or seconds respec‐
218 tively, so for example, 10ms is equivalent to 10000000. Latency
219 values with a precision of less than one milisecond can only be
220 used when precise timestamps are enabled: if --precise is not
221 given and values less than one milisecond are used it will be
222 enabled automatically.
223
224 An optional program_id or aux_data string may be associated with
225 the region. A program_id may then be used to select regions for
226 subsequent list, print, and report operations. The aux_data
227 stores an arbitrary string and is not used by dmstats or the
228 device-mapper kernel statistics subsystem.
229
230 By default dmstats creates regions with a program_id of
231 "dmstats".
232
233 On success the region_id of the newly created region is printed
234 to stdout.
235
236 delete [device_name] [--alldevices] [--allprograms|--programid id]
237 [--allregions|--regionid id]
238 Delete the specified statistics region. All counters and
239 resources used by the region are released and the region will
240 not appear in the output of subsequent list, print, or report
241 operations.
242
243 All regions registered on a device may be removed using --allre‐
244 gions.
245
246 To remove all regions on all devices both --allregions and
247 --alldevices must be used.
248
249 help [-c|-C|--columns]
250 Outputs a summary of the commands available, optionally includ‐
251 ing the list of report fields.
252
253 list [device_name] [--histogram] [--allprograms|--programid id]
254 [--units units] [--nosuffix] [--notimesuffix]
255 [-v|--verbose[-v|--verbose]]
256 List the statistics regions registered on the device. If the
257 --allprograms switch is given all regions will be listed regard‐
258 less of region program ID values.
259
260 If -v or --verbose is given the report will include a row of
261 information for each area contained in each region displayed.
262
263 If --histogram is given the report will include the bin count
264 and latency boundary values for any configured histograms.
265
266 print [device_name] [--clear] [--allprograms|--programid id]
267 [--allregions|--regionid id]
268 Print raw statistics counters for the specified region or for
269 all present regions.
270
271 report [device_name] [--interval seconds] [--count count] [--units
272 units] [--histogram] [--allprograms|--programid id]
273 [--allregions|--regionid id] [-O|--sort sort_fields]
274 [-S|--select selection] [--units units] [--nosuffix]
275 [--notimesuffix]
276 Start a report for the specified region or for all present
277 regions. If the count argument is specified, the report will
278 repeat at a fixed interval set by the --interval option. The
279 default interval is one second.
280
281 If the --allprograms switch is given, all regions will be
282 listed, regardless of region program ID values.
283
284 If the --histogram is given the report will include the his‐
285 togram values and latency boundaries.
286
287 If the --relative is used the default histogram field displays
288 bin values as a percentage of the total number of I/Os.
289
291 The device-mapper statistics facility allows separate performance coun‐
292 ters to be maintained for arbitrary regions of devices. A region may
293 span any range: from a single sector to the whole device. A region may
294 be further sub-divided into a number of distinct areas (one or more),
295 each with its own counter set.
296
297 By default new regions span the entire device. The --start and --length
298 options allows a region of any size to be placed at any location on the
299 device.
300
301 A region may be either divided into the specified number of equal-sized
302 areas, or into areas of the given size by specifying one of --areas or
303 --areasize when creating a region with the create command. Depending on
304 the size of the areas and the device region the final area within the
305 region may be smaller than requested.
306
307 Region identifiers
308
309 Each region is assigned an identifier when it is created that is used
310 to reference the region in subsequent operations. Region identifiers
311 are unique within a given device (including across different program_id
312 values).
313
314 Depending on the sequence of create and delete operations, gaps may
315 exist in the sequence of region_id values for a particular device.
316
318 The dmstats report provides several types of field that may be added to
319 the default field set, or used to create custom reports.
320
321 All performance counters and metrics are calculated per-area.
322
323 Derived metrics
324 A number of metrics fields are included that provide high level perfor‐
325 mance indicators. These are based on the fields provided by the conven‐
326 tional Linux iostat program and are derived from the basic counter val‐
327 ues provided by the kernel for each area.
328
329 reads_merged_per_sec
330 Reads merged per second.
331
332 writes_merged_per_sec
333 Writes merged per second.
334
335 reads_per_sec
336 Reads completed per second.
337
338 writes_per_sec
339 Writes completed per second.
340
341 read_size_per_sec
342 Size of data read per second.
343
344 write_size_per_sec
345 Size of data written per second.
346
347 avg_request_size
348 Average request size.
349
350 queue_size
351 Average queue size.
352
353 await The average wait time for read and write operations.
354
355 r_await
356 The average wait time for read operations.
357
358 w_await
359 The average wait time for write operations.
360
361 throughput
362 The device throughput in operations per second.
363
364 service_time
365 The average service time (in milliseconds) for operations issued
366 to the device.
367
368 util Percentage of CPU time during which I/O requests were issued to
369 the device (bandwidth utilization for the device). Device satu‐
370 ration occurs when this value is close to 100%.
371
372 Region and area meta fields
373 Meta fields provide information about the region or area that the sta‐
374 tistics values relate to. This includes the region and area identifier,
375 start, length, and counts, as well as the program ID and auxiliary data
376 values.
377
378 region_id
379 Region identifier. This is a non-negative integer returned by
380 the kernel when a statistics region is created.
381
382 region_start
383 The region start location. Display units are selected by the
384 --units option.
385
386 region_len
387 The length of the region. Display units are selected by the
388 --units option.
389
390 area_id
391 Area identifier. Area identifiers are assigned by the device-
392 mapper statistics library and uniquely identify each area within
393 a region. Each ID corresponds to a distinct set of performance
394 counters for that area of the statistics region. Area identi‐
395 fiers are always monotonically increasing within a region so
396 that higher ID values correspond to greater sector addresses
397 within the area and no gaps in the sequence of identifiers
398 exist.
399
400 area_start
401 The area start location. Display units are selected by the
402 --units option.
403
404 area_len
405 The length of the area. Display units are selected by the
406 --units option.
407
408 area_count
409 The number of areas in this region.
410
411 program_id
412 The program ID value associated with this region.
413
414 aux_data
415 The auxiliary data value associated with this region.
416
417 interval_ns
418 The estimated interval over which the current counter values
419 have accumulated. The value is reported as an interger expressed
420 in units of nanoseconds.
421
422 interval
423 The estimated interval over which the current counter values
424 have accumulated. The value is reported as a real number in
425 units of seconds.
426
427 Basic counters
428 Basic counters provide access to the raw counter data from the kernel,
429 allowing further processing to be carried out by another program.
430
431 The kernel provides thirteen separate counters for each statistics
432 area. The first eleven of these match the counters provided in
433 /proc/diskstats or /sys/block/*/*/stat. The final pair provide separate
434 counters for read and write time.
435
436 read_count
437 Count of reads completed this interval.
438
439 reads_merged_count
440 Count of reads merged this interval.
441
442 read_sector_count
443 Count of 512 byte sectors read this interval.
444
445 read_time
446 Accumulated duration of all read requests (ns).
447
448 write_count
449 Count of writes completed this interval.
450
451 writes_merged_count
452 Count of writes merged this interval.
453
454 write_sector_count
455 Count of 512 byte sectors written this interval.
456
457 write_nsecs
458 Accumulated duration of all write requests (ns).
459
460 in_progress_count
461 Count of requests currently in progress.
462
463 io_ticks
464 Nanoseconds spent servicing requests.
465
466 queue_ticks
467 This field is incremented at each I/O start, I/O completion, I/O
468 merge, or read of these stats by the number of I/Os in progress
469 multiplied by the number of milliseconds spent doing I/O since
470 the last update of this field. This can provide an easy measure
471 of both I/O completion time and the backlog that may be accumu‐
472 lating.
473
474 read_ticks
475 Nanoseconds spent servicing reads.
476
477 write_ticks
478 Nanoseconds spent servicing writes.
479
480 Histogram fields
481 Histograms measure the frequency distribution of user specified I/O
482 latency intervals. Histogram bin boundaries are specified when a region
483 is created.
484
485 A brief representation of the histogram values and latency intervals
486 can be included in the report using these fields.
487
488 hist_count
489 A list of the histogram counts for the current statistics area
490 in order of ascending latency value. Each value represents the
491 number of I/Os with latency times falling into that bin's time
492 range during the sample period.
493
494 hist_count_bounds
495 A list of the histogram counts for the current statistics area
496 in order of ascending latency value including bin boundaries:
497 each count is prefixed by the lower bound of the corresponding
498 histogram bin.
499
500 hist_count_ranges
501 A list of the histogram counts for the current statistics area
502 in order of ascending latency value including bin boundaries:
503 each count is prefixed by both the lower and upper bounds of the
504 corresponding histogram bin.
505
506 hist_percent
507 A list of the relative histogram values for the current statis‐
508 tics area in order of ascending latency value, expressed as a
509 percentage. Each value represents the proportion of I/Os with
510 latency times falling into that bin's time range during the sam‐
511 ple period.
512
513 hist_percent_bounds
514 A list of the relative histogram values for the current statis‐
515 tics area in order of ascending latency value, expressed as a
516 percentage and including bin boundaries. Each value represents
517 the proportion of I/Os with latency times falling into that
518 bin's time range during the sample period and is prefixed with
519 the corresponding bin's lower bound.
520
521 hist_percent_ranges
522 A list of the relative histogram values for the current statis‐
523 tics area in order of ascending latency value, expressed as a
524 percentage and including bin boundaries. Each value represents
525 the proportion of I/Os with latency times falling into that
526 bin's time range during the sample period and is prefixed with
527 the corresponding bin's lower and upper bounds.
528
529 hist_bounds
530 A list of the histogram boundary values for the current statis‐
531 tics area in order of ascending latency value. The values are
532 expressed in whole units of seconds, miliseconds, microseconds
533 or nanoseconds with a suffix indicating the unit.
534
535 hist_ranges
536 A list of the histogram bin ranges for the current statistics
537 area in order of ascending latency value. The values are
538 expressed as "LOWER-UPPER" in whole units of seconds, milisec‐
539 onds, microseconds or nanoseconds with a suffix indicating the
540 unit.
541
542 hist_bins
543 The number of latency histogram bins configured for the area.
544
546 Create a whole-device region with one area on vg00/lvol1
547 # dmstats create vg00/lvol1
548 vg00/lvol1: Created new region with 1 area(s) as region ID 0
549
550 Create a 32M region 1G into device d0
551 # dmstats create --start 1G --length 32M d0
552 d0: Created new region with 1 area(s) as region ID 0
553
554 Create a whole-device region with 8 areas on every device
555 # dmstats create --areas 8
556 vg00-lvol1: Created new region with 8 area(s) as region ID 0
557 vg00-lvol2: Created new region with 8 area(s) as region ID 0
558 vg00-lvol3: Created new region with 8 area(s) as region ID 0
559 vg01-lvol0: Created new region with 8 area(s) as region ID 2
560 vg01-lvol1: Created new region with 8 area(s) as region ID 0
561 vg00-lvol2: Created new region with 8 area(s) as region ID 1
562
563 Delete all regions on all devices
564 # dmstats delete --alldevices --allregions
565
566 Create a whole-device region with areas 10GiB in size on vg00/lvol1
567 using dmsetup
568 # dmsetup stats create --areasize 10G vg00/lvol1
569 vg00-lvol1: Created new region with 5 area(s) as region ID 1
570
571 Create a 1GiB region with 16 areas at the start of vg00/lvol1
572 # dmstats create --start 0 --len 1G --areas=16 vg00/lvol1
573 vg00-lvol1: Created new region with 16 area(s) as region ID 0
574
575 List the statistics regions registered on vg00/lvol1
576 # dmstats list vg00/lvol1
577 Name RgID RStart RSize #Areas ASize ProgID
578 vg00-lvol1 0 0 61.00g 1 61.00g dmstats
579 vg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats
580 vg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats
581
582 Display five statistics reports for vg00/lvol1 at an interval of one
583 second
584 # dmstats report --interval 1 --count 5 vg00/lvol1
585 # dmstats report
586 Name RgID ArID AStart ASize RRqM/s WRqM/s R/s W/s
587 RSz/s WSz/s AvRqSz QSize Util% AWait RdAWa WrAWa
588 vg_hex-lv_home 0 0 0 61.00g 0.00 0.00 0.00
589 218.00 0 1.04m 4.50k 2.97 81.70 13.62 0.00 13.62
590 vg_hex-lv_home 1 0 61.00g 19.20g 0.00 0.00 0.00
591 5.00 0 548.00k 109.50k 0.14 11.00 27.40 0.00 27.40
592 vg_hex-lv_home 2 0 80.20g 2.14g 0.00 0.00 0.00
593 14.00 0 1.15m 84.00k 0.39 18.70 27.71 0.00 27.71
594
595 Create one region for reach target contained in device vg00/lvol1
596 # dmstats create --segments vg00/lvol1
597 vg00-lvol1: Created new region with 1 area(s) as region ID 0
598 vg00-lvol1: Created new region with 1 area(s) as region ID 1
599 vg00-lvol1: Created new region with 1 area(s) as region ID 2
600
601 Print raw counters for region 4 on device d0
602 # dmstats print --regionid 4 d0
603 2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41
604
606 Bryn M. Reeves <bmr@redhat.com>
607
609 dmsetup(8)
610
611 LVM2 resource page: https://www.sourceware.org/lvm2/
612 Device-mapper resource page: http://sources.redhat.com/dm/
613
614 Device-mapper statistics kernel documentation
615 Documentation/device-mapper/statistics.txt
616
617
618
619Linux Jul 25 2015 DMSTATS(8)