Push Monitor (Heartbeat) — monitoring zadań cron, backupów i skryptów

Czym jest Push Monitor i dlaczego warto go znać

Większość narzędzi monitoringu — w tym Uptime Kuma — działa domyślnie w modelu aktywnym: serwer monitoringu regularnie odpytuje (pulluje) monitorowane usługi, sprawdzając czy są dostępne. To doskonale sprawdza się przy monitorowaniu stron www, API czy portów TCP. Ale co z zadaniami, które nie nasłuchują na żadnym porcie? Co z cronjobami, skryptami backupowymi, procesami ETL czy zaplanowanymi zadaniami Windows, które uruchamiają się o 3:00 w nocy, wykonują swoją pracę i kończą działanie?

Tutaj wchodzi Push Monitor (nazywany też Heartbeat Monitor lub Passive Monitor) — odwrócony model monitoringu, w którym to monitorowany skrypt sam wysyła sygnał do Uptime Kuma po zakończeniu pracy. Jeśli sygnał (heartbeat) nie przyjdzie w oczekiwanym czasie — Uptime Kuma uznaje, że coś poszło nie tak, i natychmiast wysyła powiadomienie.

Koncepcja jest prosta jak genialnie prosty jest mechanizm, na którym się opiera: Dead Man's Switch (przełącznik martwego człowieka). Dopóki ktoś regularnie naciska przycisk — wszystko jest w porządku. Gdy przestaje — uruchamia się alarm. W kontekście IT: dopóki skrypt regularnie wysyła heartbeat — monitor jest zielony. Gdy heartbeat przestaje przychodzić — monitor przechodzi w stan DOWN i wysyła alert.

Push Monitor w Uptime Kuma to jedno z najbardziej niedocenianych narzędzi w arsenale administratora. Pozwala monitorować procesy, które są niewidoczne dla tradycyjnego monitoringu — a jednocześnie często krytyczne dla działania całej infrastruktury. Backup, który nie wykonał się w nocy, cronjob odnawiający certyfikat SSL, który się zawiesił, skrypt synchronizacji danych, który cicho przestał działać — to scenariusze, w których push monitoring ratuje sytuację.

Push vs Pull — dwa modele monitoringu

Aby w pełni zrozumieć wartość Push Monitora, warto porównać dwa fundamentalne modele monitoringu. Każdy z nich ma swoje zastosowania — i oba są potrzebne w dobrze zaprojektowanej infrastrukturze monitoringu.

Model Pull (aktywny monitoring)

W modelu Pull to serwer monitoringu inicjuje połączenie do monitorowanej usługi. Uptime Kuma co X sekund wysyła żądanie (HTTP GET, Ping ICMP, zapytanie DNS, połączenie TCP) i sprawdza odpowiedź. To domyślny model dla większości typów monitorów w Uptime Kuma — HTTP(s), Ping, TCP, DNS, SNMP, bazy danych i wielu innych.

Zalety modelu Pull:

• Monitoring jest niezależny od monitorowanej usługi — nawet jeśli usługa jest całkowicie niedostępna, serwer monitoringu to wykryje
• Nie wymaga modyfikacji monitorowanych aplikacji — wystarczy, że nasłuchują na porcie
• Centralna konfiguracja — wszystko zarządzasz z poziomu Uptime Kuma

Ograniczenia modelu Pull:

• Wymaga, aby monitorowana usługa była dostępna sieciowo (nasłuchuje na porcie)
• Nie działa dla zadań jednorazowych, cronjobów, skryptów batch ani procesów, które nie mają stałego endpointu
• Może wymagać konfiguracji firewalla/NAT, jeśli usługa jest za zaporą

Model Push (pasywny monitoring)

W modelu Push to monitorowana usługa inicjuje połączenie do serwera monitoringu. Skrypt, cronjob lub aplikacja po zakończeniu pracy wysyła sygnał HTTP do Uptime Kuma. Serwer monitoringu czeka pasywnie na sygnały i reaguje, gdy sygnał nie przyjdzie w oczekiwanym czasie.

Zalety modelu Push:

• Idealny dla zadań, które nie mają stałego endpointu — cronjobów, backupów, pipeline'ów ETL, skryptów
• Działa przez NAT i firewalle — monitorowany host nawiązuje połączenie wychodzące (HTTP)
• Pozwala monitorować sukces wykonania, nie tylko dostępność — skrypt może wysłać heartbeat dopiero po pomyślnym zakończeniu
• Umożliwia przesyłanie dodatkowych informacji — status, czas wykonania, komunikat o błędzie

Ograniczenia modelu Push:

• Wymaga modyfikacji monitorowanych skryptów (dodanie wywołania HTTP na końcu)
• Jeśli skrypt ma błąd, który nie pozwala mu dojść do linii z heartbeatem — nie wyśle sygnału (ale to właśnie chcemy wykryć)
• Zależy od łączności sieciowej z Uptime Kuma — jeśli łącze jest niedostępne, heartbeat nie dotrze

W praktyce najlepsze podejście to kombinacja obu modeli. Pull monitoring dla usług ciągłych (serwery www, API, bazy danych), push monitoring dla zadań okresowych (cronjobs, backupy, synchronizacje). Uptime Kuma obsługuje oba modele natywnie, co czyni ją kompletnym narzędziem monitoringu.

Dead Man's Switch — mechanizm heartbeat

Dead Man's Switch (DMS) to mechanizm bezpieczeństwa znany z kolei i przemysłu — maszynista musi regularnie naciskać pedał lub przycisk, aby pociąg kontynuował jazdę. Jeśli przestanie (np. z powodu zasłabnięcia), system automatycznie zatrzyma pojazd. W IT ten sam koncept stosuje się do monitoringu procesów, które powinny regularnie dawać znać, że żyją.

Push Monitor w Uptime Kuma działa dokładnie na tej zasadzie:

Kluczowa różnica w stosunku do tradycyjnego monitoringu: Push Monitor nie sprawdza stanu usługi aktywnie. Czeka na sygnały i reaguje na ich brak. To odwrócona logika — „brak wiadomości" to zła wiadomość.

Konfiguracja Push Monitora w Uptime Kuma krok po kroku

Dodanie Push Monitora w Uptime Kuma to kilka minut. Poniżej pełna instrukcja krok po kroku — od utworzenia monitora do skonfigurowania pierwszego heartbeatu.

Push URL, interwał i graceful period

Push URL to serce Push Monitora. Każdy monitor generuje unikalny URL z tokenem, który służy jako endpoint do odbierania heartbeatów. Zrozumienie jego struktury i parametrów jest kluczowe dla prawidłowej konfiguracji.

Struktura Push URL

Format Push URL w Uptime Kuma wygląda następująco:

https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=OK&ping=

Parametry URL:

• TOKEN — unikalny identyfikator monitora, generowany automatycznie. Traktuj go jak hasło — nie udostępniaj publicznie
• status — status heartbeatu: up (domyślny, wszystko OK) lub down (skrypt zgłasza błąd)
• msg — opcjonalna wiadomość tekstowa, np. „Backup zakończony pomyślnie" lub „Błąd: brak miejsca na dysku"
• ping — opcjonalny czas w milisekundach, np. czas wykonania skryptu. Wyświetlany na wykresie Response Time w Uptime Kuma

Heartbeat Interval — jak dobrać wartość

Heartbeat Interval to najważniejszy parametr Push Monitora. Określa maksymalny oczekiwany czas między sygnałami. Zbyt krótki interwał generuje fałszywe alarmy. Zbyt długi — opóźnia wykrycie problemu.

Zasada kciuka: ustaw interwał na czas cyklu zadania + margines bezpieczeństwa. Przykłady:

Graceful Period i Retry Logic

Poza Heartbeat Interval, Uptime Kuma oferuje dodatkowe mechanizmy, które pomagają uniknąć fałszywych alarmów:

• Max Retries — liczba cykli, które monitor może „przegapić" przed przejściem w stan DOWN. Przy interwale 300s i max retries = 2, monitor przejdzie w DOWN dopiero po 900 sekundach (3 × 300s) bez heartbeatu
• Retry Interval — czas (w sekundach) między sprawdzeniami po pierwszym przegapieniu. Domyślnie równy heartbeat interval
• Resend Notification — opcja ponownego wysyłania powiadomień co X sekund, dopóki monitor jest w stanie DOWN. Przydatne, gdy chcesz eskalację — np. powtarzany alert co 30 minut

Przykład konfiguracji dla nocnego backupu:

# Konfiguracja Push Monitora:
# Heartbeat Interval: 86400 sekund (24 godziny)
# Max Retries: 1
# Retry Interval: 3600 sekund (1 godzina)
#
# Logika:
# - Backup powinien zakończyć się codziennie do ~4:00
# - Jeśli do 3:00 następnego dnia nie ma heartbeatu → pierwsze sprawdzenie
# - Po dodatkowej godzinie (4:00) bez heartbeatu → status DOWN + alert
# - Łączny czas tolerancji: ~25 godzin od ostatniego heartbeatu

Zastosowania Push Monitora — praktyczne scenariusze

Push Monitor w Uptime Kuma jest niezwykle wszechstronny. Poniżej opisujemy najczęstsze zastosowania z konkretnymi przykładami konfiguracji i integracji.

Monitoring zadań cron (Linux/macOS)

Cron to scheduler zadań w systemach Unix/Linux. Zadania cron uruchamiają się automatycznie według harmonogramu — ale domyślnie nikt nie wie, czy się wykonały pomyślnie. Cron wysyła e-mail z outputem (jeśli skonfigurowano MTA), ale w praktyce większość serwerów nie ma skonfigurowanej poczty, a nawet jeśli ma — kto czyta e-maile z crona?

Push Monitor rozwiązuje ten problem elegancko. Dodaj curl na końcu komendy w crontab — i masz monitoring:

# Przykład: cronjob wykonujący cleanup logów co godzinę
0 * * * * /usr/local/bin/cleanup-logs.sh && curl -fsS -m 10 --retry 3 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=OK" > /dev/null

# Kluczowe flagi curl:
# -f  → fail silently (zwróć kod błędu przy HTTP 4xx/5xx)
# -sS → cichy tryb, ale pokaż błędy
# -m 10 → timeout 10 sekund
# --retry 3 → ponów 3 razy przy błędach sieciowych

Dlaczego && zamiast ;? Operator && oznacza, że curl wykona się tylko jeśli poprzedni skrypt zakończy się sukcesem (kod wyjścia 0). Jeśli skrypt zwróci błąd — heartbeat nie zostanie wysłany — i Uptime Kuma zaalarmuje. To właśnie esencja push monitoringu: heartbeat wysyłamy tylko po sukcesie.

Bardziej zaawansowany wariant z raportowaniem statusu:

# Cronjob z raportowaniem sukcesu/porażki
0 * * * * /usr/local/bin/cleanup-logs.sh \
  && curl -fsS -m 10 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=Cleanup+OK" > /dev/null \
  || curl -fsS -m 10 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=down&msg=Cleanup+FAILED" > /dev/null

W tym wariancie operator || powoduje, że jeśli skrypt się nie powiedzie, wyślemy heartbeat ze statusem down — Uptime Kuma natychmiast oznaczy monitor jako DOWN i wyśle alert, nie czekając na upłynięcie interwału.

Monitoring skryptów backupowych

Backup, który nie wykonał się w nocy, to jeden z najczęstszych i najgroźniejszych problemów w administracji IT. Odkrywany zazwyczaj dopiero, gdy dane są potrzebne — czyli w najgorszym możliwym momencie. Push Monitor zamienia cichy błąd w natychmiastowy alert.

#!/bin/bash
# backup-database.sh — backup bazy danych z push monitoring

PUSH_URL="https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"
START_TIME=$(date +%s)

# Wykonaj backup
mysqldump --all-databases --single-transaction \
  | gzip > /backup/db-$(date +%Y%m%d-%H%M%S).sql.gz

BACKUP_EXIT=$?
END_TIME=$(date +%s)
DURATION=$(( END_TIME - START_TIME ))
DURATION_MS=$(( DURATION * 1000 ))

if [ $BACKUP_EXIT -eq 0 ]; then
    # Sprawdź rozmiar pliku backupu
    BACKUP_SIZE=$(ls -lh /backup/db-*.sql.gz | tail -1 | awk '{print $5}')

    curl -fsS -m 10 --retry 3 \
      "${PUSH_URL}?status=up&msg=Backup+OK+(${BACKUP_SIZE})+w+${DURATION}s&ping=${DURATION_MS}" \
      > /dev/null
else
    curl -fsS -m 10 --retry 3 \
      "${PUSH_URL}?status=down&msg=Backup+FAILED+(exit+code+${BACKUP_EXIT})" \
      > /dev/null
fi

Ten skrypt nie tylko monitoruje, czy backup się wykonał, ale też raportuje rozmiar pliku i czas wykonania do Uptime Kuma. Dzięki parametrowi ping z czasem w milisekundach, na wykresie Response Time w Uptime Kuma zobaczysz historyczny trend czasu trwania backupu — i wykryjesz, jeśli backup zaczyna trwać niepokojąco długo.

Monitoring procesów batch i ETL

Procesy ETL (Extract-Transform-Load) i zadania batch processing to kręgosłup wielu firm — przetwarzanie zamówień, synchronizacja danych między systemami, generowanie raportów, import z hurtowni. Ich awaria często pozostaje niezauważona godzinami lub dniami.

#!/bin/bash
# etl-pipeline.sh — pipeline ETL z monitoringiem push

PUSH_URL="https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"
PROCESSED=0
ERRORS=0

# Etap 1: Extract
python3 /etl/extract.py --source warehouse
[ $? -ne 0 ] && { curl -fsS -m 10 "${PUSH_URL}?status=down&msg=ETL+EXTRACT+FAILED"; exit 1; }

# Etap 2: Transform
python3 /etl/transform.py --validate
[ $? -ne 0 ] && { curl -fsS -m 10 "${PUSH_URL}?status=down&msg=ETL+TRANSFORM+FAILED"; exit 1; }

# Etap 3: Load
PROCESSED=$(python3 /etl/load.py --target production | grep "records" | awk '{print $1}')
[ $? -ne 0 ] && { curl -fsS -m 10 "${PUSH_URL}?status=down&msg=ETL+LOAD+FAILED"; exit 1; }

# Sukces — raportuj liczbę przetworzonych rekordów
curl -fsS -m 10 "${PUSH_URL}?status=up&msg=ETL+OK:+${PROCESSED}+rekordow"

Każdy etap pipeline'u może zgłosić błąd niezależnie — w wiadomości push zobaczysz, który konkretnie etap się nie powiódł. To znacznie przyspiesza diagnozę problemów.

Monitoring zaplanowanych zadań na Windows (Task Scheduler)

Windows Task Scheduler to odpowiednik crona w środowisku Windows. Monitoring jest równie ważny — i równie prosty dzięki PowerShell:

# W Task Scheduler utwórz nowe zadanie, które na końcu wykonuje:
# Program: powershell.exe
# Arguments: -ExecutionPolicy Bypass -File C:\Scripts\backup-with-heartbeat.ps1

# Zawartość backup-with-heartbeat.ps1:
$PushUrl = "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"
$StartTime = Get-Date

try {
    # Twoje zadanie backupowe
    & "C:\Scripts\backup-sqlserver.ps1"

    $Duration = [math]::Round(((Get-Date) - $StartTime).TotalMilliseconds)
    Invoke-RestMethod -Uri "${PushUrl}?status=up&msg=Backup+OK&ping=$Duration" -Method Get
}
catch {
    $ErrorMsg = $_.Exception.Message -replace ' ', '+'
    Invoke-RestMethod -Uri "${PushUrl}?status=down&msg=FAILED:+$ErrorMsg" -Method Get
}

Monitoring urządzeń IoT

Urządzenia IoT (Internet of Things) — czujniki, sterowniki, bramy sieciowe — często działają w trudnych warunkach sieciowych: za NATem, na LTE, z ograniczoną łącznością. Tradycyjny pull monitoring jest często niemożliwy. Push Monitor jest idealnym rozwiązaniem:

# Przykład: ESP32 (MicroPython) wysyłający heartbeat co minutę
import urequests
import time

PUSH_URL = "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"

while True:
    try:
        temp = read_temperature_sensor()
        response = urequests.get(
            f"{PUSH_URL}?status=up&msg=Temp:{temp}C&ping="
        )
        response.close()
    except Exception as e:
        pass  # Brak łączności — Uptime Kuma wykryje brak heartbeatu

    time.sleep(60)  # Heartbeat co 60 sekund

W Uptime Kuma ustaw interwał na 120 sekund (podwójny czas cyklu). Jeśli urządzenie IoT straci łączność na dłużej niż 2 minuty — otrzymasz alert. Dzięki parametrowi msg możesz nawet przesyłać dane telemetryczne (temperaturę, wilgotność, stan baterii) bezpośrednio do interfejsu Uptime Kuma.

Integracja ze skryptami — curl, Python, PowerShell, Docker

Push Monitor w Uptime Kuma akceptuje żądania HTTP GET i POST. Integracja jest trywialna w dowolnym języku programowania i środowisku. Poniżej kompletne przykłady dla najpopularniejszych technologii.

Bash / curl

Najprostszy i najczęściej używany sposób — jedna linia na końcu skryptu:

# Minimalny heartbeat (GET)
curl -fsS -m 10 --retry 3 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=OK" > /dev/null

# Heartbeat z czasem wykonania
START=$(date +%s%N)
# ... twój skrypt ...
END=$(date +%s%N)
PING=$(( (END - START) / 1000000 ))  # nanosekundy → milisekundy
curl -fsS -m 10 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=OK&ping=${PING}"

# Heartbeat z dodatkowym kontekstem (POST z body)
curl -fsS -m 10 -X POST \
  -H "Content-Type: application/json" \
  -d '{"status":"up","msg":"Przetworzone: 1523 rekordów","ping":4521}' \
  "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"

Python (requests)

Idealne dla skryptów Python — ETL, data science, automatyzacja:

import requests
import time

PUSH_URL = "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"

def send_heartbeat(status="up", msg="OK", ping=None):
    """Wyślij heartbeat do Uptime Kuma Push Monitora."""
    params = {"status": status, "msg": msg}
    if ping is not None:
        params["ping"] = int(ping)
    try:
        response = requests.get(PUSH_URL, params=params, timeout=10)
        response.raise_for_status()
    except requests.RequestException as e:
        print(f"Heartbeat failed: {e}")

# Użycie w skrypcie:
start = time.time()
try:
    # Twoja logika biznesowa
    result = process_data()
    duration_ms = int((time.time() - start) * 1000)
    send_heartbeat(
        status="up",
        msg=f"Przetworzono {result['count']} rekordów",
        ping=duration_ms
    )
except Exception as e:
    send_heartbeat(
        status="down",
        msg=f"Błąd: {str(e)[:100]}"
    )

Python — dekorator do automatycznego monitoringu funkcji

Elegancki wzorzec dla wielu monitorowanych zadań:

import requests
import time
import functools

def push_monitor(push_url):
    """Dekorator do automatycznego wysyłania heartbeatu po wykonaniu funkcji."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            start = time.time()
            try:
                result = func(*args, **kwargs)
                duration_ms = int((time.time() - start) * 1000)
                requests.get(push_url, params={
                    "status": "up",
                    "msg": f"{func.__name__} OK",
                    "ping": duration_ms
                }, timeout=10)
                return result
            except Exception as e:
                requests.get(push_url, params={
                    "status": "down",
                    "msg": f"{func.__name__} FAILED: {str(e)[:80]}"
                }, timeout=10)
                raise
        return wrapper
    return decorator

# Użycie:
@push_monitor("https://twoja-instancja.uptimekuma.eu/api/push/TOKEN_BACKUP")
def run_backup():
    # ... logika backupu ...
    pass

@push_monitor("https://twoja-instancja.uptimekuma.eu/api/push/TOKEN_ETL")
def run_etl():
    # ... logika ETL ...
    pass

PowerShell (Windows)

Natywne rozwiązanie dla środowisk Windows Server i Active Directory:

# Prosty heartbeat
$PushUrl = "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"

try {
    # Twoje zadanie
    & "C:\Scripts\maintenance-task.ps1"

    Invoke-RestMethod -Uri "$PushUrl`?status=up&msg=Task+completed" -Method Get -TimeoutSec 10
}
catch {
    $ErrMsg = $_.Exception.Message.Substring(0, [Math]::Min(100, $_.Exception.Message.Length))
    $ErrMsg = $ErrMsg -replace ' ', '+' -replace '&', '%26'
    Invoke-RestMethod -Uri "$PushUrl`?status=down&msg=FAILED:+$ErrMsg" -Method Get -TimeoutSec 10
}

# Wersja z pomiarem czasu (jako Scheduled Task)
$Stopwatch = [System.Diagnostics.Stopwatch]::StartNew()

# ... zadanie ...

$Stopwatch.Stop()
$PingMs = $Stopwatch.ElapsedMilliseconds
Invoke-RestMethod -Uri "$PushUrl`?status=up&msg=OK&ping=$PingMs" -Method Get

Docker Healthcheck — integracja z kontenerami

Docker HEALTHCHECK pozwala zdefiniować komendę sprawdzającą zdrowie kontenera. Połączenie tego z Push Monitorem daje podwójne zabezpieczenie — Docker restartuje kontener, a Uptime Kuma alarmuje:

# Dockerfile
FROM your-app:latest

# Healthcheck wysyła heartbeat do Uptime Kuma
HEALTHCHECK --interval=60s --timeout=10s --retries=3 \
  CMD curl -fsS -m 5 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=Container+healthy" || exit 1

Alternatywnie w docker-compose.yml:

services:
  my-app:
    image: your-app:latest
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-m", "5",
             "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=healthy"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 30s

W tej konfiguracji kontener co 60 sekund wysyła heartbeat do Uptime Kuma. Jeśli kontener się zawiesi, healthcheck nie wykona się, heartbeat przestanie przychodzić — i Uptime Kuma poinformuje Cię o problemie, nawet jeśli Docker nie zdoła zrestartować kontenera.

wget — alternatywa dla curl

Na niektórych systemach curl nie jest zainstalowany, ale wget jest dostępny domyślnie:

# wget jako alternatywa dla curl
wget -q --spider --timeout=10 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=OK"

# W crontab:
0 * * * * /usr/local/bin/myscript.sh && wget -q --spider --timeout=10 "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up" 2>/dev/null

Zaawansowane: wiadomości, status i body w push

Push Monitor w Uptime Kuma obsługuje znacznie więcej niż prosty sygnał „jestem żywy". Parametry status, msg i ping pozwalają na budowanie zaawansowanego monitoringu z bogatym kontekstem.

Parametr status: up vs down

Domyślny push (bez parametru status lub ze status=up) oznacza sukces. Ale możesz też aktywnie zgłosić błąd, wysyłając status=down. To natychmiast przełącza monitor w stan DOWN — nie musisz czekać na upłynięcie interwału:

# Skrypt zgłaszający błąd aktywnie
if ! /usr/local/bin/critical-task.sh; then
    curl -fsS "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=down&msg=Task+failed"
    exit 1
fi
curl -fsS "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=Task+OK"

To kluczowa różnica: bez aktywnego zgłaszania błędu musisz czekać, aż heartbeat interval upłynie. Ze status=down alert jest natychmiastowy.

Parametr msg: kontekst w wiadomości

Parametr msg pozwala przekazać dodatkowy kontekst, który jest widoczny w historii heartbeatów w interfejsie Uptime Kuma. Przydatne zastosowania:

• Rozmiar backupu: msg=Backup+OK+(12.4+GB)
• Liczba przetworzonych rekordów: msg=ETL:+15420+records+processed
• Wersja aplikacji: msg=Deployed+v2.4.1
• Stan zasobów: msg=Disk+usage:+73%25 (uwaga: % musi być zakodowane jako %25 w URL)
• Komunikat błędu: msg=FAILED:+Connection+timed+out

Pamiętaj o kodowaniu URL — spacje zastępuj + lub %20, znaki specjalne koduj odpowiednio. W curl możesz użyć --data-urlencode dla automatycznego kodowania.

Parametr ping: czas wykonania na wykresie

Parametr ping przyjmuje wartość w milisekundach i wyświetla ją na wykresie Response Time w Uptime Kuma — tak samo jak czas odpowiedzi HTTP w pull monitorach. To pozwala na:

• Trend czasu wykonania — widzisz, czy Twój backup trwa coraz dłużej
• Wykrywanie anomalii — nagły skok czasu wykonania może sygnalizować problem (rosnąca baza, pełny dysk, degradacja dysku)
• Planowanie capacity — gdy backup zajmuje 5 godzin z 8 dostępnych, czas na optymalizację lub zwiększenie zasobów

# Pomiar czasu z precyzją milisekundową
START_MS=$(date +%s%3N)
/usr/local/bin/heavy-task.sh
END_MS=$(date +%s%3N)
PING=$((END_MS - START_MS))

curl -fsS "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN?status=up&msg=OK&ping=${PING}"

Push z body (POST request)

Oprócz parametrów URL, Push Monitor akceptuje również żądania POST z body w formacie JSON:

# POST z JSON body
curl -fsS -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "status": "up",
    "msg": "Backup completed: 15.2 GB, 1523 files",
    "ping": 184200
  }' \
  "https://twoja-instancja.uptimekuma.eu/api/push/TOKEN"

POST z body jest wygodniejszy przy dłuższych wiadomościach i eliminuje problemy z kodowaniem URL. Format JSON jest czytelniejszy w kodzie i łatwiejszy do generowania programistycznie.

Alerting — co się dzieje, gdy heartbeat nie przychodzi

Cały sens Push Monitora polega na wykrywaniu braku heartbeatu i szybkim alertowaniu. Oto co dzieje się w Uptime Kuma, gdy heartbeat nie przychodzi:

Sekwencja zdarzeń

Specjalny przypadek: status=down w heartbeat

Warto pamiętać, że alert może nastąpić na dwa sposoby:

• Brak heartbeatu — skrypt się nie wykonał, zawiesił się lub stracił łączność z Uptime Kuma. Alert po upływie interwału + retries
• Heartbeat ze status=down — skrypt się wykonał, ale wykrył błąd i aktywnie zgłosił problem. Alert natychmiastowy, bez czekania na upłynięcie interwału

Kombinacja obu mechanizmów daje kompletne pokrycie: wykrywasz zarówno ciche awarie (skrypt nie wykonał się w ogóle), jak i wykryte błędy (skrypt wykonał się, ale napotkał problem).

Konfiguracja kanałów powiadomień

Push Monitor obsługuje wszystkie 91 kanałów powiadomień dostępnych w Uptime Kuma. Dla monitoringu zadań krytycznych (backupy, procesy biznesowe) zalecamy skonfigurować minimum 2 kanały z eskalacją:

• Pierwszy alert (natychmiast): Telegram / Slack / Discord — szybkie powiadomienie push na telefon
• Eskalacja (po 30 min): E-mail + SMS — jeśli nikt nie zareagował na pierwszy alert
• Krytyczny (po 1h): PagerDuty / OpsGenie — integracja z systemem dyżurów on-call

Best practices — jak skonfigurować push monitoring prawidłowo

Push monitoring jest prosty koncepcyjnie, ale łatwo go źle skonfigurować — zbyt agresywne interwały generują fałszywe alarmy, zbyt luźne opóźniają wykrycie problemów. Oto sprawdzone praktyki.

1. Interwał = cykl zadania × 2 (minimum)

Ustaw heartbeat interval na co najmniej dwukrotność cyklu zadania. Cronjob co 5 minut? Interwał 10 minut. Backup co 24h? Interwał 48h (lub 25-26h, jeśli chcesz szybszą reakcję, ale dodaj retries). Zbyt ciasny interwał + jitter w czasie wykonania = fałszywe alarmy, które prowadzą do ignorowania alertów (alert fatigue).

2. Heartbeat wysyłaj TYLKO po sukcesie

Najczęstszy błąd: heartbeat na końcu skryptu niezależnie od wyniku. Używaj && zamiast ; w crontab. W skryptach sprawdzaj kody wyjścia. Heartbeat powinien być potwierdzeniem sukcesu, nie dowodem uruchomienia. Wyjątek: aktywne zgłaszanie błędu ze status=down — to celowe i wartościowe.

3. Używaj timeout w wywołaniach HTTP

Zawsze ustawiaj timeout dla wywołań heartbeat: curl -m 10, requests.get(..., timeout=10), -TimeoutSec 10 w PowerShell. Bez timeout'u, jeśli Uptime Kuma jest chwilowo niedostępna, Twój skrypt może zawisnąć na minuty, czekając na odpowiedź — co zablokuje cały cronjob.

4. Dodaj retry w wywołaniu heartbeat

Chwilowy problem sieciowy nie powinien powodować fałszywego alarmu. curl --retry 3 --retry-delay 5 ponowi próbę 3 razy z 5-sekundowym odstępem. W Pythonie użyj biblioteki tenacity lub prostego try/except z pętlą.

5. Nazewnictwo monitorów — bądź opisowy

Zamiast „Push Monitor 1" napisz „Backup nocny — MySQL prod — serwer db01". W alertach i na dashboardzie od razu wiesz, co się zepsuło. Stosuj konwencję: [Typ] [Co] — [Gdzie], np. „[Cron] Cleanup logów — srv-web03", „[Backup] PostgreSQL — db-master".

6. Tagowanie i grupowanie monitorów

Używaj tagów Uptime Kuma do kategoryzacji push monitorów: backup, cron, etl, iot. Twórz grupy monitorów per serwer lub per środowisko (production, staging). Ułatwia to filtrowanie na dashboardzie i przypisywanie kanałów powiadomień per grupa.

7. Monitoruj monitor — watchdog pattern

Jeśli Twoja instancja Uptime Kuma przestanie działać, push monitory nie wykryją problemów — bo nie ma kto odebrać heartbeat. Rozwiązanie: skonfiguruj zewnętrzny monitoring samej instancji Uptime Kuma (np. prosty uptime check z innej usługi lub drugiej instancji). Na hostingu zarządzanym SmartXHosting.pl ten problem nie istnieje — monitoring infrastruktury jest po stronie dostawcy.

8. Przechowuj Push URL bezpiecznie

Push URL zawiera token, który pozwala wysyłać heartbeaty do Twojego monitora. Traktuj go jak hasło — przechowuj w zmiennych środowiskowych, secret managerze (Vault, AWS Secrets Manager) lub plikach konfiguracyjnych z ograniczonymi uprawnieniami. Nie commituj tokenów do repozytoriów Git.

# Zamiast hardcoded URL w skrypcie:
# curl "https://instancja/api/push/TOKEN_W_JAWNYM_TEKSCIE"

# Użyj zmiennej środowiskowej:
export UPTIME_KUMA_PUSH_URL="https://instancja/api/push/TOKEN"
# W skrypcie:
curl -fsS -m 10 "${UPTIME_KUMA_PUSH_URL}?status=up&msg=OK"

# Lub z pliku:
PUSH_URL=$(cat /etc/uptime-kuma/backup-monitor.url)
curl -fsS -m 10 "${PUSH_URL}?status=up&msg=OK"

9. Testuj push monitoring po konfiguracji

Po dodaniu Push Monitora zawsze przetestuj cały flow: wyślij ręczny heartbeat (curl z terminala), upewnij się że monitor przechodzi w UP, poczekaj na upłynięcie interwału bez heartbeatu i sprawdź czy alert dochodzi. Jeden test uchroni Cię przed fałszywym poczuciem bezpieczeństwa.

10. Dokumentuj, co jest monitorowane

Utrzymuj listę push monitorów z informacją: co monitorują, na jakim serwerze działa skrypt, jaki jest oczekiwany harmonogram, kto jest odpowiedzialny. Bez dokumentacji push monitory stają się „magicznymi" elementami — nikt nie wie co robią, ale wszyscy boją się ich dotknąć.

Podsumowanie

Push Monitor (Heartbeat) w Uptime Kuma to potężne narzędzie do monitorowania procesów, które są niewidoczne dla tradycyjnego monitoringu aktywnego. Dzięki odwróconej logice — to skrypt wysyła sygnał do Uptime Kuma, nie odwrotnie — możesz monitorować dosłownie każde zadanie, które da się zakończyć wywołaniem HTTP.

Kluczowe wnioski z tego artykułu:

• Push monitoring uzupełnia pull monitoring — oba modele są potrzebne w dobrze zaprojektowanej infrastrukturze
• Dead Man's Switch — brak heartbeatu oznacza problem. Prosta, ale niezwykle skuteczna logika
• Jedno wywołanie HTTP — integracja to dosłownie jedna linia kodu (curl, requests.get(), Invoke-RestMethod)
• Bogaty kontekst — parametry status, msg i ping pozwalają na raportowanie sukcesu/błędu, wiadomości i czasu wykonania
• Uniwersalne zastosowanie — cronjobs, backupy, ETL, Windows Task Scheduler, Docker healthcheck, urządzenia IoT
• Natychmiastowy alert — ze status=down nie musisz czekać na upłynięcie interwału
• Best practices — odpowiedni interwał, heartbeat tylko po sukcesie, timeout, retry, bezpieczne przechowywanie tokenów

Push Monitor jest jedną z tych funkcji, które wydają się proste — bo takie są. Ale ich wartość jest ogromna. Ile razy backup nie wykonał się w nocy i nikt o tym nie wiedział? Ile razy cronjob cicho przestał działać? Push monitoring w Uptime Kuma eliminuje te scenariusze — za cenę jednej linii kodu na końcu skryptu.

Najczęściej zadawane pytania