Checkmk
to checkmk.com

1. Einleitung

grafana logo

Checkmk verfügt mit seinem integrierten Graphing-System über ein mächtiges Werkzeug zum Aufzeichnen und Visualisieren von Metriken. Dennoch kann es sinnvoll sein, Grafana als externes Graphing-System anzubinden, z.B. weil Sie Grafana bereits nutzen und die Daten von Checkmk mit Daten aus anderen Systemen in gemeinsamen Dashboards zusammenführen möchten.

Ab Grafana 8.x ist es möglich, Checkmk in allen Editionen direkt als Datenquelle anzusprechen und einzelne Metriken oder sogar ganze Graphen, wie sie in Checkmk vordefiniert sind, anzeigen zu lassen. Zusätzlich können Sie dynamisch eigene Graphen erstellen lassen, indem Sie über reguläre Ausdrücke eine Gruppe von Hosts und Services bestimmen, von denen bestimmte Metriken in dem Graphen berücksichtigt werden sollen.

Dieser Artikel beschreibt, wie Sie Ihre Metriken aus Checkmk in Grafana abrufen und darstellen. Screenshots wurden mit Grafana 10.1 erstellt, frühere Versionen weichen in der Benutzerführung etwas davon ab. Eine ausführliche Anleitung, wie Sie Grafana nutzen und konfigurieren können, finden Sie in der Dokumentation bei Grafana Labs.

Das Grafana-Plugin wird unabhängig von Checkmk entwickelt und in einem eigenen Github-Repository gepflegt. Dieser Artikel beschreibt die Einrichtung des Plugins in Version 3.1, welche mit Checkmk 2.1.0 und 2.2.0 zusammenspielt. Da die Installation des Plugins in Grafana erfolgt, ist eine Auslieferung zusammen mit Checkmk nicht sinnvoll.

2. Das Plugin in Grafana installieren

Je nach Installationsart Ihres Grafana-Servers und Ihrer Checkmk-Edition kommen verschiedene Methoden der Plugin-Installation in Frage. Einzige Einschränkung hierbei: Benutzer des Grafana Cloud Angebots müssen die CSE Checkmk Cloud Edition verwenden und das Plugin über die offizielle Grafana Plugin-Sammlung aktivieren. On-Premises-Installationen von Grafana können an alle Checkmk-Editionen angebunden werden.

2.1. Installation auf der Kommandozeile (Cloud Edition, eigener Grafana-Server)

Diese Installationsart setzt die Verwendung von CSE Checkmk Cloud Edition voraus. Bei Betrieb von Grafana auf einem eigenen Server ist dort die Installation aus der Grafana Plugin-Sammlung via Kommandozeile möglich:

root@linux# grafana-cli plugins install checkmk-cloud-datasource

Starten Sie den Grafana-Serverdienst neu:

root@linux# systemctl restart grafana-server

Anschließend ist das Plugin in der Oberfläche von Grafana verfügbar und kann aktiviert und eingerichtet werden.

2.2. Installation aus der Grafana Cloud GUI (Cloud Edition, Grafana Cloud)

Loggen Sie sich zuerst in der Grafana-Instanz ein, in der Sie die Checkmk-Datenquelle installieren wollen. Rufen Sie dann die Seite der Datenquelle in der Grafana Plugin-Sammlung auf. Im Reiter Installation setzen Sie ein Häkchen bei der Grafana-Instanz, die das Plugin erhalten soll und klicken anschließend auf den Knopf Install. Bis das Plugin im Web-Interface der Grafana-Installation verfügbar ist, können wenige Minuten vergehen.

2.3. Installation aus Zip-Archiv (alle Editionen, eigener Grafana-Server)

Auf der Releases-Seite des GitHub-Repositories finden Sie zwei Varianten des Plugins als Zip-Archiv:

  • Die oben erwähnte signierte Variante checkmk-cloud-datasource-X.Y.Z.zip, die nur mit der Cloud Edition genutzt werden kann.

  • Eine Variante, die das alte Namensschema tribe-29-checkmk-datasource-X.Y.Z.zip nutzt, für alle Editionen von Checkmk 2.1.0 an aufwärts.

Laden Sie einfach die aktuellste Version als Zip-Datei herunter und kopieren Sie sie, zum Beispiel mit scp, auf den Grafana-Server.

grafana download plugin

Statt über den Browser können Sie die Datei natürlich auch direkt über die Kommandozeile laden. Beachten Sie, dass Sie dafür die aktuelle Version wissen müssen – im folgenden Beispiel schreiben wir die Version in die Variable $plugvers.

root@linux# plugvers='3.1.1'
root@linux# wget https://github.com/Checkmk/grafana-checkmk-datasource/releases/download/v${plugvers}/tribe-29-checkmk-datasource-${plugvers}.zip

Entpacken Sie jetzt das Zip-Archiv:

root@linux# unzip tribe-29-checkmk-datasource-${plugvers}.zip

Erstellen Sie ein Plugin-Verzeichnis, falls dieses noch nicht existiert, und machen Sie den Linux-Benutzer, unter dessen Kennung die Grafana-Prozesse ausgeführt werden (meist grafana) zu dessen Eigentümer:

root@linux# mkdir -p /var/lib/grafana/plugins
root@linux# chown grafana:grafana /var/lib/grafana/plugins

Verschieben Sie den entstandenen Ordner in das Plugin-Verzeichnis von Grafana. Üblicherweise ist das der Pfad /var/lib/grafana/plugins/:

root@linux# mv -v tribe-29-checkmk-datasource /var/lib/grafana/plugins/tribe-29-checkmk-datasource

Ändern Sie den Eigentümer auf den Grafana-Benutzer:

root@linux# chown -R grafana:grafana /var/lib/grafana/plugins/tribe-29-checkmk-datasource

Eine Installation über das Klonen des Git-Archivs (wie es früher in diesem Artikel beschrieben wurde) ist nicht mehr möglich. Falls Sie am Plugin mitentwickeln wollen, lesen Sie die Hinweise für Entwickler.

Nicht signierte Plugins zulassen

Seit Grafana 8.0 ist es nicht mehr ohne Weiteres möglich, externe Plugins einzubinden, solange sie nicht signiert sind. Das trifft auch auf das Checkmk-Plugin zu, so dass Sie einen zusätzlichen Schritt benötigen.

Passen Sie dazu die Konfigurationsdatei /etc/grafana/grafana.ini im Abschnitt [plugins] an. Ändern Sie hier die Zeile ;allow_loading_unsigned_plugins = wie folgt. Achten Sie dabei darauf, das Semikolon am Zeilenanfang zu entfernen:

/etc/grafana/grafana.ini
[plugins]
allow_loading_unsigned_plugins = tribe-29-checkmk-datasource

Mit dieser Einstellung fügen Sie eine Ausnahme für dieses eine Plugin hinzu. Sollten Sie Grafana in einem (Docker-) Container einsetzen, haben Sie verschiedene Möglichkeiten, Änderungen an der Grafana-Konfiguration vorzunehmen. Sind nur kleine Konfigurationsänderungen nötig, können diese über Umgebungsvariablen vorgenommen werden:

user@host:~$ sudo docker run -d \
-e GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=tribe-29-checkmk-datasource \
-p 3000:3000 --name grafana \
-v grafana-plugins:/var/lib/grafana/plugins \
-v grafana-db:/var/lib/grafana grafana/grafana

Falls größere Anpassungen an der INI-Datei oder dem gesamten /etc/grafana/ erforderlich sind, verlinken Sie entweder die angepasste INI-Datei in den Container oder erstellen ein Volume, welches Sie auf das Verzeichnis im Container (/etc/grafana/) mappen. Es folgt ein Beispiel, wie Sie mit --mount die INI-Datei verlinken. Beachten Sie, dass es sich hier nur um ein Beispiel handelt und wahrscheinlich nicht direkt auf Ihre Umgebung passt:

user@host:~$ sudo docker run -d \
--mount type=bind,source=/home/user/grafana/grafana.ini,target=/etc/grafana/grafana.ini \
-p 3000:3000 --name grafana \
-v grafana-plugins:/var/lib/grafana/plugins \
-v grafana-db:/var/lib/grafana grafana/grafana

Neustart des Grafana-Dienstes

Nach der Installation des Plugins, Updates oder einer Änderung der Konfigurationsdatei starten Sie den Grafana-Serverdienst neu:

root@linux# systemctl restart grafana-server

Anschließend ist das Plugin in der Oberfläche von Grafana verfügbar und kann aktiviert und eingerichtet werden.

3. Grafana-Benutzer in Checkmk erstellen

Die Grafana-Anbindung benötigt auf Seite von Checkmk einen Benutzer, der über ausreichende Berechtigungen verfügt und sich zudem über ein Automationspasswort (automation secret) statt eines Passworts authentifiziert. Normale Gast- oder Monitoring-Benutzer genügen nicht, aus Sicherheitsgründen sollten Sie jedoch keinen Administrator verwenden.

Der einfachste Weg zu einem "passenden" Benutzer ist, die Rolle des Gastbenutzers (guest) zu klonen und mit der zusätzlichen Berechtigung User management (lesender Zugriff auf Benutzerinformationen) zu versehen. Falls Sie Ihre Grafana-Benutzerrolle auf einer anderen Rolle basieren lassen, achten Sie darauf, dass neben User management auch die Berechtigung See all host and services gesetzt ist.

Ist die Rolle erstellt, legen Sie einen oder mehrere Grafana-Benutzer mit Automationspasswort (automation secret) an. Der Rolle zugewiesene Berechtigungen können Sie später weiter einschränken, beispielsweise wird kein Zugriff auf BI oder die Event Console benötigt.

4. Plugin aktivieren und einrichten

Nachdem die notwendigen Dateien installiert wurden, können Sie das Plugin in Grafana aktivieren. Wechseln Sie dazu in die Konfiguration und wählen den Reiter Data sources aus. Hier können Sie über den Knopf Add data source eine neue Datenquelle hinzufügen:

grafana plugins overview

Den Eintrag zu Checkmk finden Sie unten in der Kategorie Others:

grafana plugin cmk

Das Formular zu dieser Datenquelle ist recht einfach gehalten. Geben Sie hier die URL zu Ihrer Instanz, den Typ Ihrer Edition und den soeben für Grafana angelegten Benutzer ein. Wichtig: Wenn Sie Checkmk in einer verteilten Umgebung verwenden, dann geben Sie hier die URL zu Ihrer Zentralinstanz an:

grafana plugin config

Falls Sie mehrere Checkmk-Instanzen anbinden möchten, können Sie die einzelnen Verbindungen optional mit einem eindeutigen Namen versehen. Ansonsten lassen Sie den Standard Checkmk respektive Checkmk for Cloud Edition einfach stehen.

Nachdem Sie die Verbindung mit dem Knopf Save & test gespeichert haben, steht sie Ihnen als Datenquelle in Grafana zur Verfügung und Sie können Ihre ersten Graphen konfigurieren.

5. Graphen erstellen

5.1. Ein leeres Dashboard erzeugen

Unter Home > Dashboards finden Sie ein Drop-down-Menü, welches mit dem Pluszeichen gekennzeichnet ist. Klicken Sie dort auf New dashboard, um ein neues Dashboard zu erstellen:

grafana new dashboard

5.2. Eine einzelne Metrik eines Hosts anzeigen

Das einfachste Dashboard zeigt einen einzigen Graphen eines Services eines Hosts. Dies kann auch die Metrik eines lokalen Checks sein, für den keine vorgefertigten Graphen existieren. In einem bestehenden oder dem eben erzeugten Dashboard erstellen Sie eine neue Visualisierung. Wählen Sie hier zuerst Add visualization aus:

grafana dashboard addpanel

Mit Erstellung der Visualisierung gelangen Sie zur Auswahl der Datenquelle. Nach der Auswahl von Checkmk befinden Sie sich direkt im Editiermodus der Abfrage (Query) für das neu erstellte Panel. Ein Panel ist ein Container für eine Visualisierung.

Der Zugriff auf zu visualisierende Daten unterscheidet sich etwas zwischen der CRE Checkmk Raw Edition und den kommerziellen Editionen: In der Raw Edition arbeiten Sie mit vordefinierten Menüs für Instanz, Host-Name, Service und so weiter. In den kommerziellen Editionen haben Sie die Möglichkeit, Kaskaden von Filtern zu bestimmen. Dies erlaubt eine sehr detaillierte Auswahl auch unter Verwendung regulärer Ausdrücke. Das folgende einfache Beispiel ist so gewählt, dass Sie es mit allen Editionen durchspielen können.

Wählen Sie zunächst die Site, danach filtern Sie nach einem Hostname im Monitoring. Nutzen Sie für den ersten Test einen beliebigen Host, der den Windows- oder Linux-Agenten nutzt. Als Service wählen Sie Check_MK. Setzen Sie den Typ der Aggregation auf Maximum. Als Graph type stehen Single metric oder Predefined graph (vordefinierte Graphen) zur Auswahl: Predefined graphs übernehmen Metriken aus Checkmk, welche auch kombinierte Graphen enthalten können. Unsere Screenshots zeigen hier die Single metric, welche die Gesamtausführungszeit des Agenten (Time spent waiting for Checkmk agent) enthält.

grafana dashboard single config
Auswahl der Metriken über Filter in den kommerziellen Editionen
grafana dashboard single config cre
Auswahl der Metriken über vordefinierte Menüs in der Raw Edition

Grafana zeigt das Ergebnis direkt an. Mit dem Knopf Apply können Sie den Graphen anwenden ohne das Dashboard zu sichern. Mit Save werden Sie aufgefordert, einen Titel für das neue Dashboard anzugeben und speichern schließlich das neu erstellte Dashboard.

grafana dashboard single view
Neues Dashboard mit wiedererkennbarer Benennung

5.3. Einen vordefinierten Graphen aus Checkmk anzeigen

Die Entwickler von Checkmk haben bereits viele korrespondierende Metriken in gemeinsamen Graphen zusammengefasst, damit Benutzer leichter einen Überblick über verschiedene Aspekte einer einzigen Ressource erhalten. Sie können die Metriken aus einem solchen vorgefertigten Graphen direkt in Grafana anzeigen lassen.

Die Vorgehensweise entspricht zunächst der im vorherigen Abschnitt erläuterten. Allerdings wählen Sie zum Abschluss als Graph type den Eintrag Predefined graph und den zu verwendenden Predefined graph des Services.

Sollten Sie eine Fehlermeldung erhalten, dass die Auswahl kombinierter Metriken mit mehr als 200 Elementen unzulässig ist, schränken Sie mit weiteren Filtern ein. Stellen Sie im Zweifel die Filter nach vorne, die eine deutliche Einschränkung der Ergebnismenge versprechen.

grafana dashboard predefined config

Sind Sie mit der getroffenen Auswahl zufrieden, klicken Sie den Knopf Apply. Der Graph ist nun im gewählten Dashboard verfügbar.

grafana dashboard predefined view

5.4. Komplexe Graphen erstellen

Gerade in einem dynamischen Cluster möchte man oft den gesamten Verlauf einer Metrik über alle beteiligten Hosts verfolgen können, ohne einen Graphen jedes Mal anpassen zu müssen, wenn ein neuer Knoten hinzukommt oder wegfällt. Um dies zu erreichen, haben Sie verschiedene Möglichkeiten, Graphen dynamisch anzupassen.

Die erste Möglichkeit besteht in der Filterung nach Host Labels oder Host Tags statt der Auswahl einzelner Hosts. Eine weitere Möglichkeit ist die Verwendung regulärer Ausdrücke. Sie können reguläre Ausdrücke auf Hosts oder Services anwenden. Im folgenden Beispiel matcht filesystem alle Services, die filesystem enthalten – egal, wie viele Dateisysteme ein Host eingebunden hat.

grafana dashboard combined config

Mit filesystem.*nvme würden Sie die Auswahl auf alle Dateisysteme auf NVMe-Laufwerken einschränken, ganz gleichen welchen Dateisystemtyp diese nutzen, da der Teil des Strings zwischen filesystem und nvme beliebig sein kann.

Zusätzlich zu den erweiterten Filtermöglichkeiten bestimmen Sie mit Aggregation die Darstellung der Metriken im Graphen und mit Graph, welcher Graph als Referenz herangezogen werden soll. Beachten Sie, dass nur dann Metriken zu einem Host/Service angezeigt werden, wenn dieser auch über den ausgewählten Graphen verfügt. Der Graph sieht dann zum Beispiel so aus:

grafana dashboard combined view

5.5. Umbenennung über reguläre Ausdrücke

Im Editiermodus jedes Panels finden Sie einen Reiter Transform. Mit dem hier vorhandenen Unterpunkt Rename by regex können Sie die Bezeichnung von Metriken umsortieren oder nicht benötigte Informationen unterdrücken. Unser folgendes Beispiel sucht zwei durch Komma und folgendes Leerzeichen getrennte Zeichengruppen, vertauscht diese und stellt explizit Service und Host vorne an:

grafana series renaming regex

Die Variablen $1 und $2 entsprechen hierbei den in der Zeile darüber „eingefangenen“ Zeichenketten (Match-Gruppen oder Capture Groups). Grafana erlaubt auch verschachtelte Match-Gruppen. Einen Überblick über deren Möglichkeiten zeigt der entsprechende Abschnitt im Artikel zu regulären Ausdrücken.

6. Flexiblere Graphen mit Variablen

Über Variablen können Sie Dashboards flexibel mit Graphen versehen. So haben Sie die Möglichkeit per Drop-down-Auswahl den Host einer bestimmten Metrik zu bestimmen oder Sie nutzen Variablen, um Graphen für mehrere Hosts auf einen Schlag einem Dashboard hinzuzufügen. Dieser Artikel kann und soll nicht die Dokumentation bei Grafana ersetzen. In erster Linie wollen wir einen Überblick der Einsatzmöglichkeiten und einen Einstieg in das Thema vermitteln.

Variablen können aus Queries erstellt werden. In diesem Fall können Sie auf Sites, Hosts oder Services filtern. Alternativ haben Sie die Möglichkeit, Mengen oder Freitextfelder zu definieren, was beliebige Filter ermöglicht.

6.1. Variablen erstellen

Jede Variable ist eine Eigenschaft eines Dashboards. Sie muss in den Einstellungen des Dashboards erstellt werden und kann dann nur innerhalb dieses Dashboards verwendet werden. Da Query die umfangreichste Konfiguration erfordert, zeigen wir dessen Verwendung in unserem Beispiel.

Die relevanten Eigenschaften einer Variablen sind ihr Typ und ihr Name, alle anderen Eigenschaften dienen nur der Übersichtlichkeit im Dashboard. Der Name sollte Unterscheidungen unterstützen. Wenn Sie also planen, mehrere Variablen zur Auswahl von Hosts aus verschiedenen Untermengen zu nutzen, verwenden Sie statt host wie im Beispiel einen Namen, der auf diese Menge referenziert, zum Beispiel host_from_linuxservers.

grafana variable name
Erstellung einer Variable host in den Dashboard-Eigenschaften

Achten Sie bei der Wahl der Datenquelle darauf, dass eine Checkmk-Verbindung ausgewählt ist. Den gewählten Objekttyp können sie weiter einschränken, zum Beispiel mit regulären Ausdrücken. Verwendete Filter werden auf dem Checkmk-Server ausgewertet. Dagegen werden die folgenden Felder Regex und Sort von Grafana ausgewertet.

grafana variable query
Mit Filtern legen Sie fest, welche Werte die Variable annehmen kann

Die beiden Checkboxen für Selection options ganz unten auf der Seite sind von der späteren Verwendung abhängig. Sie können diese bei Bedarf jederzeit anpassen, lassen Sie für den ersten Test beide auf der (leeren) Voreinstellung. Speichern Sie die Variablen mittels Save dashboard, wenn Sie alle Einstellungen vorgenommen haben.

6.2. Variablen für Graphen nutzen

Sie können die vergebenen Variablen nun in die dafür passenden Felder eintragen um einen flexiblen Graphen zu erstellen. Die Verwendung der Variablen ist zudem im Titel des Graphen möglich.

grafana variable use
Der Zugriff auf Variablennamen geschieht, wie in einigen Shells, über das vorangestellte Dollarzeichen

Im Dashboard wird für jede Variable eine Drop-down-Auswahl angezeigt, über die Sie einstellen, für welche Variablenwerte (Hosts, Services…​) Sie das Dashboard anzeigen lassen. Wenn Sie Mehrfachauswahl aktiviert haben, können Sie in den Einstellungen des Panels die Option Repeat by variable setzen, um das Panel für jeden ausgewählten Variablenwert anzuzeigen.

grafana variable panel
Drop-down-Auswahl der referenzierten Hosts mit Möglichkeit der Mehrfachauswahl

7. Dateien und Verzeichnisse

Die folgenden Dateien und Verzeichnisse sind auf einem selbst gehosteten Grafana-Server relevant.

Pfad Bedeutung

/var/lib/grafana/plugins/

Hier sucht Grafana nach (neuen) Plugins. Jedes Plugin bekommt dabei ein eigenes Unterverzeichnis. Das Plugin von Checkmk legen Sie daher hier ab.

/etc/grafana/

Konfigurationsverzeichnis von Grafana.

/etc/grafana/grafana.ini

Zentrale Konfigurationsdatei von Grafana. Hier legen Sie fest, welche nicht signierten Plugins Sie zulassen.

Auf dieser Seite