1DM 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
187