# Heartbeat — Monitoring cron

> Twoje crony działają? Heartbeat pilnuje za Ciebie

Dead man's switch dla zadań cron i procesów w tle. Każdy heartbeat ma unikalny URL do pingowania — jeśli ping nie przyjdzie w oczekiwanym czasie, status zmienia się na "down".

## Funkcje

- **Dead man's switch**: Heartbeat oczekuje pingu w zadanym interwale. Brak pingu = alarm. Prosta i niezawodna zasada.
- **Unikalne URL-e pingowania**: Każdy heartbeat generuje token (hb_*). Twój cron job pinguje GET lub POST na /hb/{token}.
- **Period + grace**: Oczekiwany interwał (period) + dodatkowa tolerancja (grace) na opóźnienia sieciowe i zegar.
- **Trzy statusy**: pending (brak pingów), up (ping w terminie), down (przekroczony deadline). Status obliczany on-demand.
- **Limit 50 per projekt**: Wystarczająco dla nawet rozbudowanych systemów z wieloma zadaniami.
- **Edycja bez utraty historii**: Zmień nazwę, period lub grace bez resetowania ostatniego pingu i statusu.

## Jak to działa

1. **Utwórz heartbeat**: Podaj nazwę (np. "Backup nocny"), oczekiwany interwał (np. 60 min) i grace (np. 5 min).
2. **Skopiuj URL pingowania**: System generuje unikalny URL: /hb/hb_abc123xyz. Pokaże Ci przykład konfiguracji cURL i crontab.
3. **Dodaj ping do zadania cron**: Na końcu skryptu dodaj: curl -s https://your-instance/hb/hb_abc123xyz
4. **Monitoruj status**: Dashboard pokazuje status: zielony (up), czerwony (down), szary (pending). Badge w sidebarze liczy heartbeaty "down".

## AI i MCP

Agent AI może sprawdzać status heartbeatów, tworzyć nowe i modyfikować konfigurację — 5 narzędzi MCP.

- `list_heartbeats`: Wszystkie heartbeaty z obliczonym statusem
- `get_heartbeat`: Szczegóły z URL pingowania, period/grace, status
- `create_heartbeat`: Nowy heartbeat z nazwą, period i grace (w minutach)
- `update_heartbeat`: Zmień nazwę, period lub grace
- `delete_heartbeat`: Usuń heartbeat

## Szczegóły techniczne

- **Token**: Format hb_ + 16 znaków URL-safe base64. Unikalne w ramach bazy danych.
- **Status**: Obliczany on-demand: elapsed_time = now - last_ping_at. Jeśli elapsed > period + grace → down.
- **Ping endpoint**: GET/POST /hb/{token}. Publiczny endpoint — nie wymaga autoryzacji. Aktualizuje last_ping_at.
- **Przechowywanie**: period i grace przechowywane w sekundach w bazie, konwertowane do/z minut w UI.