qemu/docs/throttle.txt

1 The QEMU throttling infrastructure
6 This work is licensed under the terms of the GNU GPL, version 2 or
7 later. See the COPYING file in the top-level directory.
12 I/O operations. The code itself is generic and independent of the I/O
13 units, but it is currently used to limit the number of bytes per second
16 This document explains how to use the throttling code in QEMU, and how
17 it works internally. The implementation is in throttle.c.
22 Two aspects of the disk I/O can be limited: the number of bytes per
23 second and the number of operations per second (IOPS). For each one of
24 them the user can set a global limit or separate limits for read and
27 I/O limits can be set using the throttling.* parameters of -drive, or
28 using the QMP 'block_set_io_throttle' command. These are the names of
29 the parameters for both cases:
42 It is possible to set limits for both IOPS and bps at the same time,
45 iops-read nor iops-write can be set. The same applies to bps-total and
48 The default value of these parameters is 0, and it means 'unlimited'.
50 In its most basic usage, the user can add a drive to QEMU with a limit
51 of 100 IOPS with the following -drive line:
55 We can do the same using QMP. In this case all these parameters are
56 mandatory, so we must set to 0 the ones that we don't want to limit:
73 In addition to the basic limits we have just seen, QEMU allows the
75 an amount of I/O that can exceed the basic limit. Bursts are useful to
76 allow better performance when there are peaks of activity (the OS
77 boots, a service needs to be restarted) while keeping the average
78 limits lower the rest of the time.
80 Two parameters control bursts: their length and the maximum amount of
82 the six basic parameters described in the previous section, but in
85 The I/O limit during bursts is set using 'iops-total-max', and the
88 bursts of 2000 IOPS for 60 seconds, we would do it like this (the line
112 With this, the user can perform I/O on hd0.qcow2 at a rate of 2000
115 The user will be able to do bursts again if there's a sufficiently
118 The default value for 'iops-total-max' is 0 and it means that bursts
122 Here's the complete list of parameters for configuring bursts:
142 Controlling the size of I/O operations
145 regardless of their size. This means that the user can take advantage
146 of this in order to circumvent the limits and submit one huge I/O
150 from happening. This setting specifies the size (in bytes) of an I/O
159 The default value of iops-size is 0 and it means that the size of the
165 In all the examples so far we have seen how to apply limits to the I/O
167 they all share the same limits.
169 The way it works is that each drive with I/O limits is assigned to a
170 group named using the throttling.group parameter. If this parameter is
171 not specified, then the device name (i.e. 'virtio0', 'ide0-hd0') will
172 be used as the group name.
174 Limits set using the throttling.* parameters discussed earlier in this
175 document apply to the combined I/O of all members of a group.
191 I/O requests on several drives of the same group they will be
194 When I/O limits are applied to an existing drive using the QMP command
195 'block_set_io_throttle', the following things need to be taken into
198    - I/O limits are shared within the same group, so new values will
199      affect all members and overwrite the previous settings. In other
200      words: if different limits are applied to members of the same
201      group, the last one wins.
203    - If 'group' is unset it is assumed to be the current group of that
204      drive. If the drive is not in a group yet, it will be added to a
205      group named after the device name.
207    - If 'group' is set then the drive will be moved to that group if
208      it was member of a different one. In this case the limits
209      specified in the parameters will be applied to the new group
213      case the device will be removed from its group and the rest of
214      its members will not be affected. The 'group' parameter is
218 The Leaky Bucket algorithm
220 I/O limits in QEMU are implemented using the leaky bucket algorithm
221 (specifically the "Leaky bucket as a meter" variant).
223 This algorithm uses the analogy of a bucket that leaks water
224 constantly. The water that gets into the bucket represents the I/O
225 that has been performed, and no more I/O is allowed once the bucket is
228 To see the way this corresponds to the throttling parameters in QEMU,
229 consider the following values:
235   - Water leaks from the bucket at a rate of 100 IOPS.
236   - Water can be added to the bucket at a rate of 2000 IOPS.
237   - The size of the bucket is 2000 x 60 = 120000
238   - If 'iops-total-max-length' is unset then it defaults to 1 and the
239     size of the bucket is 2000.
241     unset as well. In this case the bucket size is 100.
243 The bucket is initially empty, therefore water can be added until it's
244 full at a rate of 2000 IOPS (the burst rate). Once the bucket is full
245 we can only add as much water as it leaks, therefore the I/O rate is
246 reduced to 100 IOPS. If we add less water than it leaks then the
249 Note that since water is leaking from the bucket even during bursts,
251 up. After those 60 seconds the bucket will have leaked 60 x 100 =
254 Also, due to the way the algorithm works, longer burst can be done at
258 The 'throttle' block filter
260 Since QEMU 2.11 it is possible to configure the I/O limits using a
261 'throttle' block filter. This filter uses the exact same throttling
262 infrastructure described above but can be used anywhere in the node
265 The user can create an arbitrary number of filters and each one of
266 them must be assigned to a group that contains the actual I/O limits.
267 Different filters can use the same group so the limits are shared as
270 A group can be created using the object-add QMP function:
287 A throttle-group can also be created with the -object command line
288 option but at the moment there is no way to pass a 'limits' parameter
289 that contains a ThrottleLimits structure. The solution is to set the
294 Note however that this is not a stable API (hence the 'x-' prefixes) and
298 Once we have a throttle-group we can use the throttle block filter,
299 where the 'file' property must be set to the block device that we want
324 A similar setup can also be done with the command line, for example:
329 The scenario described so far is very simple but the throttle block
332 each one of them and an additional set of limits for the combined I/O
335 First we would define all throttle groups, one for each one of the
343 Now we can define the drives, and for each one of them we use two
344 chained throttle filters: the drive's own filter and the combined
357 In this example the individual drives have IOPS limits of 2000, 2500
358 and 3000 respectively but the total combined I/O can never exceed 4000