Linux 怎样读取 cgroup v2 CPU 节流统计

读取 cgroup v2 的 CPU 节流统计，核心是目标目录里的 cpu.stat：关注 nr_periods、nr_throttled、throttled_usec，并对同一对象做区间增量。一次累计值只能说明历史，不能直接证明刚才的慢请求就是配额导致的。

如果面对“增加并发后延迟升高，但整机 CPU 还不满”的场景，我会先保留节流假设，再采集证据，不立即扩机器或放宽限制。本文没有执行采样或压测，以下数据均为说明用假设。官方接口文档：https://docs.kernel.org/admin-guide/cgroup-v2.html。

我会先把慢请求与配额猜测分开

一个服务受 CPU 带宽限制时，增加工作线程不一定获得更多可用运行时间。带宽用尽可能使任务暂时不能继续执行，但类似延迟现象也可能来自其他原因。我的取舍是先回答“这个观察窗口里有没有节流计数增长”，而不是编造一次架构改造成功案例。

带宽机制说明可参考 https://docs.kernel.org/scheduler/sched-bwc.html。该文部分管理文件属于 v1，不能照搬到 v2；本文统一读取 v2 的 cpu.stat 与 cpu.max，不写任何控制文件。

确认cpu.stat属于目标服务

# systemd 系统服务的只读查询；worker.service 应替换为真实单元名。
systemctl show worker.service -p ControlGroup
# 核对当前命名空间内的 cgroup2 挂载点。
findmnt -t cgroup2

假如已确认 ControlGroup 是 /system.slice/worker.service，且当前命名空间将完整统一层级挂载于 /sys/fs/cgroup，目录才可对应为 /sys/fs/cgroup/system.slice/worker.service。容器、委托子树或不同挂载根下不能直接照拼宿主机路径。

# 仅在上面的路径映射已经确认后读取；不存在时停止并重查对象。
cat /sys/fs/cgroup/system.slice/worker.service/cpu.stat
# 只读配额背景，不向 cpu.max 写入任何内容。
cat /sys/fs/cgroup/system.slice/worker.service/cpu.max

我会把目标服务身份、目录与生命周期一起记录。服务重新创建 cgroup 后，即使路径字符串相同，也不能无条件把新旧累计计数相减。

分别读使用量、节流次数和节流时长

当前接口文档区分了范围：使用量覆盖组及后代进程；上述带宽节流统计面向 fair-class 调度，并非将祖先限制造成的全部节流简单汇总到当前层。不同字段不能随意套用同一层级口径。控制器未启用等情况下，节流字段可能缺失，缺失不是零。

用两次采样替代累计值比较

下面的 Python 3 标准库脚本只读给定目录中的 cpu.stat，等待约两秒再读一次。它按键求差、保留实际采样时长，并拒绝明显的目录变化、字段缺失与负增量。它不是完整监控代理，目录 inode 比对也不能取代生产系统的服务生命周期标识。

from pathlib import Path
import sys
import time


def read_stat(path):
    # 按键解析，允许内核增加字段，不依赖固定行序。
    return {
        key: int(value)
        for key, value in (
            line.split() for line in path.read_text().splitlines()
        )
    }


def main():
    # 参数必须是已经定位好的目标 cgroup 目录。
    group = Path(sys.argv[1])
    stat_path = group / "cpu.stat"
    keys = ("nr_periods", "nr_throttled", "throttled_usec")
    identity = group.stat()
    start = time.monotonic()
    before = read_stat(stat_path)
    time.sleep(2)
    after = read_stat(stat_path)
    elapsed = time.monotonic() - start
    current = group.stat()
    # 目录被替换时拒绝把不同生命周期拼成一段增量。
    if (identity.st_dev, identity.st_ino) != (current.st_dev, current.st_ino):
        raise RuntimeError("cgroup 目录已变化，请重新采样")
    if any(key not in before or key not in after for key in keys):
        raise RuntimeError("节流字段缺失，请先核对 CPU 控制器与内核")
    delta = {key: after[key] - before[key] for key in keys}
    if any(value  0:
        ratio = delta["nr_throttled"] / delta["nr_periods"]
        print("节流计数与周期计数之比：", round(ratio, 4))
    else:
        print("无周期增量，本次不计算比值")


if __name__ == "__main__":
    # 错误直接显式退出，不将读取失败当作零节流。
    main()

# 将代码保存为 read_cpu_stat.py，路径换成已确认的目标目录。
python3 read_cpu_stat.py /sys/fs/cgroup/system.slice/worker.service

本文未运行这些命令，因此不展示伪造日志。实际读失败、权限不足、文件缺失等错误应原样处理，不能静默补成 0 后声称“没有节流”。多字段读取与两次文件读取也不是对运行系统的全局原子快照。

把统计结果放回容量决策

假设两次采样的 nr_periods 分别为 1000、1020，nr_throttled 分别为 100、106，throttled_usec 分别为 400000、550000。对应增量是 20、6、150000；6/20=0.30 是这两个计数增量的比值，150000 微秒是 0.15 秒。它们只是算术示例，不是生产测量，也不表示“30% 请求被节流”或“每次请求慢了 0.15 秒”。

我会将这种结果记为“当前窗口有本层带宽节流活动”，再对照相同窗口的负载与请求延迟。没有同期业务信号，就不足以认定它是延迟的唯一根因；也不应直接用 throttled_usec 除以墙钟时间命名为 CPU 使用率。

若后续计划调整并发或容量，我会先固定采样对象与工作负载，再比较窗口。改配额会影响资源隔离，改并发也可能影响吞吐；这些是需要独立评估的变更，本文不替读者执行，更不预设调整一定有效。

我会保留的边界与常见疑问

cpu.max 显示 max 就一定不会受到 CPU 限制吗？

不能这样判断，它只能说明此处配置的背景，还要查看祖先层级限制。当前层计数没有增长，也不能排除祖先配额耗尽让后代无法运行；应沿已确认的可见层级分别读取，而不是把父子计数随意相加。

节流计数为零能排除所有 CPU 等待吗？

不能，它不是所有调度等待的总表，也不是全局繁忙程度。先确认字段存在、采样窗口有效、工作负载确实处于目标组，再决定是否需要调查别的等待来源。

为什么不同内核会出现额外字段？

接口会随内核演进，解析时应按字段名而非固定行号。额外字段可保留，但不要把 v1 的纳秒时长名套到 v2 的 throttled_usec 上，也不要把未识别项猜成已知指标。

对我来说，这套读取方法适合给“配额是否在当前窗口产生节流”补上证据，不适合单独给扩容或优化背书。先确保同一对象，再区分字段口径，最后才谈业务影响。