🖥️🩺 SysHealth
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
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
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]oruv 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_genafter every Rust change so that the.pyistub 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
sysinfodoes not provide (e.g. GPU name), implement it as a plain Python helper function incli.pyusingsubprocessor theplatformmodule — seeget_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/queryusing 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.
📄 License
See LICENSE for details.
Metadata
Release files for syshealth 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| syshealth-0.0.3.tar.gz | 457.5 kB | With provenance | Details for syshealth-0.0.3.tar.gz |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| syshealth-0.0.3-cp312-cp312-win_amd64.whl | CPython 3.12 | CPython 3.12 | Windows x86-64 | Details for syshealth-0.0.3-cp312-cp312-win_amd64.whl |
| syshealth-0.0.3-cp312-cp312-manylinux_2_38_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.38+ x86-64 | Details for syshealth-0.0.3-cp312-cp312-manylinux_2_38_x86_64.whl |
Total release size: 6.3 MB
Release files / syshealth-0.0.3.tar.gz
| Download URL | syshealth-0.0.3.tar.gz |
|---|---|
| Size | 457.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ee63560d78f33661f9ebdcb73e251308822d064212a6ebd93f0ebd6f1d60916
|
|
BLAKE2b-256 checksum How to use checksums |
ce1f1a5566a8f52cede5b537fcb55a77275f5f06628772e6edd87f4a8637da42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 26, 2026.
Transparency logRelease files / syshealth-0.0.3-cp312-cp312-win_amd64.whl
| Download URL | syshealth-0.0.3-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
9b79c7aa4ffd581f0c74b3af83e56859f3be8973fd7c6982758973bc2e969902
|
|
BLAKE2b-256 checksum How to use checksums |
7fa0e827669168ca8c097bf8624d7afe72b6a1628daf7166b26b2d844042c90a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 26, 2026.
Transparency logRelease files / syshealth-0.0.3-cp312-cp312-manylinux_2_38_x86_64.whl
| Download URL | syshealth-0.0.3-cp312-cp312-manylinux_2_38_x86_64.whl |
|---|---|
| Size | 4.3 MB |
| Tags | CPython 3.12 Linux glibc 2.38+ x86-64 |
|
SHA-256 checksum How to use checksums |
60c82ddb17847c4ed8f5e8c67ede9ebc69926befbf63f507409f0e0a0c3d19ea
|
|
BLAKE2b-256 checksum How to use checksums |
286b72ae48f27ba5ec4638b272e2d8ad977b2eb41ec5232d0fa7fcdacdaf9007
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 26, 2026.
Transparency logSecurity for syshealth 0.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 3 files in this release have been uploaded with provenance metadata.
Attestation for syshealth-0.0.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.