Skip to content

πŸ” Lightweight service monitoring tool with notifications. Zero dependencies and instant alerts when services go down.

License

Notifications You must be signed in to change notification settings

MowlCoder/heimdall

Repository files navigation

Heimdall Logo

πŸ” Heimdall - Service Monitoring Guardian πŸ”

Watchful protector of your services

Go Version License Go Report Card Dependencies


Heimdall - A lightweight, high-performance service monitoring tool that continuously checks your services' health and sends instant notifications when they become unavailable.

✨ Features

  • πŸ”„ Continuous Monitoring: Real-time health checks with configurable intervals
  • πŸ“± Multi-Platform Notifications: Instant alerts via Telegram, Discord, Slack, or custom webhook
  • ⚑ High Performance: Lightweight Go implementation with minimal resource usage
  • 🎯 Flexible Configuration: Support for both strict and lenient health checks
  • πŸš€ Zero Dependencies: No external dependencies - only Go standard library

πŸš€ Quick Start

Prerequisites

  • Go 1.24.2 or higher
  • Telegram Bot Token (for Telegram notifications)
  • Discord Webhook URL (for Discord notifications)
  • Slack Bot Token (for Slack notifications)

Installation

  1. Clone the repository

    git clone https://github.com/MowlCoder/heimdall.git
    cd heimdall
  2. Build the application

    # Using Task (recommended)
    task build
    
    # Or using Go directly
    go build -o bin/heimdall ./cmd/heimdall/main.go
  3. Create configuration file

    cp config.example.json config.json
  4. Configure your services and notifiers

    {
      "services": [
        {
          "name": "My Website",
          "url": "https://example.com",
          "interval": "30s",
          "strict": true,
          "headers": {
            "User-Agent": "Heimdall-Monitor/1.0",
            "Authorization": "Bearer your-token"
          }
        },
        {
          "name": "API Service",
          "url": "https://api.example.com/health",
          "interval": "1m",
          "strict": false,
          "timeout": 5000
        }
      ],
      "notifiers": {
        "telegram": {
          "chatId": "YOUR_CHAT_ID",
          "botToken": "YOUR_BOT_TOKEN",
          "enabled": true
        },
        "discord": {
          "webhook": "YOUR_DISCORD_WEBHOOK_URL",
          "enabled": false
        },
        "slack": {
          "chatId": "YOUR_CHANNEL_ID",
          "botToken": "YOUR_SLACK_BOT_TOKEN",
          "enabled": true
        },
        "webhook": {
          "webhook": "YOUR_CUSTOM_WEBHOOK_URL",
          "enabled": false
        }
      }
    }
  5. Run the service

    # Using Task
    task run
    
    # Or directly
    ./bin/heimdall --config ./config.json

πŸ“‹ Configuration

Service Configuration

Each service in the services array supports the following parameters:

Parameter Type Required Description Example
name string βœ… Human-readable service name "My API"
url string βœ… Service URL to monitor "https://api.example.com"
interval string βœ… Check interval (supports Go duration or milliseconds) "30s", "1m", "30000"
strict boolean ❌ Strict mode (only 200 OK considered healthy) true
timeout integer ❌ Request timeout in milliseconds 600
headers object ❌ Custom HTTP headers to send with requests {"Authorization": "Bearer token"}

Notifiers Configuration

Telegram Notifier

Parameter Type Required Description
chatId string βœ… Telegram chat ID where notifications will be sent
botToken string βœ… Telegram bot token from @BotFather
enabled boolean ❌ Enable/disable Telegram notifications (default: true)

Discord Notifier

Parameter Type Required Description
webhook string βœ… Discord webhook URL for the channel
enabled boolean ❌ Enable/disable Discord notifications (default: true)

Slack Notifier

Parameter Type Required Description
chatId string βœ… Slack channel ID where notifications will be sent
botToken string βœ… Slack bot token
enabled boolean ❌ Enable/disable Slack notifications (default: true)

Custom Webhook Notifier

Parameter Type Required Description
webhook string βœ… Custom webhook URL where notifications will be sent
enabled boolean ❌ Enable/disable custom webhook notifications (default: true)

Webhook Payload Structure:

{
  "name": "Service Name",
  "statusCode": 500,
  "body": "Error response body",
  "error": "Error message"
}

Health Check Modes

Strict Mode (strict: true)

  • Only HTTP 200 status code is considered healthy
  • Any other status code triggers a notification
  • Ideal for APIs that should always return 200 OK

Lenient Mode (strict: false or omitted)

  • HTTP 200-499 status codes are considered healthy
  • Only 5xx server errors trigger notifications
  • Suitable for services that may return redirects or client errors

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ™ Acknowledgments

  • Named after Heimdall, the Norse god who watches over the BifrΓΆst bridge
  • Built with Go for performance and reliability
  • Telegram Bot API, Discord Webhooks, Slack API, and custom webhooks for instant notifications
  • Rich message formatting with emojis, timestamps, and structured information

Made with ❀️ for reliable service monitoring

About

πŸ” Lightweight service monitoring tool with notifications. Zero dependencies and instant alerts when services go down.

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages