[PATCH v2 0/2] blk-iolatency: fix io.latency documentation accuracy

[PATCH v2 0/2] blk-iolatency: fix io.latency documentation accuracy

[Tao Cui]

From: Tao Cui <cuitao@kylinos.cn>

Hi,

This series fixes three inaccuracies in the io.latency documentation
(Documentation/admin-guide/cgroup-v2.rst), all caused by the doc
describing only rotational-device behavior:

  Patch 1 documents the rotational vs non-rotational difference:
  throttling is based on average latency on rotational devices but on the
  fraction of IOs that miss the target on non-rotational devices; the
  tuning guidance and io.stat field list are updated accordingly
  (avg_lat/win are rotational-only; missed/total are documented for
  non-rotational devices).

  Patch 2 corrects the delay unit: io.stat reports delay_nsec in
  nanoseconds, not microseconds as the doc stated.

Both patches are documentation-only and checkpatch-clean.

---

Changes in v2 (address review feedback):
  - The non-rotational tuning guidance no longer implies missed/total is a
    latency baseline: iolatency reports no average latency for
    non-rotational devices, so the target must be chosen from device
    characteristics and missed/total only verifies it is being met.
  - missed/total are now described as live counters for the current window
    (accumulated since the last window boundary), not "the last window":
    iolatency_ssd_stat() sums the per-cpu counters without resetting them,
    while they are reset at window end by iolatency_check_latencies().

Tao Cui (2):
  Docs/admin-guide/cgroup-v2: document io.latency rotational vs
    non-rotational behavior
  Docs/admin-guide/cgroup-v2: fix delay_nsec unit in io.latency doc

 Documentation/admin-guide/cgroup-v2.rst | 55 +++++++++++++++++--------
 1 file changed, 38 insertions(+), 17 deletions(-)

--
2.43.0

[PATCH v2 1/2] Docs/admin-guide/cgroup-v2: document io.latency rotational vs non-rotational behavior

[Tao Cui]

From: Tao Cui <cuitao@kylinos.cn>

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 <cuitao@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v2.rst | 49 ++++++++++++++++++-------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 0df15a672cf3..4386365ef180 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2260,9 +2260,12 @@ 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.
+with a latency target, and if the group misses its target the controller will
+throttle any peers that have a lower latency target than the protected
+workload.  How a miss is detected depends on the device: on rotational devices
+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.
 
 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
@@ -2279,10 +2282,12 @@ 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, 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 operation.
-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 devices,
+use the avg_lat value as a basis for your real setting, setting it 10-15%
+higher.  On non-rotational devices io.stat reports no average latency; set
+the target based on your device and use the missed/total fields to verify it
+is being met.
 
 How IO Latency Throttling Works
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2324,19 +2329,35 @@ IO Latency Interface Files
 	the blkcg_debug_stats module parameter is enabled (it is disabled by
 	default).
 
+	The reported latency fields depend on the device.  Rotational devices
+	report avg_lat and win; non-rotational devices report missed and total
+	instead.  missed and total are live counters for the current window and
+	may change between reads.
+
 	  depth
 		This is the current queue depth for the group.
 
 	  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.
 
 	  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
+		current window whose latency exceeded the target.
+
+	  total
+		(Non-rotational devices only.)  The total number of IOs
+		accounted in the current window.  A group is considered to be
+		missing its target once missed reaches 10% of total.
 
 IO Priority
 ~~~~~~~~~~~
-- 
2.43.0

[PATCH v2 2/2] Docs/admin-guide/cgroup-v2: fix delay_nsec unit in io.latency doc

[Tao Cui]

From: Tao Cui <cuitao@kylinos.cn>

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 <cuitao@kylinos.cn>
---
 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 4386365ef180..755c2a1942ef 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2305,9 +2305,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 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
+  originating group is being throttled you will see the use_delay and delay_nsec
+  fields in io.stat increase.  The delay_nsec value is how many nanoseconds 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.
 
-- 
2.43.0

Re: [PATCH v2 1/2] Docs/admin-guide/cgroup-v2: document io.latency rotational vs non-rotational behavior

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 990 bytes --]

Hi.

On Fri, Jul 17, 2026 at 02:02:24PM +0800, Tao Cui <cui.tao@linux.dev> wrote:
> -		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
> +		current window whose latency exceeded the target.

		A group is considered to be missing its target once
		missed reaches certain ratio of total.

I would not bind to the exact value in the docs and put the explanation
to the "missed" stanza.

Thanks for documenting missed (pun intended) fields.

Besides that
Acked-by: Michal Koutný <mkoutny@suse.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

Re: [PATCH v2 2/2] Docs/admin-guide/cgroup-v2: fix delay_nsec unit in io.latency doc

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 516 bytes --]

On Fri, Jul 17, 2026 at 02:02:25PM +0800, Tao Cui <cui.tao@linux.dev> wrote:
> From: Tao Cui <cuitao@kylinos.cn>
> 
> 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 <cuitao@kylinos.cn>
> ---
>  Documentation/admin-guide/cgroup-v2.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)

Acked-by: Michal Koutný <mkoutny@suse.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

Re: [PATCH v2 1/2] Docs/admin-guide/cgroup-v2: document io.latency rotational vs non-rotational behavior

[Tejun Heo]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 227 bytes --]

Hello,

On Fri, Jul 17, 2026 at 04:48:40PM +0200, Michal Koutný wrote:
> I would not bind to the exact value in the docs and put the explanation
> to the "missed" stanza.

I'll wait for an updated version.

Thanks.

-- 
tejun

Re: [PATCH v2 2/2] Docs/admin-guide/cgroup-v2: fix delay_nsec unit in io.latency doc

[Tejun Heo]

Hello,

Applied 2/2 to cgroup/for-7.3 with Michal's ack added.

Thanks.

-- 
tejun