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