Wykresy w DOMIQ – integracja z Grafana

W tym samouczku opiszemy integrację DOMIQ z oprogramowaniem Prometheus i Grafana. Dzięki tej integracji nasz system zyskał zupełnie nowe możliwość w zakresie tworzenia wykresów.

Możliwość zobrazowania na wykresie interesujących wartości jest jedną z bardziej pożądanych cech inteligentnego domu. Od teraz bez problemu stworzysz np. wykres zużycia energii elektrycznej, wody lub gazu, obejrzysz przebiegi temperatury lub parametrów pracy systemu rekuperacji w dowolnym zakresie czasowym. Możliwości są nieograniczone – możesz utworzyć wykres dowolnej zmiennej, która występuje w systemie DOMIQ.

1. Jak zacząć? #

W tym rozdziale wskażemy, jakie urządzenia muszą znaleźć się w instalacji i jaką pełnią w niej rolę, aby korzystać z nowego mechanizmu wykresów.

• Moduł DOMIQ/Base – w nim zostaną zdefiniowane tzw. metryki, czyli definicje zmiennych występujących w systemie DOMIQ, które będą używane na wykresach. Jeżeli na tą chwilę pojęcie metryk jest dla Ciebie niejasne, nie zrażaj się. W dalszej części samouczka omówiliśmy je wraz z przykładami.
  
• Komputer (może być również mikroPC typu RaspberryPi lub podobny) lub zewnętrzny serwer, na którym zostanie zainstalowane oprogramowanie Prometheus i Grafana. Na tym etapie chcielibyśmy wyszczególnić zadanie obu aplikacji.
  
  • Prometheus – jego główną funkcją jest gromadzenie danych. Prometheus cyklicznie odpytuje wskazane urządzenie/urządzenia (w naszym przypadku moduł Base) o dane dla zdefiniowanych metryk i gromadzi je w bazie danych. Interwał ten jest ustalany w konfiguracji Prometheus, jednakże po stronie Base wprowadziliśmy ograniczenie, aby odpytywanie nie było częściej, niż co 15 sekund. Moduł Base odpowiada na żądania odsyłając aktualny stan wszystkich identyfikatorów przypisanych do zdefiniowanych metryk. Aplikacja Prometheus daje możliwość kreślenia wykresów, jednakże w bardzo ograniczonym zakresie. Z tego powodu w naszym przypadku używana jest jednocześnie także Grafana.
    
  • Grafana – stanowi doskonałe uzupełnienie funkcjonalności aplikacji Prometheus. Umożliwia definiowanie wykresów wielu typów (np. wykresy liniowe, słupkowe, kołowe, itd.), dając przy tym bardzo rozbudowane możliwości edycji prezentowanych danych, włącznie z nakładaniem na te dane formuł matematycznych. Z poziomu Grafany, Prometheus stanowi źródło danych do wykresów.
    
    Obie aplikacje muszą mieć do siebie dostęp, dlatego najwydajniejszym rozwiązaniem jest zainstalowanie ich na jednym urządzeniu. Urządzenie, na którym zainstalowane są aplikacje, musi być wyposażone w przestrzeń dyskową na potrzeby gromadzenia danych, które będą wyświetlone na wykresach. Jeżeli urządzenie będzie zainstalowane w tej samej lokalizacji, co moduł Base, wówczas należy podłączyć je do tej samej sieci lokalnej.
    
    W przypadku instalacji Prometheus i Grafana na serwerze zewnętrznym (np. serwer dedykowany w ramach hostingu) należy zapewnić możliwość odpytywania o metryki poprzez przekierowanie w routerze portu web modułu Base do Internetu. Aby przekierowanie portu web nie prowadziło równocześnie do dostępu do interfejsu konfiguracyjnego, wprowadziliśmy zabezpieczenie, które umożliwia odbieranie przez moduł Base żądań odczytu metryk przesyłanych przez aplikację Prometheus, ale bez konieczności ustawiania dostępu administracyjnego z całego Internetu (zakładka Użytkownicy). To zabezpieczenie całkowicie blokuje dostęp do interfejsu konfiguracyjnego modułu Base spoza sieci lokalnej nawet, gdy zostanie przekierowany w routerze port web modułu Base.
    
    W przypadku pracy urządzenia w sieci lokalnej ważne jest, aby zapewnić stałość adresu IP, pod którym urządzenie jest dostępne.
    
    Należy zadbać o to, aby Prometheus i Grafana były uruchamiane przy starcie systemu na urządzeniu, na którym są zainstalowane.
    
• Urządzenie z aplikacją Remote – w chwili pisania tego samouczka (luty 2019) wsparcie dla mechanizmu wykresów posiada jedynie Remote dla systemu iOS, natomiast w najbliższym czasie również wersja dla systemu Android zyska tą funkcjonalność. Aplikacja Remote wyświetla wykresy łącząc się bezpośrednio z urządzeniem, na którym pracuje oprogramowanie Grafana. Jeżeli chcesz mieć dostęp do wykresów będąc poza siecią lokalną, wówczas należy przekierować dostęp do urządzenia z aplikacją Grafana do Internetu (nie dotyczy instalacji na serwerze hostingowym).

Prezentacja wykresu inicjowana jest w aplikacji Remote, która przesyła żądanie do oprogramowania Grafana. Aplikacja Grafana pobiera z Prometheus dane niezbędne do zaprezentowania wykresu dla określonego zakresu czasowego. Dane są przetwarzane i zwracane przez Grafanę do aplikacji Remote, jako gotowy widok wykresu, który jest prezentowany przez aplikację. Wymiana danych między Prometheus a Base jest niezależna i występuje cyklicznie, co określony interwał. Inicjatorem tej wymiany jest aplikacja Prometheus.

2. Konfiguracja #

W samouczku nie będziemy przedstawiać jako takiego procesu instalacji aplikacji Prometheus i Grafana, gdyż zostało to dokładnie opisane przez wydawców oprogramowania. Natomiast przybliżymy kilka detali konfiguracji obu aplikacji, aby współpracowały z modułem Base i aplikacją Remote.

2.1. Prometheus #

Po prawidłowym zainstalowaniu aplikacji Prometheus, w folderze w którym zainstalowana jest aplikacja znajdziesz plik konfiguracyjny prometheus.yml. Otwórz plik w dowolnym edytorze tekstu i dostosuj ustawienia wg wskazań. Poniżej prezentujemy poglądowy plik .yml z naszej testowej instalacji.

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
# The job name is added as a label `job=` to any timeseries scraped from this config.
- job_name: 'base'

# metrics_path defaults to '/metrics'
metrics_path: '/prometheus/metrics'
# scheme defaults to 'http'.

static_configs:
- targets: ['192.168.1.30:80']

job_name to nazwa, która jest używana jako podpis na w legendzie wykresów. W naszym przypadku nazwa może być dowolna, bez polskich znaków i spacji. W prezentowanym przykładzie: base.

metrics_path: '/prometheus/metrics' – ścieżka adresu, który będzie używany do pobierana metryk z modułu Base. Ten parametr musi mieć wartość, jak pokazano w przykładzie. W przeciwnym wypadku nie będzie możliwe pobranie danych z modułu Base.
static_configs:
targets: ['192.168.1.30:80']
Czyli adres i port web modułu Base. W przypadku instalacji na serwerze zewnętrznym należy podać tu publiczny adres dostępu do modułu Base.

2.2. Grafana #

Po prawidłowym zainstalowaniu aplikacji Grafana, w folderze w którym zainstalowana jest aplikacja znajdziesz w folderze conf, plik konfiguracyjny custom.ini. Otwórz plik w dowolnym edytorze tekstu i dostosuj ustawienia wg wskazań.

# The http port to use
http_port = 3000
# The public facing domain name used to access grafana from a browser
domain =

# Default role new users will be automatically assigned (if auto_assign_org above is set to true)
auto_assign_org_role = Editor

############################## Anonymous Auth ######################
[auth.anonymous]
# enable anonymous access
enabled = true
############################## Basic Auth ######################
[auth.basic]
enabled = false

http_port – tu można wpisać numer portu, na którym będzie dostępna Grafana (możesz zostawić także wartość domyślną).
domain – Tą wartość zostaw pustą (skasuj localhost).
auto_assign_org_role – zmień na wartość Editor.

# enable anonymous access
enabled = true

Jeżeli enabled ustawisz na false, wówczas każde żądanie wysyłane do Grafany będzie wymagało podania loginu i hasła.

[auth.basic]
enabled = false

Ustaw na false, aby wyłączyć sprawdzanie hasła dostępowego.

2.3. Konfiguracja Base #

We wstępie samouczka wspomnieliśmy o metrykach. Definicja metryk jest niezbędnym krokiem, aby oprogramowanie Grafana mogło wyświetlać interesujące nas wykresy. Metryki to nic innego, jak definicje zmiennych, które Grafana będzie odczytywała z modułu Base. Metryki definiowane są w zakładce Wykresy w konfiguratorze modułu Base.

Zakładka ma trzy kolumny: Identyfikator, Nazwa oraz Opis. Aby dodać nowy wpis kliknij przycisk Dodaj i skonfiguruj go następująco:

• W kolumnie Identyfikator wpisz nazwę identyfikatora zmiennej, która jest dostępna w systemie DOMIQ.
• Uzupełnienie kolumny Nazwa jest opcjonalne, ale przez nas bardzo zalecane. W tej kolumnie możesz wpisać nazwę, która będzie opisywała czym jest dany identyfikator.
  Przykład: Przyjmijmy, że użyto identyfikatora LCN.value.0.10.r1. Ta nazwa za wiele nie mówi, o tym, co kryje się w zmiennej R1 modułu LCN z adresem 10. Natomiast jeżeli w kolumnie Nazwa wpiszemy temperatura_salon, wówczas dużo łatwiej będzie zrozumieć przeznaczenie danej metryki. Jest to sporym ułatwieniem zwłaszcza przy definiowaniu wykresów w oprogramowaniu Grafana.
  
  Jeżeli kolumna Nazwa nie zostanie uzupełniona dla danej metryki, wówczas w czasie tworzenia wykresu należy odwoływać się wprost do nazwy identyfikatora, ale w miejsce kropek należy używać znaków podkreślenia i małych liter. Nie wolno tu używać spacji i polskich znaków!
  Przykład: Jeżeli użyjemy identyfikatora LCN.value.0.10.r1, wówczas w definicji wykresu należy użyć lcn_value_0_10_r1. Oprogramowanie Grafana ułatwia nam pracę, ponieważ ma mechanizm podpowiadania nazw metryk.
  
• W kolumnie Opis możesz wpisać dowolny opis dotyczący metryki.

Wg powyższej procedury zdefiniuj tyle metryk ile potrzebujesz, a na końcu zapisz zakładkę wykresy.

3. Uruchomienie Grafany #

Po zainstalowaniu i uruchomieniu serwera Prometheus i Grafana (patrz dokumentacja obu programów), czas na utworzenie pierwszego wykresu. Domyślnie po zainstalowaniu serwer Grafana pracuje na porcie 3000. Zatem, aby uruchomić interfejs konfiguracyjny Grafany, w przeglądarce internetowej wpisz: http://<adres_ip>:3000, gdzie <adres_ip>, to adres IP urządzenia, na którym zainstalowano Grafanę, np. http://192.168.1.100:3000. Interfejs Grafana jest w języku angielskim. W dalszej części opisu konfiguracji Grafana, będziemy bazować na przykładzie, gdzie zarówno Grafana, jak i Prometheus są zainstalowane na tym samym urządzeniu.

3.1. Konfiguracja źródła danych #

Pierwszym krokiem jest zdefiniowanie źródła danych, z których będzie korzystać Grafana. W tym celu kliknij: Configuration -> Data Sources -> Add data source. Następnie skonfiguruj źródło danych zgodnie z poniższym obrazkiem:

W polu Name możesz użyć dowolnej innej nazwy dla definiowanego źródła danych.
Pole URL należy dostosować do użytych ustawień serwera Prometheus. Jeżeli nie wprowadziłeś żadnych zmian, wówczas zostaw to pole z domyślną wartością.

Parametr Scrape interval oznacza częstotliwość z jaką Grafana odpytuje o dane. Nie należy wpisywać wartości mniejszych niż 15s, gdyż moduł Base nie zezwala na częstsze odpytywanie.

3.2. Konfiguracja tablicy #

Kolejnym krokiem jest zdefiniowanie tablicy, na której wyświetlane będą wykresy. Tablice pozwalają uporządkować wykresy i grupować je np. wg tematyki. Możesz mieć osobną tablicę dla każdego typu wykresów, np. jedną tablicę dla wszystkich wykresów temperatur, inną dla wykresów zużycia mediów itd.

Aby dodać nową tablicę, na pasku narzędzi po lewej stronie kliknij ikonę + -> Dashboard.
Następnie kliknij ikonkę koła zębatego na górnym pasku narzędzi, aby wejść w ustawienia tablicy. W sekcji General, w polu Name wpisz nazwę utworzonej tablicy.

3.3. Pierwszy wykres #

Aby dodać wykres, kliknij ikonę wykresu z plusem na górnym pasku narzędzi. W oknie głównym wybierz opcję Graph. W rezultacie powinieneś zobaczyć wykres. Na tą chwilę nie pokazuje on realnych danych. Aby to zmienić kliknij na belce tytułowej wykresu (domyślnie Panel Title) i wybierz opcję Edit. Poniżej wykresu zobaczysz zestaw narzędzi do jego edycji.

Wybierz zakładkę Metrics. W polu Data Source wybierz nazwę źródła danych, które utworzyłeś. W naszym przykładzie prometheus. W dolnej części zakładki Metrics należy wskazać, którą metrykę chcesz zobrazować na wykresie. Kliknij w polu obok litery A i zacznij wpisywać nazwę metryki zdefiniowanej w konfiguratorze (Grafana ma autouzupełnianie). W naszym przypadku temperatura_salon. Po wpisaniu nazwy metryki kliknij w dowolnym miejscu okna, aby zatwierdzić w ten sposób wpisaną nazwę. W tym momencie wykres powinien stać się widoczny.

W pojedynczym panelu wykresu możesz wyświetlić wykresy dla wielu metryk. W tym celu należy dodać kolejne definicje metryk. Kliknij przycisk Add Query, aby dodać nowy wiersz. Każda kolejna definicja metryki otrzyma kolejną literę alfabetu.

W zakładce General, w polu Title możesz nadać tytuł wykresu. Pozostałe zakładki służą do formatowania wykresu (m.in kolor, skala, typ prezentacji). Zapoznaj się z dokumentacją Grafany i poeksperymentuj, aby przekonać się do czego służą poszczególne opcje.

Dla paneli, w których jest umieszczonych kilka wykresów warto zdefiniować legendę. Domyślnie legenda będzie wyświetlona w dolnej części okna. Kliknięcie na elemencie legendy powoduje wyświetlenie wyłącznie wykresu, którego ten element legendy dotyczy. Ponowne kliknięcie na tym samym elemencie legendy przywraca widoczność wszystkich wykresów w obrębie tego panelu.

Aby zapisać wykres kliknij na ikonie dyskietki na górnym pasku narzędzi.

Wykres temperatur z LCN

Temperatury w systemie LCN są kodowane wg wzoru tlcn=tc*10+1000, gdzie tc to temperatura w stopniach Celsjusza, tlcn, to temperatura w skali LCN.

Pole do wpisywania nazw metryk w zakładce Metrics ma oprócz swojej podstawowej roli zdecydowanie większe możliwości, które na pewno odkryjesz wraz z używaniem Grafany. Jedną z nich jest możliwość stosowania formuł matematycznych do przeliczania danych zawartych w metryce. Dzięki temu z łatwością możemy zrobić przekształcenie temperatury w skali LCN na stopnie Celsjusza. W polu,gdzie należy wpisać nazwę metryki wpisz: (temperatura_salon-1000)/10. Oczywiście zastąp nazwę metryki swoją własną.

3.4. Wykresy w Remote #

Aplikacja Remote umożliwia wyświetlanie pojedynczych paneli wykresów (także tych, w których jest kilka wykresów), jak i całych tablic składających się z wielu paneli wykresów.

Wyświetlanie tablicy wykresów

W aplikacji Grafana, przejdź do widoku danej tablicy i skopiuj adres URL z okna przeglądarki. Następnie przejdź do konfiguratora modułu Base. Wybierz zakładkę Remote i dodaj kontrolkę typu Wykres. Kliknij na niej dwukrotnie, aby ją wyedytować. W polu Lokalny adres URL wklej adres skopiowany z przeglądarki internetowej. Jeżeli wykres ma być dostępny poza siecią lokalną, wówczas w polu Zdalny adres URL należy wprowadzić adres tablicy, który jest osiągalny z Internetu.
Przykład tablicy wyświetlonej w aplikacji Remote

Wyświetlanie panelu wykresów

W aplikacji Grafana przejdź do widoku tablicy, gdzie znajduje się interesujący Cię wykres. Kliknij na wykresie i z menu wybierz opcję View. Następnie skopiuj adres URL z okna przeglądarki. Resztę czynności wykonaj analogicznie, jak w przypadku tablicy wykresów.
Zmiany potwierdź zapisaniem zakładki Remote.

Przykład panelu wykresów zawierających dane z czujników systemu wentylacji:

Zakresy czasowe na wykresach

Kontrolka Wykres wyświetla domyślnie wykres dla ostatnich 24 godzin. Aby zmienić zakres czasowy prezentowanych danych, kliknij ikonę w górnym rogu aplikacji i wybierz interesujący Cię zakres danych. Zmiana zakresu czasowego ma odniesienie zarówno do pojedynczego panelu wykresów, jak i do tablicy.

3.5. Alarmy #

Grafana umożliwia tworzenie alarmów. Alarmy pozwalają obserwować i analizować dane prezentowane na wykresie i podejmować akcje według określonych reguł. Alarm może być przykładowo wywołany, gdy wartość na wykresie przekroczy określony próg. Jeżeli nie dokonujesz analizy danych w Grafanie, to wystarczy, że utworzysz zdarzenie dla zmian wartości obserwowanej zmiennej wprost w module Base. Ważne jest, aby nie sprowadzić alarmów w Grafanie do funkcji, którą w tej chwili pełnią zdarzenia w Base.

Jednakże, jeżeli dane, które Grafana odczytuje z Base są poddawane obróbce i zachodzi konieczność poinformowania systemu automatyki (modułu Base) o tym, że zaszło interesujące Cię zdarzenie, wówczas alarmy są tym, czego potrzebujesz. Może również zdarzyć się sytuacja, gdzie dane są odczytywane z innego urządzenia lub systemu, a chcesz wykonać jakąś akcję w systemie DOMIQ, wówczas alarmy także stają się bardzo pomocne.

Jedną z możliwych akcji, które Grafana może wykonać jest wysłanie dowolnego żądania HTTP. Moduł Base udostępnia specjalny adres URL, na który mogą być wysyłane alarmy z Grafany. Odebranie żądania wysłanego na ten URL powoduje rozgłoszenie zdarzenia w Base. Do tego zdarzenia możesz podłączyć wykonanie dowolnych komend. Możliwości są praktyczne nieograniczone.

Jeżeli nie planujesz korzystania z alarmów w Grafanie, wówczas nasz samouczek kończy się w tym miejscu. Jeżeli jednak potrzebujesz alarmów, wówczas zapraszamy Cię do dalszej lektury.

3.5.1. Kanały notyfikacji #

Aby Grafana mogła wysłać alarm do Base konieczne jest zdefiniowanie tzw. kanału notyfikacji. W tym celu w Grafanie kliknij ikonkę dzwonka na bocznym pasku narzędzi i wybierz opcję Notification channels. Następnie kliknij New Channel. Poniżej przedstawiamy przykładową definicję, która wysyła żądanie HTTP do Base.

W polu Name wpisz nazwę kanału notyfikacji (bez polskich znaków).
W polu Type wybierz typ akcji, w naszym przypadku interesuje nas webhook.
W polu Url wpisz adres w następującym formacie:
http://<IP_BASE>/grafana/alert/<nazwa_alarmu>, gdzie <IP_BASE> zastąp adresem IP modułu Base, a <nazwa_alarmu> powinna zawierać informację czego alarm dotyczy. Fragment adresu /grafana/alert/ jest niezmienny i powinien być w każdym kanale notyfikacji, który ma służyć do wysyłania alarmów do Base.

Kolejnym krokiem jest zdefiniowanie alarmu dla konkretnego wykresu. W tym celu wyedytuj panel z interesującym Cię wykresem. Następnie wybierz zakładkę Alert i kliknij Create Alert. W oknie, które się wyświetli należy zdefiniować reguły sterujące wywoływanie alarmu (zakładka Alert Config). W zakładce Notifications, w polu Send to należy wskazać kanał notyfikacji, na który ma zostać wysłany alarm. Na koniec należy zapisać konfigurację wykresu. Każde spełnienie reguły alarmu wyśle żądanie do modułu Base wg ustalonej reguły.

Po stronie modułu Base wygenerowane zostanie następujące zdarzenie: E.GRAFANA.alert=<nazwa_alarmu>, gdzie <nazwa_alarmu> jest tożsama z nazwą wprowadzoną w czasie definiowania kanału notyfikacji.

Przykłady

Poniżej prezentujemy, kilka przykładowych wykresów, które można wykonać dzięki integracji DOMIQ z Grafaną i Prometheus. Możliwości są naprawdę niesamowite i bardzo cieszymy się, że mogliśmy oddać w Wasze ręce tą funkcjonalność.