statistics.rst

  1=============
  2DM statistics
  3=============
  4
  5Device Mapper supports the collection of I/O statistics on user-defined
  6regions of a DM device.	 If no regions are defined no statistics are
  7collected so there isn't any performance impact.  Only bio-based DM
  8devices are currently supported.
  9
 10Each user-defined region specifies a starting sector, length and step.
 11Individual statistics will be collected for each step-sized area within
 12the range specified.
 13
 14The I/O statistics counters for each step-sized area of a region are
 15in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
 16Documentation/admin-guide/iostats.rst).  But two extra counters (12 and 13) are
 17provided: total time spent reading and writing.  When the histogram
 18argument is used, the 14th parameter is reported that represents the
 19histogram of latencies.  All these counters may be accessed by sending
 20the @stats_print message to the appropriate DM device via dmsetup.
 21
 22The reported times are in milliseconds and the granularity depends on
 23the kernel ticks.  When the option precise_timestamps is used, the
 24reported times are in nanoseconds.
 25
 26Each region has a corresponding unique identifier, which we call a
 27region_id, that is assigned when the region is created.	 The region_id
 28must be supplied when querying statistics about the region, deleting the
 29region, etc.  Unique region_ids enable multiple userspace programs to
 30request and process statistics for the same DM device without stepping
 31on each other's data.
 32
 33The creation of DM statistics will allocate memory via kmalloc or
 34fallback to using vmalloc space.  At most, 1/4 of the overall system
 35memory may be allocated by DM statistics.  The admin can see how much
 36memory is used by reading:
 37
 38	/sys/module/dm_mod/parameters/stats_current_allocated_bytes
 39
 40Messages
 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
202Examples
203========
204
205Subdivide the DM device 'vol' into 100 pieces and start collecting
206statistics on them::
207
208  dmsetup message vol 0 @stats_create - /100
209
210Set the auxiliary data string to "foo bar baz" (the escape for each
211space must also be escaped, otherwise the shell will consume them)::
212
213  dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
214
215List the statistics::
216
217  dmsetup message vol 0 @stats_list
218
219Print the statistics::
220
221  dmsetup message vol 0 @stats_print 0
222
223Delete the statistics::
224
225  dmsetup message vol 0 @stats_delete 0