mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-08-27 19:53:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

Docs/admin-guide/cgroup-v2: document io.latency rotational vs non-rotational behavior

Browse Source 
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 once enough 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).

Acked-by: Michal Koutný <mkoutny@suse.com>
Signed-off-by: Tao Cui <cuitao@kylinos.cn>
Signed-off-by: Tejun Heo <tj@kernel.org>
This commit is contained in:
Tao Cui
2026-07-28 17:57:07 +08:00
committed by Tejun Heo
parent 5457025fa8
commit 2fd9b4cfce
1 changed files with 36 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
Documentation/admin-guide/cgroup-v2.rst
View File

@@ -2239,9 +2239,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 once enough 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
@@ -2258,10 +2261,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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2303,19 +2308,36 @@ 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. A group is
considered to be missing its target once missed reaches a
certain ratio of total.
total
(Non-rotational devices only.) The total number of IOs
accounted in the current window.
IO Priority
~~~~~~~~~~~