Linux PSI Explained: Measuring Resource Contention

Updated on Oct 11, 2026

9 min read

When a Linux service becomes slow, utilization graphs do not always explain why. CPUs can appear idle while tasks wait on memory reclaim or storage, and a busy CPU does not necessarily mean applications are missing their latency targets. Linux Pressure Stall Information (PSI) helps administrators and developers measure how much time workloads spend stalled because of CPU, memory, or I/O contention.

What Is Linux Pressure Stall Information?

Pressure Stall Information is a set of kernel metrics describing the time tasks lose while waiting for resources. Instead of reporting only how much CPU, memory, or I/O is being used, PSI reports whether resource contention is keeping work from making progress. The Linux kernel PSI documentation defines its interfaces, averages, cumulative counters, and event triggers.

On a Linux system with PSI enabled, the kernel exposes system-wide measurements in /proc/pressure/cpu, /proc/pressure/memory, and /proc/pressure/io. On cgroup v2 systems, equivalent files such as cpu.pressure and memory.pressure can report pressure for an individual group of processes. That makes it possible to distinguish pressure affecting one service from pressure affecting the entire host.

PSI is a Linux kernel interface, not an application-level profiler or a measure of resource capacity by itself. The Linux kernel project maintains the kernel and its documentation; higher-level tools can collect PSI data and use it for dashboards or alerting.

Why PSI Exists

Traditional utilization metrics describe activity, but not necessarily the impact of contention. A CPU at 90% utilization might be completing useful work without delaying requests. Conversely, a service can have low CPU utilization while many of its tasks wait for memory reclaim or blocked I/O. Utilization alone cannot answer how much work is affected or how long it waits.

Other summary metrics also leave gaps. Linux load average includes runnable tasks and tasks in uninterruptible sleep, but it does not tell an operator which resource is responsible or what share of time is lost. Per-device I/O statistics can show a busy disk without directly saying whether application tasks are stalled. PSI provides a common way to observe the effect of contention across CPU, memory, and I/O.

This distinction is useful for capacity planning and incident response. An operator can compare PSI with application latency, throughput, resource limits, and utilization to decide whether a bottleneck is affecting users. PSI is evidence of stalled work, not a diagnosis of the process or configuration that caused it.

How PSI Works

The kernel tracks task stalls associated with resource pressure, aggregates them, and exposes the measurements as text files. A typical pressure file contains some and full lines, each with moving averages and a cumulative total:

some avg10=0.00 avg60=0.00 avg300=0.00 total=0
full avg10=0.00 avg60=0.00 avg300=0.00 total=0

The avg10, avg60, and avg300 fields are rolling percentages of time over roughly 10-, 60-, and 300-second horizons. total is cumulative stall time in microseconds since the counters were initialized. An avg10 of 5.00 means that some or all relevant work was stalled during about five percent of that recent interval; it does not mean that the resource was 5% utilized.

The two stall categories answer different questions:

some measures periods when at least some non-idle work was stalled on the resource.
full measures periods when all non-idle work in the measured scope was stalled at the same time. System-wide CPU full is undefined and reported as zero; CPU pressure is generally interpreted through some.

The signal depends on resource type and scope:

Pressure file	What the signal describes	Example question it helps answer
`cpu`	Runnable work that cannot get CPU time	Are tasks waiting for scheduler capacity?
`memory`	Work stalled by memory reclaim or related pressure	Is memory pressure delaying useful work?
`io`	Work stalled while waiting for I/O	Are storage waits affecting task progress?

The kernel can also expose per-cgroup pressure through cgroup v2. The cgroup v2 documentation describes the unified hierarchy and its controller files. PSI measurements in a service’s cgroup help separate local contention from pressure elsewhere on the host, though access and file availability depend on the kernel and cgroup setup.

Key PSI Concepts

Pressure is not utilization. CPU utilization measures time spent executing on a processor. CPU PSI reflects runnable tasks that could not run when they wanted to. Memory and I/O PSI likewise describe stalled work rather than a simple percentage of RAM used or device bandwidth consumed.

Scope matters. System-wide files aggregate work across the host. A cgroup’s files describe work within that group, subject to kernel support and hierarchy configuration. Compare measurements from matching scopes; a host-level metric may hide a constrained container, while one cgroup’s pressure may not indicate a host-wide shortage.

Averages smooth events. The rolling averages make trends easier to monitor but can hide short spikes. The cumulative total value grows over time, so it is useful when comparing changes across samples rather than as a percentage on its own.

Triggers are event interfaces. A process can register a threshold on a PSI file and wait for a notification when the measured stall time crosses it. A trigger specifies some or full, a stall duration in microseconds, and a time window in microseconds. Keeping the file descriptor open keeps the trigger registered; closing it removes the trigger.

Real-World Uses

PSI can help operators determine whether a performance issue is likely related to CPU scheduling, memory, or I/O. If CPU pressure rises along with a growing runnable queue, compute demand may exceed available CPU time. If memory pressure rises while memory use approaches a cgroup limit, reclaim or limit settings may be delaying tasks. If I/O pressure increases alongside device latency, storage waits may be affecting the application.

It is also useful for container platforms and shared servers. A host can have reasonable overall utilization while one container experiences substantial pressure because of a CPU quota, memory ceiling, or noisy neighbor. Per-cgroup PSI can help identify that difference, while cgroup counters show the associated resource use and limits. For background on those controls, see Linux cgroups and resource management.

Monitoring systems may collect PSI averages for dashboards, alert on sustained changes, or use triggers to wake a controller before an application becomes unresponsive. Thresholds should be based on the workload’s normal behavior and service objectives. A brief spike during a batch job may be harmless; a smaller but sustained increase during an interactive workload may matter.

Getting Started: Inspect and Monitor PSI

PSI is provided by the Linux kernel and does not require a separate PSI package. The kernel must be built with PSI support, and per-cgroup data depends on cgroup support and the mounted hierarchy. Start by checking the system-wide files and cgroup filesystem:

uname -r
cat /proc/pressure/cpu
cat /proc/pressure/memory
cat /proc/pressure/io
stat -fc %T /sys/fs/cgroup

On a cgroup v2 system, stat reports cgroup2fs. The root group and child groups can expose pressure files such as memory.pressure; inspect the relevant group rather than assuming the root-level reading represents a particular service:

cat /sys/fs/cgroup/memory.pressure

To establish a baseline, sample PSI before and during the slow period and compare the changes with application latency. Use complementary tools to investigate likely causes:

vmstat 1 5
iostat -xz 1 5
ps -eo pid,stat,comm --sort=-%cpu | head

iostat and vmstat are commonly provided by the sysstat and procps packages, respectively. Check your distribution’s package manager if either command is missing. Neither tool replaces PSI: use the device and process data to investigate a pressure signal rather than interpreting one metric in isolation.

For a simple memory-pressure notification, Python can register a trigger and wait for the kernel to signal it:

import os
import select

fd = os.open("/proc/pressure/memory", os.O_RDWR | os.O_NONBLOCK)
try:
    os.write(fd, b"some 150000 1000000")
    poller = select.poll()
    poller.register(fd, select.POLLPRI)
    print("Waiting for at least 150 ms of memory stall in a 1-second window")
    poller.poll()
    print("Memory pressure threshold crossed")
finally:
    os.close(fd)

The trigger asks to be notified when some memory stall time reaches 150,000 microseconds within a 1,000,000-microsecond window. Run it with Python 3 on a system that exposes the interface. A production monitor should handle repeated notifications, process shutdown, permissions, and workload-specific thresholds.

If /proc/pressure is missing, check whether the running kernel has PSI enabled and consult the kernel configuration or distribution documentation. If system-wide files exist but a cgroup pressure file does not, check whether the system uses cgroup v2 and whether the kernel exposes PSI for cgroups. If PSI remains low while an application is slow, investigate causes PSI does not describe, such as network dependencies, locks, or application-level queuing.

Common Misconceptions

“PSI is another utilization percentage.” It is a percentage of time during which tasks are stalled, not the percentage of a CPU, memory pool, or disk that is in use. A high utilization reading can coexist with low PSI if work is making progress.

“High PSI identifies the offending process.” PSI measures the impact of stalls in a scope; it does not name the task, device, or limit responsible. Use process statistics, cgroup counters, device latency, and application telemetry to narrow down the cause.

“A system-wide reading explains every container.” Host-level aggregates and per-cgroup readings have different scopes. A cgroup can be constrained even when the host has spare capacity, and one pressured cgroup does not prove the whole host is saturated.

“Any pressure spike needs an alert or capacity increase.” Short stalls can be normal, and raising capacity or limits without investigation can waste resources or move the bottleneck. Interpret PSI against a baseline and the service’s latency and throughput goals.

Changelog and Last Updated

Initial publication. Last updated: October 11.