ghaymah-exam-Mohamed_Moustafa-SRE/q5-mithal-monitor/README.md

Mithal.space Monitor

Production-quality website monitoring solution for mithal.space — an Arabic-first, privacy-respecting search engine.

Overview

This project provides continuous monitoring of mithal.space, collecting uptime, latency, DNS, SSL, and search-response metrics every 60 seconds. A static HTML dashboard displays real-time charts and status cards, auto-refreshing every 30 seconds.

Features

• Continuous monitoring — runs every 60 seconds (configurable)
• HTTP status & latency tracking
• DNS lookup time measurement
• SSL certificate validity, expiration date, and days remaining
• Search endpoint response time (real /search?q= request)
• JSON persistence — last 24 hours of data (1,440 records)
• Static dashboard — no frameworks, just HTML/CSS/Vanilla JS
• Chart.js line and bar charts
• Dark mode toggle
• Auto-refresh with countdown timer
• CSV export of all metrics
• CLI arguments for interval, target, max records
• Logging to both console and monitor.log
• Never crashes — all errors handled gracefully

Requirements

• Python 3.10+
• pip
• A modern web browser (for the dashboard)

Installation

1. Clone / Download

cd q5-mithal-monitor

2. Create a Python Virtual Environment

python3 -m venv venv
source venv/bin/activate        # Linux / macOS
# venv\Scripts\activate         # Windows

3. Install Dependencies

pip install -r requirements.txt

4. Run the Monitor

python monitor.py

With options:

python monitor.py --interval 30 --target https://mithal.space --max-records 720

Flag	Default	Description
--interval	60	Check interval in seconds
--target	https://mithal.space	URL to monitor
--max-records	1440	Max records to keep (≈24h at 60s)
--search-query	test	Query sent to /search endpoint
--metrics-file	metrics.json	Path to metrics file

5. View the Dashboard

Open dashboard.html in a browser. It reads metrics.json directly via fetch().

# Option A: just open the file
open dashboard.html          # macOS
xdg-open dashboard.html      # Linux

# Option B: serve via Python
python3 -m http.server 8080
# then visit http://localhost:8080/dashboard.html

Project Structure

q5-mithal-monitor/
├── monitor.py          # Main monitoring script
├── metrics.json        # Collected metrics (auto-generated)
├── dashboard.html      # Dashboard page
├── style.css           # Dashboard styles
├── script.js           # Dashboard logic
├── requirements.txt    # Python dependencies
├── README.md           # This file
├── monitor.log         # Log file (auto-generated)
└── screenshots/
    ├── dashboard.png
    └── monitor.png

How Monitoring Works

Every check interval the script:

1. DNS — resolves the hostname and measures lookup time
2. SSL — connects on port 443 and reads the certificate expiry
3. HTTP — sends GET to the target URL, records status code and latency
4. Search — sends GET /search?q=test to measure search endpoint response
5. Persist — appends the record to metrics.json, trims to 1,440 entries

All exceptions (DNS failures, SSL errors, timeouts, connection refused) are caught and logged — the script never crashes.

Uptime Percentage Calculation

uptime % = (checks where uptime == true) / (total checks) × 100

The dashboard computes this from the loaded metrics.json data. When the file contains ≤1,440 records, the percentage reflects all available data; otherwise it represents the last 24 hours.

Known Limitations

• Single-target — monitors only one URL per instance
• No alerting — no email/Slack/webhook notifications (designed for visual monitoring)
• No auth — dashboard has no authentication; serve behind a reverse proxy for production
• Local file — metrics.json is read via browser fetch(); requires same-origin or local file access
• Chart.js CDN — the dashboard loads Chart.js from a CDN; works offline after first load (cached)
• Search metric — only measures response time, not result quality or completeness

License

MIT