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.

• 🛠 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

• 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

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

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

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

Manage everything with:

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

• 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

• 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

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.

This project is licensed under the MIT License.

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

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