syswatch

A lightweight Linux system monitoring CLI tool written in idiomatic Python.

============================================================
  syswatch  |  devbox
============================================================
  Platform : Linux-6.8.0-51-generic-x86_64-with-glibc2.39
  Kernel   : 6.8.0-51-generic
  Uptime   : 14.2h  (booted 2025-05-19 08:30 UTC)

============================================================
  CPU
============================================================
  Overall  : [##########--------------------]  33.2%
  Cores    : 4 physical / 8 logical
  Freq     : 3600.0 MHz
  Per-core : C0:28.0%  C1:35.0%  C2:40.0%  C3:30.0%

============================================================
  Memory
============================================================
  RAM      : [###############---------------]  50.0%
  Usage    : 8.0 GB / 16.0 GB  (8.0 GB available)

============================================================
  Disks
============================================================
  /dev/sda1 (/)
    Usage  : [############------------------]  40.0%
    Space  : 200.0 GB used / 500.0 GB total (300.0 GB free)
    I/O    : read 1024.0 MB  |  write 512.0 MB

============================================================
  Network
============================================================
  eth0
    Sent   : 100.0 MB  (1000 pkts)
    Recv   : 200.0 MB  (2000 pkts)

============================================================
  Top 10 Processes (by CPU)
============================================================
    PID  NAME                  CPU%    MEM%  STATUS      USER
  ----------------------------------------------------------------------
   1234  python3               28.5    2.14  running     krish

============================================================
  !!! ALERTS (1 triggered) !!!
============================================================
  [WARNING]  CPU is elevated: 80.0% (threshold 75.0%)

Features

• CPU — overall usage, per-core breakdown, clock frequency
• Memory — RAM and swap with colour-coded progress bars
• Disk — usage percentage and cumulative I/O per partition
• Network — per-interface traffic stats and error counts
• Processes — top N processes sorted by CPU usage
• Alert system — configurable warning/critical thresholds for CPU, memory, disk, and swap
• Desktop notifications — optional notify-send integration for triggered alerts
• Watch mode (--watch) — live dashboard with configurable refresh interval
• JSON output (--json) — machine-readable metrics for scripting and pipelines
• Colour-coded bars — green / yellow / red by usage level
• No external dependencies beyond psutil

Installation

pip install syswatch

Or from source:

git clone https://github.com/Krish02789/syswatch.git
cd syswatch
pip install -r requirements.txt

Install as an Ubuntu Snap

# Build the snap locally (requires snapcraft and LXD or Multipass)
snapcraft

# Install the locally built snap
sudo snap install syswatch_1.0.0_amd64.snap --dangerous

# Run it
syswatch

The snap uses strict confinement with explicitly declared interfaces:

Interface	Why it's needed
system-observe	Read /proc/stat, /proc/meminfo, /proc/net/dev
hardware-observe	Read CPU topology and frequency from /sys/devices
mount-observe	Read /proc/mounts for disk partition information
network-observe	Read per-interface network statistics
process-control	List running processes and their resource usage

Each interface is declared explicitly — syswatch requests the minimum permissions it actually needs, which is the correct approach for snap confinement.

Usage

syswatch [options]

Display options

Flag	Default	Description
--watch	off	Continuously refresh the display (Ctrl+C to exit)
--interval SECONDS	3	Refresh interval for --watch
--top N	10	Number of top processes to show
--json	off	Output as JSON
--no-color	off	Disable ANSI colour output

Alert options

Flag	Default	Description
--alert	off	Enable threshold alerts
--alert-only	off	Only print output when an alert fires (for scripting)
--notify	off	Send desktop notification via notify-send
--cpu-warn PCT	75	CPU warning threshold
--cpu-crit PCT	90	CPU critical threshold
--mem-warn PCT	75	Memory warning threshold
--mem-crit PCT	90	Memory critical threshold
--disk-warn PCT	80	Disk warning threshold
--disk-crit PCT	95	Disk critical threshold
--swap-warn PCT	50	Swap warning threshold
--swap-crit PCT	80	Swap critical threshold

Examples

# One-shot snapshot
syswatch

# Live dashboard, refresh every 5 seconds
syswatch --watch --interval 5

# Show top 20 processes
syswatch --top 20

# Enable alerts with default thresholds
syswatch --alert

# Custom thresholds
syswatch --alert --cpu-warn 60 --cpu-crit 85 --mem-warn 70

# Live dashboard with alerts and desktop notifications
syswatch --watch --alert --notify

# Only print when something is wrong (useful in cron jobs)
syswatch --alert-only

# Machine-readable JSON (alerts included when --alert is set)
syswatch --json --alert | jq '.alerts'

# No colour (for logging or CI)
syswatch --no-color

Scripting example

# Alert-only mode in a cron job — emails you only when something fires
*/5 * * * * syswatch --alert-only --no-color >> /var/log/syswatch.log 2>&1

Development

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=syswatch --cov-report=term-missing

# Type checking
mypy syswatch/

Project structure

syswatch/
├── syswatch/
│   ├── __init__.py      # Package metadata
│   ├── models.py        # Typed dataclasses for all metric types
│   ├── collector.py     # psutil-based metric collection (independently mockable)
│   ├── formatter.py     # Stateless terminal output formatter with colour bars
│   ├── alerts.py        # Threshold evaluation, alert formatting, notify-send
│   └── cli.py           # argparse CLI entry point — thin orchestration only
├── tests/
│   ├── test_collector.py
│   ├── test_formatter.py
│   ├── test_alerts.py
│   └── test_cli.py
├── .github/workflows/ci.yml
├── pyproject.toml
└── README.md

Architecture

syswatch follows a strict separation of concerns across four layers:

• models — pure dataclasses with no logic; the shared data contract between all layers
• collector — all psutil calls isolated here; each function is independently mockable and testable without touching real OS state
• formatter — stateless rendering function; takes a SystemSnapshot, returns a string; no I/O
• alerts — pure evaluation logic (check_alerts) plus formatting and optional side effect (send_desktop_notification); evaluation is a pure function of snapshot + config
• cli — thin orchestration; parses args, calls the above layers, handles watch loop and KeyboardInterrupt

This design means every layer is independently testable. The test suite mocks psutil entirely — tests run identically on any OS and in CI without requiring real system metrics.

License

MIT