Richard/EdgeWatch
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
A hardware monitoring tool for edge devices that collects key system metrics and makes them available for remote monitoring. https://www.youtube.com/watch?v=gy89iaE0Wlg
65 commits 5 branches 0 tags 209 KiB
Find a file
Exact
Richard Nixon 4d16704ede ci(security): bump Silleellie/pylint-github-action to v3 
Closes Dependabot PR #2.

v3 changelog: adds an optional commit-message parameter (we do not
use it, default is fine), removes the Endbug dependency that caused
issues on github-enterprise, and bumps its own internal checkout /
setup-python actions. None of the inputs we pass (lint-path,
python-version, requirements-path, pylintrc-path, readme-path,
badge-text, color-*) changed.

Re-pinned by full commit SHA, same hardening pattern as v2.1.
2026-05-17 18:44:31 +00:00
.github ci(security): bump Silleellie/pylint-github-action to v3 2026-05-17 18:44:31 +00:00
docs Delete docs/MVP.md 2025-10-15 10:00:00 +01:00
frontend chore(frontend-deps): bump recharts, globals, eslint-plugin-react-refresh 2026-05-17 18:30:43 +00:00
tests test: cover Settings validation and Metrics schema 2026-05-17 17:19:50 +01:00
.gitignore test: add pytest suite for validation, alerting and WS auth 2026-05-17 14:45:00 +00:00
.pylintrc Update .pylintrc 2025-10-06 10:00:00 +01:00
backend.py feat(security): validate full MQTT payload schema with Pydantic 2026-05-17 17:19:50 +01:00
collect_metrics.py feat(config): typed settings via pydantic-settings 2026-05-17 17:19:50 +01:00
env_sample feat(security): authenticate WebSocket clients with shared token 2026-05-17 13:35:00 +00:00
README.md Updated pylint badge 2026-05-17 16:20:31 +00:00
requirements-dev.txt test: add pytest suite for validation, alerting and WS auth 2026-05-17 14:45:00 +00:00
requirements.txt chore(deps): bump websockets to 16.0 and setup-python to v6 2026-05-17 18:20:43 +00:00

README.md

EdgeWatch

License PyPI - Python Version AWS pylint

A lightweight hardware monitoring agent for edge devices.
It collects key system metrics (CPU, RAM, Disk, GPU, agent self-metrics) and makes them available for remote monitoring via MQTT, WebSocket, and Slack alerts.

Table of Contents

Prerequisites

  • Python 3.12+
  • Node.js v23.7.0+ (only if running the frontend dashboard)
  • Linux (Ubuntu/Debian) or macOS
  • Local MQTT broker (e.g., Mosquitto) or an AWS IoT Core endpoint

Install

1 - Clone repositoy and cd to the directory:

git clone https://github.com/richardnixondev/EdgeWatch

cd EdgeWatch

2 - Create and activate a virtual environment.
It’s recommended to isolate dependencies in a virtualenv:

python3 -m venv .venv

source .venv/bin/activate   # on Linux / macOS

3 - Install Python dependencies

pip install --upgrade pip

pip install -r requirements.txt

4 - Configure environment variables

cp env_sample .env

Update .env with your broker, WebSocket, and Slack settings. See Environment Variables for details.

5 - Run the agent
Starts collecting metrics and publishing them to MQTT.

python collect_metrics.py

6 - Run the backend (bridge MQTT → WebSocket + Slack)
Makes metrics available to frontends and sends Slack alerts.

python backend.py

The backend exposes a WebSocket server at ws://localhost:6789

7 - Run the frontend (React dashboard, optional)

cd frontend
npm install
npm run dev

The dashboard will be available at: http://localhost:5173

Design Explanation

See DESIGN.md for architecture choices, trade-offs,suggestions for improvements, scalability and security considerations.

Environment Variables

  • MQTT_BROKER: Hostname or endpoint of the MQTT broker (e.g., Mosquitto or AWS IoT Core).
  • MQTT_PORT: Port where the MQTT broker listens (default: 1883 for insecure, 8883 for TLS).
  • TOPIC: MQTT topic pattern used to publish device metrics.
  • WS_HOST: Host/IP where the WebSocket server should bind.
  • WS_PORT: Port where the WebSocket server should listen.
  • PRUNE_SECONDS: Time window (in seconds) to consider a device as “active” before pruning.
  • CPU_ALERT_TH: CPU usage threshold (%) to trigger alerts (e.g., Slack).
  • SLACK_WEBHOOK_URL: Slack Incoming Webhook URL used for sending notifications.
  • DEVICE_ID: Unique identifier for the device running the agent.
  • INTERVAL: Collection interval (in seconds) between metric samples.
  • CA_CERT: Path to the CA certificate file (for TLS/mTLS).
  • CLIENT_CERT: Path to the device’s client certificate (for TLS/mTLS).
  • CLIENT_KEY: Path to the device’s private key (for TLS/mTLS).

Assignment Checklist MVP

See MVP.md list of tasks performed based on the Assignment requirements.

Live Demo

Coming soon 🚀