Overview • Features • Tech Stack • Architecture • Getting Started • API Reference • Deployment • Contributing

---

📖 Overview

System Monitor is a lightweight, self-hosted web dashboard that watches your machine's vital signs in real time — CPU load, memory usage, disk space, network I/O, process count, uptime, and (where supported) CPU temperature — and raises clear alerts the moment something crosses a healthy threshold.

No agents, no external monitoring SaaS, no config files — clone it, run it, and you have a live health dashboard for any machine it's deployed on.

🔗 Live Demo  ·  Report a Bug

🎥 Tip: Record a short GIF of the live dashboard updating (CPU spiking, an alert firing) with ScreenToGif or Kap, save it to docs/demo.gif, and embed it here:

![System Monitor demo](./docs/demo.gif)

A moving dashboard preview is the single most persuasive thing a recruiter will see on this repo — nothing sells "I can build real, live-updating tools" faster.

---

✨ Features

📊 Live System Metrics	CPU %, memory %, disk usage %, process count, network sent/received (MB), and uptime, refreshed continuously
🌡️ CPU Temperature	Reads hardware sensors where available, gracefully falls back to N/A when not supported
🚨 Smart Alerting	Automatic threshold checks — CPU > 80%, memory > 80%, disk > 90%, temp > 80° — each escalating the system status
🟢🟡🔴 Status Levels	Rolls all checks into a single Healthy / Warning / Critical status for an at-a-glance read
🕒 Alert History	Keeps the last 10 unique alerts with timestamps, so you can see what happened and when
🌐 Simple JSON API	A single /health endpoint returns everything the frontend needs — easy to consume from anywhere
⚡ Zero-config Frontend	Server-rendered dashboard (Flask + Jinja) with a small vanilla JS layer (sam.js) polling for updates
🚀 Production-ready	Ships with a Procfile and gunicorn, ready to deploy on Render, Heroku, Railway, or any WSGI host

---

🛠 Tech Stack

Layer	Technology
Backend	Python, Flask
System Metrics	psutil (CPU, memory, disk, network, sensors, process count)
Frontend	Jinja2-rendered HTML, CSS, vanilla JavaScript (sam.js)
WSGI Server	Gunicorn
Deployment	Procfile-based (Render / Heroku-style platforms)

---

🏗 Architecture & How It Works

System-Monitor/
├── app.py            # Flask app — routes, request handling, alert history
├── monitor.py         # Collects raw system metrics via psutil
├── alerts.py           # Applies thresholds to metrics → alerts + status
├── templates/
│   └── index.html       # Dashboard shell rendered by Flask
├── static/
│   └── sam.js             # Client-side polling — fetches /health and updates the UI
├── requirements.txt
└── Procfile             # gunicorn app:app — production entry point

Data flow, end to end:

Browser (sam.js, polling)
      │  GET /health
      ▼
app.py  ──▶  monitor.get_system_health()  ──▶  psutil (CPU / RAM / disk / net / temp)
      │
      ▼
alerts.check_alerts(data)  ──▶  thresholds → [alerts...], status
      │
      ▼
JSON response: { data, alerts, status, history }
      │
      ▼
Browser updates dashboard + alert feed in place

Key design details:

• monitor.py isolates all system-metric collection — CPU/memory/disk percentages, network counters converted to MB, uptime derived from psutil.boot_time(), and a best-effort CPU temperature read that safely degrades to "N/A" on platforms without sensor support (e.g. most cloud hosts).
• alerts.py is a pure function: metrics in, (alerts, status) out — easy to unit test or extend with new thresholds.
• app.py keeps a rolling in-memory alert_history, deduplicating consecutive identical alerts so the feed doesn't spam the same warning every poll cycle.
• The frontend is intentionally dependency-light: sam.js polls /health and updates the DOM directly, no frontend framework or build step required.

---

🚀 Getting Started

Prerequisites

• Python ≥ 3.8
• pip for installing dependencies

1. Clone the repository

git clone https://github.com/thetelgote/System-Monitor.git
cd System-Monitor

2. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Run the app

python app.py

The dashboard will be available at http://127.0.0.1:5000. 🎉

Metrics refresh automatically as sam.js polls the /health endpoint — no page reload needed.

5. Run in production mode (optional, local test)

gunicorn app:app

---

📡 API Reference

Base URL: http://127.0.0.1:5000

Method	Endpoint	Description
GET	/	Renders the dashboard (index.html)
GET	/health	Returns live system metrics, active alerts, overall status, and recent alert history as JSON

Example /health response:

{
  "data": {
    "cpu": 23.4,
    "memory": 61.2,
    "disk": 47.8,
    "processes": 214,
    "net_sent": 152.34,
    "net_recv": 980.12,
    "uptime": 93042,
    "system": "Linux",
    "cpu_temp": 52.0
  },
  "alerts": [],
  "status": "Healthy",
  "history": [
    { "message": "🔥 High CPU Usage", "time": "14:32:10" }
  ]
}

Alert thresholds:

Metric	Warning	Critical
CPU usage	> 80%	—
Memory usage	> 80%	—
Disk usage	—	> 90%
CPU temperature	—	> 80°

---

📦 Deployment

The repo ships with everything needed for a one-click deploy to any Heroku-style platform (Render, Railway, Heroku):

Procfile → web: gunicorn app:app

To deploy on Render:

1. Push this repo to GitHub (already done ✅)
2. Create a new Web Service on Render, pointing at this repo
3. Build command: pip install -r requirements.txt
4. Start command: gunicorn app:app
5. Deploy — Render will detect the Procfile automatically

⚠️ Note: CPU temperature sensors are typically unavailable on cloud VMs/containers — cpu_temp will report "N/A" in most hosted environments. This is expected and handled gracefully by the app.

---

🗺 Roadmap

• WebSocket-based live updates instead of polling
• Historical charts (CPU/memory trend over time)
• Configurable alert thresholds via environment variables
• Email/Slack notifications on Critical status
• Multi-host monitoring (dashboard for several machines at once)
• Unit tests for monitor.py and alerts.py

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

⬆ Back to top