Checkmk
to checkmk.com

1. Einleitung

grafana logo

Checkmk verfügt mit seinem integrierten Graphingsystem über ein umfangreiches System zum Aufzeichnen und Visualisieren von Metriken. Dennoch kann es sinnvoll sein, Grafana als externes Graphingsystem 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.

Beginnend mit Version 2.0.0 ist es in allen Checkmk-Editionen möglich, Checkmk direkt als Datenquelle in Grafana 8.x anzusprechen und einzelne Metriken oder sogar ganze Graphen, wie sie in Checkmk vordefiniert sind, in Grafana 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. 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. Da die Installation des Plugins in Grafana erfolgen muss, ist Auslieferung zusammen mit Checkmk nicht sinnvoll. Eine Aufnahme in die ofizielle Plugin-Sammlung von Grafana wird gerade durch die Grafana-Maintainer geprüft. Ist diese Prüfung abgeschlossen, wird die Installation direkt aus der Grafana-Oberfläche möglich sein.

2. Das Plugin in Grafana einrichten

2.1. Plugin installieren

Um das Plugin benutzen zu können, haben Sie zwei Möglichkeiten, es Grafana bekannt zu machen:

  • Sie laden die ZIP-Datei aus dem GitHub-Repository herunter und legen die Inhalte manuell in das Plugin-Verzeichnis von Grafana.

  • Sie klonen das GitHub-Projekt direkt in das Plugin-Verzeichnis.

Installation der ZIP-Datei

Dieser Variante ist die einfachste und dann zu bevorzugen, wenn Sie git auf dem Grafana-Server nicht installiert haben und dies auch nicht können/wollen. Laden Sie einfach die aktuellste Version als ZIP-Datei herunter und kopieren Sie diese, z.B. mit scp, auf den Grafana-Server:

grafana download plugin

Alternativ können Sie die Datei natürlich auch direkt über die Kommandozeile laden. Beachten Sie, dass Sie dafür die korrekte Version wissen müssen. In folgendem Befehl wird der Dateiname, so wie er lokal gespeichert werden soll, mit der wget-Option -O festgelegt, da die Datei sonst einfach 2.0b2.zip heißen würde:

root@linux# wget -O grafana-checkmk-datasource-2.0b2.zip https://github.com/tribe29/grafana-checkmk-datasource/archive/refs/tags/2.0b2.zip

Entpacken Sie jetzt das Zip-Archiv und verschieben Sie den entstandenen Ordner in das Plugin-Verzeichnis von Grafana. Üblicherweise ist das der Pfad /var/lib/grafana/plugins/:

root@linux# unzip grafana-checkmk-datasource-2.0b2.zip
root@linux# mv -v grafana-checkmk-datasource-2.0b2 /var/lib/grafana/plugins/grafana-checkmk-datasource

Anschließend fahren Sie mit der Anpassung der Berechtigungen fort.

Installation über das Klonen des Git-Archivs

Die oben beschriebene Variante hat die wenigsten Voraussetzungen und ist auch für weniger versierte Nutzer leicht umsetzbar. Falls Sie aber das Plugin direkt aus dem Git-Archiv beziehen, haben Sie dadurch verschiedene Vorteile:

  • Die Aktualisierung auf eine neue Version geht schnell über diesen Befehl: git pull

  • Sie haben die Möglichkeit, direkt den aktuellen Entwicklungsstand aus dem Archiv zu nutzen, wenn Sie ein neues Features testen wollen: git checkout develop

Um das Plugin mit Hilfe einer Kopie des Archivs zu nutzen, benötigen Sie zwingend das Programm git. Das Vorgehen ist danach recht einfach. Klonen Sie das Archiv in das Plugin-Verzeichnis von Grafana:

root@linux# cd /var/lib/grafana/plugins/
root@linux# git clone https://github.com/tribe29/grafana-checkmk-datasource.git
Cloning into 'grafana-checkmk-datasource'...
remote: Enumerating objects: 541, done.
remote: Total 541 (delta 0), reused 0 (delta 0), pack-reused 541
Receiving objects: 100% (541/541), 291.55 KiB | 0 bytes/s, done.
Resolving deltas: 100% (374/374), done.
Checking connectivity... done.

Da der Main-Branch immer die aktuellste Version abbildet, brauchen Sie nach einer neuen Veröffentlichung lediglich folgenden Befehl auszuführen, um das Plugin auf dem Grafana-Server zu aktualisieren:

root@linux# cd /var/lib/grafana/plugins/grafana-checkmk-datasource && git pull

Bei der Verwendung des Development-Trees fehlen noch einige notwendige Dateien und Verzeichnisse, um das Plugin in Grafana nutzen zu können. So ist das Plugin in Typescript programmiert, welches nicht direkt interpretiert werden kann, sondern vorher nach Javascript kompiliert werden muss. Über folgendes Kommando erledigt das Programm yarn das Bauen der fehlenden Dateien für Sie:

root@linux# cd /var/lib/grafana/plugins/grafana-checkmk-datasource && yarn run build

2.2. 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 an und ändern Sie 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, 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

2.3. Neustart des Grafana-Dienstes

Nach Änderung der Konfigurationsdatei, Updates oder der Installation des Plugins 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.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

Die Konfigurationsmaske zu der Datenquelle ist recht einfach gehalten. Geben Sie hier die URL zu Ihrer Instanz, den Typ Ihrer Edition und einen Automations-Nutzer an, der Rechte hat, auf das Web-API zuzugreifen. 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 tribe-29-checkmk-datasource 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.

3. Graphen erstellen

3.1. Ein leeres Dashboard erzeugen

Dashboards werden in Grafana über das Pluszeichen auf der linken Seite erzeugt. Klicken Sie auf Dashboard, um ein neues Dashboard zu erstellen:

grafana new dashboard

3.2. Eine einzelne Metrik eines Hosts anzeigen

Das simpelste 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 ein neues panel: Wählen Sie hier zuerst Add Panel aus:

grafana dashboard addpanel

Mit Erstellung des Panels gelangen Sie sofort zum Hinzufügen einer neuen Abfrage (Query). Als Data source wählen Sie im Dropdown-Menü tribe-29-checkmk-data-source aus.

Der Zugriff auf zu visualisierende Daten unterscheidet sich etwas zwischen CRE Checkmk Raw Edition und CEE Checkmk Enterprise Editions: In CRE Checkmk Raw Edition arbeiten Sie mit vordefinierten Dropdwon-Menüs für Site, Hostname, Sevice und so weiter. In CEE Checkmk Enterprise Editions 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 beiden 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 Checkmk. Setzen Sie den Typ der Aggregation auf Lines. Als Graph Type stehen Single metric oder Template (Vorlagen) zur Auswahl: Templates übernehmen Metriken aus Checkmk, welche auch kombinierte Graphen enthalten können. Unser Screenshot zeigt 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 CEE Checkmk Enterprise Editions
grafana dashboard single config cre
Auswahl der Metriken über vordefinierte Dropdown-Menüs in CRE Checkmk Raw Edition

Grafana zeigt das Ergebnis direkt an. Sobald Sie oben rechts auf den Button Save geklickt haben, werden Sie aufgefordert, einen Titel für das neue Dashboard anzugeben. Danach gelangen Sie zurück zum Dashboard:

grafana dashboard single view

3.3. Einen vordefinierten Graphen aus Checkmk anzeigen

Die Entwickler von Checkmk haben bereits viele korrespondierende Metriken in gemeinsamen Graphen zusammengefasst, damit Nutzer leichter einen Überblick über verschiedene Aspekte einer 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 Template und das zu verwendende Template des Services.

grafana dashboard predefined config

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

grafana dashboard predefined view

3.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. Sie haben daher 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 Beispiel matcht filesystem alle Services, die filesystem enthalten — Egal, wieviele Dateisysteme ein Host eingebunden hat. 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.

grafana dashboard combined config

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

4. Änderungen gegenüber früheren Versionen

4.1. Weggefallene Variablen

Versionen des Plugins vor 2.0b1 haben zugelassen, die angezeigten Metriknamen mittels Variablen zu steuern. Hier waren folgende Variablen erlaubt:

VariableBeschreibung

$title

Der Titel der Metrik, wie er auch in Checkmk dargestellt werden würde.

$site

Die Checkmk-Instanz, auf der der Host und seine Metrik überwacht wird.

$host

Der Host, dem die Metrik zugeordnet ist.

$service

Der Service, dem die zugeordnet Metrik ist.

Diese Funktion wurde mit der Version 2.0b1 des Grafana-Plugins entfernt, weil sie letztlich Funktionalität dupliziert, die inzwischen Teil von Grafana ist.

4.2. 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 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.

5. Dateien und Verzeichnisse

PfadBedeutung

/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.

Auf dieser Seite