Skip to content
opierrePublic

About

πŸ’»πŸ©Ί A lightweight computer constants monitor using Rust and Python

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

75 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ–₯️🩺 SysHealth

PyPI version CI Pipeline

A highly optimized, cross-platform system resource monitor with a Rust core and a beautiful Python CLI.

SysHealth pushes the performance-critical work (polling loops, hardware inspection, network sampling) into compiled Rust code via PyO3, while keeping the Python surface clean, ergonomic, and easy to extend.


✨ Features

  • ⚑ Near-zero CPU footprint β€” all heavy lifting runs in compiled Rust via sysinfo
  • πŸ–₯️ Rich terminal UI β€” colour-coded panels with adaptive side-by-side layout
  • 🌐 Cross-platform β€” Windows and Linux supported
  • πŸ”Œ Extensible β€” adding a new Rust metric takes fewer than 10 lines
  • πŸ§ͺ Tested β€” pytest integration tests with full mock coverage
  • πŸ“‘ Background Exporters β€” Start a zero-overhead Rust background thread to continuously export metrics to MQTT or VictoriaMetrics
  • πŸŽ›οΈ Configurable Priorities β€” Control the exporter thread priority dynamically (from 0 to 5) so it never impacts system performance

πŸš€ Installation

Install SysHealth directly from PyPI using uv (recommended) or standard pip:

# Install system-wide or in your active environment
uv tool install syshealth

# OR using standard pip
pip install syshealth

(Optional: If you plan to use the MQTT exporter, install with the mqtt extra: uv tool install syshealth[mqtt])


πŸ“– Usage

CLI Dashboard (global-metrics)

Displays a full system snapshot dashboard. Panels are automatically placed side-by-side when the terminal is wide enough.

syshealth global-metrics

global-metrics demo

Output panels:

Panel Metric Backend
πŸ–₯️ System Information OS name & version πŸ¦€ Rust (sysinfo)
πŸ–₯️ System Information Kernel version πŸ¦€ Rust (sysinfo)
πŸ–₯️ System Information Hostname πŸ¦€ Rust (sysinfo)
πŸ–₯️ System Information CPU brand, cores & threads πŸ¦€ Rust (sysinfo)
πŸ–₯️ System Information GPU name 🐍 Python (wmic / lspci subprocess)
πŸ–₯️ System Information Total RAM πŸ¦€ Rust (sysinfo)
πŸ–₯️ System Information Available disk space & % πŸ¦€ Rust (sysinfo)
πŸ–₯️ System Information Boot time & uptime πŸ¦€ Rust (sysinfo)
πŸ‘₯ System Users Real OS user accounts πŸ¦€ Rust (sysinfo)
πŸ‘₯ System Users Admin rights detection 🐍 Python (group name filtering)
⚑ System Instant Metrics CPU usage % πŸ¦€ Rust (sysinfo)
⚑ System Instant Metrics CPU temperature πŸ¦€ Rust (sysinfo components)
⚑ System Instant Metrics Per-core CPU usage πŸ¦€ Rust (sysinfo)
⚑ System Instant Metrics Load average (1m / 5m / 15m) πŸ¦€ Rust (sysinfo)
⚑ System Instant Metrics RAM usage % πŸ¦€ Rust (sysinfo)
⚑ System Instant Metrics Swap usage % πŸ¦€ Rust (sysinfo)
πŸ† Top CPU Consumers Top 4 processes by CPU πŸ¦€ Rust (sysinfo)
🌐 Network Instant Metrics Interface names πŸ¦€ Rust (sysinfo)
🌐 Network Instant Metrics Local IPv4 address πŸ¦€ Rust (sysinfo)
🌐 Network Instant Metrics Rx / Tx speed (MB/s) πŸ¦€ Rust (sysinfo)

Process Monitor (process)

Monitors all running instances of a named process and shows per-PID resource usage, sorted by CPU consumption.

syshealth process --name python
# or short form:
syshealth process -n chrome.exe

process demo

Output table:

Column Metric Backend
PID Process identifier πŸ¦€ Rust (sysinfo)
CPU Usage (%) Per-process CPU % πŸ¦€ Rust (sysinfo)
RAM Usage (%) Per-process RAM % of total πŸ¦€ Rust (sysinfo)

Note

Rows are sorted descending by CPU usage. If multiple instances of the same process are running (e.g. browser tabs), you will see one row per PID.


Background Service (install-service)

Installs SysHealth as a background service for the current OS (Windows or Linux). Requires Administrator or root privileges.

# Windows: open terminal as Administrator
# Linux: run with sudo
syshealth install-service

Note

If the service is already installed, you will be prompted to stop and replace it.


Background Exporter (Python API)

Important

When using the MQTT exporter, ensure you have installed the optional dependency (pip install syshealth[mqtt] or uv pip install ".[mqtt]") and that your MQTT broker is up and running before starting the exporter.

You can run SysHealth as a background thread in your own Python applications. It will automatically load your configuration from ~/.syshealth/config.json.

from syshealth.monitor import ExporterType, SysHealth
import time

# Use the context manager to ensure graceful shutdown
with SysHealth() as monitor:
    # Start background monitoring thread (priority 0 to 5)
    # The 'duration' argument will automatically stop the thread after 60 seconds.
    monitor.start(refresh_rate=5, exporter_type=ExporterType.MQTT, priority=5, duration=60)

    # Do your other work while metrics are exported automatically in Rust
    time.sleep(60)
    
# monitor.stop() is automatically called when exiting the 'with' block!

πŸ› οΈ Development

Prerequisites

Tool Purpose
rustup Rust compiler toolchain
uv Python project & venv manager

Install & Build from Source

# 1. Create virtual environment and compile the Rust extension in one step
uv pip install -e .

# 2. (Optional) install dev dependencies for tests and linting
uv pip install -e ".[dev]"

uv detects maturin as the build backend in pyproject.toml, compiles src/lib.rs, and links the resulting shared library into your local Python environment automatically.

Start External Dependencies

If you plan to use the background exporter for MQTT or VictoriaMetrics, ensure these services are running. You can quickly start them using docker-compose or podman-compose with the provided file:

docker-compose up -d
# OR with podman
podman-compose up -d

Run Tests & Linting

uv sync --group test && uv run pytest   # run all tests
uv run ruff format .                    # auto-format
uv run ruff check .                     # lint

Rebuild After Rust Changes

Every time you modify src/lib.rs you need to recompile the extension and regenerate the Python stubs:

# 1. Recompile & reinstall the Rust extension into the active venv
uv pip install -e .

# 2. Regenerate Python type stubs (updates python/syshealth/_rust_monitor.pyi)
cargo run --bin stub_gen

πŸ”§ Adding a New Metric

Follow these steps to expose a new piece of system data end-to-end.

Step 1 β€” Add the field to GlobalMetricsSnapshot in src/lib.rs

#[gen_stub_pyclass]
#[pyclass(get_all)]
pub struct GlobalMetricsSnapshot {
    // ... existing fields ...
    pub my_new_metric: f32,   // πŸ‘ˆ add your field here
}

Step 2 β€” Populate the field inside get_global_metrics()

fn get_global_metrics() -> PyResult<GlobalMetricsSnapshot> {
    // ... existing logic ...

    let my_new_metric = sys.some_sysinfo_call();   // πŸ‘ˆ gather data

    Ok(GlobalMetricsSnapshot {
        // ... existing fields ...
        my_new_metric,   // πŸ‘ˆ include in the struct literal
    })
}

Step 3 β€” Recompile and regenerate stubs

uv pip install -e .
cargo run --bin stub_gen

Step 4 β€” Display it in python/syshealth/cli.py

# Inside global_metrics():
table.add_row("My New Metric:", f"{metrics.my_new_metric:.2f}")

Step 5 β€” Update the mock in tests/test_cli.py

mock_metrics.my_new_metric = 42.0

Important

Always run cargo run --bin stub_gen after every Rust change so that the .pyi stub file stays in sync with the compiled extension. Without this, IDEs and type checkers will show incorrect type information.

Note

If you need a metric that sysinfo does not provide (e.g. GPU name), implement it as a plain Python helper function in cli.py using subprocess or the platform module β€” see get_gpu_name() for an example.


πŸ—οΈ Architecture

syshealth/
β”œβ”€β”€ scripts/
β”‚   └── linux/
β”‚       β”œβ”€β”€ syshealth.service               # systemd service configuration
β”‚       └── service_runner.py               # 🐍 Main program to run with systemd
β”‚   └── windows/
β”‚       └── syshealth_windows_service.py    # 🐍 Windows Service implementation
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ bin/
β”‚   β”‚   └── stub_gen.rs                     # πŸ¦€ Standalone Rust binary to generate Python type stubs
β”‚   β”œβ”€β”€ lib.rs                              # πŸ¦€ Rust extension β€” sysinfo polling, PyO3 bindings, background thread
β”‚   └── exporter/
β”‚       β”œβ”€β”€ mod.rs                          # πŸ¦€ Exporter trait + factory (create_exporter)
β”‚       β”œβ”€β”€ mqtt.rs                         # πŸ¦€ MQTT exporter (rumqttc, non-blocking channel)
β”‚       └── victoria_metrics.rs             # πŸ¦€ VictoriaMetrics exporter (ureq, non-blocking channel)
β”œβ”€β”€ python/
β”‚   └── syshealth/
β”‚       β”œβ”€β”€ _rust_monitor.pyi               # 🐍 Auto-generated type stubs (do not edit manually)
β”‚       β”œβ”€β”€ monitor.py                      # 🐍 Python wrapper β€” SysHealth + ExporterType enum
β”‚       └── cli.py                          # 🐍 Typer CLI + Rich display logic
└── tests/
    β”œβ”€β”€ test_cli.py                         # 🐍 Integration tests for all CLI commands
    └── test_monitor.py                     # 🐍 Integration tests: Rust backend + MQTT subscriber

Data flow β€” background exporter

sysinfo (Rust crate)
    └─▢ get_global_metrics_internal()          [monitoring thread β€” priority-adjusted]
            └─▢ GlobalMetricsSnapshot (Serialize)
                    └─▢ serde_json::to_string()
                            └─▢ mpsc::Sender<String>   [non-blocking, exporter worker thread]
                                    └─▢ MqttExporter / VictoriaMetricsExporter
                                            └─▢ Broker / Database

πŸ“‘ Receiving Exported Data

MQTT

SysHealth publishes a JSON object (all fields of GlobalMetricsSnapshot) to a single topic every refresh_rate seconds.

Item Value
Broker address ~/.syshealth/config.json β†’ endpoints.mqtt (e.g. localhost:1883)
Topic syshealth/metrics
QoS 0 (At Most Once)
Retain No
Payload format UTF-8 JSON

Payload fields (all in one JSON object on syshealth/metrics):

JSON key Type Description
cpu_usage float Global CPU usage %
cpu_brand string CPU model name
ram_percent float RAM used %
max_ram int Total RAM in bytes
disk_percent float Disk free %
available_disk int Available disk in bytes
boot_time int Unix timestamp of last boot
os_name string OS name
os_version string OS version string
kernel_version string Kernel version
hostname string Machine hostname
core_count_physical int | null Physical CPU core count
core_count_logical int Logical CPU thread count
cpu_temperature float | null CPU temperature in Β°C (if available)
swap_total int Total swap in bytes
swap_used int Used swap in bytes
network_rx_bytes int Total bytes received (all interfaces)
network_tx_bytes int Total bytes transmitted (all interfaces)
network_interfaces array Per-interface [name, rx, tx, [ips]]
per_core_usage array[float] Per-logical-core usage %
load_avg_1m float 1-minute load average
load_avg_5m float 5-minute load average
load_avg_15m float 15-minute load average
users array [username, [groups]] pairs
top_processes array Top 4 CPU consumers β€” [name, pid, cpu%]

Example subscriber (Python):

import json
import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    data = json.loads(msg.payload)
    print(f"CPU: {data['cpu_usage']:.1f}%  RAM: {data['ram_percent']:.1f}%")

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.on_message = on_message
client.connect("localhost", 1883)
client.subscribe("syshealth/metrics")
client.loop_forever()

VictoriaMetrics

SysHealth POSTs the same JSON snapshot to the VictoriaMetrics import endpoint.

Item Value
Endpoint ~/.syshealth/config.json β†’ endpoints.victoriametrics (e.g. http://localhost:8428/api/v1/import)
HTTP method POST
Content-Type application/json
Payload format JSON (same field list as the MQTT table above)

Note

Query stored metrics via MetricsQL or /api/v1/query using field names as metric names, e.g. cpu_usage, ram_percent.

Grafana Dashboard Example

A complete and pre-configured Grafana dashboard template for VictoriaMetrics is provided in the resources/grafana-dashboard.json file. You can import this JSON directly into your Grafana instance to instantly get a comprehensive visualization of your SysHealth metrics.

Grafana Dashboard Example


πŸ“„ License

See LICENSE for details.

About

πŸ’»πŸ©Ί A lightweight computer constants monitor using Rust and Python

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages