Rejestracja i komunikacja z kontrolerem

Agent komunikuje się z kontrolerem przez połączenie WebSocket (WSS) na port kontrolera 44443. Połączenie jest zawsze inicjowane przez agenta, co pozwala na komunikację w przypadku gdy agent schowany jest za NATem.

Rejestracja agenta

Podczas rejestracji agent wysyła do kontrolera informacje identyfikujące agenta min. identyfikator instancji agenta generowany podczas pierwszego uruchomienia, nazwę agenta, wersję oraz adres IP. W celu rejestracji agenta należy zalogować się na jego interfejs graficzny https://<adres_ip_agenta>/.

Do rejestracji konieczne jest wypełnienie poniższych dwóch pól formularza rejestracyjnego:

Komunikacja z kontrolerem po rejestracji

Po udanej rejestracji agent utrzymuje stałe połączenie WebSocket z kontrolerem. Kontroler sprawdza, czy dla danego agenta istnieją zadania do uruchomienia — dotyczy to zadań w statusach pending, sent lub running.

Jeżeli zadanie powinno działać na tym agencie, kontroler wysyła do niego komunikat create_job. Agent uruchamia odpowiedni typ zadania, np. ICMP, HTTP Timing, UDP Trace, Speedtest albo TCP Port Monitor, a następnie potwierdza start zadania komunikatem job_started. Po stronie kontrolera zadanie przechodzi wtedy w status running.

Agent cyklicznie wysyła do kontrolera heartbeat — krótki komunikat potwierdzający, że nadal działa i ma aktywną komunikację z kontrolerem. Domyślnie heartbeat jest wysyłany co 30 sekund.

Po odebraniu heartbeatu kontroler aktualizuje czas ostatniego kontaktu z agentem (last_heartbeat) i odsyła potwierdzenie heartbeat_ack. Kontroler uznaje agenta za offline, jeżeli przez 60 sekund nie otrzyma od niego heartbeatu. Mechanizm sprawdzający działa cyklicznie, dlatego w praktyce status offline może pojawić się po około 60-70 sekundach od utraty komunikacji.

Utrata komunikacji

Jeżeli agent utraci połączenie z kontrolerem, po stronie agenta lokalnie zatrzymywane są uruchomione zadania. Agent czyści też tymczasowe bufory pomiarów, aby nie gromadzić danych bez końca podczas długiej awarii połączenia. Następnie agent próbuje automatycznie połączyć się ponownie z kontrolerem. Opóźnienie między kolejnymi próbami zaczyna się od 1 sekundy i podwaja się po każdym nieudanym połączeniu (1 s → 2 s → 4 s → 8 s → …), maksymalnie do 60 sekund. Po udanym połączeniu opóźnienie wraca do 1 sekundy.

Po stronie kontrolera brak heartbeatów powoduje oznaczenie agenta jako offline. Aktywne zadania tego agenta w statusach running, sent lub pending są automatycznie przenoszone do statusu auto_paused z powodem agent_offline. Dzięki temu kontroler wie, że zadania nie zostały zatrzymane ręcznie przez użytkownika, tylko z powodu utraty komunikacji z agentem. W ustawieniach kontrolera można włączyć auto-resume, aby automatycznie wznawiać zadania w statusie auto_paused po powrocie agenta do statusu online.

Powrót agenta online

Gdy agent odzyska połączenie, ponownie rejestruje się w kontrolerze używając swojego identyfikatora AIID.

Kontroler aktualizuje jego status z powrotem na registered. Jeżeli w ustawieniach włączone jest automatyczne wznawianie zadań po powrocie agenta, zadania w statusie auto_paused zostają przeniesione z powrotem do pending.

Następnie kontroler ponownie wysyła je do agenta. Agent uruchamia zadania i odsyła job_started, po czym zadania wracają do statusu running.

Wyrejestrowanie agenta

Agenta można wyrejestrować na dwa sposoby: z poziomu kontrolera lub z poziomu agenta.

Wyrejestrowanie z poziomu agenta wysyła do kontrolera komunikat unregister. Agent zachowuje swój identyfikator AIID w lokalnym storage, co umożliwia ponowną rejestrację tego samego agenta.

Wyrejestrowanie z poziomu kontrolera powoduje odrzucenie ponownej rejestracji agenta z tym samym AIID (unregistered_by_controller). Aby przywrócić możliwość rejestracji z tej samej maszyny, na której hostowany jest kontener agenta, należy usunąć kontener i uruchomić go od nowa — agent wygeneruje wtedy nowy identyfikator instancji.

W ustawieniach kontrolera (Settings → Tasks, sekcja Agent Automation) można skonfigurować powiązane automatyzacje: Archive on agent unregister archiwizuje zadania przypisane do agenta po wyrejestrowaniu (domyślnie włączone), a Delete on agent delete trwale usuwa zadania przy usunięciu agenta z kontrolera (domyślnie wyłączone).

Komunikaty błędów