GlanceWatch

GlanceWatch is a lightweight monitoring adapter that bridges Glances system metrics with Uptime Kuma and other monitoring tools. It exposes simple HTTP endpoints with configurable thresholds that answer: "Is my system healthy?"

Features

• One-Command Install: pip install glancewatch - everything included
• Auto-Glances Management: Automatically installs and starts Glances for you
• HTTP Status Alerting: Returns HTTP 200 (OK) or 503 (unhealthy) based on thresholds
• Router-Style Web UI: Clean admin interface at / (root)
• Configurable Thresholds: Set custom limits for RAM, CPU, and disk usage
• Persistent Configuration: Changes saved to config.yaml automatically
• Multiple Disk Monitoring: Monitor all or specific mount points
• Health Checks: Built-in health endpoint for service monitoring
• OpenAPI Docs: Auto-generated API documentation at /api
• Real-Time Metrics: Auto-refreshing dashboard shows live system status

Installation

macOS (Homebrew)

brew tap collynes/glancewatch
brew install glancewatch
glancewatch

Windows (Chocolatey)

choco install glancewatch
glancewatch

Node.js/npm (All platforms)

# Global installation
npm install -g glancewatch
glancewatch

# Or use npx
npx glancewatch

Python/pip (All platforms)

pip install glancewatch
glancewatch

Quick Start

Background Service (Recommended for Production)

Linux/Ubuntu (systemd):

# One-command install as background service
curl -sSL https://raw.githubusercontent.com/collynes/glancewatch/main/scripts/install-pip.sh | bash

# Service automatically starts on boot and runs in background

Simple background start (nohup):

# Start in background
nohup glancewatch > /dev/null 2>&1 &

# Check if running
ps aux | grep glancewatch

See docs/BACKGROUND-SERVICE.md for complete guide including screen/tmux options.

Foreground (Development)

pip install glancewatch
glancewatch

# Or run with custom port
glancewatch --port 8080

# Access the dashboard
open http://localhost:8000

That's it! 🎉 GlanceWatch automatically handles Glances installation and startup.

Usage

# Start GlanceWatch (auto-starts Glances)
glancewatch

# Start without auto-starting Glances
glancewatch --ignore-glances

# Custom port
glancewatch --port 9000

# Custom host
glancewatch --host 0.0.0.0

📚 Documentation

• Installation Guide - Detailed installation instructions
• Quick Start Guide - Get started in minutes
• Ubuntu Quick Start - Ubuntu-specific guide
• Background Service Setup - Run as a service
• UI Guide - Web interface overview
• Pip Installation - Python package details
• Release Notes - All version history

📡 API Endpoints

• GET / - Web UI (root endpoint)
• GET /status - Combined status (HTTP 503 on threshold violation)
• GET /ram - RAM usage check
• GET /cpu - CPU usage check
• GET /disk - Disk usage check
• GET /health - Service health check
• GET /config - Get configuration
• PUT /config - Update thresholds
• GET /docs - Interactive API documentation

🔔 Uptime Kuma Integration

1. In Uptime Kuma, create a new HTTP(s) monitor
2. Set URL to: http://your-server:8000/status
3. Set "Accepted Status Codes" to: 200

When any metric exceeds its threshold, GlanceWatch returns HTTP 503, triggering an alert.

Configuration

GlanceWatch creates ~/.config/glancewatch/config.yaml:

glances_base_url: "http://localhost:61208/api/4"
host: "0.0.0.0"
port: 8000
log_level: "INFO"
return_http_on_failure: 503

thresholds:
  ram_percent: 80
  cpu_percent: 80
  disk_percent: 85

disk:
  mounts:
    - "/"

Adjust thresholds via the Web UI at / or edit the config file.

🧪 Testing & Development

GlanceWatch has comprehensive test coverage to ensure reliability:

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=app --cov-report=html

# Run specific test file
pytest tests/test_api.py -v

# Run and stop on first failure
pytest tests/ -x

Test Coverage

• 78%+ code coverage with 63+ test cases
• All endpoints tested (including new /thresholds endpoints)
• CLI functionality tests
• Error handling and edge cases
• Integration workflow tests

CI/CD

Every push and pull request automatically runs:

• ✅ Tests on Python 3.8, 3.9, 3.10, 3.11, 3.12
• ✅ Code linting
• ✅ Coverage checks (minimum 75%)
• ✅ Package build verification

See docs/TEST_SUMMARY.md for detailed test documentation.

🆕 What's New in v1.2.1

• ✅ Dynamic Version Display: Fixed version display bug - now shows correct version in UI
• ✅ Template-based Version: Uses {{VERSION}} placeholder replaced at runtime
• ✅ Improved UI: Green/red circle status indicators with thin borders
• ✅ System Health Monitor: Added uptime, load average, and network statistics
• ✅ Better Thresholds: CPU now supports 0.1% minimum threshold
• ✅ Reset Defaults: Reset button always enabled with proper default values (80/80/85)
• ✅ Clean Documentation: Removed all unsolicited emojis from docs
• ✅ Section Reordering: Moved threshold configuration before system health

See docs/RELEASE_NOTES_v1.2.1.md for complete release notes.

📄 License

MIT License - see LICENSE file for details.

📧 Support

• Issues: GitHub Issues
• PyPI: pypi.org/project/glancewatch

Made with ❤️ for simple system monitoring