Merge tag 'drm-intel-next-fixes-2016-05-25' of git://anongit.freedesktop.org/drm...
[sfrench/cifs-2.6.git] / Documentation / device-mapper / statistics.txt
1 DM statistics
2 =============
3
4 Device Mapper supports the collection of I/O statistics on user-defined
5 regions of a DM device.  If no regions are defined no statistics are
6 collected so there isn't any performance impact.  Only bio-based DM
7 devices are currently supported.
8
9 Each user-defined region specifies a starting sector, length and step.
10 Individual statistics will be collected for each step-sized area within
11 the range specified.
12
13 The I/O statistics counters for each step-sized area of a region are
14 in the same format as /sys/block/*/stat or /proc/diskstats (see:
15 Documentation/iostats.txt).  But two extra counters (12 and 13) are
16 provided: total time spent reading and writing.  When the histogram
17 argument is used, the 14th parameter is reported that represents the
18 histogram of latencies.  All these counters may be accessed by sending
19 the @stats_print message to the appropriate DM device via dmsetup.
20
21 The reported times are in milliseconds and the granularity depends on
22 the kernel ticks.  When the option precise_timestamps is used, the
23 reported times are in nanoseconds.
24
25 Each region has a corresponding unique identifier, which we call a
26 region_id, that is assigned when the region is created.  The region_id
27 must be supplied when querying statistics about the region, deleting the
28 region, etc.  Unique region_ids enable multiple userspace programs to
29 request and process statistics for the same DM device without stepping
30 on each other's data.
31
32 The creation of DM statistics will allocate memory via kmalloc or
33 fallback to using vmalloc space.  At most, 1/4 of the overall system
34 memory may be allocated by DM statistics.  The admin can see how much
35 memory is used by reading
36 /sys/module/dm_mod/parameters/stats_current_allocated_bytes
37
38 Messages
39 ========
40
41     @stats_create <range> <step>
42                 [<number_of_optional_arguments> <optional_arguments>...]
43                 [<program_id> [<aux_data>]]
44
45         Create a new region and return the region_id.
46
47         <range>
48           "-" - whole device
49           "<start_sector>+<length>" - a range of <length> 512-byte sectors
50                                       starting with <start_sector>.
51
52         <step>
53           "<area_size>" - the range is subdivided into areas each containing
54                           <area_size> sectors.
55           "/<number_of_areas>" - the range is subdivided into the specified
56                                  number of areas.
57
58         <number_of_optional_arguments>
59           The number of optional arguments
60
61         <optional_arguments>
62           The following optional arguments are supported
63           precise_timestamps - use precise timer with nanosecond resolution
64                 instead of the "jiffies" variable.  When this argument is
65                 used, the resulting times are in nanoseconds instead of
66                 milliseconds.  Precise timestamps are a little bit slower
67                 to obtain than jiffies-based timestamps.
68           histogram:n1,n2,n3,n4,... - collect histogram of latencies.  The
69                 numbers n1, n2, etc are times that represent the boundaries
70                 of the histogram.  If precise_timestamps is not used, the
71                 times are in milliseconds, otherwise they are in
72                 nanoseconds.  For each range, the kernel will report the
73                 number of requests that completed within this range. For
74                 example, if we use "histogram:10,20,30", the kernel will
75                 report four numbers a:b:c:d. a is the number of requests
76                 that took 0-10 ms to complete, b is the number of requests
77                 that took 10-20 ms to complete, c is the number of requests
78                 that took 20-30 ms to complete and d is the number of
79                 requests that took more than 30 ms to complete.
80
81         <program_id>
82           An optional parameter.  A name that uniquely identifies
83           the userspace owner of the range.  This groups ranges together
84           so that userspace programs can identify the ranges they
85           created and ignore those created by others.
86           The kernel returns this string back in the output of
87           @stats_list message, but it doesn't use it for anything else.
88           If we omit the number of optional arguments, program id must not
89           be a number, otherwise it would be interpreted as the number of
90           optional arguments.
91
92         <aux_data>
93           An optional parameter.  A word that provides auxiliary data
94           that is useful to the client program that created the range.
95           The kernel returns this string back in the output of
96           @stats_list message, but it doesn't use this value for anything.
97
98     @stats_delete <region_id>
99
100         Delete the region with the specified id.
101
102         <region_id>
103           region_id returned from @stats_create
104
105     @stats_clear <region_id>
106
107         Clear all the counters except the in-flight i/o counters.
108
109         <region_id>
110           region_id returned from @stats_create
111
112     @stats_list [<program_id>]
113
114         List all regions registered with @stats_create.
115
116         <program_id>
117           An optional parameter.
118           If this parameter is specified, only matching regions
119           are returned.
120           If it is not specified, all regions are returned.
121
122         Output format:
123           <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
124                 precise_timestamps histogram:n1,n2,n3,...
125
126         The strings "precise_timestamps" and "histogram" are printed only
127         if they were specified when creating the region.
128
129     @stats_print <region_id> [<starting_line> <number_of_lines>]
130
131         Print counters for each step-sized area of a region.
132
133         <region_id>
134           region_id returned from @stats_create
135
136         <starting_line>
137           The index of the starting line in the output.
138           If omitted, all lines are returned.
139
140         <number_of_lines>
141           The number of lines to include in the output.
142           If omitted, all lines are returned.
143
144         Output format for each step-sized area of a region:
145
146           <start_sector>+<length> counters
147
148           The first 11 counters have the same meaning as
149           /sys/block/*/stat or /proc/diskstats.
150
151           Please refer to Documentation/iostats.txt for details.
152
153           1. the number of reads completed
154           2. the number of reads merged
155           3. the number of sectors read
156           4. the number of milliseconds spent reading
157           5. the number of writes completed
158           6. the number of writes merged
159           7. the number of sectors written
160           8. the number of milliseconds spent writing
161           9. the number of I/Os currently in progress
162           10. the number of milliseconds spent doing I/Os
163           11. the weighted number of milliseconds spent doing I/Os
164
165           Additional counters:
166           12. the total time spent reading in milliseconds
167           13. the total time spent writing in milliseconds
168
169     @stats_print_clear <region_id> [<starting_line> <number_of_lines>]
170
171         Atomically print and then clear all the counters except the
172         in-flight i/o counters.  Useful when the client consuming the
173         statistics does not want to lose any statistics (those updated
174         between printing and clearing).
175
176         <region_id>
177           region_id returned from @stats_create
178
179         <starting_line>
180           The index of the starting line in the output.
181           If omitted, all lines are printed and then cleared.
182
183         <number_of_lines>
184           The number of lines to process.
185           If omitted, all lines are printed and then cleared.
186
187     @stats_set_aux <region_id> <aux_data>
188
189         Store auxiliary data aux_data for the specified region.
190
191         <region_id>
192           region_id returned from @stats_create
193
194         <aux_data>
195           The string that identifies data which is useful to the client
196           program that created the range.  The kernel returns this
197           string back in the output of @stats_list message, but it
198           doesn't use this value for anything.
199
200 Examples
201 ========
202
203 Subdivide the DM device 'vol' into 100 pieces and start collecting
204 statistics on them:
205
206   dmsetup message vol 0 @stats_create - /100
207
208 Set the auxiliary data string to "foo bar baz" (the escape for each
209 space must also be escaped, otherwise the shell will consume them):
210
211   dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
212
213 List the statistics:
214
215   dmsetup message vol 0 @stats_list
216
217 Print the statistics:
218
219   dmsetup message vol 0 @stats_print 0
220
221 Delete the statistics:
222
223   dmsetup message vol 0 @stats_delete 0