Lokale Checks

Sie können einen lokalen Check in jeder beliebigen Programmiersprache schreiben, die der Ziel-Host unterstützt. Das Skript muss so konstruiert sein, dass es pro Check eine Statuszeile ausgibt, die aus vier Teilen besteht. Hier ist ein Beispiel:

Die vier Teile sind durch Leerzeichen getrennt und haben folgende Bedeutung:

Zwischen den vier Teilen dieser Ausgabe muss immer genau ein Leerzeichen (ASCII 0x20) stehen. Innerhalb der Statusdetails können beliebige Leerzeichen in beliebiger Reihenfolge verwendet werden.

Wenn Sie wegen einer möglichen Ausgabe unsicher sind, können Sie diese einfach testen, indem Sie ein kleines Skript mit dem Kommando echo schreiben. Fügen Sie in das echo-Kommando Ihre Ausgabe ein, die Sie testen möchten. Unser Beispiel verwendet außen die doppelten Anführungszeichen, da innerhalb stehende Variablen (Umgebungsvariablen und im Skript gesetzte) ausgewertet werden. Das hat zur Folge, dass Sie die Anführungszeichen für den Service-Namen mit \ maskieren müssen, damit diese Zeichen nicht von der Shell als Ende und Anfang eines Strings interpretiert (und damit aus der Ausgabe entfernt) werden:

Für Windows-Hosts sieht so ein Testskript sehr ähnlich aus:

Beide Skripte führen in der Ausgabe zum selben Ergebnis:

Für Checkmk ist nur diese Ausgabe relevant, nicht wie Sie diese Ausgabe erzeugt haben.

Sie können übrigens beliebig viele Ausgaben in einem Skript erzeugen. Für jede ausgegebene Zeile wird dann ein eigener Service in Checkmk erstellt. Daher sind in der Ausgabe auch keine Zeilenumbruchzeichen erlaubt — es sei denn, sie sind maskiert, zum Beispiel für eine mehrzeilige Ausgabe in Checkmk.

Wie Sie prüfen, ob das lokale Skript vom Agenten richtig aufgerufen wird, sehen Sie in der Fehleranalyse.

Nachdem das Skript geschrieben ist, können Sie es an die entsprechenden Hosts verteilen. Der Pfad unterscheidet sich je nach Betriebssystem. Eine Liste der Pfade finden Sie in Dateien und Verzeichnisse weiter unten.

Vergessen Sie nicht, das Skript auf Unix-artigen Systemen ausführbar zu machen. Der Pfad in dem Beispiel bezieht sich auf Linux:

Wenn Sie die Agentenbäckerei nutzen, können Sie das Skript auch regelbasiert verteilen. Mehr zur Regelerstellung erfahren Sie im Kapitel Verteilung über die Agentenbäckerei.

Bei jedem Aufruf des Checkmk-Agenten wird auch der im Skript enthaltene lokale Check ausgeführt und an die Ausgabe des Agenten angehängt. Die Service-Erkennung funktioniert also wie bei anderen Services auch automatisch:

Nachdem Sie den Service ins Monitoring übernommen und die Änderungen aktiviert haben, ist die Einrichtung eines selbst erstellten Services mit Hilfe eines lokalen Checks bereits abgeschlossen. Falls es bei der Service-Erkennung zu Problemen kommen sollte, kann Ihnen die Fehleranalyse weiterhelfen.

Sie können in einem lokalen Check auch Metriken festlegen. Damit diese ausgewertet werden, muss der zurückgelieferte Status P sein. Die Berechnung des Zustands erfolgt dann durch Checkmk.

Die allgemeine Syntax für Metrikdaten ist:

wobei value der aktuelle Wert ist, warn und crit die (oberen) Schwellwerte festlegen sowie min und max den Wertebereich fixieren — zum Beispiel so:

Die Werte werden mit Semikolon getrennt. Alle Werte mit Ausnahme von value sind optional. Wird ein Wert nicht benötigt, so bleibt das Feld leer bzw. wird am Ende weggelassen, wie im Folgenden für warn, crit und max:

Hinweis: In den kommerziellen Editionen können die Werte für min und max zwar gesetzt werden — aber nur aus Kompatibilitätsgründen. Die Begrenzung des zugehörigen Graphen auf einen bestimmten Wertebereich hat in den kommerziellen Editionen keine Auswirkungen.

Bei der Wahl des - hier im Beispiel metricname genannten - Bezeichners dieser Metrik sollten Sie besondere Vorsicht walten lassen. Wir empfehlen, die Bezeichner mit einem Präfix zu versehen, um Überschneidungen mit bereits in Checkmk vorhandenen Metriken zu verhindern.

Statt also beispielsweise eine Metrik, die die Zahl von derzeit wartenden Anfragen in einer von Ihnen überwachten Queue angibt, einfach 'current' zu nennen, empfehlen wir hier einen klareren Bezeichner mit einem Präfix - etwa: mycompany_current_requests.

Sollten Sie hier nämlich einen Bezeichner wählen, der bereits in Checkmk vorhanden ist, würde die Darstellung Ihrer Metriken in Graphen mit den bereits vorliegenden Definitionen überschrieben.

Natürlich können Sie auch absichtlich eine bereits vorhandene Metrik aus Checkmk wiederverwenden. Eine Metrik für eine elektrische Spannung könnten Sie also bspw. durch die Verwendung des Bezeichners current ohne weiteres in Ihrem lokalen Check nutzen. Im Zweifelsfall müssen Sie sich die aktuelle Definition dieser Metrik aber in ~/lib/python3/cmk/gui/plugins/metric selbsttätig heraussuchen.

Sie können auch mehrere Metriken ausgeben lassen. Diese werden dann durch das "Pipe"-Zeichen | getrennt, zum Beispiel so:

Achtung: Auf Windows-Hosts müssen Sie diesen Pipes im Skript noch einen Zirkumflex (^) voranstellen, damit diese Pipes auch in der Ausgabe ankommen.

Eine komplette Ausgabe mit zwei Metriken sieht dann etwa so aus:

Nachdem Sie auch den neuen Service ins Monitoring aufgenommen haben, sehen Sie in der Service-Liste im Feld Summary den Text zum Statusdetail. Nach Anklicken des Services wird die Seite mit den Service-Details gezeigt. Die Metriken zeigt das Feld Details, und darunter sehen Sie die von Checkmk automatisch erzeugten Service-Graphen:

In den vorherigen Kapiteln haben Sie erfahren, wie man für Metriken Schwellwerte festlegen und diese auch in den Graphen anzeigen lassen kann. Der nächste naheliegende Schritt ist es nun, diese Schwellwerte für eine dynamische Berechnung des Service-Zustands zu nutzen. Checkmk bietet genau diese Möglichkeit, um einen lokalen Check auszubauen.

Wenn Sie im ersten Feld der Ausgabe, das den Status bestimmt, statt einer Ziffer den Buchstaben P übergeben, wird der Service-Zustand anhand der übergebenen Schwellwerte berechnet.

Eine Ausgabe würde dann so aussehen:

… und die Anzeige in einer Service-Ansicht so:

Die Anzeige unterscheidet sich in zwei Punkten von derjenigen, die bisher zu sehen war:

Manche Parameter haben nicht nur obere, sondern auch untere Schwellwerte. Ein Beispiel dafür ist die Luftfeuchtigkeit. Für solche Fälle bietet der lokale Check die Möglichkeit, jeweils zwei Schwellwerte für die Zustände WARN und CRIT zu übergeben. Sie werden durch einen Doppelpunkt getrennt und stellen jeweils den unteren und den oberen Schwellwert dar.

In der allgemeinen Syntax sieht das so aus:

… im Beispiel so:

… und in der Anzeige einer Service-Ansicht so:

Falls es Ihnen nur um untere Schwellwerte geht, lassen Sie die Felder der oberen Schwellwerte weg:

Mit dieser Ausgabe legen Sie fest, dass der Service bei einem Wert kleiner 40 WARN und kleiner 30 CRIT werden soll: beim festgelegten Wert 37 wird der Service also den WARN-Zustand erhalten.

Auch die Option, die Ausgabe über mehrere Zeilen zu verteilen, steht Ihnen zur Verfügung. Da Checkmk unter Linux läuft, können Sie mit der Escape-Sequenz \n arbeiten, um einen Zeilenumbruch zu erzwingen. Auch wenn Sie, bedingt durch die Skriptsprache, den Backslash selbst maskieren müssen, wird das von Checkmk korrekt interpretiert:

In den Details des Services können Sie dann diese zusätzlichen Zeilen unter der Summary sehen:

Die Ausgabe lokaler Checks kann, wie auch die von Agenten-Plugins, zwischengespeichert werden (caching). Das kann nützlich sein, wenn Skripte längere Zeit zur Ausführung benötigen. Ein solches Skript wird dann asynchron und nur in einem definierten Zeitintervall ausgeführt und die letzte Ausgabe zwischengespeichert. Wird der Agent vor Ablauf der Zeit erneut abgefragt, verwendet er für den lokalen Check diesen Cache und liefert ihn in der Agentenausgabe zurück.

Hinweis: Das Caching steht nur für AIX, FreeBSD, Linux, OpenWrt und Windows zur Verfügung.

Wenn Sie bei einem selbst geschriebenen Skript auf Probleme stoßen, sollten Sie die folgenden potentiellen Fehlerquellen prüfen:

Wenn das Skript selbst korrekt ist, können Sie den Agenten auf dem Host ausführen. Bei Unix-artigen Betriebssystemen, wie Linux, BSD und so weiter, bietet sich der Befehl grep an, um nach einem bestimmten Textmuster zu suchen. Mit der Option -A bestimmen Sie die Anzahl der zusätzlichen Zeilen, die nach einem Treffer angezeigt werden sollen. Sie können diese Zahl entsprechend der Anzahl der erwarteten Ausgabezeilen anpassen:

In der letzten Zeile erkennen Sie einen zwischengespeicherten Service an der vorangestellten cache-Information mit der aktuellen Unixzeit und dem Ausführungsintervall in Sekunden.

Unter Windows können Sie mit der PowerShell und dem „Cmdlet“ Select-String ein sehr ähnliches Resultat erreichen wie mit dem grep-Befehl unter Linux. Im folgenden Befehl bestimmen die beiden Ziffern hinter dem Parameter Context wie viele Zeilen vor und nach dem Treffer ausgegeben werden sollen:

Zuletzt können Sie die Verarbeitung der Skriptausgaben auch auf dem Checkmk-Server mit dem Befehl cmk testen — einmal die Service-Erkennung:

… und mit einem ähnlichen Befehl auch die Verarbeitung der Serviceausgabe:

Für beide Befehle haben wir die Ausgabe um für dieses Thema nicht relevante Zeilen gekürzt.

Wenn es in den lokalen Checks Fehler gibt, wird Checkmk Sie in der Serviceausgabe darauf hinweisen. Das gilt sowohl für fehlerhafte Metriken, als auch für falsche, unvollständige Informationen in der Skriptausgabe oder einen ungültigen Status. Diese Fehlermeldungen sollen Ihnen helfen, die Fehler in den Skripten schnell zu identifizieren.

Hier werden zwischengespeicherte Daten einzelner Sektionen, u.a. der local Sektion, abgelegt und dem Agenten, solange die Daten gültig sind, bei jeder Ausführung wieder angehängt.