Skip to main content

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:

  • full Stalls (Critical): Any sustained value $\mathbf{\ge 1%}$ for cpu.full, io.full, or memory.full on the 60s or 300s average is a strong indication of a chronic bottleneck (starvation/deadlock) and demands investigation.
  • some Stalls (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.
    • t prompts 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.
    • i changes the event interval; e.g., if it is 10s, then only the 10s average stat is watched for events.
    • b toggles 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.
    • d immediately 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 psistat collects 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)

Source distribution for psistat 1.2.2
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)

Table of built distributions (wheels) for psistat 1.2.2
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.2.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page