Kuvasz HTTP uptime monitoring for all SpaceMusic services.
Overview¶
Kuvasz is a self-hosted uptime monitoring service running at uptime.spacemusic.tv. It replaced Uptime Kuma, which lacked a REST API for monitor management (it used Socket.IO internally).
Stack: Kuvasz (Kotlin) + PostgreSQL 16
Web UI: uptime.spacemusic.tv (protected by Authentik forward auth)
Monitored Services¶
| Monitor | URL | Interval |
|---|---|---|
| API Gateway | https://api.spacemusic.tv/api/health |
60s |
| Stream Dashboard | https://stream.spacemusic.tv |
60s |
| Auth (Authentik) | https://auth.spacemusic.tv |
60s |
| Dashboard (Grafana) | https://dashboard.spacemusic.tv |
60s |
| Storage (MinIO) | https://storage.spacemusic.tv |
60s |
| Relay (Centrifugo) | https://relay.spacemusic.tv |
60s |
| Docs | https://docs.spacemusic.tv |
60s |
| Uptime (self) | https://uptime.spacemusic.tv |
60s |
Monitors are managed via the REST API, not config files. The kuvasz.yml config file is intentionally kept empty to preserve API write access (if monitors are defined in the config file, the REST API becomes read-only).
REST API¶
Base URL: https://uptime.spacemusic.tv/api/v2/
Authentication: X-API-KEY header (also accepts Authorization: Bearer for Prometheus)
| Endpoint | Methods | Purpose |
|---|---|---|
/api/v2/health |
GET | Service health check |
/api/v2/http-monitors |
GET, POST | List / create monitors |
/api/v2/http-monitors/{id} |
GET, PATCH, DELETE | Monitor CRUD |
/api/v2/http-monitors/{id}/uptime-events |
GET | Event history |
/api/v2/prometheus |
GET | Prometheus metrics endpoint |
All monitor endpoints are also available through the API gateway at api.spacemusic.tv/api/monitor/*.
Prometheus Metrics¶
Kuvasz exports metrics at /api/v2/prometheus (bearer token auth):
| Metric | Description |
|---|---|
http_uptime_status |
Current up/down status per monitor (1 = up, 0 = down) |
http_latest_latency |
Latest response time in milliseconds per monitor |
ssl_status |
SSL certificate validity per monitor |
ssl_expiry |
Days until SSL certificate expiry per monitor |
These metrics are scraped by Prometheus and visualized in the "Uptime & Alerts" Grafana dashboard (state timeline, response time table, SSL expiry countdown).
Prometheus export gotcha
ENABLE_METRICS_EXPORT=true enables individual meter instruments but does not enable the /api/v2/prometheus endpoint. You must also set ENABLE_PROMETHEUS_EXPORT=true separately.
Data Retention¶
| Data Type | Retention |
|---|---|
| Uptime events | 365 days |
| Latency measurements | 30 days |
Infrastructure¶
Kuvasz runs via Docker Compose at /opt/spacemusic/uptime/spacemusic-uptime/. Deployed via GitHub Actions SSH.
Docker networks:
devpush_default-- Traefik routing + Prometheus scrapingdevpush_runner-- API gateway accesskuvasz-internal-- Kuvasz to PostgreSQL communication
Timezone: Europe/Zurich