Dlaczego automatyzacja monitoringu ma znaczenie • Dwa interfejsy API — REST i Socket.IO • Autentykacja — API Key i tokeny • REST API — Push URL i Prometheus metrics • Socket.IO API — real-time CRUD • Zarządzanie monitorami przez API • Przykłady automatyzacji — skrypty i integracje • Narzędzia społeczności • Podsumowanie • Najczęściej zadawane pytania
Ręczne zarządzanie monitorami jest akceptowalne dla kilku stron — ale gdy monitorujesz dziesiątki lub setki usług, automatyzacja staje się koniecznością. API Uptime Kuma pozwala na programistyczne tworzenie monitorów, zarządzanie powiadomieniami, integrację z CI/CD pipeline i automatyczne reagowanie na incydenty.
Typowe scenariusze automatyzacji:
Uptime Kuma oferuje dwa interfejsy programistyczne, każdy z innym przeznaczeniem:
| Cecha | REST API | Socket.IO API |
|---|---|---|
| Protokół | HTTP GET/POST | WebSocket (Socket.IO) |
| Komunikacja | Request-response | Real-time bidirectional |
| Autentykacja | API Key (header/query) | Login + token / API Key |
| Funkcje | Push URL, Prometheus /metrics | Pełny CRUD — monitory, powiadomienia, status pages, tagi, maintenance |
| Zastosowanie | Heartbeat, scraping metryk | Automatyzacja, IaC, integracje |
| Dostępność | Publiczne (Push URL) | Wymaga autentykacji |
Od Uptime Kuma 2.x dostępne są API Keys generowane w Settings → API Keys. Token dodajesz jako header:
Authorization: Bearer kuma_xxxxxxxxxxxxxxxxxxDla Socket.IO możesz też użyć klasycznego loginu username/password. Biblioteka Python uptime-kuma-api obsługuje oba sposoby, włącznie z 2FA (TOTP).
Każdy Push Monitor generuje unikalny URL. Twój skrypt wysyła GET na ten URL po zakończeniu zadania:
# Heartbeat po zakończeniu backupu
curl -s "https://uptime.twoja-domena.pl/api/push/abc123?status=up&msg=Backup+OK&ping=42"
# W skrypcie bash
backup_start=$(date +%s)
rsync -av /data /backup/
backup_time=$(( $(date +%s) - backup_start ))
curl -s "https://uptime.twoja-domena.pl/api/push/abc123?status=up&msg=Backup+done&ping=$backup_time"Endpoint /metrics wystawia metryki w formacie Prometheus:
curl -s https://uptime.twoja-domena.pl/metrics
# Przykład odpowiedzi:
monitor_status{monitor_name="Strona WWW",monitor_type="http"} 1
monitor_response_time{monitor_name="Strona WWW",monitor_type="http"} 245
monitor_cert_days_remaining{monitor_name="Strona WWW"} 67Dodaj ten endpoint do konfiguracji Prometheus (scrape_configs) i twórz dashboardy w Grafana z historią uptime, wykresami czasu odpowiedzi i alertami.
Socket.IO API to główny interfejs programistyczny Uptime Kuma. Oferuje pełny CRUD w czasie rzeczywistym — tworzenie, odczyt, aktualizację i usuwanie wszystkich zasobów.
from uptime_kuma_api import UptimeKumaApi
api = UptimeKumaApi("https://uptime.twoja-domena.pl")
api.login("admin", "password123")
# Utwórz monitor HTTP
result = api.add_monitor(
type="http",
name="API Production",
url="https://api.mojafirma.pl/health",
interval=30,
maxretries=3,
accepted_statuscodes=["200-299"],
notificationIDList=[1, 2] # Telegram + Email
)
print(f"Monitor ID: {result['monitorID']}")
api.disconnect()# monitors.yaml
monitors:
- name: "Strona WWW"
type: http
url: "https://www.mojafirma.pl"
interval: 30
- name: "API v2"
type: http
url: "https://api.mojafirma.pl/v2/health"
interval: 20
- name: "Baza MySQL"
type: mysql
hostname: "db.mojafirma.pl"
port: 3306
interval: 60import yaml
from uptime_kuma_api import UptimeKumaApi
api = UptimeKumaApi("https://uptime.twoja-domena.pl")
api.login("admin", "password123")
with open("monitors.yaml") as f:
config = yaml.safe_load(f)
for m in config["monitors"]:
result = api.add_monitor(**m)
print(f"Created: {m['name']} (ID: {result['monitorID']})")
api.disconnect()# GitHub Actions - dodaj monitor po deployu
- name: Create Uptime Kuma monitor
run: |
pip install uptime-kuma-api
python3 -c "
from uptime_kuma_api import UptimeKumaApi
api = UptimeKumaApi('${{ secrets.KUMA_URL }}')
api.login_by_token('${{ secrets.KUMA_TOKEN }}')
api.add_monitor(type='http', name='PR-${{ github.event.number }}',
url='https://pr-${{ github.event.number }}.preview.mojafirma.pl',
interval=60)
api.disconnect()
"#!/bin/bash
# /etc/cron.daily/backup-with-heartbeat.sh
PUSH_URL="https://uptime.twoja-domena.pl/api/push/backup-daily"
# Wykonaj backup
if borgmatic --config /etc/borgmatic.d/config.yaml; then
curl -s "${PUSH_URL}?status=up&msg=Backup+OK"
else
curl -s "${PUSH_URL}?status=down&msg=Backup+FAILED"
fi| Narzędzie | Język | Opis |
|---|---|---|
| uptime-kuma-api | Python | Pełny wrapper Socket.IO z CRUD dla wszystkich zasobów. pip install uptime-kuma-api |
| Kuma CLI | Go | Narzędzie CLI do zarządzania Uptime Kuma z terminala |
| AutoKuma | Rust | Automatyczne tworzenie monitorów na podstawie Docker labels (Infrastructure as Code) |
| Terraform provider | Go | Provider Terraform dla Uptime Kuma — IaC z pełnym stanem |
| Ansible collection | Python | Ansible modules do zarządzania monitorami jako kodem |
API Uptime Kuma to potężne narzędzie automatyzacji monitoringu. Dwa interfejsy — REST (Push URL, Prometheus) i Socket.IO (pełny CRUD) — pokrywają wszystkie scenariusze, od prostego heartbeat po Infrastructure as Code z Terraform.
Kluczowe elementy API:
Uptime Kuma ma ograniczone REST API — głównie Push URL i Prometheus /metrics. Głównym interfejsem jest Socket.IO API z pełnym CRUD. Biblioteki społeczności (uptime-kuma-api Python) opakowują Socket.IO w wygodne interfejsy.
W Uptime Kuma 2.x wygeneruj API Key w Settings → API Keys. Token używasz jako header Authorization: Bearer lub parametr połączenia Socket.IO.
Tak. Przez Socket.IO API możesz tworzyć, edytować, usuwać, pauzować i wznawiać monitory, zarządzać powiadomieniami, stronami statusu, tagami, maintenance i proxy.
Tak. Endpoint /metrics wystawia metryki w formacie Prometheus — status monitorów, czas odpowiedzi, dni do wygaśnięcia certyfikatu SSL. Scrapuj przez Prometheus, wizualizuj w Grafana.
Najpopularniejsza to uptime-kuma-api (pip install uptime-kuma-api) — pełny wrapper Socket.IO z CRUD dla monitorów, powiadomień, status pages, tagów i maintenance. Obsługuje login, 2FA i context manager.
Push URL to REST endpoint dla Push Monitors. Każdy Push Monitor generuje unikalny URL — Twój skrypt/cronjob wysyła GET na ten URL po zakończeniu. Brak sygnału w określonym czasie = alert.