From nobody Sat Jul 25 06:09:13 2026 Received: from out-178.mta1.migadu.com (out-178.mta1.migadu.com [95.215.58.178]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 48C8E37AA8C; Fri, 17 Jul 2026 04:29:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=95.215.58.178 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784262552; cv=none; b=IHY1FDdhm0KaB2Z/AvTGOG2XAjdW83zJZCdlTlmQ/drgUYDTJFmN5ICeuDWQBPda0eTt1MK5/qX+Fg1nemcIkKxbjrrGUFIDcBlSw/3DDjGtUrqn8A2y4EmYa3apjjpA0O0e24RmXVZSOyt6oHYKXgYfDCfI9y8wMuXa+5YatwU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784262552; c=relaxed/simple; bh=wQi/SMTVdefiMqu2PxD/sLKpm4cCjxK0NTsWiOHILnU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=nXEWTX9mcXhkCbEMr3gYq0wIRwLFdiZqFtpJgU4o6tlJQyIQysxJdJNCENdr1LuIwrZlmxvx9f09nLQntj7z8QTOJzQ3cCnvADpOYmJM0WRVDV91ABhr1HJE7WGGX2EReKaBiyuLXWLRybu3Uf2Jvk5yTEWn1egAeObOUA3EufA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.dev; spf=pass smtp.mailfrom=linux.dev; dkim=pass (1024-bit key) header.d=linux.dev header.i=@linux.dev header.b=V2tuN53e; arc=none smtp.client-ip=95.215.58.178 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.dev Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linux.dev Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=linux.dev header.i=@linux.dev header.b="V2tuN53e" X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.dev; s=key1; t=1784262548; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qeAimfuoN51h/ppgVeCctCXr7ldsL6uIsocF+GoKyVY=; b=V2tuN53e9ti/v1nPfd99pyN3KpS5g1U98e/QbfayqnGSnapYNKfXSCaNGmv8V26j/d3FhG DMmoIr53uyTRzJ77FQosdqgHYu568Sxl1U20cwTfd18Wl0QOktrKpoCUw0RFtU+pF5Fp7D N1NVv6TjS/qtdtdilG+r6mUTDp+XN+U= From: Tao Cui To: Tejun Heo Cc: Johannes Weiner , =?UTF-8?q?Michal=20Koutn=C3=BD?= , Jonathan Corbet , Shuah Khan , Josef Bacik , Jens Axboe , cgroups@vger.kernel.org, linux-doc@vger.kernel.org, linux-block@vger.kernel.org, linux-kernel@vger.kernel.org, Tao Cui Subject: [PATCH 1/2] Docs/admin-guide/cgroup-v2: document io.latency rotational vs non-rotational behavior Date: Fri, 17 Jul 2026 12:28:16 +0800 Message-ID: <20260717042817.2001826-2-cui.tao@linux.dev> In-Reply-To: <20260717042817.2001826-1-cui.tao@linux.dev> References: <20260717042817.2001826-1-cui.tao@linux.dev> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Migadu-Flow: FLOW_OUT Content-Type: text/plain; charset="utf-8" From: Tao Cui io.latency is documented only in terms of average latency and the avg_lat stat, which matches rotational devices. On non-rotational devices a group misses its target when 10% or more of the IOs in the window individually exceed it, and io.stat reports missed/total rather than avg_lat/win. Describe both cases: how a miss is detected, note that the avg_lat tuning guidance is rotational-only, and update the io.stat field list (mark avg_lat/win as rotational-only, document missed/total). Signed-off-by: Tao Cui --- Documentation/admin-guide/cgroup-v2.rst | 47 +++++++++++++++++-------- 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-= guide/cgroup-v2.rst index 0df15a672cf3..eec99813d82d 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -2260,9 +2260,12 @@ IO Latency ~~~~~~~~~~ =20 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 t= he -protected workload. +with a latency target, and if the group misses its target the controller w= ill +throttle any peers that have a lower latency target than the protected +workload. How a miss is detected depends on the device: on rotational dev= ices +the average latency over the window must exceed the target, while on +non-rotational devices a miss is counted when 10% or more of the IOs in the +window individually exceed the target. =20 The limits are only applied at the peer level in the hierarchy. This mean= s that in the diagram below, only groups A, B, and C will influence each other, a= nd @@ -2279,10 +2282,11 @@ So the ideal way to configure this is to set io.lat= ency 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, with -blkcg_debug_stats enabled, watch the avg_lat value in io.stat for your -workload group to get an idea of the latency you see during normal operati= on. -Use the avg_lat value as a basis for your real setting, setting at 10-15% -higher than the value in io.stat. +blkcg_debug_stats enabled, observe io.stat for your workload group to get = an +idea of the latency you see during normal operation. On rotational device= s, +use the avg_lat value as a basis for your real setting, setting it 10-15% +higher. On non-rotational devices avg_lat is not reported; watch the +missed/total ratio instead. =20 How IO Latency Throttling Works ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2324,19 +2328,34 @@ IO Latency Interface Files the blkcg_debug_stats module parameter is enabled (it is disabled by default). =20 + The reported latency fields depend on the device. Rotational devices + report avg_lat and win; non-rotational devices report missed and total + instead. + depth This is the current queue depth for the group. =20 avg_lat - This is an exponential moving average with a decay rate of 1/exp - bound by the sampling interval. The decay rate interval can be - calculated by multiplying the win value in io.stat by the - corresponding number of samples based on the win value. + (Rotational devices only.) This is an exponential moving + average with a decay rate of 1/exp bound by the sampling + interval. The decay rate interval can be calculated by + multiplying the win value in io.stat by the corresponding number + of samples based on the win value. =20 win - The sampling window size in milliseconds. This is the minimum - duration of time between evaluation events. Windows only elapse - with IO activity. Idle periods extend the most recent window. + (Rotational devices only.) The sampling window size in + milliseconds. This is the minimum duration of time between + evaluation events. Windows only elapse with IO activity. Idle + periods extend the most recent window. + + missed + (Non-rotational devices only.) The number of IOs in the last + window whose latency exceeded the target. + + total + (Non-rotational devices only.) The total number of IOs + accounted in the last window. A group is considered to be + missing its target once missed reaches 10% of total. =20 IO Priority ~~~~~~~~~~~ --=20 2.43.0 From nobody Sat Jul 25 06:09:13 2026 Received: from out-179.mta1.migadu.com (out-179.mta1.migadu.com [95.215.58.179]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D5DB137C10A for ; Fri, 17 Jul 2026 04:29:14 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=95.215.58.179 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784262559; cv=none; b=sbJA2Fz/CO0OdPxKH30jzVydr1mIJ6mpk/uw2sIXd/iL/E+DRT7ybM+eAYkJgkgg1vPQVr9+FuRJhcH8X+h9Pdk1YMEljKzVDOblYWvtOKXtiGgRAe2W1WtvS+jrRNoEpaZCjEAVbZ5Z2VGgyVizhAjBcOYNSc6V97WTxiGF0u8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784262559; c=relaxed/simple; bh=ua3GEs8av4fKYGgEome92IxLpMf9Xz9GhNiVp1ilV6w=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=lKcS5p74yM6nVjf7/B87IR/Wk5byWuVCd1RWCkIzxlQfs9cU8zRvZkUzG3vfZn3L+uTz7kuTnmpJtan1AJTWX6e0w4/+mIy2LAYKqadcShH7pGuH2REDp+x8uj8HmBgk6rczEkGoOkrouVZg1ZIeFnooCA4XHU5bdvDuMIz64NE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.dev; spf=pass smtp.mailfrom=linux.dev; dkim=pass (1024-bit key) header.d=linux.dev header.i=@linux.dev header.b=W8z8SST+; arc=none smtp.client-ip=95.215.58.179 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.dev Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linux.dev Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=linux.dev header.i=@linux.dev header.b="W8z8SST+" X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.dev; s=key1; t=1784262552; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=0WA/PccghGHgwDI3QqI4VMqYsFAIGgfe0C5h0k9pSEA=; b=W8z8SST++zfFC9i3WtnOP0DxUpDZvwy4SWcjOBJ42YAhBVUfKpdgpoenK1a6GyrnpMkiHS s5pDbSLzRqVIX8aDdZ0mls7aRSjt9SgH+SJkmute2AZpirbCxOwiNbnk818sf/E1uuYr0T HJqCmS6Q9NrUMGJOSPHjkG1w3fm9WRk= From: Tao Cui To: Tejun Heo Cc: Johannes Weiner , =?UTF-8?q?Michal=20Koutn=C3=BD?= , Jonathan Corbet , Shuah Khan , Josef Bacik , Jens Axboe , cgroups@vger.kernel.org, linux-doc@vger.kernel.org, linux-block@vger.kernel.org, linux-kernel@vger.kernel.org, Tao Cui Subject: [PATCH 2/2] Docs/admin-guide/cgroup-v2: fix delay_nsec unit in io.latency doc Date: Fri, 17 Jul 2026 12:28:17 +0800 Message-ID: <20260717042817.2001826-3-cui.tao@linux.dev> In-Reply-To: <20260717042817.2001826-1-cui.tao@linux.dev> References: <20260717042817.2001826-1-cui.tao@linux.dev> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Migadu-Flow: FLOW_OUT Content-Type: text/plain; charset="utf-8" From: Tao Cui The io.latency doc says the io.stat delay field counts microseconds. The field is delay_nsec and is reported in nanoseconds. Refer to it by its real name and correct the unit. Signed-off-by: Tao Cui --- Documentation/admin-guide/cgroup-v2.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-= guide/cgroup-v2.rst index eec99813d82d..687839cf5c73 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -2304,9 +2304,9 @@ This throttling takes 2 forms: throttled without possibly adversely affecting higher priority groups. = This includes swapping and metadata IO. These types of IO are allowed to occ= ur 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 th= at are - being added to any process that runs in this group. Because this number= can + originating group is being throttled you will see the use_delay and dela= y_nsec + fields in io.stat increase. The delay_nsec value is how many nanosecond= s that + are being added to any process that runs in this group. Because this nu= mber 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. =20 --=20 2.43.0