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.
- β‘ 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
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])
Displays a full system snapshot dashboard. Panels are automatically placed side-by-side when the terminal is wide enough.
syshealth global-metricsOutput 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) |
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.exeOutput 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.
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-serviceNote
If the service is already installed, you will be prompted to stop and replace it.
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!| Tool | Purpose |
|---|---|
rustup |
Rust compiler toolchain |
uv |
Python project & venv manager |
# 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.
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 -duv sync --group test && uv run pytest # run all tests
uv run ruff format . # auto-format
uv run ruff check . # lintEvery 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_genFollow these steps to expose a new piece of system data end-to-end.
#[gen_stub_pyclass]
#[pyclass(get_all)]
pub struct GlobalMetricsSnapshot {
// ... existing fields ...
pub my_new_metric: f32, // π add your field here
}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
})
}uv pip install -e .
cargo run --bin stub_gen# Inside global_metrics():
table.add_row("My New Metric:", f"{metrics.my_new_metric:.2f}")mock_metrics.my_new_metric = 42.0Important
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.
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
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
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()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.
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.
See LICENSE for details.


