Skip to main content

🖥️🩺 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.

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)

Source distribution for syshealth 0.0.3
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)

Table of built distributions (wheels) for syshealth 0.0.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Release 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 log

Security 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.

Select from 3 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page