Linux Pressure Stall Information (PSI) Status App
psistat is a python3 program to display the PSIs and to capture/display exception events. See PSI - Pressure Stall Information — The Linux Kernel documentation for more information.
The Unique Value of psistat
psistat fills a critical gap in Linux monitoring by providing one simple package that offers:
- High-Granularity, Calculated Averages: It provides 1s and 3s averages—data points that are more relevant for real-time latency debugging than the kernel's $60s$/$300s$ averages.
- Smart Event Logging: It automatically logs incidents that cross user-defined thresholds ($1%-99%$), implements a cooldown period to prevent spam, and provides forensic data (sequence number, absolute time, interval used).
- TUI and Dump Capability: The ability to instantly dump the historical log for copy/paste is a massive feature for quick troubleshooting and reporting that no other simple tool provides.
- Simplicity: It's a Python application installed via
pipx—easy to install, easy to run, and requires zero configuration.
While the raw PSI data exists in the kernel, no tool currently offers the combination of live TUI monitoring, high-resolution calculation, and intelligent event logging that psistat does.
Interpreting PSI Values
PSI percentages represent the fraction of time that some or all tasks were stalled waiting for a resource. Since PSIs are workload-dependent, there is no single "bad" value, but these are general guidelines:
fullStalls (Critical): Any sustained value $\mathbf{\ge 1%}$ forcpu.full,io.full, ormemory.fullon the 60s or 300s average is a strong indication of a chronic bottleneck (starvation/deadlock) and demands investigation.someStalls (Warning/Actionable): Sustained values on the 60s or 300s average are a more reliable indicator of system health than momentary spikes:- $\mathbf{10%-25%}$: Performance degradation is likely. This is often the ideal range to trigger load-shedding or autoscale.
- $\mathbf{\ge 25%}$: Performance is severely impacted and the system is likely overloaded.
psistat provides calculated 1s, 3s, and 10s averages, which are derived from the kernel's cumulative stall count. These short-term metrics offer high-resolution visibility into immediate performance bottlenecks that are intentionally smoothed out by the kernel's built-in $60s$ and $300s$ averages. Use the 1s average to spot transient spikes (e.g., a short I/O hiccup or lock contention) that cause latency for users; use the 3s and 10s averages to confirm if a stall is momentary or is becoming a more sustained problem before it affects the long-term averages.
Installation
pipx install psistat
Instruction for Use
Typically, simply run psistat. Its window looks like:
PSIs 18:54:04 | [t]hresh=5% [i]tvl=1 [b]rief=off [d]ump ?:help [q]uit
----1s ----3s ---10s ---60s --300s Full% ----1s ----3s ---10s ---60s --300s Some%
0.00 0.00 0.00 0.00 0.00 cpu 1.70 2.10 6.70 1.10 0.50 cpu
0.00 0.10 0.20 0.10 0.10 io 0.00 0.20 0.30 0.10 0.10 io
0.00 0.00 1.40 0.20 0.00 memory 0.00 0.00 1.50 0.20 0.00 memory
──────────────────────────────────────────────────────────────────────────────────────────────
000 8s: 10-18 18:53:56.099 .................... 10.50% cpu.some >=5% i=1s
001 9s: 10-18 18:53:55.097 14.20% memory.full 14.50% memory.some >=5% i=1s
002 9s: 10-18 18:53:55.097 .................... 40.70% cpu.some >=5% i=1s
003 26s: 10-18 18:53:37.995 10.00% io.full 10.50% io.some >=5% i=1s
004 1m26s: 10-18 18:52:37.665 5.80% io.full 6.00% io.some >=5% i=1s
005 3m35s: 10-18 18:50:28.977 .................... 5.20% io.some >=5% i=1s
006 4m35s: 10-18 18:49:28.644 .................... 5.00% io.some >=5% i=1s
psistat displays:
- The first line of the screen shows some of the control keys and values.
tprompts for a new event threshold percent. Values between 1% and 99% are supported; an out-of-range reply re-opens the prompt with the accepted range on its footer.ichanges the event interval; e.g., if it is 10s, then only the 10s average stat is watched for events.btoggles brief mode. When enabled, only events that fit on the screen are shown (disables scrolling). When disabled (Full mode), the full history (up to 200 events) is scrollable.dimmediately dumps the full event history (up to 1000 events) to the terminal, exits the display mode for easy copy/paste, and prompts you to return when ready. A dump will drop out of the display mode so you can copy events to another app, and allow you to display mode return when ready.?will show all the control and navagation keys of the current screen and the current values of the controls; the values can still be changed there. ESC returns to the report. The first visit also carries a font check for the symbols the library draws.q(or Ctrl-C) terminates the app.
- On the top portion of the screen, the 1s, 3s, 10s, 60s, and 300s PSI stats (each is a percent stalled during the interval).
- The 60s and 300s are averages computed by the system.
- Below the stats is a list of exception events beginning with the most recent;
each event includes:
- A sequence number from 000 for the most recent.
- The relative time and absolute time of the event.
- For the 'full' and 'some' stats:
- The pressure value as a percentage that met or exceeded the current threshold.
- The type of event.
- NOTE: Since the 'full' and 'some' stats are highly correlated, you will often see both in one "event" as
psistatcollects them.
psistat has only a few options:
usage: psistat [-h] [-b] [-i {1,3,10,60,300}] [-t THRESHOLD_PCT]
options:
-h, --help show this help message and exit
-b, --brief whether present only as meay events as fit on the screen
-i {1,3,10,60,300}, --event-interval {1,3,10,60,300}
average interval used for events
-t THRESHOLD_PCT, --threshold-pct THRESHOLD_PCT
event threshold percent [1-99,dflt=5]
psistat --version prints the release number and exits without starting the
display; that is the check the release gate runs on a freshly built wheel.
Load Test
To create some test loads, you can use the create_load.c program found at
psi-by-example.
Development
The developer notes -- layout, test gate, release gate, branch model and the
distribution inspector -- live in tests/README-DEV.md.
The short version:
Build the project's editable environment (the package, console-window and the
dev extra, including the release toolchain) in .venv:
bt penv
Run psistat from source without installing anything or touching
~/.local/bin, using the runner wrapper, which re-execs into
.venv/bin/python:
./runner # run with defaults
./runner --help # show all CLI options
./runner -t 10 -i 3 # e.g. threshold=10%, event interval=3s
Run the same commands the test gate runs, on that same interpreter:
.venv/bin/python -m ruff check .
.venv/bin/python -m compileall -q psistat tests
.venv/bin/python -m pytest -q --cov=psistat --cov-report=term-missing
Releasing goes through ./bless, the vendored release gate emitted from
blessd; it is never edited here.
Metadata
Release files for psistat 1.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| psistat-1.2.2.tar.gz | 14.0 kB | Without provenance | Details for psistat-1.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| psistat-1.2.2-py3-none-any.whl | Python 3 | none | any | Details for psistat-1.2.2-py3-none-any.whl |
Total release size: 26.1 kB
Release files / psistat-1.2.2.tar.gz
| Download URL | psistat-1.2.2.tar.gz |
|---|---|
| Size | 14.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
056d4afdc11e252b4561820bbb751edf6f658f391d323f5cd4b35d9a8d0bb080
|
|
BLAKE2b-256 checksum How to use checksums |
fb2ea0c0eb3f6e45b2dd6ed448e412c60d3c9879f8151efcb97eb903f830db69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Release files / psistat-1.2.2-py3-none-any.whl
| Download URL | psistat-1.2.2-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36270b1c13bf8420d3a8086e0150d569538a92ce8658765a06a78d69fb29ddb8
|
|
BLAKE2b-256 checksum How to use checksums |
0a5483bc50d0fc023b372ba026d64482049fa972d3913599591020943480adfa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Security for psistat 1.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.