About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / device-mapper / statistics.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:36 EST.

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 in milliseconds.	 All
17	these counters may be accessed by sending the @stats_print message to
18	the appropriate DM device via dmsetup.
19	
20	Each region has a corresponding unique identifier, which we call a
21	region_id, that is assigned when the region is created.	 The region_id
22	must be supplied when querying statistics about the region, deleting the
23	region, etc.  Unique region_ids enable multiple userspace programs to
24	request and process statistics for the same DM device without stepping
25	on each other's data.
26	
27	The creation of DM statistics will allocate memory via kmalloc or
28	fallback to using vmalloc space.  At most, 1/4 of the overall system
29	memory may be allocated by DM statistics.  The admin can see how much
30	memory is used by reading
31	/sys/module/dm_mod/parameters/stats_current_allocated_bytes
32	
33	Messages
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	
163	Examples
164	========
165	
166	Subdivide the DM device 'vol' into 100 pieces and start collecting
167	statistics on them:
168	
169	  dmsetup message vol 0 @stats_create - /100
170	
171	Set the auxillary data string to "foo bar baz" (the escape for each
172	space must also be escaped, otherwise the shell will consume them):
173	
174	  dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
175	
176	List the statistics:
177	
178	  dmsetup message vol 0 @stats_list
179	
180	Print the statistics:
181	
182	  dmsetup message vol 0 @stats_print 0
183	
184	Delete the statistics:
185	
186	  dmsetup message vol 0 @stats_delete 0
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.