statistics.rst 7.6 KB

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