archive mirror
 help / color / mirror / Atom feed
From: Josef Bacik <>
Cc: Josef Bacik <>
Subject: [PATCH 13/13] Documentation: add a doc for blk-iolatency
Date: Tue,  5 Jun 2018 09:29:48 -0400	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

From: Josef Bacik <>

A basic documentation to describe the interface, statistics, and
behavior of io.latency.

Signed-off-by: Josef Bacik <>
 Documentation/cgroup-v2.txt | 79 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt
index 74cdeaed9f7a..f6684ec99720 100644
--- a/Documentation/cgroup-v2.txt
+++ b/Documentation/cgroup-v2.txt
@@ -51,6 +51,9 @@ v1 is available under Documentation/cgroup-v1/.
      5-3. IO
        5-3-1. IO Interface Files
        5-3-2. Writeback
+       5-3-3. IO Latency
+         5-3-3-1. How IO Latency Throttling Works
+         5-3-3-2. IO Latency Interface Files
      5-4. PID
        5-4-1. PID Interface Files
      5-5. Device
@@ -1395,6 +1398,82 @@ writeback as follows.
+IO Latency
+This is a cgroup v2 controller for IO workload protection.  You provide a group
+with a latency target, and if the average latency exceeds that target the
+controller will throttle any peers that have a lower latency target than the
+protected workload.
+The limits are only applied at the peer level in the hierarchy.  This means that
+in the diagram below, only groups A, B, and C will influence each other, and
+groups D and F will influence each other.  Group G will influence nobody.
+			[root]
+		/	   |		\
+		A	   B		C
+	       /  \        |
+	      D    F	   G
+So the ideal way to configure this is to set io.latency in groups A, B, and C.
+Generally you do not want to set a value lower than the latency your device
+supports.  Experiment to find the value that works best for your workload, start
+at higher than the expected latency for your device and watch the total_lat_avg
+value in io.stat for your workload group to get an idea of the latency you see
+during normal operation.  Use this value as a basis for your real setting,
+setting at 10-15% higher than the value in io.stat.  Experimentation is key here
+because total_lat_avg is a running total, so is the "statistics" portion of
+"lies, damned lies, and statistics."
+How IO Latency Throttling Works
+io.latency is work conserving, so as long as everybody is meeting their latency
+target the controller doesn't do anything.  Once a group starts missing it's
+target it begins throttling any peer group that has a higher target than itself.
+This throttling takes 2 forms:
+- Queue depth throttling.  This is the number of outstanding IO's a group is
+  allowed to have.  We will clamp down relatively quickly, starting at no limit
+  and going all the way down to 1 IO at a time.
+- Artificial delay induction.  There are certain types of IO that cannot be
+  throttled without possibly adversely affecting higher priority groups.  This
+  includes swapping and metadata IO.  These types of IO are allowed to occur
+  normally, however they are "charged" to the originating group.  If the
+  originating group is being throttled you will see the use_delay and delay
+  fields in io.stat increase.  The delay value is how many microseconds that are
+  being added to any process that runs in this group.  Because this number can
+  grow quite large if there is a lot of swapping or metadata IO occurring we
+  limit the individual delay events to 1 second at a time.
+Once the victimized group starts meeting it's latency target again it will start
+unthrottling any peer groups that were throttled previously.  If the victimized
+group simply stops doing IO the global counter will unthrottle appropriately.
+IO Latency Interface Files
+  io.latency
+	This takes a similar format as the other controllers.
+		"MAJOR:MINOR target=<target time in microseconds"
+  io.stat
+	If the controller is enabled you will see extra stats in io.stat in
+	addition to the normal ones.
+	  depth
+		This is the current queue depth for the group.
+	  avg_lat
+		The running average IO latency for this group in microseconds.
+		Running average is generally flawed, but will give an
+		administrator a general idea of the overall latency they can
+		expect for their workload on the given disk.

  parent reply	other threads:[~2018-06-05 13:30 UTC|newest]

Thread overview: 22+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-06-05 13:29 [PATCH 00/13][V2] Introduce io.latency io controller for cgroups Josef Bacik
2018-06-05 13:29 ` [PATCH 01/13] block: add bi_blkg to the bio " Josef Bacik
2018-06-05 13:29 ` [PATCH 02/13] block: introduce bio_issue_as_root_blkg Josef Bacik
2018-06-05 13:29 ` [PATCH 03/13] blk-cgroup: allow controllers to output their own stats Josef Bacik
2018-06-05 13:29 ` [PATCH 04/13] blk: introduce REQ_SWAP Josef Bacik
2018-06-05 13:29 ` [PATCH 05/13] swap,blkcg: issue swap io with the appropriate context Josef Bacik
2018-06-05 19:41   ` Tejun Heo
2018-06-11 14:06   ` Johannes Weiner
2018-06-05 13:29 ` [PATCH 06/13] blkcg: add generic throttling mechanism Josef Bacik
2018-06-05 20:45   ` Tejun Heo
2018-06-05 13:29 ` [PATCH 07/13] memcontrol: schedule throttling if we are congested Josef Bacik
2018-06-05 20:46   ` Tejun Heo
2018-06-11 14:08   ` Johannes Weiner
2018-06-05 13:29 ` [PATCH 08/13] blk-stat: export helpers for modifying blk_rq_stat Josef Bacik
2018-06-05 13:29 ` [PATCH 09/13] blk-rq-qos: refactor out common elements of blk-wbt Josef Bacik
2018-06-05 13:29 ` [PATCH 10/13] block: remove external dependency on wbt_flags Josef Bacik
2018-06-05 13:29 ` [PATCH 11/13] rq-qos: introduce dio_bio callback Josef Bacik
2018-06-05 13:29 ` [PATCH 12/13] block: introduce blk-iolatency io controller Josef Bacik
2018-06-05 13:29 ` Josef Bacik [this message]
  -- strict thread matches above, loose matches on Subject: below --
2018-05-29 21:17 [PATCH 00/13] Introdue io.latency io controller for cgroups Josef Bacik
2018-05-29 21:17 ` [PATCH 13/13] Documentation: add a doc for blk-iolatency Josef Bacik
2018-05-30 16:44   ` Tejun Heo
2018-05-30 18:32   ` Randy Dunlap

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \ \ \
    --subject='Re: [PATCH 13/13] Documentation: add a doc for blk-iolatency' \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).