Obiekty i zależności pomiędzy nimi

W tym dokumencie opisane są najważniejsze rodzaje obiektów występujących w API, powiązania między nimi oraz uprawnienia do nich.

Użytkownicy i konta

Każdy użytkownik systemu posiada konto ("account"). Konto zawiera informacje takie jak login, hasło, nazwę użytkownika czy informacje o limitach, a także preferowany język powiadomień i raportów okresowych (ze słownika languages). Dodatkowo każde konto posiada stowarzyszony obiekt danych właściciela ("user_data"), o takim samym identyfikatorze co konto. Obiekt ten zawiera np. dane kontaktowe i ustawienia filtra adresów IP mających dostęp do API. Jest widoczny jedynie dla właściciela konta.

Konto można zarejestrować za pomocą wywołania POST /accounts/register i kliknięcia w link aktywacyjny w otrzymanej wiadomości e-mail. Tą metodą można zakładać konta z jednym z pakietów oznaczonych jako dostępne dla nowych kont. Konto może także zostać założone bezpośrednio przez administratora (POST /admin/accounts) lub jako konto dodatkowego użytkownika istniejącego konta (POST /accounts).

Usługi monitoringu i ich typy

Aby skorzystać z systemu monitoringu, należy utworzyć jedną lub więcej usług ("services"). Każda usługa należy do dokładnie jednego konta, nazywanego jej właścicielem ("owner"). Każda usługa jest określonego typu ("service_type"); np. typ "http" odpowiada usłudze monitoringu strony WWW, a typ "dns" usłudze weryfikującej działanie serwerów DNS. Dostępne typy usług mogą różnić się w zależności od konta. Nie jest możliwa zmiana typu istniejącej usługi. Każdy typ należy do jednej z kategorii, wpływającej na dostępność stacji monitorujących dla usług tego typu (np. nie wszystkie stacje obsługują sprawdzanie po IPv6 lub sprawdzanie aplikacji mobilnych).

Monitoring usługi może być włączony lub wyłączony - decyduje o tym jej atrybut is_active. Częstotliwość wykonywania sprawdzeń można zmienić za pomocą atrybutu interval.

Monitorowane adresy

Atrybut address usługi określa adres strony lub usługi, którą należy monitorować w ramach tej usługi. W zależności od typu może to być na przykład:

adres URL - np. dla usług Http czy FullPage,
domena serwera - np. dla usług SMTP,
adres IP np. dla usług Ping.

Adres należy określić z pominięciem "prefiksu protokołu" zależnego od typu usługi, określonego w jego atrybucie address_prefix. Na przykład dla typu FullPageHttps prefiksem jest https://, więc aby uruchomić monitoring strony https://monit24.pl, w polu address usługi należy ustawić po prostu monit24.pl (bez https://).

Zaawansowane ustawienia usług

Poza podstawowymi ustawieniami (takimi jak nazwa, monitorowany adres, czy częstotliwość wykonywania sprawdzeń), każda usługa posiada atrybut rozszerzonych ustawień ("extended_settings"). Atrybuty tego obiektu zależą od typu usługi - na przykład dla typu "http" dostępne jest ustawienie "metoda HTTP", które nie miałoby sensu dla usługi typu "ping". O tym, jakie ustawienia są dostępne dla danego typu (i jakie mogą przyjmować wartości) decyduje tablica obiektów "extended_setting_formats" stowarzyszona z typem usługi. Dla wybranego typu można ją pobrać za pomocą zapytania GET /service_types/{_id}/extended_setting_formats; można ją także dowiązać do typu lub samej usługi. Na jej podstawie można w zautomatyzowany sposób renderować interfejs (pole formularza) do edycji każdego z ustawień.

Scenariusze

Sprawdzenia niektórych z usług polegają na wykonaniu kliku następujących po sobie kroków. Takie usługi nazywają się "scenariuszami". Można je rozpoznać po tym, że ich atrybut path_steps zawiera tablicę nazw kolejnych kroków, zaczynając od pierwszego (dla usług nie będących scenariuszami ma on wartość null). Dla scenariuszy niektóre informacje związane z wynikami sprawdzeń są dostępne z podziałem na kroki:

dane do wykresów szybkości działania - GET /services/{_id}/history/performance/steps
czas przejścia i rozmiar pobranych danych dla poszczególnych kroków wybranym sprawdzeniu usługi - GET /services/{_id}/history/analyses/{_analysis_id}/checks/{_sensor_id}/details, pole step_data

W przypadku awarii scenariusza szczegółowe informacje o awarii oraz powiadomienia zawierają dodatkową informację o kroku, na którym wystąpił problem.

Archiwum usług

Od wersji API 3.8 dostępna jest funkcja archiwizacji usług. Do archiwizacji i przywracania usług z archiwum służą operacje POST /services/{_id}/archive oraz POST /services/{_id}/restore. Atrybut is_archived usługi mówi o tym, czy jest ona zarchiwizowana.

Monitoring zarchiwizowanych usług jest zatrzymany, nie można ich edytować (w tym także włączyć monitoringu), dostępne jest jedynie przeglądanie historii ich działania. Zarchiwizowane usługi nie wliczają się do zużycia limitów określonych w pakiecie konta.

Grupy usług

Każda usługa należy do dokładnie jednej grupy usług ("group"). Grupy, podobnie jak usługi, mają właścicieli ("owner"). Właściciel grupy jest także właścicielem wszystkich usług do niej należących.

Ponadto każde konto posiada jedną wyróżnioną grupę, zwaną grupą domyślną ("default group"). Grupy domyślnej nie można zmienić na inną ani usunąć.

Do grupy są przypisane stacje monitorujące (atrybut assigned_sensor_ids grupy, każda grupa ma osobne listy stacji dla każdej kategorii typów usług), a także adresy powiadomień i raportów. Oznacza to, że wszystkie usługi danej kategorii w grupie co do zasady są monitorowane z tych samych stacji monitorujących, zaś powiadomienia dla nich są wysyłane na te same adresy (dla pojedynczych usług można jedynie decydować, które kanały powiadomień mają być aktywne). Ograniczenia te nie dotyczą nowej wersji raportów (zasobów /reports i /report_templates) oraz podsystemu powiadamiania o zdarzeniach. Można także przypisać stacje monitorujące bezpośrednio do usługi (atrybut sensor_ids usługi), wówczas nadpisują one stacje monitorujące przypisane do grupy.

Limity konta

Każde z kont posiada ograniczenia na liczbę usług, jednocześnie aktywnych stacji monitorujących, dostępne kanały powiadomień itp. Limity te są zdefiniowane w przypisanym do konta pakiecie ("package"). Pakiet określa między innymi następujące limity:

liczba usług (maximum_services) - maksymalna liczba usług należących do konta,
liczba stacji monitorujących (maximum_sensors) - maksymalna liczba stacji monitorujących przypisanych do każdej z grup w każdej kategorii (różne grupy mogą mieć przypisane różne stacje), oraz bezpośrednio do usług,
maksymalna częstotliwość sprawdzeń (minimum_interval) - żadna z usług nie może być sprawdzana częściej, niż określa ten limit,
dostępne typy usług (available_service_types) - dla każdego z dostępnych typów mogą być określone dodatkowe limity na liczbę usług i częstotliwość sprawdzeń,
identyfikatory dostępnych kanałów powiadomień (available_notification_channel_ids) - nie jest możliwe tworzenie adresów powiadomień dla innych kanałów.

Dodatkowi użytkownicy konta

Możliwe jest tworzenie dodatkowych użytkowników ("subkont") istniejącego konta. Służy do tego operacja POST /accounts. Użytkownicy stworzeni w ten sposób mają dostęp do wszystkich usług i grup konta podstawowego (także udostępnionych mu przez innych użytkowników). Użytkownicy mają własne konta, ale domyślnie nie mogą posiadać usług (ich pakiet pozwala na utworzenie 0 usług). Można tworzyć użytkowników read-only (atrybut is_read_only konta), w takim przypadku nie mogą oni modyfikować grup ani usług. O tym, czy konto jest kontem dodatkowego użytkownika, czy kontem podstawowym, decyduje atrybut parent_account_id - identyfikator konta "nadrzędnego", którego użytkownikiem jest dane konto lub NULL jeśli jest to konto główne. Konta dodatkowych użytkowników innego konta nie mogą tworzyć własnych dodatkowych użytkowników.

Udostępnianie grup

Oprócz tworzenia dodatkowych użytkowników konta istnieje możliwość udostępniania grup innym kontom, być może niezwiązanym w żaden inny sposób z kontem użytkownika. Konta, którym możemy udostępniać grupy, mają aktywne uprawnienie permissions.share_groups - jeśli chcesz udostępnić usługi innemu użytkownikowi, skontaktuj się z Biurem Obsługi Klienta. Grupy, które możemy im udostępniać, mają aktywne uprawnienie permissions.share.

Do zarządzania udostępnieniami grupy służy zasób /groups/{_id}/shares. Domyślnie grupa udostępniana jest jedynie tylko do odczytu, ale można umożliwić edycję grupy oraz usług do niej należących. Służą do tego atrybuty can_modify_group i can_modify_services obiektu udostępnienia (share).

Czasowe zawieszanie monitoringu

Dostępne są dwa sposoby zawieszania monitoringu usług:

Harmonogram tygodniowy - obiekty weekly_suspensions (z atrybutem only_notifications ustawionym na false) umożliwiające planowanie cotygodniowych zawieszeń monitoringu z dokładnością do minuty. Harmonogram tygodniowy działa w strefie czasowej konta, do którego należy usługa.
Zaplanowane zawieszenia - obiekty suspensions (z atrybutem only_notifications ustawionym na false), umożliwiające szczegółowe zaplanowanie jednorazowych zawieszeń monitoringu.

Dostępna jest także poprzednia wersja harmonogramu tygodniowego - atrybut suspension_hours usługi, zawierający 168 zer lub jedynek oznaczający zawieszenie w kolejnych godzinach tygodnia. Pierwsza godzina oznacza przedział 00:00:00 - 00:59:59 w poniedziałek. Harmonogram tygodniowy działa w strefie czasowej konta, do którego należy usługa. Nie jest zalecane korzystanie z tej wersji harmonogramu, zostanie ona usunięta w jednej z nadchodzących wersji API.

Wszytkie te ustawienia działają niezależnie od siebie - wystarczy, aby z jednego z nich wynikało, że usługa powinna być zawieszona, a monitoring zostanie wstrzymany.

Historia monitoringu

Usługi, których monitoring nie jest wyłączony (atrybut is_active ma wartość true) oraz nie zostały czasowo zawieszone, są monitorowane. Monitorowanie polega na cyklicznym wykonaniu tzw. analizy ("analysis") działania usługi, w ramach której jest wykonywane jedno lub więcej sprawdzeń ("checks"). Wynikiem analizy jest stwierdzenie, czy usługa działa poprawnie i ewentualne wysłanie powiadomień o zmianie stanu.

Analizy działania usługi

Dla każdej z monitorowanych usług system wykonuje analizy, które tworzą historię monitoringu. Nowa analiza może zostać rozpoczęta w wyniku:

normalnego cyklu sprawdzeń - kiedy od rozpoczęcia poprzedniej analizy upłynęła liczba sekund określona parametrem interval usługi,
ręcznego wymuszenia testowej analizy przez użytkownika - np. za pomocą operacji POST /services/{_id}/force_analysis,
przyspieszonego sprawdzenia bezpośrednio po wykryciu awarii - system wykonuje dodatkowe analizy "potwierdzające" po wykryciu awarii; dla niektórych typów usług zachowanie to można wyłączyć za pomocą ustawienia disable_breakdown_checks ("Nie przyspieszaj sprawdzeń po wykryciu awarii"),
konieczności odświeżenia statusu usługi celem potwierdzenia wysłania powiadomienia o awarii lub jej końcu (w przypadku opóźnionych powiadomień).

Analiza polega na:

Wyborze stacji monitorujących, z których usługa zostanie sprawdzona. W normalnych okolicznościach wybierane są po prostu stacje przypisane do grupy w odpowiedniej kategorii, ewentualnie bezpośrednio do usługi. Jeśli któraś ze stacji jest tymczasowo niedostępna i usługa ma włączone ustawienie sensors_failover_enabled ("Losuj zastępcze stacje monitorujące w przypadku awarii stacji"), może ona na czas awarii zostać zastąpiona inną stacją; przy wyborze takiej stacji preferowane są stacje geograficznie zbliżone do awaryjnej.
Zleceniu wykonania sprawdzenia usługi wszystkim wybranym stacjom i odebraniu wszystkich wyników ze stacji.
Stwierdzenia, czy usługa działa poprawnie, czy jest w stanie awarii. Decyduje o tym porównanie procentowej liczby stacji, które zwróciły błąd, z ustawieniem error_tolerance usługi ("Ile stacji monitorujących musi zgłosić błąd, aby został on uznany"). Za czas wykonania analizy (atrybut time) przyjmuje się czas podjęcia decyzji o nowym statusie usługi.
Jeśli w wyniku poprzedniego kroku stwierdzono zmianę statusu działania (np. usługa działała poprawnie, a analiza zmieniła jej status na awarię) - wysłaniu odpowiednich powiadomień. W przypadku powiadomień o kontynuacji awarii mogą one zostać także wysłane przy analizach nie zmieniających statusu.

Identyfikatory analiz pojedynczej usługi są napisami złożonymi z piętnastu cyfr dziesiętnych, na przykład 147401403020222. Pojedynczą analizę można pobrać za pomocą wywołania GET /services/{_id}/history/analyses/{_analysis_id}, na przykład GET /services/1000/history/analyses/147401403020222. Piętnastocyfrowy identyfikator jest unikalny jedynie w obrębie pojedynczej usługi - może okazać się, że inna usługa będzie miała analizę z tym samym identyfikatorem. "Kluczem głównym" analiz jest para ID usługi + 15-cyfrowe ID analizy.

Jeśli w adresie URL zasobu występuje ID analizy, można w jego miejsce użyć jednej ze specjalnych wartości:

last_analysis - ID ostatniej wykonanej analizy dla usługi,
last_ok_analysis - ID ostatniej analizy, która zakończyła się sukcesem (stwierdzeniem, że usługa działa poprawnie),
last_failure_analysis - ID ostatniej analizy, która zakończyła się wykryciem awarii usługi.

Na przykład aby pobrać sprawdzenia wchodzące w skład ostatniej analizy usługi o identyfikatorze 12345, można użyć zapytania GET /services/12345/history/analyses/last_analysis/checks.

Uważny Czytelnik zauważy zapewne, że identyfikatory analiz są prawdopodobnie generowane na podstawie timestampów uniksowych. Tak jest w istocie, ale nie należy na tym fakcie polegać - w szczególności analizy posortowane po czasie nie muszą być zgodne z posortowanymi po identyfikatorze.

Sprawdzenia

Zgodnie z powyższym opisem sposobu wykonywania analiz, w skład każdej analizy wchodzą sprawdzenia, każde wykonywane na innej stacji monitorującej. Dlatego identyfikatorem pojedynczego sprawdzenia jest identyfikator analizy i identyfikator stacji monitorującej, czyli trójka ID usługi + 15-cyfrowe ID analizy + ID stacji monitorującej. Stąd wynika format adresu sprawdzenia: GET /services/1000/history/analyses/147401403020222/checks/24 (w tym przypadku 24 to ID stacji monitorującej).

Dla pojedynczego sprawdzenia można pobrać dodatkowo:

szczegóły sprawdzenia, np. nagłówki odpowiedzi czy czasy przejścia poszczególnych kroków scenariusza - operacja GET /services/{_id}/history/analyses/{_analysis_id}/checks/{_sensor_id}/details,
artefakty - pliki zawierające dodatkowe informacje o sprawdzeniu, np. screenshot lub treść strony z momentu awarii. Listę artefaktów dla sprawdzenia można pobrać za pomocą operacji GET /services/{_id}/history/analyses/{_analysis_id}/checks/{_sensor_id}/artifacts.

Zmiany stanów usług

W każdym momencie usługa jest w jednym z trzech podstawowych stanów:

ok - poprawne działanie - monitoring jest włączony, ostatnia analiza nie wykryła błędu,
failure - niepoprawne działanie - monitoring jest włączony, ostatnia analiza wykryła błąd,
paused - stan jest nieznany ze względu na zatrzymanie (ręczne lub automatyczne zawieszenie) monitoringu usługi.

Tak zdefiniowany stan działania usługi może zmienić się w wyniku:

analizy (przejście w stan ok lub failure) - np. błędna analiza może spowodować status failure,
zatrzymania monitoringu, ręcznego lub w wyniku zawieszenia (przejście w stan paused).

Historię tak zdefiniowanych zmian można pobrać za pomocą wywołania GET /services/{_id}/history/status_changes. Historia ta zawiera między innymi edytowalny opis każdej zmiany stanu, przyczynę przejścia w wybrany stan (identyfikator analizy lub rodzaj pauzy / zawieszenia), czas rozpoczęcia i zakończenia przebywania usługi w danym stanie. Dla stanów ok i failure można dodatkowo pobrać liczbę sprawdzeń wykonanych na każdej ze stacji monitorujących podczas przebywania usługi w danym stanie (GET /services/{_id}/history/status_changes/{_change_id}/stats ).

Korekty Service Level

Dane Service Level w raportach i na wykresach są generowane na podstawie zmian stanów, można jednak nakładać na nie korekty, które powodują zmianę stanu działania usługi na inny w wybranym przedziale czasowym. Korekty nie wpływają na historię zmian stanów, sprawdzeń ani analiz, jedynie na wyniki Service Level.

Korekty można pobierać, tworzyć, edytować i usuwać za pomocą zasobu /corrections. Korekty dodane później nadpisują wcześniejsze korekty dla tego samego przedziału czasowego. Do zmian stanów można dowiązać statystyki korekt zawierające informacje o liczbie korekt wpływających na daną zmianę stanu oraz o liczbie sekund tej zmiany pokrytych korektami.

Aktualny status usługi

Informacje o aktualnym stanie działania usługi są dostępne w stowarzyszonym z nią obiekcie service_status. Każda usługa posiada dokładnie jeden obiekt service_status, o takim samym identyfikatorze, co usługa.

Status jest obiektem informacyjnym, którego nie można modyfikować. Jego głównym polem jest summary, zawierające podsumowanie statusu usługi. Wartość tego pola wynika jednoznacznie z wartości pól check_status (status działania usługi), monitoring_status (status monitoringu usługi) oraz check_status_is_up_to_date (ważność wyników z ostatniej analizy) w następujący sposób:

failure - monitoring_status == "on" && check_status == "failure" && check_status_is_up_to_date
ok - monitoring_status == "on" && check_status == "ok" && check_status_is_up_to_date
paused - monitoring_status == "off"
suspended - monitoring_status == "suspended"
unknown - monitoring_status == "on" && !check_status_is_up_to_date

Oprócz statusów cząstkowych i zargegowanego, obiekty service_statuses zawierają pola określające:

status wysyłania powiadomień - pole notifications_status,
czas ostatniej zmiany statusu działania - pole last_check_status_change_time,
identyfikatory i czasy wykonania ostatnich analiz (dowolnej, poprawnej i błędnej) - pola last_analysis_id, last_analysis_time, last_ok_analysis_id, last_ok_analysis_time, last_failure_analysis_id oraz last_failure_analysis_time.

Dzienniki i statystyki konta

Od wersji 3.3 możliwe jest pobranie dzienników wysłanych powiadomień (notifications) oraz zmian stanów działania usług (status_changes) dla konta, a od wersji 3.4 także logowań do konta (sesji utworzonych za pomocą OAuth2 lub zasobu auth_token - authentications). Do przeglądania dzienników służą zasoby /accounts/{_id}/logs/*.

O ile w dokumentacji operacji pobierania danych dziennika nie zostało powiedziane inaczej, dzienniki są dostępne przez 400 dni. Pobieranie dzienników konta wymaga uprawnienia read_logs do konta.

Za pomocą operacji GET /accounts/{_id}/stats można pobrać statystyki dotyczące liczby usług i kroków, zarówno należących do konta jak i mu udostępnionych. Pobieranie statystyk wymaga uprawnienia read_stats do konta.

Powiadomienia

Niektóre ze zdarzeń, na przykład wykrycie awarii lub jej koniec, powodują wysłanie powiadomień.

Kanały powiadomień

Adresy powiadomień (np. adresy e-mail, numery telefonu itp.) są reprezentowane przez obiekty notification_addresses. Typ adresu jest określony przez jego kanał powadomień - jeden z obiektów ze słownika notification_channels. Dostępne są następujące kanały powiadomień:

email - standardowe powiadomienie e-mail,
email_dedicated - powiadomienie e-mail w dedykowanym formacie, implementowane na życzenie,
email_extended - rozszerzone powiadomienie e-mail, zawierające między innymi nagłówki i treść odpowiedzi z każdej ze stacji monitorujących,
email_short - krótkie powiadomienie e-mail,
email_simplified - uproszczone powiadomienie e-mail,
gadu_gadu - powiadomienia wysyłane przez komunikator Gadu-Gadu, jako adres powiadomień należy podać numer GG,
slack - powiadomienia wysyłane przez Slacka, jako adres powiadomień należy podać wygenerowany uprzednio URL "Incoming Webhook" do wysyłki powiadomień, w formacie https://hooks.slack.com/services/XXXXXXXXX/YYYYYYYYY/ZZZZZZZZZZZZZZZZZZZZZZZZ,
jabber - powiadomienie wysyłane przez Jabber, należy podać swój Jabber ID,
json_post - powiadomienia w formacie JSON, wysyłane metodą HTTP POST na wybrany adres URL,
pagerduty - powiadomienia zgłaszające incydent w systemie PagerDuty, adresem jest klucz API PagerDuty w wersji 2, z opcjonalnym prefiksem określającym poziom ważności incydentu (info;, warning;, error; lub critical;),
push - powiadomienia wykorzystywane przez aplikację mobilną Monit24.pl, nie jest możliwa ich ręczna edycja - zarządza nimi aplikacja,
sms - powiadomienia SMS, adres powiadomień to numer telefonu, na który należy wysyłać wiadomości,
rocketchat - powiadomienia RocketChat, jako adres należy podać adres URL "Incoming Webhooka" skonfigurowanego w aplikacji RocketChat (Administration → Integrations → New Integration → Incoming Webhook)
ms_teams - powiadomienia MS Teams, adresem jest URL "Incoming Webhooka" skonfigurowanego w aplikacji MS Teams (Store → Connectors → Incoming Webhook).
alerta - powiadomienia Alerta.io, adresem jest URL do wysyłania powiadomień przez API Alerta, z tokenem API podanym w parametrze GET o nazwie api-key. Można także modyfikować większość parametrów powiadomienia za pomocą parametrów GET.

Każdy adres powiadomień jest przypisany do jednej grupy usług. Powiadomienia o zdarzeniach dotyczących usług z danej grupy będą wysyłane na adresy przypisane do niej. Dla każdej z usług można włączyć lub wyłączyć wybrane kanały powiadomień modyfikując jej atrybut notification_channel_ids - tablicę identyfikatorów włączonych kanałów powiadomień.

Zdarzenia

Możliwe jest powiadamianie o następujących zdarzeniach:

failure - wykrycie awarii (błędna analiza w przypadku, kiedy poprzednia była poprawna, usługa była wcześniej zatrzymana lub pierwsza po utworzeniu usługi),
failure_continuation - kontynuacja awarii (kolejna błędna analiza po wykryciu awarii, wysyłane kilka razy po wykryciu awarii, ale nie częściej niż raz na minutę),
pause - zatrzymanie monitoringu usługi przez użytkownika (nie dotyczy zawieszeń według harmonogramu),
recovery - koniec awarii (poprawna analiza w przypadku, kiedy poprzednia analiza była błędna),
silent_failure - kontynuacja awarii po wyjściu z trybu cichego (wykrycie awarii podczas przebywania usługi w trybie cichym) i późniejsze zakończenie tego trybu.

Zdarzenia, o których chcemy być powiadamiani, można dla każdej z usług ustawić modyfikując jej atrybut notification_condition_ids. Jest to tablica identyfikatorów obiektów ze słownika notification_conditions.

Opóźnianie powiadomień

Jeśli nie chcemy być powiadamiani o "krótkich" awariach, możemy zmienić tryb wysyłania powiadomień (atrybut notification_mode_id usługi, identyfikator obiektu ze słownika notification_modes). Dostępne tryby:

off - wyłączenie wszystkich powiadomień dla usługi,
default - domyślny tryb - wysyłanie powiadomienia bezpośrednio po wykryciu awarii,
after_30_seconds_failure, after_1_minute_failure, after_5_minutes_failure, after_10_minutes_failure, after_15_minutes_failure, after_30_minutes_failure, - wysyłania powiadomienia o awarii dopiero kiedy awaria trwa odpowiednio 30 sekund, 1, 5, 10, 15 lub 30 minut.

W przypadku wybrania jednej z opcji after_*_failure po wybranym czasie trwania awarii wykonywana jest dodatkowa analiza "potwierdzająca". Powiadomienie jest wysyłane dopiero, kiedy usługa po tej analizie wciąż będzie w stanie awarii.

Atrybut recovery_notification_mode_id działa podobnie jak notification_mode_id, ale dotyczy opóźnionych powiadomień o końcu awarii (słownik: recovery_notification_modes).

Tryb cichy

Można także określić godziny doby, w których nie chcemy otrzymywać żadnych powiadomień - tzw. tryb cichy. Służą do tego zasoby suspensions i weekly_suspensions z atrybutem only_notifications. Podobnie jak w przypadku zawieszeń monitoringu, zawieszanie powiadomień działa w strefie czasowej konta, do którego należy usługa. Podczas trybu cichego usługa jest monitorowana w normalny sposób, jedynie powiadomienia nie są wysyłane.

Dostępna jest także poprzednia wersja trybu cichego: atrybut silent_hours usługi - 24 zera lub jedynki oznaczające kolejne godziny doby. Podobnie jak suspension_hours, ten mechanizm zostanie wyłączony w jednej z nadchodzących wersji API i nie jest zalecane korzystanie z niego.

Jeśli podczas trwania trybu cichego usługa przestała działać, można otrzymać powiadomienie bezpośrednio po zakończeniu trybu cichego. W tym celu należy włączyć warunek powiadomień silent_failure dla usługi.

Raporty okresowe

Uwaga: Poniższy prosty mechanizm generowania raportów okresowych powstał przed ich nową wersją i działa od niej niezależnie.

Możliwe jest wysyłanie na wybrane adresy e-mail raportów okresowych o działaniu usług w formacie PDF. Adresy wysyłki raportów są reprezentowane przez obiekty periodic_report_addresses (docelowo będą one zastąpione przez nową wersję modułu raportów). Adresy raportów, podobnie jak adresy powiadomień, są przypisane do grup usług i dotyczą wszystkich usług w grupie. Każdy adres posiada atrybut report_frequency oznaczający częstotliwość wysyłania raportu - raz na dobę, raz na tydzień lub raz na miesiąc. Jeśli chcemy otrzymywać wszystkie trzy typy raportów, należy utworzyć trzy adresy przypisane do grupy.

Można włączyć lub wyłączyć wysyłanie raportów dla grupy modyfikując jej atrybuty periodic_daily_reports, periodic_weekly_reports i periodic_monthly_reports.

Reguły nadawania uprawnień

Poniżej przedstawione są szczegółowe zasady obliczania uprawnień (permissions) dla poszczególnych typów obiektów. Zasady te są miejscami dość skomplikowane, ale w większości przypadków powinno wystarczyć dowiązanie odpowiedniego obiektu permissions. Na przykład, aby na liście grup usług w aplikacji wyświetlić (lub nie) przycisk usuwania danej grupy, wystarczy dowiązać do pobieranych grup permissions.delete, nie przejmując się zbytnio z czego dokładnie wynika jego wartość.

Konta

Użytkownik może pobierać (read) obiekty kont:

własnego,
konta, którego jest dodatkowym użytkownikiem (jeśli takie istnieje),
dodatkowych użytkowników własnego konta,
użytkowników, którzy mogą udostępniać mu grupy,
użytkowników, którym może udostępniać grupy,
użytkowników, którzy mogą udostępniać grupy kontu, którego jest dodatkowym użytkownikiem,
użytkowników, którym może udostępniać grupy konto, którego jest dodatkowym użytkownikiem.

O ile użytkownik nie jest użytkownikiem read-only, może także:

modyfikować (update) własne konto oraz konto, którego jest dodatkowym użytkownikiem, a także konta dodatkowych użytkowników własnego konta oraz konta, którym może udostępniać grupy (wymaga włączenia tej opcji przez administratorów Monit24.pl),
usuwać konta dodatkowych użytkowników własnego konta (delete),
tworzyć dodatkowych użytkowników (create_subaccounts) własnego konta (o ile sam nie jest dodatkowym użytkownikiem innego konta) oraz konta, którego jest dodatkowym użytkownikiem,
tworzyć grupy usług (create_groups) przypisane do własnego konta oraz konta, którego jest dodatkowym użytkownkiem,
tworzyć szablony raportów (create_report_templates) przypisane do własnego konta oraz konta, którego jest dodatkowym użytkownkiem,
udostępniać własne grupy (share_groups) kontom zdefiniowanymi przez administratora systemu.

Użytkownik może także przeglądać dzienniki i pobierać statystyki własnego konta oraz konta, którego jest dodatkowym użytkownikiem.

Pakiety

Użytkownik może pobierać (read) pakiety:

własny,
konta, którego jest dodatkowym użytkownikiem (jeśli takie istnieje),
dodatkowych użytkowników własnego konta,
użytkowników, którzy mogą udostępniać mu grupy,
użytkowników, którzy mogą udostępniać grupy kontu, którego jest dodatkowym użytkownikiem.

Grupy

Użytkownik może pobierać (read) grupy:

własne,
należące do konta, którego jest dodatkowym użytkownikiem,
udostępnione mu przez innych użytkowników,
udostępnione kontu, którego jest dodatkowym użytkownikiem.

Jeśli nie jest użytkownikiem read-only, może także:

modyfikować (update) własne grupy, grupy należące do konta, którego jest dodatkowym użytkownikiem oraz grupy udostępnione mu lub kontu, którego jest dodatkowym użytkownikiem z flagą can_modify_group,
usuwać (delete) własne grupy oraz grupy należące do konta, którego jest dodatkowym użytkownikiem, za wyjątkiem grup domyślnych,
tworzyć usługi (create_services) we własnych grupach, grupach konta, którego jest dodatkowym użytkownikiem oraz grupach udostępnionych mu z flagą can_create_services,
tworzyć adresy powiadomień (create_notification_addresses) i raportów okresowych (create_periodic_report_addresses) w grupach, które może modyfikować,
udostępniać innym użytkownikom (share) własne grupy,
wysyłać testowe powiadomienia SMS (send_test_sms_notifications) na numery telefonu przypisane do własnych grup.

Usługi

Użytkownik może pobierać (read) usługi należące do grup, do których ma dostęp.

Jeśli użytkownik nie jest użytkownikiem read-only, może ponadto:

modyfikować (update) własne usługi, usługi konta, którego jest dodatkowym użytkownikiem, oraz usługi udostępnione mu lub kontu, którego jest dodatkowym użytkownikiem z ustawioną flagą can_modify_services,
usuwać (delete) własne usługi oraz usługi konta, którego jest dodatkowym użytkownikiem,
tworzyć zaplanowane zawieszenia (create_suspensions) oraz wymuszać dodatkowe analizy działania (force_analyses) usług, które może modyfikować,
wysyłać testowe powiadomienia SMS (send_test_sms_notifications) na numery telefonu przypisane do własnych usług.

Raporty

Użytkownik może pobierać (read) raporty należące do niego oraz do konta, którego jest dodatkowym użytkownikiem.

Jeśli nie jest użytkownikiem read-only, może ponadto usuwać (delete) raporty, do których ma dostęp, z wyłączeniem raportów aktualnie generowanych (dla których pole status ma wartość in_progress).

Udostępnienia grup

Użytkownik może pobierać (read) udostępnienia grup:

własnych,
konta, którego jest dodatkowym użytkownikiem,
sobie, tzn. udostępnienia grup innych użytkowników, na podstawie których ma dostęp do ich grup,
kontu, którego jest dodatkowym użytkownikiem.

Jeśli nie jest użytkownikiem read-only, może także modyfikować (update) i usuwać (delete) udostępnienia własnych grup innym użytkownikom.

Adresy raportów okresowych

Użytkownik może pobierać (read) adresy raportów okresowych (periodic_report_addresses) przypisane do grup, do których ma dostęp.

Jeśli może modyfikować (update) daną grupę, to może także modyfikować (update) i usuwać (delete) adresy raportów przypisane do niej.

Adresy powiadomień

Użytkownik może pobierać (read) adresy powiadomień przypisane do grup, do których ma dostęp.

Jeśli może modyfikować (update) daną grupę, to może także modyfikować (update) i usuwać (delete) adresy powiadomień przypisane do niej.

Może także wysyłać testowe powiadomienia SMS na adresy będące numerami telefonu (dla których kanał powiadomień to sms) przypisane do własnych grup.

Zawieszenia monitoringu i powiadomień

Użytkownik może pobierać (read) zawieszenia usług, do których ma dostęp.

Może także modyfikować (update) i usuwać (delete) zawieszenia usług, które może modyfikować (update).

Historia zmian statusu działania usługi

Użytkownik może pobierać (read) zmiany statusu działania w historii usług, do których ma dostęp.

Może także modyfikować (update) opisy zmian statusu usług, które może modyfikować (update).

Dane użytkowników

Użytkownik może pobierać (read) jedynie własne dane użytkownika. Jeśli nie jest read-only, to może je także modyfikować (update).

Raporty i ich szablony

Użytkownik może pobierać (read) własne raporty i szablony, oraz należące do konta, którego jest dodatkowym użytkownikiem.

Jeśli nie jest użytkownikiem read-only, może także modyfikować (update) szablony, generować raporty (create_reports) oraz usuwać (delete) raporty i szablony.

API administracyjne

API administracyjne (zasoby /admin/...) dostępne jest jedynie dla administratorów dystrybucji, np. administratorów Monit24.pl lub partnerów. Należy traktować je jako oddzielne API, niezależne od pozostałych zasobów - administratorzy nie mają dostępu do zasobów użytkowników, a użytkownicy do zasobów administratorów. W szczególności występujące w nim obiekty account i package nie muszą mieć takiego samego schematu i flag uprawnień, co konta i pakiety widziane przez użytkowników.

API administracyjne umożliwia między innymi zakładanie aktywowanych kont z pakietami innymi niż podstawowy lub pusty, blokadę kont czy pobieranie statystyk zużycia zasobów przez użytkowników. Zasób /admin/accounts oznacza konta użytkowników razem z ich danymi (to, co użytkownicy widzą jako user_data). Zasób /admin/packages oznacza pakiety; flaga uprawnień create_accounts oznacza, czy można tworzyć nowe konta z wybranym pakietem za pomocą wywołań POST /admin/accounts.

Narzędzia i statystyki systemowe

Zasób /system daje dostęp do narzędzi diagnostycznych i globalnych statystyk systemu Monit24.pl:

asynchroniczne sprawdzanie odpowiedzi serwera DNS z wybranej stacji monitorującej - `/system/dns_diagnostics`,
asynchroniczne sprawdzanie trasy do wybranego hosta z wybranej stacji monitorującej - `/system/traceroute_diagnostics`,
bieżące statystyki: liczba wykonanych sprawdzeń, analiz, wykrytych błędów i awarii oraz wysłanych powiadomień - /system/stats.

Spis treści