Documentation/admin-guide/cgroup-v1/blkio-controller.rst

   1 ===================
   2 Block IO Controller
   3 ===================
   4
   5 Overview
   6 ========
   7 cgroup subsys "blkio" implements the block io controller. There seems to be
   8 a need of various kinds of IO control policies (like proportional BW, max BW)
   9 both at leaf nodes as well as at intermediate nodes in a storage hierarchy.
  10 Plan is to use the same cgroup based management interface for blkio controller
  11 and based on user options switch IO policies in the background.
  12
  13 One IO control policy is throttling policy which can be used to
  14 specify upper IO rate limits on devices. This policy is implemented in
  15 generic block layer and can be used on leaf nodes as well as higher
  16 level logical devices like device mapper.
  17
  18 HOWTO
  19 =====
  20
  21 Throttling/Upper Limit policy
  22 -----------------------------
  23 Enable Block IO controller::
  24
  25         CONFIG_BLK_CGROUP=y
  26
  27 Enable throttling in block layer::
  28
  29         CONFIG_BLK_DEV_THROTTLING=y
  30
  31 Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::
  32
  33         mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
  34
  35 Specify a bandwidth rate on particular device for root group. The format
  36 for policy is "<major>:<minor>  <bytes_per_second>"::
  37
  38         echo "8:16  1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device
  39
  40 This will put a limit of 1MB/second on reads happening for root group
  41 on device having major/minor number 8:16.
  42
  43 Run dd to read a file and see if rate is throttled to 1MB/s or not::
  44
  45         # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024
  46         1024+0 records in
  47         1024+0 records out
  48         4194304 bytes (4.2 MB) copied, 4.0001 s, 1.0 MB/s
  49
  50 Limits for writes can be put using blkio.throttle.write_bps_device file.
  51
  52 Hierarchical Cgroups
  53 ====================
  54
  55 Throttling implements hierarchy support; however,
  56 throttling's hierarchy support is enabled iff "sane_behavior" is
  57 enabled from cgroup side, which currently is a development option and
  58 not publicly available.
  59
  60 If somebody created a hierarchy like as follows::
  61
  62                         root
  63                         /  \
  64                      test1 test2
  65                         |
  66                      test3
  67
  68 Throttling with "sane_behavior" will handle the
  69 hierarchy correctly. For throttling, all limits apply
  70 to the whole subtree while all statistics are local to the IOs
  71 directly generated by tasks in that cgroup.
  72
  73 Throttling without "sane_behavior" enabled from cgroup side will
  74 practically treat all groups at same level as if it looks like the
  75 following::
  76
  77                                 pivot
  78                              /  /   \  \
  79                         root  test1 test2  test3
  80
  81 Various user visible config options
  82 ===================================
  83
  84   CONFIG_BLK_CGROUP
  85           Block IO controller.
  86
  87   CONFIG_BFQ_CGROUP_DEBUG
  88           Debug help. Right now some additional stats file show up in cgroup
  89           if this option is enabled.
  90
  91   CONFIG_BLK_DEV_THROTTLING
  92           Enable block device throttling support in block layer.
  93
  94 Details of cgroup files
  95 =======================
  96
  97 Proportional weight policy files
  98 --------------------------------
  99
 100   blkio.weight
 101           Specifies per cgroup weight. This is default weight of the group
 102           on all the devices until and unless overridden by per device rule.
 103           (See blkio.weight_device).
 104           Currently allowed range of weights is from 10 to 1000.
 105
 106   blkio.weight_device
 107           One can specify per cgroup per device rules using this interface.
 108           These rules override the default value of group weight as specified
 109           by blkio.weight.
 110
 111           Following is the format::
 112
 113             # echo dev_maj:dev_minor weight > blkio.weight_device
 114
 115           Configure weight=300 on /dev/sdb (8:16) in this cgroup::
 116
 117             # echo 8:16 300 > blkio.weight_device
 118             # cat blkio.weight_device
 119             dev     weight
 120             8:16    300
 121
 122           Configure weight=500 on /dev/sda (8:0) in this cgroup::
 123
 124             # echo 8:0 500 > blkio.weight_device
 125             # cat blkio.weight_device
 126             dev     weight
 127             8:0     500
 128             8:16    300
 129
 130           Remove specific weight for /dev/sda in this cgroup::
 131
 132             # echo 8:0 0 > blkio.weight_device
 133             # cat blkio.weight_device
 134             dev     weight
 135             8:16    300
 136
 137   blkio.time
 138           Disk time allocated to cgroup per device in milliseconds. First
 139           two fields specify the major and minor number of the device and
 140           third field specifies the disk time allocated to group in
 141           milliseconds.
 142
 143   blkio.sectors
 144           Number of sectors transferred to/from disk by the group. First
 145           two fields specify the major and minor number of the device and
 146           third field specifies the number of sectors transferred by the
 147           group to/from the device.
 148
 149   blkio.io_service_bytes
 150           Number of bytes transferred to/from the disk by the group. These
 151           are further divided by the type of operation - read or write, sync
 152           or async. First two fields specify the major and minor number of the
 153           device, third field specifies the operation type and the fourth field
 154           specifies the number of bytes.
 155
 156   blkio.io_serviced
 157           Number of IOs (bio) issued to the disk by the group. These
 158           are further divided by the type of operation - read or write, sync
 159           or async. First two fields specify the major and minor number of the
 160           device, third field specifies the operation type and the fourth field
 161           specifies the number of IOs.
 162
 163   blkio.io_service_time
 164           Total amount of time between request dispatch and request completion
 165           for the IOs done by this cgroup. This is in nanoseconds to make it
 166           meaningful for flash devices too. For devices with queue depth of 1,
 167           this time represents the actual service time. When queue_depth > 1,
 168           that is no longer true as requests may be served out of order. This
 169           may cause the service time for a given IO to include the service time
 170           of multiple IOs when served out of order which may result in total
 171           io_service_time > actual time elapsed. This time is further divided by
 172           the type of operation - read or write, sync or async. First two fields
 173           specify the major and minor number of the device, third field
 174           specifies the operation type and the fourth field specifies the
 175           io_service_time in ns.
 176
 177   blkio.io_wait_time
 178           Total amount of time the IOs for this cgroup spent waiting in the
 179           scheduler queues for service. This can be greater than the total time
 180           elapsed since it is cumulative io_wait_time for all IOs. It is not a
 181           measure of total time the cgroup spent waiting but rather a measure of
 182           the wait_time for its individual IOs. For devices with queue_depth > 1
 183           this metric does not include the time spent waiting for service once
 184           the IO is dispatched to the device but till it actually gets serviced
 185           (there might be a time lag here due to re-ordering of requests by the
 186           device). This is in nanoseconds to make it meaningful for flash
 187           devices too. This time is further divided by the type of operation -
 188           read or write, sync or async. First two fields specify the major and
 189           minor number of the device, third field specifies the operation type
 190           and the fourth field specifies the io_wait_time in ns.
 191
 192   blkio.io_merged
 193           Total number of bios/requests merged into requests belonging to this
 194           cgroup. This is further divided by the type of operation - read or
 195           write, sync or async.
 196
 197   blkio.io_queued
 198           Total number of requests queued up at any given instant for this
 199           cgroup. This is further divided by the type of operation - read or
 200           write, sync or async.
 201
 202   blkio.avg_queue_size
 203           Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
 204           The average queue size for this cgroup over the entire time of this
 205           cgroup's existence. Queue size samples are taken each time one of the
 206           queues of this cgroup gets a timeslice.
 207
 208   blkio.group_wait_time
 209           Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
 210           This is the amount of time the cgroup had to wait since it became busy
 211           (i.e., went from 0 to 1 request queued) to get a timeslice for one of
 212           its queues. This is different from the io_wait_time which is the
 213           cumulative total of the amount of time spent by each IO in that cgroup
 214           waiting in the scheduler queue. This is in nanoseconds. If this is
 215           read when the cgroup is in a waiting (for timeslice) state, the stat
 216           will only report the group_wait_time accumulated till the last time it
 217           got a timeslice and will not include the current delta.
 218
 219   blkio.empty_time
 220           Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
 221           This is the amount of time a cgroup spends without any pending
 222           requests when not being served, i.e., it does not include any time
 223           spent idling for one of the queues of the cgroup. This is in
 224           nanoseconds. If this is read when the cgroup is in an empty state,
 225           the stat will only report the empty_time accumulated till the last
 226           time it had a pending request and will not include the current delta.
 227
 228   blkio.idle_time
 229           Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
 230           This is the amount of time spent by the IO scheduler idling for a
 231           given cgroup in anticipation of a better request than the existing ones
 232           from other queues/cgroups. This is in nanoseconds. If this is read
 233           when the cgroup is in an idling state, the stat will only report the
 234           idle_time accumulated till the last idle period and will not include
 235           the current delta.
 236
 237   blkio.dequeue
 238           Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. This
 239           gives the statistics about how many a times a group was dequeued
 240           from service tree of the device. First two fields specify the major
 241           and minor number of the device and third field specifies the number
 242           of times a group was dequeued from a particular device.
 243
 244   blkio.*_recursive
 245           Recursive version of various stats. These files show the
 246           same information as their non-recursive counterparts but
 247           include stats from all the descendant cgroups.
 248
 249 Throttling/Upper limit policy files
 250 -----------------------------------
 251   blkio.throttle.read_bps_device
 252           Specifies upper limit on READ rate from the device. IO rate is
 253           specified in bytes per second. Rules are per device. Following is
 254           the format::
 255
 256             echo "<major>:<minor>  <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
 257
 258   blkio.throttle.write_bps_device
 259           Specifies upper limit on WRITE rate to the device. IO rate is
 260           specified in bytes per second. Rules are per device. Following is
 261           the format::
 262
 263             echo "<major>:<minor>  <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
 264
 265   blkio.throttle.read_iops_device
 266           Specifies upper limit on READ rate from the device. IO rate is
 267           specified in IO per second. Rules are per device. Following is
 268           the format::
 269
 270            echo "<major>:<minor>  <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
 271
 272   blkio.throttle.write_iops_device
 273           Specifies upper limit on WRITE rate to the device. IO rate is
 274           specified in io per second. Rules are per device. Following is
 275           the format::
 276
 277             echo "<major>:<minor>  <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
 278
 279           Note: If both BW and IOPS rules are specified for a device, then IO is
 280           subjected to both the constraints.
 281
 282   blkio.throttle.io_serviced
 283           Number of IOs (bio) issued to the disk by the group. These
 284           are further divided by the type of operation - read or write, sync
 285           or async. First two fields specify the major and minor number of the
 286           device, third field specifies the operation type and the fourth field
 287           specifies the number of IOs.
 288
 289   blkio.throttle.io_service_bytes
 290           Number of bytes transferred to/from the disk by the group. These
 291           are further divided by the type of operation - read or write, sync
 292           or async. First two fields specify the major and minor number of the
 293           device, third field specifies the operation type and the fourth field
 294           specifies the number of bytes.
 295
 296 Common files among various policies
 297 -----------------------------------
 298   blkio.reset_stats
 299           Writing an int to this file will result in resetting all the stats
 300           for that cgroup.