0001 =============
0002 DM statistics
0003 =============
0004
0005 Device Mapper supports the collection of I/O statistics on user-defined
0006 regions of a DM device. If no regions are defined no statistics are
0007 collected so there isn't any performance impact. Only bio-based DM
0008 devices are currently supported.
0009
0010 Each user-defined region specifies a starting sector, length and step.
0011 Individual statistics will be collected for each step-sized area within
0012 the range specified.
0013
0014 The I/O statistics counters for each step-sized area of a region are
0015 in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
0016 Documentation/admin-guide/iostats.rst). But two extra counters (12 and 13) are
0017 provided: total time spent reading and writing. When the histogram
0018 argument is used, the 14th parameter is reported that represents the
0019 histogram of latencies. All these counters may be accessed by sending
0020 the @stats_print message to the appropriate DM device via dmsetup.
0021
0022 The reported times are in milliseconds and the granularity depends on
0023 the kernel ticks. When the option precise_timestamps is used, the
0024 reported times are in nanoseconds.
0025
0026 Each region has a corresponding unique identifier, which we call a
0027 region_id, that is assigned when the region is created. The region_id
0028 must be supplied when querying statistics about the region, deleting the
0029 region, etc. Unique region_ids enable multiple userspace programs to
0030 request and process statistics for the same DM device without stepping
0031 on each other's data.
0032
0033 The creation of DM statistics will allocate memory via kmalloc or
0034 fallback to using vmalloc space. At most, 1/4 of the overall system
0035 memory may be allocated by DM statistics. The admin can see how much
0036 memory is used by reading:
0037
0038 /sys/module/dm_mod/parameters/stats_current_allocated_bytes
0039
0040 Messages
0041 ========
0042
0043 @stats_create <range> <step> [<number_of_optional_arguments> <optional_arguments>...] [<program_id> [<aux_data>]]
0044 Create a new region and return the region_id.
0045
0046 <range>
0047 "-"
0048 whole device
0049 "<start_sector>+<length>"
0050 a range of <length> 512-byte sectors
0051 starting with <start_sector>.
0052
0053 <step>
0054 "<area_size>"
0055 the range is subdivided into areas each containing
0056 <area_size> sectors.
0057 "/<number_of_areas>"
0058 the range is subdivided into the specified
0059 number of areas.
0060
0061 <number_of_optional_arguments>
0062 The number of optional arguments
0063
0064 <optional_arguments>
0065 The following optional arguments are supported:
0066
0067 precise_timestamps
0068 use precise timer with nanosecond resolution
0069 instead of the "jiffies" variable. When this argument is
0070 used, the resulting times are in nanoseconds instead of
0071 milliseconds. Precise timestamps are a little bit slower
0072 to obtain than jiffies-based timestamps.
0073 histogram:n1,n2,n3,n4,...
0074 collect histogram of latencies. The
0075 numbers n1, n2, etc are times that represent the boundaries
0076 of the histogram. If precise_timestamps is not used, the
0077 times are in milliseconds, otherwise they are in
0078 nanoseconds. For each range, the kernel will report the
0079 number of requests that completed within this range. For
0080 example, if we use "histogram:10,20,30", the kernel will
0081 report four numbers a:b:c:d. a is the number of requests
0082 that took 0-10 ms to complete, b is the number of requests
0083 that took 10-20 ms to complete, c is the number of requests
0084 that took 20-30 ms to complete and d is the number of
0085 requests that took more than 30 ms to complete.
0086
0087 <program_id>
0088 An optional parameter. A name that uniquely identifies
0089 the userspace owner of the range. This groups ranges together
0090 so that userspace programs can identify the ranges they
0091 created and ignore those created by others.
0092 The kernel returns this string back in the output of
0093 @stats_list message, but it doesn't use it for anything else.
0094 If we omit the number of optional arguments, program id must not
0095 be a number, otherwise it would be interpreted as the number of
0096 optional arguments.
0097
0098 <aux_data>
0099 An optional parameter. A word that provides auxiliary data
0100 that is useful to the client program that created the range.
0101 The kernel returns this string back in the output of
0102 @stats_list message, but it doesn't use this value for anything.
0103
0104 @stats_delete <region_id>
0105 Delete the region with the specified id.
0106
0107 <region_id>
0108 region_id returned from @stats_create
0109
0110 @stats_clear <region_id>
0111 Clear all the counters except the in-flight i/o counters.
0112
0113 <region_id>
0114 region_id returned from @stats_create
0115
0116 @stats_list [<program_id>]
0117 List all regions registered with @stats_create.
0118
0119 <program_id>
0120 An optional parameter.
0121 If this parameter is specified, only matching regions
0122 are returned.
0123 If it is not specified, all regions are returned.
0124
0125 Output format:
0126 <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
0127 precise_timestamps histogram:n1,n2,n3,...
0128
0129 The strings "precise_timestamps" and "histogram" are printed only
0130 if they were specified when creating the region.
0131
0132 @stats_print <region_id> [<starting_line> <number_of_lines>]
0133 Print counters for each step-sized area of a region.
0134
0135 <region_id>
0136 region_id returned from @stats_create
0137
0138 <starting_line>
0139 The index of the starting line in the output.
0140 If omitted, all lines are returned.
0141
0142 <number_of_lines>
0143 The number of lines to include in the output.
0144 If omitted, all lines are returned.
0145
0146 Output format for each step-sized area of a region:
0147
0148 <start_sector>+<length>
0149 counters
0150
0151 The first 11 counters have the same meaning as
0152 `/sys/block/*/stat or /proc/diskstats`.
0153
0154 Please refer to Documentation/admin-guide/iostats.rst for details.
0155
0156 1. the number of reads completed
0157 2. the number of reads merged
0158 3. the number of sectors read
0159 4. the number of milliseconds spent reading
0160 5. the number of writes completed
0161 6. the number of writes merged
0162 7. the number of sectors written
0163 8. the number of milliseconds spent writing
0164 9. the number of I/Os currently in progress
0165 10. the number of milliseconds spent doing I/Os
0166 11. the weighted number of milliseconds spent doing I/Os
0167
0168 Additional counters:
0169
0170 12. the total time spent reading in milliseconds
0171 13. the total time spent writing in milliseconds
0172
0173 @stats_print_clear <region_id> [<starting_line> <number_of_lines>]
0174 Atomically print and then clear all the counters except the
0175 in-flight i/o counters. Useful when the client consuming the
0176 statistics does not want to lose any statistics (those updated
0177 between printing and clearing).
0178
0179 <region_id>
0180 region_id returned from @stats_create
0181
0182 <starting_line>
0183 The index of the starting line in the output.
0184 If omitted, all lines are printed and then cleared.
0185
0186 <number_of_lines>
0187 The number of lines to process.
0188 If omitted, all lines are printed and then cleared.
0189
0190 @stats_set_aux <region_id> <aux_data>
0191 Store auxiliary data aux_data for the specified region.
0192
0193 <region_id>
0194 region_id returned from @stats_create
0195
0196 <aux_data>
0197 The string that identifies data which is useful to the client
0198 program that created the range. The kernel returns this
0199 string back in the output of @stats_list message, but it
0200 doesn't use this value for anything.
0201
0202 Examples
0203 ========
0204
0205 Subdivide the DM device 'vol' into 100 pieces and start collecting
0206 statistics on them::
0207
0208 dmsetup message vol 0 @stats_create - /100
0209
0210 Set the auxiliary data string to "foo bar baz" (the escape for each
0211 space must also be escaped, otherwise the shell will consume them)::
0212
0213 dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
0214
0215 List the statistics::
0216
0217 dmsetup message vol 0 @stats_list
0218
0219 Print the statistics::
0220
0221 dmsetup message vol 0 @stats_print 0
0222
0223 Delete the statistics::
0224
0225 dmsetup message vol 0 @stats_delete 0
