Raporty

System Monit24.pl udostępnia możliwość generowania raportów z działania usług, zarówno cyklicznych jak i jednorazowych.

W API do obsługi raportów służą zasoby report_templates (szablony raportów) i reports (raporty), które są opisane poniżej.

Uwaga: powyższe zasoby reprezentują "nowe" raporty, wprowadzone w API 3.5. Niezależnie od nich funkcjonują "stare" raporty (zasób periodic_report_addresses i pola *_periodic_reports grup). Aktualnie nie mamy w planach wyłączania "starych" raportów, obie wersje będą istnieć równolegle. Tym niemniej, polecamy korzystanie z "nowych" raportów ze względu na istotne ograniczenia "starej" wersji - między innymi brak raportów jednorazowych, jedynie polska strefa czasowa czy brak możliwości pobrania archiwalnych raportów. Opis działania "starych" raportów znajduje się w tym miejscu.

Szablony raportów

Zanim zostanie wygenerowany jakikolwiek raport, musi zostać utworzony szablon - każdy z raportów jest przypisany do swojego szablonu. Szablony można tworzyć, edytować i usuwać za pomocą standardowych operacji na zasobie report_templates.

Oto przykład szablonu:

{
   "archived_services" : true,
   "description" : "Przykład szablonów raportów",
   "email_addresses" : ["example_report@monit24.pl"],
   "id" : 761,
   "owner_id" : 150,
   "reporting_plan_ids" : ["daily", "weekly"],
   "requested_scope" : {
      "accounts" : {
         "all" : false,
         "by_id" : [633, 126]
      },
      "groups" : {
         "all" : false,
         "by_id" : []
         "by_owner_id" : [150]
      },
      "services" : {
         "all" : false,
         "by_group_id" : [],
         "by_id" : [75642, 234566],
         "by_owner_id" : [150]
      }
   },
   "section_ids" : ["checks_summary"],
   "summary" : "enabled",
   "title" : "Przykładowy raport",
   "weekly_suspensions" : []
}

Podstawowe ustawienia

Każdy szablon posiada następujące standardowe ustawienia:

owner_id - identyfikator konta, do którego należy szablon
name - nazwa szablonu
description - opcjonalny opis szablonu, widoczny na pierwszej stronie raportów PDF
email_addresses - tablica adresów e-mail, na które zostanie wysłany plik PDF z raportem po jego wygenerowaniu
reporting_plan_ids - ustawienie cyklicznego wysyłania raportów
summary - sposób obsługi podsumowania raportu w wygenerowanym pliku PDF: enabled (włączone), disabled (wyłączone) lub only (tylko podsumowanie)
archived_services - określa, czy usługi archiwalne powinny zostać uwzględnione w raporcie
weekly_suspensions - tablica przedziałów czasowych w tygodniu, z których dane do raportu nie będą pobierane

Sekcje

Atrybut section_ids szablonu określa, jaki rodzaj informacji będzie zawarty w raporcie. Jest to tablica identyfikatorów obiektów ze słownika report_sections.

Przykładowo, dla ["service_level_summary"] zostanie wygenerowane proste zestawienie Service Level, zaś dla ["performance_by_hour", "performance_by_week_day"] - raport z informacjami o szybkości działania usług z podziałem na godziny doby i dni tygodnia.

Zakres

Atrybut requested_scope szablonu określa, czego będzie dotyczył raport. Zawiera on 3 atrybuty, określające, które usługi, grupy i konta znajdą się w raporcie:

services - określa, które usługi znajdą się w raporcie. Można wybrać wszystkie usługi, dla których właściciel szablonu ma dostęp (all), usługi należące do wybranych kont (by_owner_id), grup (by_group_id) lub konkretne usługi (by_id). Każdej usłudze wybranej w ten sposób będzie odpowiadał jeden punkt w raporcie PDF. Jeśli usługa została wskazana klika razy (np. w ramach wszystkich usług należących do konta i bezpośrednio po identyfikatorze), to zostanie uwzględniona tylko raz.
groups - określa, które grupy znajdą się w raporcie. Podobnie jak dla usług, można wybrać wszystkie grupy (all), grupy należące do wybranych kont (by_owner_id) lub bezpośrednio po identyfikatorze grupy (by_id). Dla każdej z grup wskazanych na jeden z powyższych sposobów zostanie wygenerowany jeden punkt w raporcie PDF, zawierający podsumowanie dla całej tej grupy (nawet jeśli raport nie zawiera danych dla poszczególnych usług z grupy).
accounts - określa, które konta znajdą się w raporcie. Można wybrać wszystkie konta (all), lub wskazać wybrane konta (by_id). Dla każdego z wybranych kont zostanie wygenerowany jeden punkt w raporcie PDF, zawierający podsumowanie dla wszystkich usług należących do tego konta.

Należy zwrócić uwagę, że te same dane można wybierać i agregować na różne sposoby - na przykład dane dla usług o identyfikatorach 563 i 564, jedynych należących do grupy 1645, można uwzględnić w raporcie jako:

{"services" : {"by_group_id" : [1645]}} - wszystkie usługi w grupie 1645 (dwa punkty w raporcie, odpowiadające dwóm usługom),
{"services" : {"by_id" : [563, 564]}} - usługi wskazane bezpośrednio; dopóki usługi w grupie 1645 się nie zmienią, efekt w pliku PDF z raportem będzie identyczny, jak w przykładzie wyżej - ma to znaczenie zwłaszcza przy cyklicznej wysyłce raportów,
{"groups" : {"by_id" : [1645]}} - jeden punkt w raporcie, zawierający zagregowane dane dla obu usług,
{"groups" : {"by_id" : [1645]}, "services" : {"by_group_id" : [1645]}} - kombinacja pierwszego i trzeciego przykładu - 3 punkty w raporcie, po jednym dla każdej usługi i jeden zbiorczy dla grupy.

Generowanie raportów

Po utworzeniu szablonu można generować na jego podstawie raporty. Raporty mogą być generowane jednorazowo lub cyklicznie.

Raport jednorazowy

Aby wygenerować pojedynczy raport na podstawie szablonu, należy wykonać operację POST /reports podając identyfikator szablonu oraz przedział czasowy, z jakiego należy wygenerować raport. Na przykład:

curl -u USERNAME:PASSWORD -X POST -H 'Content-Type: application/json' \
   -d '{
      "template_id" : 761,
      "from" : "2018-01-01T00:00:00Z",
      "to" : "2018-02-01T00:00:00Z"
   ' 'https://api.monit24.pl/v3/reports'

Odpowiedź API będzie standardowo zawierała identyfikator utworzonego raportu:

{
    "id" : 975
}

Poza wymaganymi parametrami template_id, from i to można określić także wartości name, description, email_addresses, section_ids, requested_scope, summary i weekly_suspensions. W takim przypadku nadpiszą one wartości domyślne (określone w szablonie) tylko dla tego konkretnego raportu.

Raport cykliczny

Oprócz ręcznego generowania raportów istnieje możliwość zaplanowania cyklicznego generowania raportów. W tym celu należy wskazać jeden lub więcej dostępnych planów generowania raportów w atrybucie reporting_plan_ids szablonu. Dostępne plany są elementami słownika reporting_plans. Przykładowo, na podstawie szablonu z przykładu powyżej będą automatycznie generowane raporty dobowe i tygodniowe.

Wszystkie plany generowania działają w strefie czasowej konta, do którego należy szablon.

Monitorowanie generowania raportów

Po dodaniu raportu (jednorazowo lub zgodnie z harmonogramem) rozpoczyna się jego generowanie. Odbywa się ono w dwóch fazach:

generating, wynikiem której jest raport w formacie JSON. Podczas tej fazy na podstawie historii działania usługi są obliczane wszystkie dane w raporcie,
rendering, podczas której na podstawie obliczonych danych jest renderowany plik PDF z raportem.

Każda z tych faz jest obsługiwana asynchronicznie, przez niezależnie działające mechanizmy. Jest możliwe renderowanie więcej niż jednego raportu jednocześnie. Raport PDF jest generowany jedynie na podstawie danych w raporcie JSON, bez pobierania dodatkowych danych z innych źródeł.

Można monitorować postęp generowania raportu (pierwszej fazy) za pomocą jego atrybutów generating_status i generating_progress - odpowiednio status (pending - oczekujący, in_progress - w trakcie lub completed - zakończony) i procentowy postęp. Analogiczne statystyki są dostępne także dla fazy renderowania (rendering_status i rendering_progress). Oprócz tego można korzystać z uproszczonych pól status i progress, które odpowiadają całemu procesowi generowania i renderowania raportu, przy założeniu, że po zakończeniu pierwszej fazy procentowy postęp wynosi 50%.

Raporty

Po zakończeniu przetwarzania raportu można pobrać jego wyniki w postaci surowych danych JSON (po pierwszej fazie) lub wyrenderowany raport PDF, opcjonalnie wysyłany także na adresy e-mail podane w atrybucie email_addresses szablonu lub raportu.

JSON

Plik JSON z wygenerowanym raportem można pobrać za pomocą operacji GET /reports/{_id}/json.

Na szczególną uwagę zasługuje pole results. Jest to tablica zawierająca dla każdego wybranego zakresu obiekt zawierający wyniki dla wszystkich wybranych sekcji. Elementy tablicy results odpowiadają punktom w raporcie PDF, zaś sekcje podpunktom.

Przykład elementu tablicy results:

{
   "checks_summary" : {
      "error" : 1643,
      "ok" : 96,
      "unknown" : 0
   },
   "scope" : {
      "account" : {"id" : 150, "name" : "Konto testowe", "username" : "test"},
      "group" : {"id" : 46782, "name" : "Grupa domyślna"},
      "service" : {"description" : "", "id" : 27, "name" : "Usługa testowa", "type" : {"id" : "http", "name" : "http"}},
      "type" : "service"
   }
}

Atrybut scope określa, jakiego zakresu dotyczy wynik. Parametr type określa typ tego zakresu i może przyjąć jedną z wartości:

summary - podsumowanie dla całego raportu (występowanie tego wyniku zależy od ustawienia summary raportu),
account - podsumowanie dla konta, w tym przypadku uproszczony obiekt konta znajduje się w parametrze account,
group - podsumowanie dla grupy, zawiera uproszczeony obiekt grupy (group) i konta, do którego należy grupa (account),
service - wyniki dla pojedynczej usługi, zawiera uproszczony obiekt usługi (service) oraz grupy (group) i konta (account), do którego należy usługa.

Poza atrybutem scope każdy element zawiera jeden atrybut z wynikami dla każdej z wybranych sekcji. W powyższym przykładzie dla sekcji checks_summary została zwrócona liczba poprawnych, błędnych i nieznanych sprawdzeń. Format tego wyniku jest inny dla każdej sekcji, ich opis można znaleźć w dokumentacji operacji pobierania wyników raportu JSON.

PDF

Po zakończeniu drugiej fazy przetwarzania raportu (renderowania), można pobrać plik PDF z raportem za pomocą operacji GET /reports/{_id}/pdf. Plik ten jest także wysyłany pocztą elektroniczną na adresy określone w polu email_addresses bezpośrednio po zakończeniu renderowania.