Powiadomienia HTTP

Ten dokument zawiera opis sposobu działania i formatu powiadomień HTTP (JSON POST) wysyłanych przez system Monit24.pl.

Zasada działania

Wysyłanie powiadomień HTTP polega na wykonaniu zapytania HTTP metodą POST na adres URL wskazany jako adres powiadomień kanału json_post. Treść zapytania zawiera obiekt JSON opisujący powiadomienie; format tego obiektu jest opisany dalej w tym dokumencie. W adresie powiadomień można używać HTTPS, niestandardowych portów oraz Basic Auth (np. https://user:password@hostname:4443/monit24).

Powiadomienia HTTP podlegają tym samym zasadom, co pozostałe powiadomienia, w tym trybowi cichemu, filtrowaniu po typie i zdarzeniach oraz opóźnianiu wysyłki.

Oczekiwana odpowiedź serwera

Serwer HTTP powinien odpowiedzieć kodem HTTP z przedziału 200-299. W innych przypadkach (także w przypadku błędów warstwy niższej niż HTTP, w tym timeoutów) próba wysłania powiadomienia będzie ponawiana (maksymalnie 10 razy w ciągu 15 minut od pierwszej próby).

Przykład

Przykładowe powiadomienie o awarii usługi wysyłane przez system Monit24.pl - w tym przypadku ustawiona jest niska wartość limitu czasowego (kilka milisekund) i występuje błąd podczas odpytywania serwów DNS:

POST /monit24 HTTP/1.1
Host: hostname
User-Agent: www.monit24.pl-m24Notifier/1.0-
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 2533

{
   "analysis_id" : "150037378020532",
   "check_results" : [
      {
         "benchmark" : {
            "description" : "",
            "error_type_id" : null,
            "response_time" : 89.237,
            "result" : "ok"
         },
         "content" : "UEsDBBQACAAIALZj8koAAAAAAAAAAAAAAAAPAAAAdXJsX2NvbnRlbnQuZGF0AwBQSwcIAAAAAAIAAAAAAAAAUEsBAhQDFAAIAAgAtmPySgAAAAACAAAAAAAAAA8AAAAAAAAAAAAAALYBAAAAAHVybF9jb250ZW50LmRhdFBLBQYAAAAAAQABAD0AAAA/AAAAAAA=",
         "description" : "Problem podczas pobierania kodu strony: 6 Couldn't resolve host name: Resolving host timed out: monit24.pl",
         "details" : [
            {
               "base_url" : "http://monit24.pl",
               "content_type" : null,
               "data_size" : 0,
               "file_name" : "",
               "headers" : "",
               "path_step" : null,
               "response_time" : 10.29
            }
         ],
         "error_on_element" : false,
         "error_type_id" : 1000003,
         "response_time" : 10.29,
         "result" : "failure",
         "sensor_id" : 2,
         "sensor_name" : "Warszawa01 217.17.42.71",
         "time" : "2017-07-18T10:29:43Z"
      },
      {
         "benchmark" : {
            "description" : "",
            "error_type_id" : null,
            "response_time" : 93.11,
            "result" : "ok"
         },
         "content" : "UEsDBBQACAAIALVj8koAAAAAAAAAAAAAAAAPAAAAdXJsX2NvbnRlbnQuZGF0AwBQSwcIAAAAAAIAAAAAAAAAUEsBAhQDFAAIAAgAtWPySgAAAAACAAAAAAAAAA8AAAAAAAAAAAAAALYBAAAAAHVybF9jb250ZW50LmRhdFBLBQYAAAAAAQABAD0AAAA/AAAAAAA=",
         "description" : "Problem podczas pobierania kodu strony: 6 Couldn't resolve host name: Resolving host timed out: monit24.pl",
         "details" : [
            {
               "base_url" : "http://monit24.pl",
               "content_type" : null,
               "data_size" : 0,
               "file_name" : "",
               "headers" : "",
               "path_step" : null,
               "response_time" : 10.179
            }
         ],
         "error_on_element" : false,
         "error_type_id" : 1000003,
         "response_time" : 10.179,
         "result" : "failure",
         "sensor_id" : 3,
         "sensor_name" : "Amsterdam 188.166.9.246",
         "time" : "2017-07-18T10:29:42Z"
      }
   ],
   "current_downtime" : null,
   "notification_condition_id" : "failure",
   "notification_sequence_number" : 1500373785905,
   "service_id" : 8,
   "service_name" : "Usługa testowa",
   "time" : "2017-07-18T10:29:45Z"
}

Opis formatu powiadomień

Treść powiadomienia jest obiektem JSON, zawierającym następujące atrybuty:

analysis_id - identyfikator analizy, która spowodowała wysłanie powiadomienia. Pole obowiązkowe dla zdarzeń typu failure, recovery, failure_continuation oraz silent_failure, w pozostałych przypadkach przyjmuje wartość NULL.
check_results - posortowana rosnąco po identyfikatorze stacji monitorującej tablica wyników sprawdzeń z poszczególnych stacji monitorujących.
current_downtime - aktualny czas trwania awarii w sekundach (tylko dla zdarzeń failure_continuation, silent_failure i recovery, w pozostałych przypadkach NULL).
notification_condition_id - identyfikator warunku powiadomienia (zdarzenia), którego dotyczy powiadomienie. Możliwe warunki powiadomień są zdefiniowane w słowniku notification_conditions.
notification_sequence_number - liczba określająca kolejność powiadomień. Ponieważ powiadomienia są wysyłane asynchronicznie i niezależnie od siebie, a także możliwe jest ich ponawianie w przypadku błędu wysyłki, można dokonać deduplikacji i filtrowania nieaktualnych powiadomień za pomocą tej liczby. Dla powiadomień dotyczących jednej usługi wartość tej liczby będzie większa jeśli powiadomienie zostało wygenerowane później. Efektywnie oznacza to, że powiadomienia z wartością notification_sequence_number mniejszą bądź równą najwyższej wartości zaobserwowanej do tej pory dla danej usługi można w wielu przypadkach pominąć.
service_id - identyfikator usługi, której dotyczy powiadomienie.
service_name - nazwa usługi, której dotyczy powiadomienie.
time - data i czas wygenerowania powiadomienia.

Wyniki sprawdzeń

Pole check_results powiadomienia zawiera tablicę obiektów reprezentujących sprawdzenia wchodzące w skład analizy, która spowodowała wygenerowanie powiadomienia. Każdy z tych obiektów zawiera pola:

benchmark - uproszczony wynik sprawdzenia usługi benchmarkowej (http://google.pl) wykonany na stacji monitorującej zaraz po wykryciu błędu (tylko dla błędnych sprawdzeń). Zawiera pola description, error_type_id, response_time oraz result o znaczeniu takim samym, jak dla sprawdzenia usługi podstawowej. Benchmark stanowi dodatkową weryfikację, czy problem nie dotyczy samej stacji monitorującej.
content - skompresowana algorytmem zip i zakodowana w Base64 treść strony z momentu sprawdzenia (tylko dla błędnych sprawdzeń).
description - tekstowy opis błędu.
details - tablica szczegółowych wyników z rozbiciem na kroki scenariusza dla sprawdzenia, posortowana rosnąco po numerze kroku.
error_on_element - wartość true lub false oznaczająca, czy błąd został wykryty na elementach strony, czy na zawartości głównej.
error_type_id - kod wykrytego błędu (z zasobu error_types).
response_time - czas trwania sprawdzenia (szybkość działania usługi), w milisekundach.
result - wynik sprawdzenia (ok, failure lub unknown).
sensor_id - identyfikator stacji monitorującej na której zostało wykonane sprawdzenie.
sensor_name - nazwa stacji monitorującej na której zostało wykonane sprawdzenie.
time - data i czas wykonania sprawdzenia.

Szczegóły sprawdzeń

Pole details szczegółów każdego ze sprawdzeń może zawierać tablicę bardziej dokładnych wyników sprawdzenia. Dla usług będących scenariuszami elementy tej tablicy odpowiadają kolejnym krokom scenariusza. Dla pozostałych usług tablica może zawierać pojedynczy element z numerem kroku ustawionym na NULL.

Każdy element tablicy jest obiektem zawierającym atrybuty:

base_url - adres URL pobrany w tym kroku, po ewentualnych przekierowaniach HTTP.
content_type - typ MIME pobranej zawartości.
data_size - rozmiar pobranej zawartości w bajtach.
file_name - nazwa pobranego pliku.
headers - nagłówki HTTP (jako pojedynczy napis).
path_step - numer kroku w scenariuszu lub NULL jeśli usługa nie jest scenariuszem.
response_time - czas przejścia kroku w milisekundach.