1 =============
2 DM statistics
3 =============
4
5 Device Mapper supports the collection of I/O s
6 regions of a DM device. If no regions are def
7 collected so there isn't any performance impac
8 devices are currently supported.
9
10 Each user-defined region specifies a starting
11 Individual statistics will be collected for ea
12 the range specified.
13
14 The I/O statistics counters for each step-size
15 in the same format as `/sys/block/*/stat` or `
16 Documentation/admin-guide/iostats.rst). But t
17 provided: total time spent reading and writing
18 argument is used, the 14th parameter is report
19 histogram of latencies. All these counters ma
20 the @stats_print message to the appropriate DM
21
22 The reported times are in milliseconds and the
23 the kernel ticks. When the option precise_tim
24 reported times are in nanoseconds.
25
26 Each region has a corresponding unique identif
27 region_id, that is assigned when the region is
28 must be supplied when querying statistics abou
29 region, etc. Unique region_ids enable multipl
30 request and process statistics for the same DM
31 on each other's data.
32
33 The creation of DM statistics will allocate me
34 fallback to using vmalloc space. At most, 1/4
35 memory may be allocated by DM statistics. The
36 memory is used by reading:
37
38 /sys/module/dm_mod/parameters/stats_cu
39
40 Messages
41 ========
42
43 @stats_create <range> <step> [<number_of_o
44 Create a new region and return the reg
45
46 <range>
47 "-"
48 whole device
49 "<start_sector>+<length>"
50 a range of <length> 512-byte s
51 starting with <start_sector>.
52
53 <step>
54 "<area_size>"
55 the range is subdivided into a
56 <area_size> sectors.
57 "/<number_of_areas>"
58 the range is subdivided into t
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
66
67 precise_timestamps
68 use precise timer with nanosec
69 instead of the "jiffies" varia
70 used, the resulting times are
71 milliseconds. Precise timesta
72 to obtain than jiffies-based t
73 histogram:n1,n2,n3,n4,...
74 collect histogram of latencies
75 numbers n1, n2, etc are times
76 of the histogram. If precise_
77 times are in milliseconds, oth
78 nanoseconds. For each range,
79 number of requests that comple
80 example, if we use "histogram:
81 report four numbers a:b:c:d. a
82 that took 0-10 ms to complete,
83 that took 10-20 ms to complete
84 that took 20-30 ms to complete
85 requests that took more than 3
86
87 <program_id>
88 An optional parameter. A name that
89 the userspace owner of the range. T
90 so that userspace programs can ident
91 created and ignore those created by
92 The kernel returns this string back
93 @stats_list message, but it doesn't
94 If we omit the number of optional ar
95 be a number, otherwise it would be i
96 optional arguments.
97
98 <aux_data>
99 An optional parameter. A word that
100 that is useful to the client program
101 The kernel returns this string back
102 @stats_list message, but it doesn't
103
104 @stats_delete <region_id>
105 Delete the region with the specified i
106
107 <region_id>
108 region_id returned from @stats_creat
109
110 @stats_clear <region_id>
111 Clear all the counters except the in-f
112
113 <region_id>
114 region_id returned from @stats_creat
115
116 @stats_list [<program_id>]
117 List all regions registered with @stat
118
119 <program_id>
120 An optional parameter.
121 If this parameter is specified, only
122 are returned.
123 If it is not specified, all regions
124
125 Output format:
126 <region_id>: <start_sector>+<length>
127 precise_timestamps histogram:n
128
129 The strings "precise_timestamps" and "
130 if they were specified when creating t
131
132 @stats_print <region_id> [<starting_line>
133 Print counters for each step-sized are
134
135 <region_id>
136 region_id returned from @stats_creat
137
138 <starting_line>
139 The index of the starting line in th
140 If omitted, all lines are returned.
141
142 <number_of_lines>
143 The number of lines to include in th
144 If omitted, all lines are returned.
145
146 Output format for each step-sized area
147
148 <start_sector>+<length>
149 counters
150
151 The first 11 counters have the same
152 `/sys/block/*/stat or /proc/diskstat
153
154 Please refer to Documentation/admin-
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
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
164 9. the number of I/Os currently in p
165 10. the number of milliseconds spent
166 11. the weighted number of milliseco
167
168 Additional counters:
169
170 12. the total time spent reading in
171 13. the total time spent writing in
172
173 @stats_print_clear <region_id> [<starting_
174 Atomically print and then clear all th
175 in-flight i/o counters. Useful when t
176 statistics does not want to lose any s
177 between printing and clearing).
178
179 <region_id>
180 region_id returned from @stats_creat
181
182 <starting_line>
183 The index of the starting line in th
184 If omitted, all lines are printed an
185
186 <number_of_lines>
187 The number of lines to process.
188 If omitted, all lines are printed an
189
190 @stats_set_aux <region_id> <aux_data>
191 Store auxiliary data aux_data for the
192
193 <region_id>
194 region_id returned from @stats_creat
195
196 <aux_data>
197 The string that identifies data whic
198 program that created the range. The
199 string back in the output of @stats_
200 doesn't use this value for anything.
201
202 Examples
203 ========
204
205 Subdivide the DM device 'vol' into 100 pieces
206 statistics on them::
207
208 dmsetup message vol 0 @stats_create - /100
209
210 Set the auxiliary data string to "foo bar baz"
211 space must also be escaped, otherwise the shel
212
213 dmsetup message vol 0 @stats_set_aux 0 foo\\
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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.