From patchwork Tue May 29 21:17:24 2018
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: Josef Bacik <josef@toxicpanda.com>
X-Patchwork-Id: 10437099
Return-Path: <linux-block-owner@kernel.org>
Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org
	[172.30.200.125])
	by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id
	D5848601E9 for <patchwork-linux-block@patchwork.kernel.org>;
	Tue, 29 May 2018 21:18:11 +0000 (UTC)
Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1])
	by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C4E1228991
	for <patchwork-linux-block@patchwork.kernel.org>;
	Tue, 29 May 2018 21:18:11 +0000 (UTC)
Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486)
	id B9944289A0; Tue, 29 May 2018 21:18:11 +0000 (UTC)
X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on
	pdx-wl-mail.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID, MAILING_LIST_MULTI,
	RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1
Received: from vger.kernel.org (vger.kernel.org [209.132.180.67])
	by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 448A628994
	for <patchwork-linux-block@patchwork.kernel.org>;
	Tue, 29 May 2018 21:18:11 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S967450AbeE2VSG (ORCPT
	<rfc822;patchwork-linux-block@patchwork.kernel.org>);
	Tue, 29 May 2018 17:18:06 -0400
Received: from mail-qt0-f194.google.com ([209.85.216.194]:45901 "EHLO
	mail-qt0-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S967355AbeE2VRs (ORCPT
	<rfc822;linux-block@vger.kernel.org>);
	Tue, 29 May 2018 17:17:48 -0400
Received: by mail-qt0-f194.google.com with SMTP id i18-v6so9940606qtp.12
	for <linux-block@vger.kernel.org>;
	Tue, 29 May 2018 14:17:47 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
	d=toxicpanda-com.20150623.gappssmtp.com; s=20150623;
	h=from:to:cc:subject:date:message-id:in-reply-to:references;
	bh=IyJFroynqUhehY8NnXUm2JeWo7lGd19vWi6nNWJ/sfY=;
	b=RaWuD3KsXfFzd9GvINrZ5THBomvAAF9s8zNjYBXh0ujkdGr/p4XjVq0hWV8N7n+/Oe
	EfcqyQXLKpnEb5FGVnCgoxg9xei1uAQY4gcA1Y8c0HgKgYbCAMfF7Xg3oJGxBqsH0qgs
	Htl4vRR+WVHsuvGkE/87gC5AhFHEgsDwdNdXuG0fENwTANdvY5EsHlMulJ2WMfNZ+qBw
	S3BVyHyNKSrUU6/tIPP34I2C08+IbXw34d/Kc7/HICXhFNglehSehg2+0iwsg01RFDh6
	8Hp6LZr458LwjpTw5zmIFY1oLkRTo13c9bB2Wa13B80804vOlBhtjk7rC7vw24nz9oEh
	gM1g==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
	d=1e100.net; s=20161025;
	h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
	:references;
	bh=IyJFroynqUhehY8NnXUm2JeWo7lGd19vWi6nNWJ/sfY=;
	b=DfBCmUi6iY+3p0rLZFoAHyFuiaDEh76NTjhKcOAC1JdD4diOoduJfoVK0m/iYUGKBC
	soUNgSvLBrpgCRxNLlq0dy0FLd8UQO7TlKtV/Vgh76AvdFm3Bo073w43z0qCcCqZeU1P
	SrOfa92jHfcvqT2/FlrlniCxemKKoc3ahz0C+WiLidTIVaXtron2km2VoNAlBK2qX5Da
	zQgY9YZrqz8HIzFc6rbYtvvmcn1vBup78IT6cjjHtAw0yUrwfwtFVEKYQxOjogKOUAyV
	kUzpo/OT9GM2GM5BJpb9lf58GYWBNCrp+Uixukbq64Na9uQgVf8SqF48ZvspDD7cbR3V
	Hb7A==
X-Gm-Message-State: APt69E1OyM/leUqLHrtDB8LP6VuEyN3bxP5UehvqEtIe05KnO+X5M+Ch
	0jit2qFyq6bpR00ToTlnvHOIpQ==
X-Google-Smtp-Source: 
 ADUXVKLNAbwbhxyxNu7qukElTuxhXoCXC+o5oNMGSmMZY9Sv0qXbFltcxnrYCz6FN/EZOgDXoCxWgQ==
X-Received: by 2002:a0c:b7af:: with SMTP id
	l47-v6mr90445qve.110.1527628667265;
	Tue, 29 May 2018 14:17:47 -0700 (PDT)
Received: from localhost
	(cpe-2606-A000-4381-1201-225-22FF-FEB3-E51A.dyn6.twc.com.
	[2606:a000:4381:1201:225:22ff:feb3:e51a])
	by smtp.gmail.com with ESMTPSA id
	r2-v6sm4338535qtj.54.2018.05.29.14.17.46
	(version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
	Tue, 29 May 2018 14:17:46 -0700 (PDT)
From: Josef Bacik <josef@toxicpanda.com>
To: axboe@kernel.dk, kernel-team@fb.com, linux-block@vger.kernel.org,
	akpm@linux-foundation.org, linux-mm@kvack.org, hannes@cmpxchg.org,
	linux-kernel@vger.kernel.org, tj@kernel.org,
	linux-fsdevel@vger.kernel.org
Cc: Josef Bacik <jbacik@fb.com>
Subject: [PATCH 13/13] Documentation: add a doc for blk-iolatency
Date: Tue, 29 May 2018 17:17:24 -0400
Message-Id: <20180529211724.4531-14-josef@toxicpanda.com>
X-Mailer: git-send-email 2.14.3
In-Reply-To: <20180529211724.4531-1-josef@toxicpanda.com>
References: <20180529211724.4531-1-josef@toxicpanda.com>
Sender: linux-block-owner@vger.kernel.org
Precedence: bulk
List-ID: <linux-block.vger.kernel.org>
X-Mailing-List: linux-block@vger.kernel.org
X-Virus-Scanned: ClamAV using ClamSMTP

From: Josef Bacik <jbacik@fb.com>

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

Signed-off-by: Josef Bacik <jbacik@fb.com>
---
 Documentation/blk-iolatency.txt | 80 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 Documentation/blk-iolatency.txt

diff --git a/Documentation/blk-iolatency.txt b/Documentation/blk-iolatency.txt
new file mode 100644
index 000000000000..9dd86f4f64b6
--- /dev/null
+++ b/Documentation/blk-iolatency.txt
@@ -0,0 +1,80 @@
+Block IO Latency Controller
+
+Overview
+========
+
+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.
+
+Interface
+=========
+
+- 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=<integer>.  This is the current queue depth for the group.
+	- delay=<time in microseconds>. This is the current delay per task that
+	  does IO in this group.
+	- use_delay=<integer>.  This is how deep into the delay we currently
+	  are, the larger this number is the longer it'll take us to get back to
+	  queue depth > 1.
+	- total_lat_avg=<time in microseconds>.  The running average IO latency
+	  for this group.  Running average is generally flawed, but will give an
+	  admistrator a general idea of the overall latency they can expect for
+	  their workload on the given disk.
+
+HOWTO
+=====
+
+The limits are only applied at the peer level in the heirarchy.  This means that
+in the diagram below, only groups A, B, and C will influence eachother, and
+groups D and F will influence eachother.  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 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 occuring 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 previous.  If the victimized
+group simply stops doing IO the global counter will unthrottle appropriately.