blob: 2a1673adc2004beae034f0ee5d5ae3ef3bceccf8 [file] [log] [blame]
Mikulas Patockafd2ed4d2013-08-16 10:54:23 -04001DM statistics
2=============
3
4Device Mapper supports the collection of I/O statistics on user-defined
5regions of a DM device. If no regions are defined no statistics are
6collected so there isn't any performance impact. Only bio-based DM
7devices are currently supported.
8
9Each user-defined region specifies a starting sector, length and step.
10Individual statistics will be collected for each step-sized area within
11the range specified.
12
13The I/O statistics counters for each step-sized area of a region are
14in the same format as /sys/block/*/stat or /proc/diskstats (see:
15Documentation/iostats.txt). But two extra counters (12 and 13) are
16provided: total time spent reading and writing in milliseconds. All
17these counters may be accessed by sending the @stats_print message to
18the appropriate DM device via dmsetup.
19
20Each region has a corresponding unique identifier, which we call a
21region_id, that is assigned when the region is created. The region_id
22must be supplied when querying statistics about the region, deleting the
23region, etc. Unique region_ids enable multiple userspace programs to
24request and process statistics for the same DM device without stepping
25on each other's data.
26
27The creation of DM statistics will allocate memory via kmalloc or
28fallback to using vmalloc space. At most, 1/4 of the overall system
29memory may be allocated by DM statistics. The admin can see how much
30memory is used by reading
31/sys/module/dm_mod/parameters/stats_current_allocated_bytes
32
33Messages
34========
35
36 @stats_create <range> <step> [<program_id> [<aux_data>]]
37
38 Create a new region and return the region_id.
39
40 <range>
41 "-" - whole device
42 "<start_sector>+<length>" - a range of <length> 512-byte sectors
43 starting with <start_sector>.
44
45 <step>
46 "<area_size>" - the range is subdivided into areas each containing
47 <area_size> sectors.
48 "/<number_of_areas>" - the range is subdivided into the specified
49 number of areas.
50
51 <program_id>
52 An optional parameter. A name that uniquely identifies
53 the userspace owner of the range. This groups ranges together
54 so that userspace programs can identify the ranges they
55 created and ignore those created by others.
56 The kernel returns this string back in the output of
57 @stats_list message, but it doesn't use it for anything else.
58
59 <aux_data>
60 An optional parameter. A word that provides auxiliary data
61 that is useful to the client program that created the range.
62 The kernel returns this string back in the output of
63 @stats_list message, but it doesn't use this value for anything.
64
65 @stats_delete <region_id>
66
67 Delete the region with the specified id.
68
69 <region_id>
70 region_id returned from @stats_create
71
72 @stats_clear <region_id>
73
74 Clear all the counters except the in-flight i/o counters.
75
76 <region_id>
77 region_id returned from @stats_create
78
79 @stats_list [<program_id>]
80
81 List all regions registered with @stats_create.
82
83 <program_id>
84 An optional parameter.
85 If this parameter is specified, only matching regions
86 are returned.
87 If it is not specified, all regions are returned.
88
89 Output format:
90 <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
91
92 @stats_print <region_id> [<starting_line> <number_of_lines>]
93
94 Print counters for each step-sized area of a region.
95
96 <region_id>
97 region_id returned from @stats_create
98
99 <starting_line>
100 The index of the starting line in the output.
101 If omitted, all lines are returned.
102
103 <number_of_lines>
104 The number of lines to include in the output.
105 If omitted, all lines are returned.
106
107 Output format for each step-sized area of a region:
108
109 <start_sector>+<length> counters
110
111 The first 11 counters have the same meaning as
112 /sys/block/*/stat or /proc/diskstats.
113
114 Please refer to Documentation/iostats.txt for details.
115
116 1. the number of reads completed
117 2. the number of reads merged
118 3. the number of sectors read
119 4. the number of milliseconds spent reading
120 5. the number of writes completed
121 6. the number of writes merged
122 7. the number of sectors written
123 8. the number of milliseconds spent writing
124 9. the number of I/Os currently in progress
125 10. the number of milliseconds spent doing I/Os
126 11. the weighted number of milliseconds spent doing I/Os
127
128 Additional counters:
129 12. the total time spent reading in milliseconds
130 13. the total time spent writing in milliseconds
131
132 @stats_print_clear <region_id> [<starting_line> <number_of_lines>]
133
134 Atomically print and then clear all the counters except the
135 in-flight i/o counters. Useful when the client consuming the
136 statistics does not want to lose any statistics (those updated
137 between printing and clearing).
138
139 <region_id>
140 region_id returned from @stats_create
141
142 <starting_line>
143 The index of the starting line in the output.
144 If omitted, all lines are printed and then cleared.
145
146 <number_of_lines>
147 The number of lines to process.
148 If omitted, all lines are printed and then cleared.
149
150 @stats_set_aux <region_id> <aux_data>
151
152 Store auxiliary data aux_data for the specified region.
153
154 <region_id>
155 region_id returned from @stats_create
156
157 <aux_data>
158 The string that identifies data which is useful to the client
159 program that created the range. The kernel returns this
160 string back in the output of @stats_list message, but it
161 doesn't use this value for anything.
162
163Examples
164========
165
166Subdivide the DM device 'vol' into 100 pieces and start collecting
167statistics on them:
168
169 dmsetup message vol 0 @stats_create - /100
170
171Set the auxillary data string to "foo bar baz" (the escape for each
172space must also be escaped, otherwise the shell will consume them):
173
174 dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
175
176List the statistics:
177
178 dmsetup message vol 0 @stats_list
179
180Print the statistics:
181
182 dmsetup message vol 0 @stats_print 0
183
184Delete the statistics:
185
186 dmsetup message vol 0 @stats_delete 0