📡 Kuma Monitoring Reporter

A lightweight, modular tool to monitor Uptime Kuma metrics and send beautifully formatted status reports to Telegram. Stay informed about your services with real-time updates and customizable thresholds.

✨ Features

• 🛠 Modular Design — cleanly separated modules for fetching, formatting, and sending data
• 📝 Formatted Reports — Markdown-based Telegram messages with 🟢🟡🔴 status visualization
• ⚙️ Easy Configuration — interactive setup via install.sh or manual JSON editing
• 📡 Multi-Monitor Support — supports multiple monitor types (HTTP, Ping, Port, Group, etc.)
• 🔔 Customizable Notifications — sound or silent mode for Telegram alerts
• 🔄 Systemd Integration — run as a persistent background service
• 🛡️ Error Handling — detailed logging and backups for debugging
• ✅ Interactive Management — installation, updates, and control through a menu
• 🔐 Secure API Access — compatible with Uptime Kuma read-only API tokens

📋 Prerequisites

• Operating System: Linux (tested on Ubuntu)

• Dependencies:

  sudo apt-get install git python3 python3-pip systemd jq

• Python Packages (in requirements.txt):

  • requests
  • schedule
  • prometheus_client

• Uptime Kuma: a running instance with /metrics endpoint

• Telegram: bot token from @BotFather and a chat ID

🚀 Installation

🔧 Option 1 — Automatic (Recommended)

bash <(curl -s https://raw.githubusercontent.com/power0matin/kuma-monitoring-reporter/main/install.sh)

The script allows you to:

• Clone the repository
• Set up Python virtual environment
• Install dependencies
• Configure config.json interactively
• Manage systemd service
• Test Telegram connection and back up logs

🛠 Option 2 — Manual Installation (Advanced)

1. Clone the repository:

   git clone https://github.com/power0matin/kuma-monitoring-reporter.git
   cd kuma-monitoring-reporter

2. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure config.json:

   nano config/config.json

   Example:

   {
     "kuma_url": "http://your-server:3001/metrics",
     "telegram_bot_token": "1234567890:AAH...",
     "telegram_chat_id": "123456789",
     "auth_token": "",
     "thresholds": {
       "good": 200,
       "warning": 500,
       "critical": 1000
     },
     "report_interval": 1,
     "notification_mode": "sound"
   }

5. Run the reporter:

   python3 report.py

📬 Sample Report

Uptime Kuma Status Report
Time: 2025-07-29 13:55:00
════════════════════════════
🟢 Germany_hetzner (http) — 0.0 ms
🟡 Iran-0-1 (ping) — 78.0 ms
🟡 Iran-respina (http) — 86.0 ms
════════════════════════════
Summary: 3 UP, 0 DOWN

⚙️ Project Structure

File/Directory	Description
report.py	Main entry script
core/fetch.py	Fetch metrics from Uptime Kuma API
core/formatter.py	Process and format data
core/telegram.py	Send formatted reports to Telegram
config/config.json	Project configuration file
logs/error.log	Error logs for debugging
install.sh	Interactive setup and management script

🧰 Usage Instructions

Manage everything with:

cd ~/kuma-monitoring-reporter
./install.sh

📖 Detailed options in install.sh

1. Install project (clone, venv, deps)
2. Configure config.json interactively
3. Update project (git pull + pip upgrade)
4. Manage systemd service (start / stop / restart)
5. Test Telegram bot settings
6. Backup logs
7. Show project status and running services
8. Check Python dependencies
9. Completely uninstall the project
10. Exit the menu

🛡️ Troubleshooting

• No Telegram Reports

  • Use Option 5 to test bot token and chat ID

  • Check logs:

    cat ~/kuma-monitoring-reporter/logs/error.log

• Systemd Issues

  sudo systemctl status kuma-reporter.service

• Missing Python Packages

  • Use Option 8 to reinstall dependencies

• Invalid Config

  • Reconfigure with Option 2

📅 Project Roadmap

Phase	Status	Description
🔹 Phase 1: MVP	✅ Complete	Fetch Kuma metrics, format reports, send to Telegram
🔹 Phase 2: Modularization	✅ Complete	Core modules, error logging, interactive installer
🔹 Phase 3: Enhanced Features	🚧 In Progress	Systemd integration, silent mode, log backups
🔹 Phase 4: Advanced + CI/CD	📝 Planned	Selective reporting, buttons, structured logs, GitHub Actions

🌟 Future Development Ideas

• Filtering monitors by tags or names
• Selective reporting of problematic monitors only
• Multiple Telegram channels or platform support (Discord, Slack)
• Interactive Telegram buttons (Pause/Resume)
• Structured logging (e.g., JSON)
• Custom report templates

🙌 Contributing

1. Fork the repo
2. Create a branch: git checkout -b feature/your-feature
3. Commit: git commit -m "Add your feature"
4. Push: git push origin feature/your-feature
5. Open a Pull Request

Please write clear commit messages and test your changes thoroughly.

📜 License

This project is licensed under the MIT License.

📬 Contact

Matin Shahabadi (متین شاه‌آبادی / متین شاه آبادی)

• Website: matinshahabadi.ir
• Email: me@matinshahabadi.ir
• GitHub: power0matin
• LinkedIn: matin-shahabadi

For suggestions or issues, open an Issue on GitHub or contact the maintainer directly.

docs(readme): improve Kuma Monitoring Reporter README formatting and structure