go-site-sentinel

A lightweight, concurrent URL monitoring service written in Go that tracks uptime, response times, SSL certificate expiration, and HTTP status codes. Features include SQLite storage, terminal dashboards, Prometheus metrics, and flexible notification hooks.

Features

• Concurrent Monitoring: Monitor multiple URLs simultaneously using goroutines
• Comprehensive Metrics: Track uptime, response time, HTTP status codes, and SSL expiration
• Local Storage: SQLite database (modernc.org/sqlite) for persistent result storage
• Terminal Dashboards: Beautiful, colorful terminal UI for real-time monitoring
• Prometheus Integration: Optional metrics endpoint for Prometheus scraping
• Flexible Notifications: Webhook and email notification support
• YAML Configuration: Easy-to-use YAML configuration file

Installation

Prerequisites

• Go 1.19 or higher

Build from Source

git clone https://github.com/BaseMax/go-site-sentinel.git
cd go-site-sentinel
go build -o sentinel ./cmd/sentinel

Configuration

Create a config.yaml file with your monitoring targets and settings:

# Check interval in seconds
check_interval: 60

# Database configuration
database:
  path: sentinel.db

# Targets to monitor
targets:
  - name: Google
    url: https://www.google.com
    check_ssl: true
  
  - name: GitHub
    url: https://github.com
    check_ssl: true
  
  - name: Example
    url: https://example.com
    check_ssl: true

# Notification configuration
notifications:
  # Webhook notifications
  webhooks:
    - url: https://hooks.example.com/webhook
      enabled: false
      events:
        - down
        - up
        - ssl_expiring
  
  # Email notifications
  email:
    enabled: false
    from: sentinel@example.com
    to:
      - admin@example.com
    events:
      - down
      - ssl_expiring
    smtp:
      host: smtp.example.com
      port: 587
      username: user@example.com
      password: your-password
      use_tls: true

# Prometheus metrics endpoint
metrics:
  enabled: true
  port: 9090
  path: /metrics

Usage

Start Monitoring

Run continuous monitoring with live dashboard updates:

./sentinel monitor [config-file]

This will:

• Check all targets at the configured interval
• Display a live terminal dashboard
• Store results in SQLite database
• Send notifications when targets go up/down
• Expose Prometheus metrics endpoint (if enabled)

View Dashboard

Display the latest monitoring results:

./sentinel dashboard [config-file]

View Statistics

Show uptime statistics for all targets:

./sentinel stats [config-file]

Help

./sentinel help

Dashboard Output

The terminal dashboard shows:

╔══════════════════════════════════════════════════════════════════════════════╗
║                        SITE SENTINEL DASHBOARD                               ║
╚══════════════════════════════════════════════════════════════════════════════╝

TARGET                    STATUS     STATUS CODE  RESPONSE     SSL DAYS LEFT       
──────────────────────────────────────────────────────────────────────────────────────────
GitHub                    UP         200          71ms         364 days            
Google                    DOWN       0            3ms          N/A                 
  └─ Error: connection timeout
Example                   UP         200          45ms         90 days             

Last updated: 2025-12-19 17:33:01

Prometheus Metrics

When enabled, Prometheus metrics are available at http://localhost:9090/metrics (configurable):

# HELP site_sentinel_up Whether the target is up (1) or down (0)
# TYPE site_sentinel_up gauge
site_sentinel_up{target="GitHub",url="https://github.com"} 1

# HELP site_sentinel_response_time_ms Response time in milliseconds
# TYPE site_sentinel_response_time_ms gauge
site_sentinel_response_time_ms{target="GitHub",url="https://github.com"} 71

# HELP site_sentinel_status_code HTTP status code
# TYPE site_sentinel_status_code gauge
site_sentinel_status_code{target="GitHub",url="https://github.com"} 200

# HELP site_sentinel_ssl_days_left Days until SSL certificate expiration
# TYPE site_sentinel_ssl_days_left gauge
site_sentinel_ssl_days_left{target="GitHub",url="https://github.com"} 364

Notifications

Webhook Notifications

Webhooks receive JSON payloads with check results:

{
  "event": "down",
  "target_name": "Example",
  "target_url": "https://example.com",
  "status_code": 0,
  "response_time": 5000,
  "is_up": false,
  "error": "connection timeout",
  "checked_at": "2025-12-19T17:33:01Z"
}

Email Notifications

Email notifications are sent for configured events (up, down, ssl_expiring) with detailed information about the check result.

Architecture

The project follows a clean architecture pattern:

├── cmd/sentinel/          # Main CLI application
├── internal/
│   ├── config/           # Configuration loading and validation
│   ├── db/               # SQLite database layer
│   ├── monitor/          # URL monitoring with goroutines
│   ├── notifier/         # Notification system (webhook/email)
│   ├── dashboard/        # Terminal dashboard UI
│   └── metrics/          # Prometheus metrics server
└── pkg/
    └── models/           # Shared data models

Key Components

Concurrent Monitoring

The monitor package uses goroutines to check multiple URLs simultaneously:

func (m *Monitor) CheckAll(targets []models.Target) []*models.CheckResult {
    results := make([]*models.CheckResult, len(targets))
    done := make(chan bool)

    for i, target := range targets {
        go func(index int, tgt models.Target) {
            results[index] = m.Check(tgt)
            done <- true
        }(i, target)
    }

    // Wait for all checks to complete
    for range targets {
        <-done
    }

    return results
}

Database Storage

Results are stored in SQLite using modernc.org/sqlite (pure Go implementation):

• Check results with timestamps
• Uptime statistics
• Response time history
• SSL certificate expiration tracking

Development

Run Tests

go test ./...

Format Code

go fmt ./...

Build

go build -o sentinel ./cmd/sentinel

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

• Max Base (@BaseMax)

Acknowledgments

• Uses modernc.org/sqlite for pure Go SQLite implementation
• Uses gopkg.in/yaml.v3 for YAML parsing