first commit

q5-mithal-monitor/README.md

@@ -0,0 +1,136 @@
+# Mithal.space Monitor
+
+Production-quality website monitoring solution for [mithal.space](https://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
+
+```bash
+cd q5-mithal-monitor
+```
+
+### 2. Create a Python Virtual Environment
+
+```bash
+python3 -m venv venv
+source venv/bin/activate        # Linux / macOS
+# venv\Scripts\activate         # Windows
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Run the Monitor
+
+```bash
+python monitor.py
+```
+
+With options:
+
+```bash
+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()`.
+
+```bash
+# 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