doc/rbd/rbd-config-ref: add more detail on QoS settings

Signed-off-by: Josh Durgin <jdurgin@redhat.com>

diff --git a/doc/rbd/rbd-config-ref.rst b/doc/rbd/rbd-config-ref.rst
index 3f2fdc304e5a09f90a6679559abec8d8a31a1dfe..c21731adca8a925154da272ba77a7af03737dc1b 100644 (file)
--- a/doc/rbd/rbd-config-ref.rst
+++ b/doc/rbd/rbd-config-ref.rst
@@ -212,11 +212,36 @@ creating images or the default features can be configured via
 :KRBD support: no
 
 
-QOS Settings
+QoS Settings
 ============
 
-librbd supports limiting per-image IO, controlled by the following
-settings.
+librbd supports limiting per-image IO in several ways. These all apply
+to a given image within a given process - the same image used in
+multiple places, e.g. two separate VMs, would have independent limits.
+
+* **IOPS:** number of I/Os per second (any type of I/O)
+* **read IOPS:** number of read I/Os per second
+* **write IOPS:** number of write I/Os per second
+* **bps:** bytes per second (any type of I/O)
+* **read bps:** bytes per second read
+* **write bps:** bytes per second written
+
+Each of these limits operates independently of each other. They are
+all off by default. Every type of limit throttles I/O using a token
+bucket algorithm, with the ability to configure the limit (average
+speed over time) and potential for a higher rate (a burst) for a short
+period of time (burst_seconds). When any of these limits is reached,
+and there is no burst capacity left, librbd reduces the rate of that
+type of I/O to the limit.
+
+For example, if a read bps limit of 100MB was configured, but writes
+were not limited, writes could proceed as quickly as possible, while
+reads would be throttled to 100MB/s on average. If a read bps burst of
+150MB was set, and read burst seconds was set to five seconds, reads
+could proceed at 150MB/s for up to five seconds before dropping back
+to the 100MB/s limit.
+
+The following options configure these throttles:
 
 .. confval:: rbd_qos_iops_limit
 .. confval:: rbd_qos_iops_burst
@@ -237,3 +262,4 @@ settings.
 .. confval:: rbd_qos_write_bps_burst
 .. confval:: rbd_qos_write_bps_burst_seconds
 .. confval:: rbd_qos_schedule_tick_min
+.. confval:: rbd_qos_exclude_ops

diff --git a/src/common/options/rbd.yaml.in b/src/common/options/rbd.yaml.in
index 328fa43d18c41a578bc135fe4d944c9621c6bead..143241c2ba1abfc1412fb5237f78b6fb4652e2e6 100644 (file)
--- a/src/common/options/rbd.yaml.in
+++ b/src/common/options/rbd.yaml.in
@@ -742,6 +742,10 @@ options:
   type: uint
   level: advanced
   desc: minimum schedule tick (in milliseconds) for QoS
+  long_desc: This determines the minimum time (in milliseconds) at which I/Os
+    can become unblocked if the limit of a throttle is hit. In terms of the
+    token bucket algorithm, this is the minimum interval at which tokens are
+    added to the bucket.
   default: 50
   services:
   - rbd