Metadata-Version: 2.1
Name: grafmon
Version: 1.0.0
Summary: Monitor metrics in a real-time time-series line-graph (a-la perfmon.exe)
Author-email: Pragmatic Software <pragma78@gmail.com>
License: Copyright (c) 2024-2025 Pragmatic Software <pragma78@gmail.com>
        
        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.
        
Project-URL: Homepage, https://github.com/pragma-/grafmon
Project-URL: Repository, https://github.com/pragma-/grafmon.git
Project-URL: Issues, https://github.com/pragma-/grafmon/issues
Keywords: graph,perfmon,perfmon.exe,pyqtgraph,metrics,monitor,perf,performance,cpu,pcpu,rss,process,memory,ram
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: X11 Applications
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyqtgraph
Requires-Dist: PyQt6
Requires-Dist: psutil

# grafmon

Monitor metrics in a real-time time-series line-graph

![screenshot](screenshots/grafmon1.png)

# Demonstration video

[![demo video](https://img.youtube.com/vi/o76IbERE7ec/0.jpg)](https://youtube.com/watch?v=o76IbERE7ec)

# Features

* Real-time time-series graph of metrics.
* Provide your own metric command.
* Several built-in metrics.
* Polished graph interface.
* Adjustable refresh rate.
* Pausable updates.
* Hide/show lines.
* Clickable/hoverable lines.
* Remembers window position/layout.

# Install

    pip install grafmon

# Usage

```
usage: grafmon [-h] [-m MONITOR | -c COMMAND] [-r REFRESHRATE] [-t MAXTICKS]
               [-l MAXLABELS] [--list-monitors]

Monitor metrics in a real-time time-series graph

options:
  -h, --help            show this help message and exit
  -m MONITOR, --monitor MONITOR
                        Select from builtin monitors to feed data into monitor
                        [default: pcpu]
  -c COMMAND, --command COMMAND
                        User command to feed data into monitor [example: ps
                        -eo rss,pid,comm --no-headers]
  -r REFRESHRATE, --refreshrate REFRESHRATE
                        Refresh rate in milliseconds [default: 1000]
  -t TICKS, --ticks TICKS
                        Count of ticks on X axis [default: 60]
  -l LABELS, --labels LABELS
                        Count of labels on X axis [default: 10]
  --list-monitors       List available builtin monitors
```

# Builtin monitors

```
avgpcpu    Average CPU% (using `ps`) over lifetime of all processes
cuc        CPU%, including dead children, in extended ##.### format of all processes
cuu        CPU% in extended ##.### format of all processes
drs        Data resident set size of all processes
pcpu       Immediate CPU% (using `top`) of all processes
pmem       Physical memory percentage of all processes
pss        Proportional share size of all processes
rbytes     Number of bytes really fetched from storage layer of all processes
rchars     Number of bytes read from storage of all processes
rops       Number of read I/O operations of all processes
rss        Resident set size (physical memory usage, in kilobytes) of all processes
sz         Physical pages used of all processes
thcount    Thread counts of all processes
trs        Text resident set (executable code memory usage) of all processes
vsz        Virtual memory usage of all processes
wbytes     Number of bytes really written to storage layer of all processes
wcbytes    Number of canceled write bytes of all processes
wchars     Number of bytes written to storage of all processes
wops       Number of write I/O operations of all processes
```

# Custom monitor

Grafmon accepts user-provided commands for monitoring. The command must use output lines
in the format of `<float> <string>` to STDIN. The `<float>` will be the value associated
with `<string>`. The `<string>` may contain spaces. Grafmon will invoke the command every
refresh-rate tick.

Example:

    grafmon -c ps -eo pcpu,pid,comm --no-headers

# Notes

I needed an easy-to-install app that can graph in real-time various system metrics, notably
percentages of CPU usages for all active processes. The KDE and Gnome system monitors/task
managers graphed overall CPU usage rather than per-process usage.

Grafmon is inspired in part by Windows' perfmon.exe. The graph does not scroll, but instead
updates in a "wipe". A vertical line will move from left-to-right as the metrics are read
each tick. When the line reaches the end, it resets back to the beginning. This allows easy
hovering over of graph elements to inspect the data. A moving scrolling graph would be more
difficult to hover over the lines and their peaks.

Lines may be clicked on to highlight them to more easily see them in the graph. Lines may
be hovered-over to see a tooltip of their values. Their values will also appear in the status
bar at the bottom of the window.

To zoom the graph in to inspect lower valued lines, you can untick the checkboxes in the list
on the left. Unticking checkboxes for lines with the highest peaks will hide the lines and
the graph will zoom in to fit the next highest peaks.
