💓 Pulse

Pulse is a containerised infrastructure monitoring platform built with Python, FastAPI, Prometheus, and Grafana. It monitors system health, exposes operational metrics, provides Grafana dashboards, and supports configurable Slack and email alerting.

• CPU, memory, disk, and uptime monitoring
• Configurable warning and critical thresholds
• FastAPI /health and /metrics endpoints
• Prometheus-compatible metrics
• Grafana infrastructure dashboard
• Slack and email notifications
• Alert cooldowns and recovery notifications
• Structured application logging
• Containerised deployment with Docker Compose
• GitHub Actions backend CI

Current release: v2.3.2 ✅
Lifecycle: Maintenance

The core Pulse monitoring and observability stack is complete and portfolio-ready.

Pulse provides system resource monitoring, configurable Slack and email alerting, FastAPI health and metrics endpoints, Prometheus metric collection, Grafana visualisation, structured logging, Docker Compose deployment, and GitHub Actions CI.

v2.3.2 introduced a modular application structure separating the API, monitoring, alerting, logging, and dashboard components to improve maintainability.

Future work is limited to maintenance, automated testing, dependency and security updates, alert reliability, documentation, and infrastructure improvements.

See the Roadmap for release history and maintenance work.

System Resources
       │
       ▼
  Pulse Monitor
       │
       ├──────────► Structured Logging
       │
       ├──────────► Slack / Email Alerts
       │
       ▼
    FastAPI
 /health  /metrics
       ▲
       │ scrapes
       │
   Prometheus
       │
       │ queries
       ▼
    Grafana

Prometheus periodically scrapes metrics exposed by Pulse, while Grafana queries Prometheus to provide visual monitoring of CPU, memory, disk usage, and system uptime.

For a more in-depth breakdown of the system design, please see the Architecture Documentation.

Clone the repository:

git clone https://github.com/Iris408/pulse-infrastructure-monitor.git
cd pulse-infrastructure-monitor

Install dependencies:

pip install -r requirements.txt

Create the environment configuration:

cp .env.example .env

Run the terminal monitor:

python3 main.py

Or start the FastAPI service:

python3 -m uvicorn health_api:app --reload --port 8000

Start the complete monitoring stack:

docker compose up --build -d

Check service status:

docker compose ps

Stop the stack:

docker compose down

For more detailed installation and configuration instructions, please see the Setup Guide.

When running locally:

GitHub Actions automatically validates the Python backend on pushes and pull requests to main.

The current CI workflow runs automated backend checks to help catch regressions before changes are merged.

Additional automated testing, security checks, and Docker validation are tracked as maintenance improvements.

pulse-infrastructure-monitor/
├── app/
│   ├── api/
│   ├── monitoring/
│   ├── alerts/
│   ├── logging/
│   └── dashboard/
├── tests/
├── config/
├── docs/
├── screenshots/
├── examples/
├── .github/workflows/
├── Dockerfile
├── docker-compose.yml
└── README.md

Detailed engineering documentation is available in docs/.

This project is licensed under the terms in MIT LICENSE file for details.

Built by Iris408