GlanceWatch - Documentation

🌙
☀️
← Back to Dashboard

# GlanceWatch Documentation

Setting up Uptime Kuma monitoring

## 📊 Overview

GlanceWatch provides HTTP endpoints that Uptime Kuma can monitor to track your system's health. When resource usage exceeds your configured thresholds, GlanceWatch returns an HTTP 503 status code, triggering alerts in Uptime Kuma.

💡 Key Feature: GlanceWatch uses HTTP 503 (Service Unavailable) status codes to signal threshold violations. This allows Uptime Kuma to automatically detect and alert when your system resources are running low.

## 🔗 Available API Endpoints

GlanceWatch provides several monitoring endpoints. Use these URLs when adding monitors to Uptime Kuma:

### Primary Monitoring Endpoint

GET `http://localhost:8000/status`

Monitors all system metrics (RAM, CPU, and Disk). Returns HTTP 503 if any threshold is exceeded.

### Individual Metric Endpoints

GET `http://localhost:8000/ram`

Monitors RAM usage only. Returns HTTP 503 if RAM threshold is exceeded.

GET `http://localhost:8000/cpu`

Monitors CPU usage only. Returns HTTP 503 if CPU threshold is exceeded.

GET `http://localhost:8000/disk`

Monitors disk usage only. Returns HTTP 503 if disk threshold is exceeded.

### Health Check Endpoint

GET `http://localhost:8000/health`

Basic health check. Always returns HTTP 200 when the service is running.

### Response Format

All endpoints return JSON responses. Example from `/status`:

    {
      "ok": false,
      "ram": {
        "ok": false,
        "value": 85.2,
        "threshold": 80
      },
      "cpu": {
        "ok": true,
        "value": 45.3,
        "threshold": 80
      },
      "disk": {
        "ok": true,
        "threshold": 85,
        "disks": [...]
      },
      "last_check": "2025-11-12T10:30:45.123456"
    }

## ⚙️ Adding Monitors to Uptime Kuma

Follow these steps to add GlanceWatch monitoring to Uptime Kuma:

### Access Uptime Kuma

Open Uptime Kuma in your browser:

    http://localhost:3001

Log in with your credentials.

### Add New Monitor

Click the "Add New Monitor" button (usually a + icon in the top right).

### Configure Monitor Type

Select "HTTP(s)" as the monitor type.

### Fill in Monitor Details

Field | Value | Description
--- | --- | ---
Friendly Name | System Resources | Display name for the monitor
URL | `http://localhost:8000/status` | The GlanceWatch endpoint to monitor
Heartbeat Interval | 60 seconds | How often to check (recommended: 60s)
Retries | 2 | Number of retries before marking as down
HTTP Method | GET | Default HTTP method
Expected Status Code | 200-299 | Any 2xx status = healthy

### Configure Notifications (Optional)

Scroll down to the "Notifications" section and select how you want to be alerted:

- Email - Receive email alerts
- Slack - Post to a Slack channel
- Discord - Send Discord messages
- Telegram - Telegram bot notifications
- And many more...

### Save Monitor

Click "Save" at the bottom of the form. Uptime Kuma will immediately start monitoring your endpoint.

⚠️ Important: Make sure GlanceWatch is running before adding monitors. You can check if it's running by visiting http://localhost:8000

## 🔧 Advanced Configuration

### Monitoring Individual Metrics

Instead of monitoring all resources with `/status`, you can create separate monitors for each metric:

- RAM Monitor: `http://localhost:8000/ram`
- CPU Monitor: `http://localhost:8000/cpu`
- Disk Monitor: `http://localhost:8000/disk`

This gives you more granular control and separate alerts for each resource type.

### Adjusting Check Intervals

For production systems:

- Critical systems: 30-60 second intervals
- Standard systems: 60-120 second intervals
- Non-critical systems: 300 second (5 minute) intervals

### Remote Monitoring

If GlanceWatch is running on a remote server, replace `localhost` with the server's IP address or hostname:

    http://192.168.1.100:8000/status
    http://monitoring.example.com:8000/status

🔒 Security Tip: If monitoring over the internet, consider using a reverse proxy with HTTPS (nginx, Caddy, etc.) to secure the connection.

## 🔍 Troubleshooting

### Monitor Shows "Down"

1. Verify GlanceWatch is running: `ps aux | grep glancewatch`
2. Check if the port is correct (default: 8000)
3. Test the endpoint manually: `curl http://localhost:8000/status`
4. Check GlanceWatch logs for errors

### False Positives (Alerts when system is fine)

1. Adjust thresholds in the GlanceWatch dashboard
2. Increase the retry count in Uptime Kuma (to avoid transient spikes)
3. Verify Glances is running: `ps aux | grep glances`

### Not Receiving Alerts

1. Check notification settings in Uptime Kuma
2. Test notifications using the "Test" button
3. Verify the monitor is set to send notifications
4. Manually trigger an alert by setting a very low threshold (e.g., RAM 1%)

### Connection Refused Errors

1. Ensure GlanceWatch is listening on `0.0.0.0` not `127.0.0.1`
2. Check firewall rules allow port 8000
3. If using Docker, verify port mappings

## 📖 API Reference

For complete API documentation, visit:

Swagger UI: http://localhost:8000/api

### Status Codes

Status Code | Meaning | When It Occurs
--- | --- | ---
200 OK | All systems normal | All metrics below thresholds
503 Service Unavailable | Threshold exceeded | One or more metrics above threshold
500 Internal Server Error | Server error | Configuration or connection issues

GlanceWatch v1.0.5 • Back to Dashboard