Documentation/device-mapper/statistics.txt

   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