SystemPulse

SystemPulse is a lightweight cross-platform system monitoring and observability CLI for Windows, macOS, and Linux. It combines a Rich terminal dashboard with configurable alerts, local SQLite history, CSV export, and an optional Prometheus endpoint—without requiring a background daemon or web application.

Use it for an immediate view of host health, a live terminal dashboard, local metric history, or a small Prometheus target on a workstation or server.

Dashboard

The existing capture accurately represents the core dashboard layout. It predates the current active-alert panel, so a present-day systempulse live session includes an additional Alerts section. See docs/demo.md for a safe, reproducible demo-capture workflow.

Quick start

SystemPulse is not yet published to PyPI. Install the current project from source:

git clone https://github.com/guptaoni891-ctrl/systempulse.git
cd systempulse
python -m pip install -e .

Then open the menu, live dashboard, or a one-time snapshot:

systempulse
systempulse live
systempulse snapshot

Install the optional exporter dependencies from the source checkout when Prometheus support is needed:

python -m pip install -e ".[prometheus]"
systempulse serve

After a future PyPI release, installation will become:

pip install systempulse
pip install "systempulse[prometheus]"  # only when exporter support is needed

These PyPI commands are release instructions, not a claim that version 2.0 is currently published. For virtual-environment setup on each platform, see Installation from source.

Features

• CPU, memory, system-disk, and network monitoring.
• Network totals since boot and upload/download rate calculation.
• CPU temperature when the operating system exposes a usable sensor through psutil.
• Top CPU-consuming processes.
• NVIDIA GPU usage, temperature, VRAM, and optional power through nvidia-smi.
• Multiple NVIDIA GPUs represented independently in snapshots, alerts, history, and Prometheus.
• Rich one-shot and live terminal views with configurable status thresholds.
• Stateful alerts with duration, hysteresis, cooldown, escalation, and recovery transitions.
• Transactional SQLite snapshot, GPU, and durable alert-event history with retention.
• CSV snapshot logging and custom output paths.
• Optional scrape-decoupled Prometheus exporter.
• Typed, validated JSON configuration with OS-specific config and data locations.
• Python 3.11–3.13 support with cross-platform CI, static typing, and enforced branch coverage.

Platform support

Missing sensors or GPU tooling are reported as unavailable; they do not prevent core monitoring. Use --no-gpu to skip NVIDIA detection explicitly.

CLI reference

Global options must appear before the command:

--config PATH   use an explicit JSON configuration
--no-gpu        skip NVIDIA GPU collection
--version       print the installed version

Monitor the host

The installed module entry point is equivalent, for example python -m systempulse snapshot.

Alerts and history

--hours and --days are mutually exclusive. Active alerts exist only in the live process; durable transition history is stored separately in SQLite. See docs/alerts.md and docs/history.md.

Save and export

Prometheus support requires the prometheus extra. Binding beyond 127.0.0.1 exposes host metrics to reachable clients and should be an explicit decision. See docs/prometheus.md.

Inspect and update configuration

Configuration precedence, every supported key, and a complete valid example are documented in docs/configuration.md.

Architecture

flowchart TD
    C[System collectors] --> S[MonitorService]
    S --> SS[Authoritative SystemSnapshot]

    SS --> UI[Rich terminal UI]
    SS --> A[AlertEngine]
    SS --> CSV[CSV logger]
    SS --> H[SQLite history]
    A --> AE[Alert transition events]
    AE --> H

    ES[Exporter sampling loop] --> S
    SS --> LS[Lock-protected latest state]
    LS --> PE[Prometheus collector]
    PS[Prometheus scrape] --> PE

Collectors gather raw host data. MonitorService combines it into one immutable, UTC-stamped SystemSnapshot; presentation and persistence components consume that snapshot rather than collecting independently. AlertEngine evaluates state transitions but never polls hardware.

The exporter has its own monotonic sampling loop that updates lock-protected latest state. Prometheus scrapes read that state and never call MonitorService, psutil, or nvidia-smi. SQLite is a separate sink and does not feed Prometheus. See docs/architecture.md for module boundaries and design guarantees.

Installation from source

SystemPulse requires Python 3.11, 3.12, or 3.13.

Windows PowerShell

git clone https://github.com/guptaoni891-ctrl/systempulse.git
cd systempulse
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Linux and macOS

git clone https://github.com/guptaoni891-ctrl/systempulse.git
cd systempulse
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

The dev extra includes the optional Prometheus dependency so the complete test suite can exercise both normal exporter behavior and missing-dependency behavior. Runtime users can install . or .[prometheus] instead.

Documentation

• Configuration
• Alerts
• SQLite history
• Prometheus exporter
• Architecture
• Development and CI
• Demo capture
• Contributing
• Security policy
• Changelog

Engineering quality

The repository enforces branch coverage at 90% and currently maintains more than 90% coverage. CI separates quality checks, the supported Python/OS test matrix, and clean package validation. Local commands are documented in docs/development.md.

Important boundaries include immutable authoritative snapshots, monotonic interval scheduling, timezone-aware UTC persistence, transactional SQLite writes, bounded Prometheus labels, optional exporter dependencies, and no scrape-triggered hardware collection.

License

SystemPulse is available under the MIT License.