In diesem Tutorial beschreiben wir die Integration von DOMIQ mit der Software Prometheus und Grafana. Dank dieser Integration hat unser System völlig neue Möglichkeiten im Bereich der Diagrammerstellung gewonnen.
Die Möglichkeit, interessante Werte in einem Diagramm darzustellen, ist eine der begehrtesten Funktionen eines Smart Homes. Ab sofort kannst du ohne Probleme z. B. ein Diagramm des Strom-, Wasser- oder Gasverbrauchs erstellen, Temperaturverläufe oder Parameter des Lüftungssystems in einem beliebigen Zeitraum anzeigen. Die Möglichkeiten sind unbegrenzt – du kannst ein Diagramm jeder beliebigen Variablen erstellen, die im DOMIQ-System vorkommt.
In diesem Kapitel zeigen wir auf, welche Geräte in der Installation vorhanden sein müssen und welche Rolle sie spielen, um den neuen Diagrammmechanismus nutzen zu können.
Die Diagramm-Anzeige wird in der Remote-App initiiert, die eine Anfrage an Grafana sendet. Grafana holt die zur Darstellung benötigten Daten vom Prometheus-Server für den definierten Zeitbereich. Die Daten werden verarbeitet und als fertiges Diagramm an die Remote-App zurückgesendet. Der Datenaustausch zwischen Prometheus und Base erfolgt unabhängig und zyklisch, in einem festgelegten Intervall. Die Prometheus-Anwendung ist Initiator dieses Austauschs.
In diesem Tutorial werden wir nicht den Installationsprozess von Prometheus und Grafana im Detail darstellen, da dies ausführlich von den Softwareanbietern beschrieben wurde. Stattdessen werden wir einige Konfigurationsdetails beider Anwendungen erläutern, damit sie mit dem Base-Modul und der Remote-App zusammenarbeiten können.
Nach erfolgreicher Installation der Prometheus-Anwendung findest du im Installationsordner die Konfigurationsdatei prometheus.yml. Öffne die Datei in einem beliebigen Texteditor und passe die Einstellungen gemäß den folgenden Hinweisen an. Unten siehst du eine Beispielkonfiguration aus unserer Testinstallation:
# 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 job_name ist der Name, der als Legendenbeschriftung in den Diagrammen verwendet wird. In unserem Fall kann der Name beliebig gewählt werden, ohne Leerzeichen oder Sonderzeichen. Im Beispiel: base.
metrics_path: '/prometheus/metrics' – dies ist der Pfad, über den Metriken vom Base-Modul abgefragt werden. Dieser Parameter muss genau diesen Wert haben, sonst ist der Datenabruf nicht möglich. static_configs:
targets: ['192.168.1.30:80']
dies ist die Adresse und der Webport des Base-Moduls. Bei einer Installation auf einem externen Server muss hier die öffentliche Adresse des Base-Moduls angegeben werden.
Nach erfolgreicher Installation der Grafana-Anwendung findest du im Ordner conf die Konfigurationsdatei custom.ini. Öffne sie in einem beliebigen Texteditor und passe die Einstellungen wie folgt an:
# 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 – hier kannst du die Portnummer eingeben, unter der Grafana erreichbar ist (du kannst auch den Standardwert belassen).domain – dieses Feld leer lassen (also „localhost“ entfernen).auto_assign_org_role – ändere den Wert auf Editor.
# enable anonymous access
enabled = true
Wenn Sie enabled auf false setzen, erfordert jede an Grafana gesendete Anfrage einen Benutzernamen und ein Kennwort.
[auth.basic]
enabled = false
Auf false setzen, um die Kennwortprüfung zu deaktivieren.
Im Einführungsteil des Tutorials haben wir die Metriken erwähnt. Die Definition von Metriken ist ein notwendiger Schritt, damit Grafana die gewünschten Diagramme anzeigen kann. Metriken sind nichts anderes als Variablendefinitionen, die Grafana aus dem Base-Modul ausliest. Metriken werden im Tab Diagramme im Base-Konfigurator definiert.
Der Tab hat drei Spalten: Bezeichner, Name und Beschreibung. Um einen neuen Eintrag hinzuzufügen, klicke auf Hinzufügen und konfiguriere wie folgt:
Definiere auf diese Weise alle benötigten Metriken und speichere dann den Reiter „Diagramme“.
Nach der Installation und dem Start des Prometheus- und Grafana-Servers (siehe Dokumentation beider Programme) ist es an der Zeit, das erste Diagramm zu erstellen. Standardmäßig läuft der Grafana-Server nach der Installation auf Port 3000. Um die Konfigurationsoberfläche von Grafana zu öffnen, gib in deinem Webbrowser ein: http://<adres_ip>:3000 wobei <adres_ip> die IP-Adresse des Geräts ist, auf dem Grafana installiert ist, z. B. http://192.168.1.100:3000 . Die Benutzeroberfläche von Grafana ist in englischer Sprache.
Im weiteren Verlauf der Grafana-Konfiguration beziehen wir uns auf ein Beispiel, bei dem sowohl Grafana als auch Prometheus auf demselben Gerät installiert sind.
Der erste Schritt besteht darin, die Datenquelle zu definieren, die Grafana verwenden wird. Klicke dazu:
Configuration -> Data Sources -> Add data source. Dann konfiguriere die Datenquelle wie auf dem folgenden Bild dargestellt:
Im Feld Name kannst du einen beliebigen Namen für die Datenquelle vergeben.
Das Feld URL muss an die Einstellungen des Prometheus-Servers angepasst werden. Wenn du nichts verändert hast, kannst du den Standardwert beibehalten.
Der Parameter Scrape interval bestimmt, wie oft Grafana die Daten abfragt. Gib hier keine Werte unter 15 Sekunden ein, da das Base-Modul häufigere Abfragen nicht erlaubt.
Der nächste Schritt ist die Definition eines Dashboards, auf dem die Diagramme angezeigt werden. Dashboards ermöglichen die Organisation und Gruppierung von Diagrammen, z. B. thematisch. Du kannst ein separates Dashboard für jeden Diagrammtyp erstellen, z. B. ein Dashboard für alle Temperaturdiagramme, ein anderes für Medienverbrauch usw.
Um ein neues Dashboard hinzuzufügen, klicke in der linken Seitenleiste auf das + Symbol -> Dashboard.
Dann klicke auf das Zahnradsymbol in der oberen Symbolleiste, um die Einstellungen des Dashboards aufzurufen. Im Abschnitt General gib im Feld Name den Namen des erstellten Dashboards ein.
Um ein Diagramm hinzuzufügen, klicke auf das Diagramm-mit-Plus-Symbol in der oberen Symbolleiste.
Wähle im Hauptfenster die Option Graph. Du solltest nun ein Diagramm sehen. Aktuell zeigt es noch keine realen Daten. Um dies zu ändern, klicke auf die Titelleiste des Diagramms (standardmäßig „Panel Title“) und wähle Edit. Unterhalb des Diagramms erscheint nun ein Werkzeugbereich zur Bearbeitung.
Wähle den Tab Metrics. Im Feld Data Source wähle den Namen der Datenquelle, die du erstellt hast – in unserem Beispiel „prometheus“. Im unteren Bereich des Tabs Metrics gib an, welche Metrik im Diagramm dargestellt werden soll. Klicke im Feld neben dem Buchstaben A und beginne mit der Eingabe des Metriknamens aus dem Konfigurator (Grafana unterstützt Auto-Vervollständigung). In unserem Beispiel: temperatur_wohnzimmer. Klicke irgendwo im Fenster, um die Eingabe zu bestätigen. Jetzt sollte das Diagramm sichtbar werden.
In einem einzigen Diagrammpanel kannst du mehrere Metriken anzeigen. Klicke auf Add Query, um eine weitere Metrikdefinition hinzuzufügen. Jede neue Metrik erhält einen weiteren Buchstaben des Alphabets.
Im Tab General, im Feld Title, kannst du einen Diagrammtitel festlegen. Die weiteren Tabs dienen der Diagrammformatierung (z. B. Farbe, Skala, Darstellungstyp). Mach dich mit der Grafana-Dokumentation vertraut und probiere ruhig die Optionen aus, um herauszufinden, was sie bewirken.
Für Panels mit mehreren Diagrammen empfiehlt es sich, eine Legende zu definieren. Standardmäßig wird die Legende unten im Fenster angezeigt. Ein Klick auf ein Legendenelement zeigt nur das zugehörige Diagramm an. Ein weiterer Klick blendet wieder alle Diagramme im Panel ein.
Um das Diagramm zu speichern, klicke auf das Disketten-Symbol in der oberen Symbolleiste.
Temperaturdiagramm aus LCN
Temperaturen im LCN-System werden nach folgender Formel codiert: tlcn=tc*10+1000, wobei tc die Temperatur in Grad Celsius und tlcn die Temperatur in der LCN-Skala ist.
Das Eingabefeld für Metriknamen im Tab Metrics hat neben seiner Grundfunktion viele zusätzliche Möglichkeiten, die du beim Arbeiten mit Grafana entdecken wirst. Eine davon ist die Möglichkeit, mathematische Formeln zur Umrechnung von Metrikdaten zu verwenden. Dank dieser Funktion kannst du die Temperatur aus der LCN-Skala leicht in Grad Celsius umrechnen. Gib dazu im Metrikfeld ein:
(temperatur_wohnzimmer – 1000)/10 Natürlich ersetzt du temperatur_wohnzimmer durch den Namen deiner eigenen Metrik.
Die Remote-App ermöglicht das Anzeigen einzelner Diagrammpanels (auch solcher mit mehreren Diagrammen) sowie ganzer Dashboards, die aus vielen Panels bestehen.
Dashboard-Anzeige in der Remote-App
In der Grafana-Anwendung öffne die Ansicht des gewünschten Dashboards und kopiere die URL aus dem Browserfenster. Wechsle dann in den Konfigurator des Base-Moduls. Wähle den Tab Remote und füge eine Steuerung vom Typ Diagramm hinzu. Doppelklicke darauf, um sie zu bearbeiten. Im Feld Lokale URL-Adresse füge die kopierte Adresse aus dem Browser ein. Wenn das Diagramm auch außerhalb des lokalen Netzwerks verfügbar sein soll, gib im Feld Externe URL-Adresse eine Adresse ein, die aus dem Internet erreichbar ist.
Beispiel eines Dashboards in der Remote-App:
Anzeige eines einzelnen Diagrammpanels
In der Grafana-App öffne das Dashboard mit dem gewünschten Diagramm. Klicke auf das Diagramm und wähle aus dem Menü die Option View. Kopiere die URL aus dem Browserfenster. Die weiteren Schritte sind analog zur Dashboard-Anzeige. Änderungen bestätigst du durch Speichern des Tabs Remote.
Beispiel eines Diagrammpanels mit Sensordaten des Lüftungssystems:
Zeitbereiche in Diagrammen
Die Diagramm-Steuerung zeigt standardmäßig die Daten der letzten 24 Stunden an. Um den angezeigten Zeitbereich zu ändern, klicke auf das Symbol oben rechts in der Anwendung und wähle den gewünschten Zeitraum aus. Die Änderung betrifft sowohl einzelne Diagrammpanels als auch ganze Dashboards.
Mit Grafana können Sie Alarme erstellen. Mithilfe von Alarmen können Sie in einem Diagramm dargestellte Daten beobachten und analysieren und entsprechend bestimmter Regeln Maßnahmen ergreifen. Beispielsweise kann ein Alarm ausgelöst werden, wenn ein Wert in einem Diagramm einen bestimmten Schwellenwert überschreitet. Wenn Sie die Datenanalyse nicht in Grafana durchführen, reicht es aus, ein Ereignis für Änderungen im Wert der beobachteten Variable direkt im Basismodul zu erstellen. Es ist wichtig, Alarme in Grafana nicht auf die Funktion zu reduzieren, die Ereignisse derzeit in Base erfüllen.
Wenn jedoch die von Grafana aus Base gelesenen Daten verarbeitet werden und Sie das Automatisierungssystem (Base-Modul) darüber informieren müssen, dass ein interessantes Ereignis eingetreten ist, benötigen Sie Alarme. Es kann auch vorkommen, dass Daten von einem anderen Gerät oder System gelesen werden und Sie eine Aktion im DOMIQ-System ausführen möchten. Auch dann sind Alarme sehr hilfreich.
Eine der möglichen Aktionen, die Grafana ausführen kann, ist das Senden einer beliebigen HTTP-Anfrage. Das Basismodul stellt eine spezielle URL bereit, an die Warnungen von Grafana gesendet werden können. Der Empfang einer an diese URL gesendeten Anfrage führt zur Übertragung eines Ereignisses in Base. Sie können die Ausführung beliebiger Befehle mit diesem Ereignis verknüpfen. Die Möglichkeiten sind praktisch endlos.
Wenn Sie nicht vorhaben, Alarme in Grafana zu verwenden, endet unser Tutorial hier. Wenn Sie jedoch Alarme benötigen, laden wir Sie ein, weiterzulesen.
Damit Grafana einen Alarm an das Base-Modul senden kann, muss ein sogenannter Benachrichtigungskanal definiert werden. Öffne dazu in Grafana die Seitenleiste und klicke auf das Glockensymbol. Wähle die Option Notification channels. Klicke dann auf New Channel. Unten zeigen wir eine Beispieldefinition, die eine HTTP-Anfrage an das Base-Modul sendet:
Im Feld Name gib den Namen des Benachrichtigungskanals ein (ohne Sonderzeichen und ohne Leerzeichen).
Im Feld Type wähle den Typ der Aktion – in unserem Fall webhook.
Im Feld Url gib die Adresse im folgenden Format ein:
http://<IP_BASE>/grafana/alert/<alarm_name>, wobei <IP_BASE> ersetzt wird durch die IP-Adresse des Base-Moduls, <alarm_name> enthält Informationen darüber, worum es sich beim Alarm handelt. Der Adressteil /grafana/alert/ ist immer gleich und muss in jedem Benachrichtigungskanal, der für Alarme in Richtung Base dienen soll, enthalten sein.
Der nächste Schritt besteht darin, den Alarm für ein bestimmtes Diagramm zu definieren. Bearbeite dazu das Panel mit dem Diagramm, das dich interessiert. Wechsle dann zur Registerkarte Alert und klicke auf Create Alert. Im nun angezeigten Fenster müssen die Regeln definiert werden, die den Alarm auslösen (Alert Config Tab). Im Tab Notifications, im Feld Send to, wähle den zuvor erstellten Benachrichtigungskanal aus, an den der Alarm gesendet werden soll. Speichere abschließend die Diagrammkonfiguration. Jedes Auslösen der Alarmregel sendet eine HTTP-Anfrage an das Base-Modul nach dem festgelegten Schema.
Auf der Seite des Base-Moduls wird folgendes Ereignis generiert: E.GRAFANA.alert=<alarm_name> wobei <alarm_name> genau dem Namen entspricht, der bei der Definition des Benachrichtigungskanals verwendet wurde.
Beispiele
Nachfolgend zeigen wir einige Beispiel-Diagramme, die mit der Integration von DOMIQ mit Grafana und Prometheus erstellt werden können. Die Möglichkeiten sind wirklich beeindruckend, und wir freuen uns sehr, dass wir dir diese Funktionalität zur Verfügung stellen konnten. 
Powered by BetterDocs
