Overview • Features • Tech Stack • Architecture • Getting Started • API Reference • Deployment • Contributing
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.
🎥 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: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.
| 📊 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 |
| 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) |
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.pyisolates all system-metric collection — CPU/memory/disk percentages, network counters converted to MB, uptime derived frompsutil.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.pyis a pure function: metrics in,(alerts, status)out — easy to unit test or extend with new thresholds.app.pykeeps a rolling in-memoryalert_history, deduplicating consecutive identical alerts so the feed doesn't spam the same warning every poll cycle.- The frontend is intentionally dependency-light:
sam.jspolls/healthand updates the DOM directly, no frontend framework or build step required.
- Python ≥ 3.8
pipfor installing dependencies
git clone https://github.com/thetelgote/System-Monitor.git
cd System-Monitorpython -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activatepip install -r requirements.txtpython app.pyThe 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.
gunicorn app:appBase 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° |
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:
- Push this repo to GitHub (already done ✅)
- Create a new Web Service on Render, pointing at this repo
- Build command:
pip install -r requirements.txt - Start command:
gunicorn app:app - Deploy — Render will detect the
Procfileautomatically
⚠️ Note: CPU temperature sensors are typically unavailable on cloud VMs/containers —cpu_tempwill report"N/A"in most hosted environments. This is expected and handled gracefully by the app.
- WebSocket-based live updates instead of polling
- Historical charts (CPU/memory trend over time)
- Configurable alert thresholds via environment variables
- Email/Slack notifications on
Criticalstatus - Multi-host monitoring (dashboard for several machines at once)
- Unit tests for
monitor.pyandalerts.py
Contributions, issues, and feature requests are welcome!
- Fork the project
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.