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.  All these counters may
  17 be accessed by sending the @stats_print message to the appropriate DM
  18 device via dmsetup.
  19
  20 The reported times are in milliseconds and the granularity depends on
  21 the kernel ticks.  When the option precise_timestamps is used, the
  22 reported times are in nanoseconds.
  23
  24 Each region has a corresponding unique identifier, which we call a
  25 region_id, that is assigned when the region is created.  The region_id
  26 must be supplied when querying statistics about the region, deleting the
  27 region, etc.  Unique region_ids enable multiple userspace programs to
  28 request and process statistics for the same DM device without stepping
  29 on each other's data.
  30
  31 The creation of DM statistics will allocate memory via kmalloc or
  32 fallback to using vmalloc space.  At most, 1/4 of the overall system
  33 memory may be allocated by DM statistics.  The admin can see how much
  34 memory is used by reading
  35 /sys/module/dm_mod/parameters/stats_current_allocated_bytes
  36
  37 Messages
  38 ========
  39
  40     @stats_create <range> <step>
  41                 [<number_of_optional_arguments> <optional_arguments>...]
  42                 [<program_id> [<aux_data>]]
  43
  44         Create a new region and return the region_id.
  45
  46         <range>
  47           "-" - whole device
  48           "<start_sector>+<length>" - a range of <length> 512-byte sectors
  49                                       starting with <start_sector>.
  50
  51         <step>
  52           "<area_size>" - the range is subdivided into areas each containing
  53                           <area_size> sectors.
  54           "/<number_of_areas>" - the range is subdivided into the specified
  55                                  number of areas.
  56
  57         <number_of_optional_arguments>
  58           The number of optional arguments
  59
  60         <optional_arguments>
  61           The following optional arguments are supported
  62           precise_timestamps - use precise timer with nanosecond resolution
  63                 instead of the "jiffies" variable.  When this argument is
  64                 used, the resulting times are in nanoseconds instead of
  65                 milliseconds.  Precise timestamps are a little bit slower
  66                 to obtain than jiffies-based timestamps.
  67
  68         <program_id>
  69           An optional parameter.  A name that uniquely identifies
  70           the userspace owner of the range.  This groups ranges together
  71           so that userspace programs can identify the ranges they
  72           created and ignore those created by others.
  73           The kernel returns this string back in the output of
  74           @stats_list message, but it doesn't use it for anything else.
  75           If we omit the number of optional arguments, program id must not
  76           be a number, otherwise it would be interpreted as the number of
  77           optional arguments.
  78
  79         <aux_data>
  80           An optional parameter.  A word that provides auxiliary data
  81           that is useful to the client program that created the range.
  82           The kernel returns this string back in the output of
  83           @stats_list message, but it doesn't use this value for anything.
  84
  85     @stats_delete <region_id>
  86
  87         Delete the region with the specified id.
  88
  89         <region_id>
  90           region_id returned from @stats_create
  91
  92     @stats_clear <region_id>
  93
  94         Clear all the counters except the in-flight i/o counters.
  95
  96         <region_id>
  97           region_id returned from @stats_create
  98
  99     @stats_list [<program_id>]
 100
 101         List all regions registered with @stats_create.
 102
 103         <program_id>
 104           An optional parameter.
 105           If this parameter is specified, only matching regions
 106           are returned.
 107           If it is not specified, all regions are returned.
 108
 109         Output format:
 110           <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
 111
 112     @stats_print <region_id> [<starting_line> <number_of_lines>]
 113
 114         Print counters for each step-sized area of a region.
 115
 116         <region_id>
 117           region_id returned from @stats_create
 118
 119         <starting_line>
 120           The index of the starting line in the output.
 121           If omitted, all lines are returned.
 122
 123         <number_of_lines>
 124           The number of lines to include in the output.
 125           If omitted, all lines are returned.
 126
 127         Output format for each step-sized area of a region:
 128
 129           <start_sector>+<length> counters
 130
 131           The first 11 counters have the same meaning as
 132           /sys/block/*/stat or /proc/diskstats.
 133
 134           Please refer to Documentation/iostats.txt for details.
 135
 136           1. the number of reads completed
 137           2. the number of reads merged
 138           3. the number of sectors read
 139           4. the number of milliseconds spent reading
 140           5. the number of writes completed
 141           6. the number of writes merged
 142           7. the number of sectors written
 143           8. the number of milliseconds spent writing
 144           9. the number of I/Os currently in progress
 145           10. the number of milliseconds spent doing I/Os
 146           11. the weighted number of milliseconds spent doing I/Os
 147
 148           Additional counters:
 149           12. the total time spent reading in milliseconds
 150           13. the total time spent writing in milliseconds
 151
 152     @stats_print_clear <region_id> [<starting_line> <number_of_lines>]
 153
 154         Atomically print and then clear all the counters except the
 155         in-flight i/o counters.  Useful when the client consuming the
 156         statistics does not want to lose any statistics (those updated
 157         between printing and clearing).
 158
 159         <region_id>
 160           region_id returned from @stats_create
 161
 162         <starting_line>
 163           The index of the starting line in the output.
 164           If omitted, all lines are printed and then cleared.
 165
 166         <number_of_lines>
 167           The number of lines to process.
 168           If omitted, all lines are printed and then cleared.
 169
 170     @stats_set_aux <region_id> <aux_data>
 171
 172         Store auxiliary data aux_data for the specified region.
 173
 174         <region_id>
 175           region_id returned from @stats_create
 176
 177         <aux_data>
 178           The string that identifies data which is useful to the client
 179           program that created the range.  The kernel returns this
 180           string back in the output of @stats_list message, but it
 181           doesn't use this value for anything.
 182
 183 Examples
 184 ========
 185
 186 Subdivide the DM device 'vol' into 100 pieces and start collecting
 187 statistics on them:
 188
 189   dmsetup message vol 0 @stats_create - /100
 190
 191 Set the auxillary data string to "foo bar baz" (the escape for each
 192 space must also be escaped, otherwise the shell will consume them):
 193
 194   dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
 195
 196 List the statistics:
 197
 198   dmsetup message vol 0 @stats_list
 199
 200 Print the statistics:
 201
 202   dmsetup message vol 0 @stats_print 0
 203
 204 Delete the statistics:
 205
 206   dmsetup message vol 0 @stats_delete 0