psistat 1.0.0__tar.gz

psistat-1.0.0/.gitignore

@@ -0,0 +1,77 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# IDE / Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*.bak
+*~
+
+# macOS / Linux / Windows system files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Local config / secrets (optional)
+*.env
+.env.*
+
+# Project-specific
+__pypackages__/
+

psistat-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Joe Defen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

psistat-1.0.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: psistat
+Version: 1.0.0
+Summary: psistat - A simple command-line system status tool.
+Keywords: system,status,cli
+Author-email: Joe Defen <joedef@duck.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Monitoring
+License-File: LICENSE
+Requires-Dist: console-window >= 1.0.0
+
+# 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](https://docs.kernel.org/accounting/psi.html) 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.Stall%      ---1s ---3s --10s --60s -300s  Some.Stall%
+   0.0   0.0   0.0   0.0   0.0  cpu.full           1.7   2.1   6.7   1.1   0.5  cpu.some
+   0.0   0.1   0.2   0.1   0.1  io.full            0.0   0.2   0.3   0.1   0.1  io.some
+   0.0   0.0   1.4   0.2   0.0  memory.full        0.0   0.0   1.5   0.2   0.0  memory.some
+──────────────────────────────────────────────────────────────────────────────────────────────
+000     8s: 10-18 18:53:56.099  ...................    10.5% cpu.some      >=5% i=1s
+001     9s: 10-18 18:53:55.097    14.2% memory.full    14.5% memory.some   >=5% i=1s
+002     9s: 10-18 18:53:55.097  ...................    40.7% cpu.some      >=5% i=1s
+003    26s: 10-18 18:53:37.995    10.0% io.full        10.5% io.some       >=5% i=1s
+004  1m26s: 10-18 18:52:37.665     5.8% io.full         6.0% io.some       >=5% i=1s
+005  3m35s: 10-18 18:50:28.977  ...................     5.2% io.some       >=5% i=1s
+006  4m35s: 10-18 18:49:28.644  ...................     5.0% 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.
+  * `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 and the current values of the controls.
+  * `q` will terminated 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]
+```
+
+## Load Test
+To create some test loads, you can use the `create_load.c` program found at
+[psi-by-example](https://github.com/shuveb/psi-by-example).
+
+

psistat-1.0.0/README.md

@@ -0,0 +1,91 @@
+# 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](https://docs.kernel.org/accounting/psi.html) 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.Stall%      ---1s ---3s --10s --60s -300s  Some.Stall%
+   0.0   0.0   0.0   0.0   0.0  cpu.full           1.7   2.1   6.7   1.1   0.5  cpu.some
+   0.0   0.1   0.2   0.1   0.1  io.full            0.0   0.2   0.3   0.1   0.1  io.some
+   0.0   0.0   1.4   0.2   0.0  memory.full        0.0   0.0   1.5   0.2   0.0  memory.some
+──────────────────────────────────────────────────────────────────────────────────────────────
+000     8s: 10-18 18:53:56.099  ...................    10.5% cpu.some      >=5% i=1s
+001     9s: 10-18 18:53:55.097    14.2% memory.full    14.5% memory.some   >=5% i=1s
+002     9s: 10-18 18:53:55.097  ...................    40.7% cpu.some      >=5% i=1s
+003    26s: 10-18 18:53:37.995    10.0% io.full        10.5% io.some       >=5% i=1s
+004  1m26s: 10-18 18:52:37.665     5.8% io.full         6.0% io.some       >=5% i=1s
+005  3m35s: 10-18 18:50:28.977  ...................     5.2% io.some       >=5% i=1s
+006  4m35s: 10-18 18:49:28.644  ...................     5.0% 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.
+  * `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 and the current values of the controls.
+  * `q` will terminated 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]
+```
+
+## Load Test
+To create some test loads, you can use the `create_load.c` program found at
+[psi-by-example](https://github.com/shuveb/psi-by-example).
+

psistat-1.0.0/psistat.py

@@ -0,0 +1,375 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Copyright (c) 2022-2025 Joe Defen
+
+Pressure Stall Indicators (PSI) status program. Shows:
+    - 1, 3, and 5 second running averages( in percent) of the 5 PSIs
+    - the recent history of PSI events that are defined by
+      exceeding a threshold percentage in a second.
+      
+Now uses the 'console-window' library for the TUI interface.
+"""
+
+# pylint: disable=invalid-name,too-many-instance-attributes,import-outside-toplevel,broad-except,too-many-locals
+
+import sys
+import os
+import time
+import re
+import traceback
+from datetime import datetime
+from types import SimpleNamespace
+import curses as cs
+import locale
+from types import SimpleNamespace
+from console_window import ConsoleWindow, OptionSpinner
+
+locale.setlocale(locale.LC_ALL, '') # needed to draw unicode chars
+
+
+SAMPLES = 11
+BILLION = 1000000000
+
+##############################################################################
+##  Turn time differences in seconds to a compact representation;
+##  e.g., '18h·39m'
+##############################################################################
+def ago_str(delta_secs):
+    """Prints a 6-character string (max) the represents how long
+    ago (i.e., delta_secs) is briefly."""
+    ago = int(max(0, round(delta_secs if delta_secs >= 0 else -delta_secs)))
+    divs = (60, 60, 24, 7, 52, 9999999)
+    units = ('s', 'm', 'h', 'd', 'w', 'y')
+    vals = (ago%60, int(ago/60)) # seed with secs, mins (step til 2nd fits)
+    uidx = 1 # best units
+    for div in divs[1:]:
+        if vals[1] < div:
+            break
+        vals = (vals[1]%div, int(vals[1]/div))
+        uidx += 1
+    rv = '{:d}{}'.format(vals[1], units[uidx]) if vals[1] else ''
+    fmt = '{:02d}{}' if vals[1] else '{:2d}{}'
+    rv += fmt.format(vals[0], units[uidx-1])
+    return rv
+
+
+class PressureGroup:
+    """Handler for one PSI group (i.e., cpu, io, or memory)
+    """
+    pattern = re.compile(r'^(\S+)\b.*\bavg60=(\d+\.\d+)\b.*\bavg300=(\d+\.\d+)\b.*\btotal=(\d+)$')
+    def __init__(self, tag, stats):
+        self.stats = stats
+        self.avgs = {60: 0, 300: 0} # averages from /proc/pressure/{tag}
+        self.tag = tag
+        self.fullpath = '/proc/pressure/' + tag
+        self.handle = open(self.fullpath)
+        
+    def sample_ns(self):
+        """ return the initialized namespace for a sample.
+        It includes the list of recent microseconds of pressure samples and
+        the averages for 60s and 300s"""
+        return SimpleNamespace(micros=[], avgs={60: 0, 300:0})
+
+    def add_sample(self):
+        """Read/Parse the /proc/pressure/{group} file"""
+        self.handle.seek(0)
+        document = self.handle.read()
+        allowed_subkeys = {'full', 'some'}
+        for line in document.splitlines():
+            match = self.pattern.match(line)
+            
+            # NOTE: Your original regex assumed match was successful. Adding check.
+            if not match:
+                continue
+            subkey, micro = match.group(1), match.group(4)
+            avg60, avg300 = match.group(2), match.group(3)
+            if subkey not in allowed_subkeys:
+                continue
+            allowed_subkeys.discard(subkey)
+            key = f'{self.tag}.{subkey}'
+            ns = self.stats.get(key, None)
+            if not ns:
+                ns = self.stats[key] = self.sample_ns()
+            ns.micros.insert(0, int(micro))
+            del ns.micros[SAMPLES:]
+            ns.avgs[60], ns.avgs[300] = float(avg60), float(avg300)
+        assert not allowed_subkeys, f"{self.fullpath} expecting full+some values"
+
+class PsiStat:
+    """Class to display PSI information including
+    running averages and exception events"""
+    singleton = None
+    def __init__(self, threshold=5, brief=False, itvl=10):
+        assert self.singleton is None
+        PsiStat.singleton = self
+        self.next_mono = time.monotonic_ns() # when to sleep to next
+        self.stats = { 'cpu.full': None, 'cpu.some': None,
+                       'io.full': None, 'io.some': None,
+                       'memory.full': None, 'memory.some': None
+                     }
+        self.monos = []
+        self.times = []
+        self.psgs = []
+        self.events = []
+        self.event_floor = {}
+        self.lineno = 0 # Not strictly needed with ConsoleWindow, but harmless.
+        self.last_sample_mono = 0
+
+        # --- CONSOLE-WINDOW SETUP ---
+        # Setup OptionSpinner for 'j' and 'k' keys
+        self.spin = OptionSpinner()
+        self.opts = self.spin.default_obj
+        self.spin.add_key('help_mode', '? - toggle help screen', vals=[False, True])
+        self.spin.add_key(attr='event_interval', descr='i - event interval (secs)',
+                  vals=[10, 3, 1, 300, 60])
+        self.spin.add_key(attr='threshold', descr='t - set event threshold percent [1,99]',
+                          prompt="Enter event threshold percent in range [1,99]")
+        self.spin.add_key(attr='brief', descr='b - only load events that fit on screen',
+                  vals=['off', 'on'])
+        self.spin.add_key(attr='dump_now', descr='d - dump event log now',
+                  vals=[False, True])
+        self.spin.add_key(attr='quit', descr='q or CTRL-c - quit program',
+                  vals=[False, True])
+
+        # FIXME: keys
+        others = ''
+        other_keys = set(ord(x) for x in others)
+        # other_keys.add(cs.KEY_ENTER)
+        # other_keys.add(27) # ESCAPE
+        # other_keys.add(10) # another form of ENTER
+        self.opts.brief = 'on' if brief else 'off'
+        self.opts.threshold = threshold
+        self.opts.event_interval = itvl
+
+        # Initialize ConsoleWindow
+        self.window = ConsoleWindow(head_line=True, keys=self.spin.keys^other_keys)
+
+        for tag in 'cpu', 'io', 'memory':
+            self.psgs.append(PressureGroup(tag, self.stats))
+
+
+    def dump_event_log(self, do_return=False):
+        """  drop out of Window and dump the events """
+        if self.window:
+            self.window.stop_curses()
+        os.system('clear; stty sane')
+        for event in reversed(self.events):
+            print(event[1])
+        if do_return:
+            os.system(r' /bin/echo -e "\n\n===== Press ENTER to return to psistat ====> \c"; read FOO')
+            if self.window:
+                self.window._start_curses()
+
+
+    def prc_samples(self, valid_sample_count):
+        """Show the current PSI stats/events using the
+        most recent samples while also detecting new events
+        for exceptional samples. Then show the recent events.
+        """
+        # Access threshold from OptionSpinner object
+        threshold = self.opts.threshold
+        itvl = self.opts.event_interval
+        brief = self.opts.brief
+        dt_object = datetime.fromtimestamp(time.time())
+        hhmmss = dt_object.strftime("%H:%M:%S")
+
+        title = f'PSIs {hhmmss} | [t]hresh={threshold}% [i]tvl={itvl}s [b]rief={brief} [d]ump ?:help [q]uit'
+        self.window.add_header(title)
+
+        # Draw Header
+        header = (f' {"1s":->5} {"3s":->5} {"10s":->5} {"60s":->5} {"300s":->5}  {"Full.Stall%":>11}'
+                  + f'      {"1s":->5} {"3s":->5} {"10s":->5} {"60s":->5} {"300s":->5}  {"Some.Stall%":>11}')
+        self.window.add_header(header) 
+        
+        # --- Draw PSI Stats ---
+        line, event, specifically = '', '', ''
+        now = time.time()
+        for idx, key in enumerate(self.stats):
+            micros = self.stats[key].micros
+            del micros[valid_sample_count:]
+            avgs = self.stats[key].avgs
+            
+            for ii in (1, 3, 10, 60, 300):
+                if ii in (1, 3, 10):
+                    if len(micros) <= ii:
+                        line += ' ' + 'n/a'.rjust(5)
+                        continue
+
+                    delta_micros = (micros[0] - micros[ii])
+                    delta_monos = (self.monos[0] - self.monos[ii])
+                    
+                    # Avoid division by zero if delta_monos is unexpectedly zero
+                    if delta_monos == 0:
+                        pct = 0.0
+                    else:
+                        pct = 100 * 1000 * delta_micros / delta_monos
+                    
+                else:
+                    pct = avgs.get(ii, 0.0)
+                
+                line += f' {pct:5.1f}'
+
+                # detect/collect the 1s samples that exceed the threshold
+                floor_key = f'{key}.{ii}'
+                floor = self.event_floor.get(floor_key, 0)
+                if ii == itvl and round(pct, 2) >= threshold and now >= floor:
+                    if not event:
+                        dt_object = datetime.fromtimestamp(now)
+                            # Truncate microseconds to milliseconds (.mmm) with [:-3]
+                        event += dt_object.strftime("%m-%d %H:%M:%S.%f")[:-3]
+
+                    specifically = f'{pct:7.1f}% {key:<11s}'
+                    if '.full' not in event and '.some' in key:
+                        event += '  ' + '.' * len(specifically)
+                    event += '  ' + specifically
+                    self.event_floor[floor_key] = now + itvl
+            line += f'  {key:<11}'
+
+            if idx % 2 == 0:
+                line += '     '
+            else:
+                if not self.opts.help_mode:
+                    self.window.add_header(line)
+                line = ''
+                if event:
+                    if '.some' not in event and '.full' in key:
+                        event += '  ' + '.' * len(specifically)
+                    event += f'   >={threshold}% i={itvl}s'
+                    self.events.insert(0, (time.monotonic_ns(), event))
+                    event = ''
+            
+        del self.events[1000:]
+        
+        # --- Draw Events ---
+        if not self.opts.help_mode:
+            self.window.calc()
+            limit = (self.window.rows - self.window.body_base) if self.opts.brief == 'on' else 200
+            for idx, event in enumerate(self.events):
+                if idx >= limit:
+                    break
+                mono_ns, descr = event
+                ago = ago_str((time.monotonic_ns() - mono_ns)/BILLION).strip()
+                self.window.put_body(f'{idx:03d} {ago:>6s}: {descr}')
+            
+    def show_help_screen(self):
+        """ TBD """
+        self.window.clear()
+        self.window.set_pick_mode(False)
+        self.spin.show_help_nav_keys(self.window)
+        self.spin.show_help_body(self.window)
+        lines = [
+            '   CTRL-c - quit program'
+        ]
+        for line in lines:
+            self.window.put_body(line)
+            
+    def count_valid_samples(self):
+        """ Valid samples are no worse that 1.25s later than the one before
+         and no more than SAMPLES """
+        # return SAMPLES-1
+        count = 1
+        del self.monos[SAMPLES:]
+        for loop in range(0, len(self.monos) - 1):
+            delta_ns = self.monos[loop] - self.monos[loop+1]
+            if  delta_ns > 1000000000 * 1.25:
+                break
+            count += 1
+        return count
+ 
+    def process_psgs(self):
+        """ TBD """
+        for psg in self.psgs:
+            psg.add_sample()
+            
+        self.times.insert(0, time.time())
+        mono = time.monotonic_ns()
+        self.monos.insert(0, mono)
+        valid_sample_count = self.count_valid_samples()
+        del self.monos[valid_sample_count:]
+        del self.times[valid_sample_count:]
+
+        if not self.opts.help_mode:
+            self.window.clear()
+            
+        self.prc_samples(valid_sample_count)
+
+
+    def loop(self):
+        """Do one loop of collecting samples, and then displaying running
+        averages and exception events."""
+        timeout_secs, min_timout_secs = 1.0, 0.9
+        
+        if time.monotonic() - self.last_sample_mono >= min_timout_secs:
+            self.process_psgs()
+            self.last_sample_mono = time.monotonic()
+
+        if self.opts.help_mode:
+            self.show_help_screen()
+        
+        # --- CONSOLE-WINDOW LOOP INTEGRATION ---
+        
+        # Render the screen
+        self.window.render()
+        sleep_secs = timeout_secs - (time.monotonic() - self.last_sample_mono)
+        
+        # Wait for input/timeout using ConsoleWindow.prompt()
+        keystroke = self.window.prompt(seconds=sleep_secs)
+        
+        if keystroke is not None:
+            # Pass key to OptionSpinner for handling 'j' and 'k'
+            if self.spin.do_key(keystroke, self.window):
+                if isinstance(self.opts.threshold, str):
+                    try:
+                        self.opts.threshold = int(self.opts.threshold)
+                        if self.opts.threshold < 1:
+                            self.opts.threshold = 1
+                        elif self.opts.threshold > 99:
+                            self.opts.threshold = 99
+                    except Exception:
+                        self.opts.threshold = 999999
+                if self.opts.dump_now:
+                    self.dump_event_log(do_return=True)
+                    self.opts.dump_now = False
+                if self.opts.quit:
+                    sys.exit(0)
+
+                return True 
+            if keystroke in (ord('q'), ord('Q')):
+                return False # Quit
+                
+        # The loop continues after timeout or non-threshold keystroke
+        return True
+
+def main():
+    try:
+        """Main execution function, handles CLI arguments."""
+        import argparse
+        parser = argparse.ArgumentParser()
+        parser.add_argument('-b', '--brief', action='store_true',
+                            help='whether present only as meny events as fit on the screen')
+        parser.add_argument('-i', '--event-interval', default=10, type=int, choices=[1,3,10,60,300],
+                            help='average interval used for events')
+        parser.add_argument('-t', '--threshold-pct', default=5, type=int,
+                            help='event threshold percent [1-99,dflt=5]')
+        opts = parser.parse_args()
+        
+        pct = min(max(opts.threshold_pct, 1), 99)
+
+        pstall = PsiStat(threshold=pct, brief=opts.brief, itvl=opts.event_interval)
+
+        while pstall.loop():
+            pass
+
+    except Exception as exc:
+        # Note: We no longer call Window.exit_handler(), as ConsoleWindow handles it
+        # and there is no guarantee the Window class was ever initialized.
+        if PsiStat.singleton and PsiStat.singleton.window:
+            PsiStat.singleton.window.stop_curses()
+
+        print("exception:", str(exc))
+        print(traceback.format_exc())
+
+if __name__ == '__main__':
+
+    main()

psistat-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["flit_core >=3.9,<5"] # Updated to a current range
+build-backend = "flit_core.buildapi"
+
+# ----------------------------------------------------------------------
+# FLIT MODULE CONFIGURATION
+# Flit looks for a single file module named psistat.py
+[tool.flit.module]
+name = "psistat"
+
+# ----------------------------------------------------------------------
+# UNIFIED PROJECT METADATA
+[project]
+name = "psistat"
+version = "1.0.0"
+description = "psistat - A simple command-line system status tool."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+
+# Add dependencies here if you use non-stdlib PyPI packages (e.g., requests, rich)
+dependencies = [
+    'console-window >= 1.0.0',
+]
+
+authors = [
+    {name = "Joe Defen", email = "joedef@duck.com"}, # ✏️ Your info
+]
+
+# ✏️ Update classifiers to match your project
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Topic :: System :: Monitoring",
+]
+
+keywords = ["system", "status", "cli"] # ✏️ Add relevant keywords
+
+# ----------------------------------------------------------------------
+# COMMAND LINE SCRIPTS
+# This tells flit to create an executable 'psistat' command
+# that calls the 'main()' function in the 'psistat' module (psistat.py)
+[project.scripts]
+psistat = "psistat:main"