Metadata-Version: 2.4
Name: glancewatch
Version: 1.0.4
Summary: Lightweight monitoring adapter bridging Glances metrics with Uptime Kuma
Author-email: Collins Kramp <collynes@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/collynes/glancewatch
Project-URL: Documentation, https://github.com/collynes/glancewatch#readme
Project-URL: Repository, https://github.com/collynes/glancewatch
Project-URL: Issues, https://github.com/collynes/glancewatch/issues
Project-URL: Changelog, https://github.com/collynes/glancewatch/releases
Keywords: monitoring,glances,uptime-kuma,metrics,system-monitoring,server-monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Framework :: FastAPI
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: glances>=3.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ipython>=8.18.0; extra == "dev"
Dynamic: license-file

# GlanceWatch 🎯

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.109+-green.svg)](https://fastapi.tiangolo.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/glancewatch.svg)](https://pypi.org/project/glancewatch/)
[![Tests](https://github.com/collinskramp/glancewatch/workflows/Tests/badge.svg)](https://github.com/collinskramp/glancewatch/actions)
[![Coverage](https://img.shields.io/badge/coverage-78%25-brightgreen.svg)](https://github.com/collinskramp/glancewatch)

**GlanceWatch** is a lightweight monitoring adapter that bridges [Glances](https://nicolargo.github.io/glances/) system metrics with [Uptime Kuma](https://github.com/louislam/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

## 🚀 Quick Start

```bash
# Install GlanceWatch (automatically installs Glances dependency)
pip install glancewatch

# Run GlanceWatch (auto-starts Glances if needed)
glancewatch

# Access the web UI
open http://localhost:8000
```

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

## 🎯 Usage

```bash
# 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
```

## 📡 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 /api` - 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`:

```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

```bash
# 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 [TEST_SUMMARY.md](TEST_SUMMARY.md) for detailed test documentation.

## 🆕 What's New in v1.0.2

- ✅ **Fixed critical bug**: DateTime serialization in error responses
- ✅ **New endpoint**: `/thresholds` for easier threshold management
- ✅ **Comprehensive tests**: 63+ test cases covering all functionality
- ✅ **CI/CD pipeline**: Automated testing on every commit
- ✅ **78% code coverage**: Major quality improvement
- ✅ Bug fixes from v1.0.1 (missing import uvicorn)

## 🆕 What's New in v1.0.1

- ✅ **Auto-Glances Management**: Glances is now auto-installed and auto-started
- ✅ **New CLI Flag**: `--ignore-glances` to skip automatic Glances management
- ✅ **Route Reorganization**: API docs moved from `/docs` to `/api`, UI now at root `/`
- ✅ **UI Redesign**: Clean router-style admin interface with plain colors
- ✅ **Improved UX**: Single command to install and run everything

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 📧 Support

- **Issues**: [GitHub Issues](https://github.com/collinskramp/glancewatch/issues)
- **PyPI**: [pypi.org/project/glancewatch](https://pypi.org/project/glancewatch/)

---

**Made with ❤️ for simple system monitoring**
