Monitoring HTTP(s) w Uptime Kuma — metody, nagłówki, autentykacja

Dlaczego monitoring HTTP(s) to fundament monitoringu webowego

Monitoring HTTP(s) to najbardziej uniwersalny i najczęściej stosowany typ monitorowania w świecie IT. Ponad 90% usług internetowych komunikuje się przez protokół HTTP lub HTTPS — od stron wizytówkowych po złożone API mikrousługowe, panele administracyjne, sklepy e-commerce i endpointy health check. Jeśli Twoja usługa jest dostępna przez przeglądarkę lub odpowiada na zapytania REST — monitoring HTTP(s) jest tym, od czego powinieneś zacząć.

Prosty ping (ICMP) powie Ci tylko, czy serwer odpowiada na poziomie sieciowym. Sprawdzenie portu TCP potwierdzi, że usługa nasłuchuje. Ale dopiero zapytanie HTTP pozwala zweryfikować, że aplikacja faktycznie działa poprawnie — zwraca właściwy kod statusu, serwuje poprawną treść i odpowiada w akceptowalnym czasie. To różnica między informacją „serwer jest online" a informacją „strona działa i klienci mogą z niej korzystać".

Uptime Kuma oferuje jeden z najbardziej rozbudowanych monitorów HTTP(s) wśród narzędzi open-source — wszystkie metody HTTP, custom headers, request body, pięć metod autentykacji, walidację SSL/TLS, keyword monitoring, JSON Query z JSONata, konfigurowalny timeout i retry. W tym przewodniku pokażemy krok po kroku, jak wykorzystać pełen potencjał tego monitora.

Podstawy monitora HTTP(s) w Uptime Kuma

Dodanie monitora HTTP(s) w Uptime Kuma to proces, który zajmuje dosłownie kilka minut. Po zalogowaniu do panelu kliknij przycisk „Add New Monitor" w lewym górnym rogu dashboardu i wybierz typ HTTP(s), HTTP(s) - Keyword lub HTTP(s) - JSON Query z rozwijanej listy.

Konfiguracja podstawowa

Te cztery parametry wystarczą do uruchomienia podstawowego monitoringu HTTP(s). Ale prawdziwa moc Uptime Kuma ujawnia się w opcjach zaawansowanych — metodach HTTP, headerach, autentykacji i walidacji odpowiedzi.

Metody HTTP — GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

Domyślnie Uptime Kuma wykonuje zapytanie GET, co jest odpowiednie dla większości scenariuszy — sprawdzania stron internetowych, endpointów health check i prostych API. Jednak w zaawansowanych przypadkach możesz potrzebować innej metody HTTP. Uptime Kuma obsługuje siedem metod:

Praktyczne scenariusze doboru metody

HEAD zamiast GET: Jeśli interesuje Cię tylko kod statusu i czas odpowiedzi — użyj HEAD. Mniejszy transfer, szybsza odpowiedź, mniejsze obciążenie serwera.

POST do testowania API GraphQL: API GraphQL przyjmują zapytania wyłącznie przez POST z body JSON. Skonfiguruj monitor POST z headerem Content-Type: application/json.

OPTIONS do weryfikacji CORS: Zapytanie OPTIONS (preflight) weryfikuje, że nagłówki CORS są poprawnie skonfigurowane — kluczowe dla aplikacji SPA.

Custom headers — User-Agent, Accept, Authorization i inne

Nagłówki HTTP (headers) to metadane dołączane do zapytania, które informują serwer o oczekiwaniach klienta, formacie danych, tożsamości i uprawnieniach. W Uptime Kuma możesz dodawać dowolne nagłówki HTTP do monitora — w formularzu konfiguracji znajdziesz pole „Custom Headers" przyjmujące obiekt JSON.

Format nagłówków

Nagłówki definiujesz jako obiekt JSON — klucze to nazwy nagłówków, wartości to ich treść:

{
  "User-Agent": "UptimeKuma/2.1 MonitorBot",
  "Accept": "application/json",
  "Accept-Language": "pl-PL",
  "X-Custom-Header": "monitoring-check"
}

Najczęściej używane nagłówki

Scenariusze użycia custom headers

Zmiana User-Agent: Niektóre WAF-y blokują zapytania z nietypowymi User-Agentami. Jeśli monitor zwraca 403 Forbidden, ustaw User-Agent na standardowy:

{
  "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

Nagłówek autentykacji API: Wiele API wymaga klucza w nagłówku — przez Authorization lub dedykowany header:

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Accept": "application/json"
}

Request body dla POST, PUT i PATCH

Gdy wybierzesz metodę POST, PUT lub PATCH, Uptime Kuma udostępnia pole „Body", w którym możesz wpisać treść zapytania. Najczęściej jest to obiekt JSON, ale możesz wysłać również dane form-urlencoded, XML lub dowolny tekst — pod warunkiem ustawienia odpowiedniego nagłówka Content-Type.

Przykład: body JSON dla API health check

{
  "checks": ["database", "cache", "queue"],
  "verbose": true
}

W nagłówkach ustaw Content-Type: application/json i Accept: application/json.

Przykład: zapytanie GraphQL

{
  "query": "{ systemHealth { status database cache } }",
  "variables": {}
}

W połączeniu z monitorem JSON Query możesz walidować, czy pole status w odpowiedzi ma wartość "healthy".

Przykład: form data

Dla endpointów wymagających application/x-www-form-urlencoded:

grant_type=client_credentials&client_id=my-app&client_secret=secret123

Autentykacja — Basic, Bearer, OAuth2, NTLM, mTLS

Monitorowanie usług zabezpieczonych autentykacją to jedno z najczęstszych wyzwań w monitoringu HTTP. Uptime Kuma obsługuje pięć metod autentykacji natywnie — bez konieczności stosowania obejść czy zewnętrznych proxy. To więcej niż oferuje większość konkurencyjnych narzędzi, w tym wiele płatnych rozwiązań SaaS.

Basic Authentication

HTTP Basic Auth to najprostszy mechanizm autentykacji — login i hasło zakodowane w Base64 w nagłówku Authorization. Konfiguracja w Uptime Kuma:

Zastosowania: panele administracyjne zabezpieczone htpasswd (Apache/Nginx), prostsze API wewnętrzne, serwery monitoringu (Prometheus, Grafana), routery i urządzenia sieciowe z interfejsem webowym.

Bearer Token / API Key

Bearer Token to popularna metoda autentykacji API, w której klient przesyła token (JWT, API key, personal access token) w nagłówku Authorization. W Uptime Kuma możesz go przekazać na dwa sposoby:

Sposób 1 — przez custom headers:

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
}

Sposób 2 — przez sekcję Authentication: Wybierz metodę autentykacji w ustawieniach monitora i wklej token. Uptime Kuma automatycznie doda go jako nagłówek Authorization: Bearer .

Zastosowania: API REST z tokenami JWT, GitHub API (personal access tokens), Slack API, Stripe API, OpenAI API, Azure DevOps, Cloudflare API — praktycznie każde nowoczesne API komercyjne.

OAuth2 Token

OAuth2 to standard autoryzacji używany przez Google, Microsoft, AWS, Salesforce. W scenariuszu Client Credentials (machine-to-machine) konfiguracja wymaga:

• Authentication Method — wybierz OAuth2: CC (Client Credentials)
• Client ID — identyfikator aplikacji (np. my-monitoring-app)
• Client Secret — sekret aplikacji
• OAuth Token URL — endpoint serwera autoryzacji (np. https://auth.example.com/oauth2/token)
• OAuth Scopes — opcjonalne zakresy uprawnień (np. read:health)

Uptime Kuma automatycznie pobiera access token, cache'uje go i odnawia po wygaśnięciu. Działa z Keycloak, Auth0, Azure AD (Entra ID), Okta, AWS Cognito i innymi providerami OAuth2.

NTLM Authentication

NTLM (NT LAN Manager) to protokół autentykacji Microsoftu, stosowany w IIS, SharePoint, Exchange i aplikacjach .NET. Uptime Kuma obsługuje NTLM natywnie — wybierz metodę NTLM, podaj Username (DOMAIN\user), Password i opcjonalnie Domain/Workstation.

mTLS — Mutual TLS (certyfikaty klienckie)

Mutual TLS (mTLS) to najbezpieczniejsza metoda autentykacji HTTP — obie strony prezentują certyfikaty X.509 i wzajemnie się weryfikują. Konfiguracja w Uptime Kuma:

• Cert (PEM) — certyfikat klienta w formacie PEM (lub ścieżka do pliku .pem / .crt)
• Key (PEM) — klucz prywatny klienta w formacie PEM (lub ścieżka do pliku .key)
• CA Bundle (PEM) — opcjonalny pakiet CA (jeśli serwer używa prywatnego CA, np. wewnętrznego PKI)

Zastosowania: architektura zero-trust, service mesh (Istio, Linkerd), API bankowe (PSD2), Kubernetes z wzajemną autentykacją podów, systemy IoT.

Weryfikacja SSL/TLS i certyfikaty

Każdy monitor HTTPS w Uptime Kuma automatycznie weryfikuje certyfikat SSL/TLS serwera. Jeśli certyfikat jest nieważny, wygasł, jest samopodpisany lub łańcuch certyfikatów jest niepełny — monitor zgłosi błąd. To domyślne i bezpieczne zachowanie, ale Uptime Kuma oferuje kilka opcji dostosowania.

Opcja „Ignore TLS/SSL error"

W konfiguracji monitora znajdziesz przełącznik „Ignore TLS/SSL error" — po włączeniu Uptime Kuma zaakceptuje dowolny certyfikat, nawet wygasły, samopodpisany lub z nieprawidłowym CN/SAN. Ta opcja jest przydatna w następujących scenariuszach:

• Środowiska deweloperskie i testowe z certyfikatami samopodpisanymi (self-signed)
• Sieci wewnętrzne z prywatnym CA (wewnętrzne PKI), którego certyfikatu root nie ma w systemowym trust store
• Tymczasowy monitoring usługi z wygasłym certyfikatem (by śledzić dostępność niezależnie od problemu z certyfikatem)
• Starsze systemy z przestarzałymi certyfikatami, które nie mogą być szybko zaktualizowane

Monitoring wygaśnięcia certyfikatu SSL

Uptime Kuma automatycznie odczytuje datę wygaśnięcia certyfikatu SSL dla każdego monitora HTTPS i wyświetla ją w panelu. Możesz skonfigurować alert przed wygaśnięciem certyfikatu — domyślne progi to 7, 14 lub 21 dni przed datą wygaśnięcia. Dzięki temu otrzymasz powiadomienie z wyprzedzeniem, nawet jeśli automatyczne odnawianie certyfikatu (Let's Encrypt, Certbot) zawiedzie.

Informacja o certyfikacie SSL (issuer, daty ważności, days remaining, fingerprint SHA-256) jest widoczna w panelu monitora i opcjonalnie na stronach statusu.

Walidacja kodów statusu HTTP

Jednym z najważniejszych aspektów monitoringu HTTP jest walidacja kodu statusu odpowiedzi. Uptime Kuma umożliwia precyzyjne określenie, jakie kody HTTP uznaje za poprawne (UP) — domyślnie akceptowane są kody z zakresu 200–299.

Konfiguracja akceptowanych kodów

W polu „Accepted Status Codes" możesz wybrać:

• Pojedyncze kody: np. 200, 201, 204, 301, 401
• Zakresy: np. 200-299, 200-399
• Mieszane: np. 200-204, 301, 302

Kiedy zmienić domyślne kody

Domyślnie Uptime Kuma podąża za przekierowaniami (follow redirects), więc w większości przypadków otrzymasz finalny kod 200. Jeśli wyłączysz follow redirects — dodaj kody 3xx do listy akceptowanych.

Keyword monitoring — szukaj tekstu w odpowiedzi

Monitor HTTP(s) - Keyword rozszerza standardowy monitoring HTTP o sprawdzenie, czy odpowiedź serwera zawiera (lub nie zawiera) określony ciąg znaków. To potężna funkcja, która wykracza poza proste sprawdzenie kodu statusu — pozwala zweryfikować, że strona serwuje poprawną treść.

Dlaczego sam kod 200 nie wystarczy?

Istnieje wiele sytuacji, w których serwer zwraca kod 200 OK, ale treść strony jest niepoprawna:

• Defacement — strona została zhakowana i wyświetla inną treść (ale serwer wciąż zwraca 200)
• Błąd aplikacji — framework zwraca stronę z komunikatem „Internal Error" z kodem 200 (częste w PHP, WordPress)
• Pustą stronę — aplikacja nie renderuje treści, ale serwer WWW odpowiada 200
• Strona CDN/cache — CDN serwuje starą wersję strony po awarii origin
• Maintenance mode — CMS wyświetla stronę „w przerwie technicznej" z kodem 200

Konfiguracja keyword monitora

Po wybraniu typu HTTP(s) - Keyword pojawią się dodatkowe pola:

• Keyword — ciąg znaków do wyszukania w treści odpowiedzi
• Keyword should — wybór: exist (tekst musi istnieć) lub not exist (tekst nie może istnieć)
• Case Sensitive — czy wyszukiwanie ma rozróżniać wielkość liter

Przykłady praktyczne

Sprawdzenie, czy strona wyświetla właściwą treść:

Keyword: "Witamy na naszej stronie"
Keyword should: exist

Wykrycie defacement lub podmienionej treści:

Keyword: "Hacked by"
Keyword should: not exist

Weryfikacja, że sklep wyświetla produkty:

Keyword: "Dodaj do koszyka"
Keyword should: exist

Sprawdzenie, że strona nie jest w maintenance mode:

Keyword: "Przerwa techniczna"
Keyword should: not exist

Monitoring dostępności konkretnego produktu:

Keyword: "Dostępny"
Keyword should: exist

JSON Query monitoring — walidacja pól JSON

Monitor HTTP(s) - JSON Query to najbardziej zaawansowany wariant monitora HTTP w Uptime Kuma. Wyciąga konkretną wartość z odpowiedzi JSON za pomocą składni JSONata i porównuje ją z oczekiwaną wartością. Jeśli się zgadzają — monitor UP; jeśli nie — DOWN.

Konfiguracja

• JSON Query — wyrażenie JSONata do wyciągnięcia wartości (np. status, data.health, services[0].status)
• Expected Value — oczekiwana wartość zwrócona przez query (np. "ok", true, 200)

Przykłady JSONata

Prosty klucz na najwyższym poziomie:

Odpowiedź API:

{
  "status": "healthy",
  "version": "2.1.0",
  "uptime": 99.98
}

Konfiguracja:

JSON Query: status
Expected Value: healthy

Zagnieżdżony klucz:

Odpowiedź API:

{
  "data": {
    "database": { "status": "ok", "latency_ms": 12 },
    "cache": { "status": "ok", "latency_ms": 2 },
    "queue": { "status": "degraded", "pending": 1503 }
  }
}

Konfiguracja:

JSON Query: data.database.status
Expected Value: ok

Element tablicy:

Odpowiedź API:

{
  "checks": [
    { "name": "web", "alive": true },
    { "name": "db", "alive": true }
  ]
}

Konfiguracja:

JSON Query: checks[0].alive
Expected Value: true

Wyrażenie warunkowe JSONata:

JSONata obsługuje wyrażenia logiczne i matematyczne. Na przykład możesz sprawdzić, czy wszystkie serwisy w tablicy mają status „ok":

JSON Query: $count(checks[alive=false]) = 0
Expected Value: true

Lub czy czas odpowiedzi bazy danych nie przekracza progu:

JSON Query: data.database.latency_ms < 100
Expected Value: true

Czas odpowiedzi — progi i alerty

Uptime Kuma mierzy czas odpowiedzi (response time) w milisekundach i wyświetla go na wykresie w czasie rzeczywistym. Próg „Response Time Threshold" pozwala oznaczyć degradację — po przekroczeniu wartości na wykresie pojawia się żółty pasek zamiast zielonego (nie generuje alertu DOWN).

Rekomendowane progi

Czas odpowiedzi mierzony przez Uptime Kuma obejmuje pełny cykl zapytania HTTP (TCP + TLS + request + response), dlatego wartości mogą być wyższe niż samo przetwarzanie po stronie serwera.

Timeout i retry — eliminacja fałszywych alarmów

Prawidłowa konfiguracja timeout i retry to klucz do eliminacji fałszywych alarmów (false positives).

Request Timeout

Request Timeout (domyślnie 48 sekund) to maksymalny czas oczekiwania na odpowiedź. Zalecenia: strony i proste API — 10–15 s, ciężkie API z przetwarzaniem — 30–60 s, usługi w sieci LAN — 5–10 s.

Max Retries i Retry Interval

Max Retries (domyślnie 0) to liczba dodatkowych prób po nieudanym zapytaniu. Retry Interval — czas między próbami. Zalecenia: usługi krytyczne — 2–3 retries, 20–60 s, standardowe — 1–2 retries, 60 s, szybka detekcja — 0–1 retry, 20 s (wyższe ryzyko false positive).

Mechanizm „Resend Notification"

Uptime Kuma oferuje Resend Notification — ponowne wysłanie powiadomienia DOWN w ustalonych interwałach (np. co 5 minut), dopóki problem nie zostanie rozwiązany. Zabezpiecza przed przeoczeniem pierwszego alertu.

Monitoring za CDN — omijanie cache

Monitorowanie stron za CDN (Cloudflare, Fastly, CloudFront) wymaga uwagi — CDN cache'uje odpowiedzi, więc Uptime Kuma może otrzymywać odpowiedź z cache nawet gdy origin jest niedostępny.

Metody omijania cache CDN

1. Nagłówek Cache-Control:

{
  "Cache-Control": "no-cache, no-store, must-revalidate",
  "Pragma": "no-cache"
}

Te nagłówki instruują CDN, by nie serwował odpowiedzi z cache i przekazał zapytanie do serwera origin. Skuteczność zależy od konfiguracji CDN — niektóre konfiguracje ignorują te nagłówki klienta.

2. Unikalne parametry query string:

Dodaj losowy lub zmieniający się parametr do URL, np.:

https://example.com/health?_monitor=uptime-kuma&nocache=1

CDN traktuje każdy unikalny URL jako oddzielny zasób i nie serwuje cache'owanej odpowiedzi. To najprostsze i najskuteczniejsze rozwiązanie.

3. Dedykowany endpoint health check:

Najlepsza praktyka — stwórz dedykowany endpoint (np. /health lub /api/status), który:

• Jest wyłączony z cache CDN (reguła „Cache Bypass" w Cloudflare/Fastly)
• Wykonuje rzeczywiste sprawdzenia (baza danych, cache, kolejka)
• Zwraca JSON z informacjami o stanie komponentów
• Ma krótki czas odpowiedzi (nie generuje ciężkiego HTML-a)

4. Monitorowanie serwera origin bezpośrednio:

Jeśli znasz adres IP serwera origin, możesz monitorować go bezpośrednio (z pominięciem CDN), dodając nagłówek Host:

URL: https://203.0.113.10/health
Custom Headers:
{
  "Host": "example.com"
}

Serwer origin odpowie tak, jakby zapytanie przyszło na example.com, ale CDN nie jest w ścieżce. Uwaga: wymaga to, by serwer origin akceptował połączenia bezpośrednie.

Monitoring endpointów API z custom payloadami

Dzięki obsłudze custom headers, body, autentykacji i JSON Query możesz monitorować praktycznie dowolne API. Oto typowe scenariusze:

Scenariusz 1: REST API health check z Bearer Token

Scenariusz 2: GraphQL API z mutacją testową

Zapytanie { __typename } to minimalne zapytanie GraphQL, które zawsze zwraca "Query" — idealne do sprawdzenia, czy serwer GraphQL odpowiada poprawnie, bez obciążania go ciężkimi operacjami.

Scenariusz 3: Monitoring z OAuth2 Client Credentials

Wskazówki dotyczące wydajności

Przy dziesiątkach lub setkach monitorów HTTP optymalizacja staje się kluczowa:

• Używaj HEAD zamiast GET, gdy to możliwe — jeśli nie potrzebujesz keyword ani JSON Query, metoda HEAD zwraca tylko nagłówki, bez body. Mniejszy transfer, krótszy czas odpowiedzi, mniejsze obciążenie.
• Monitoruj dedykowane endpointy /health — lekki JSON ({"status":"ok"}) jest znacznie szybszy niż pełna strona główna z obrazami, CSS i JavaScript.
• Dostosuj interwał do ważności usługi — krytyczne usługi produkcyjne (20–60 s), standardowe (120–300 s), mniej ważne (300–600 s). Zmniejszysz obciążenie serwera.
• Unikaj monitorowania zasobów statycznych przez CDN — monitorowanie obrazu na CDN mierzy dostępność CDN, nie Twojego serwera. Monitoruj endpoint backendu.
• Grupuj monitory logicznie — zamiast 10 monitorów dla jednej aplikacji, utwórz 2–3 kluczowe (health check, strona główna, endpoint biznesowy).
• Ustaw odpowiedni timeout — domyślne 48 sekund to zbyt dużo. Ustaw 10–15 sekund dla stron i API.
• Dla 200+ monitorów rozważ MariaDB — SQLite przy dużej liczbie współbieżnych zapisów może stać się wąskim gardłem.

Podsumowanie

Monitor HTTP(s) w Uptime Kuma to jedno z najpotężniejszych narzędzi monitoringu webowego w segmencie open-source — 7 metod HTTP, custom headers i body, 5 metod autentykacji (Basic, Bearer, OAuth2, NTLM, mTLS), weryfikacja SSL/TLS, keyword monitoring, JSON Query z JSONata, konfigurowalny timeout i retry. Wszystko to w przejrzystym interfejsie, bez pisania kodu.

Niezależnie od tego, czy monitorujesz prostą stronę wizytówkową, sklep e-commerce za Cloudflare, API REST z tokenem JWT, czy enterprise API zabezpieczone OAuth2 i mTLS — Uptime Kuma ma narzędzia do precyzyjnego i niezawodnego monitoringu.

Najczęściej zadawane pytania