Agentenbasierte Check-Plugins schreiben

Für die Programmierung der Check-Plugins gibt es seit der Checkmk-Version 2.0.0 eine neu entwickelte Check-API. Wir zeigen Ihnen, wie Sie diese Check-API für die Plugin-Programmierung nutzen können.

Über die Checkmk-Benutzeroberfläche haben Sie jederzeit Zugriff auf die Dokumentation der Check-API: Help > Developer resources > Check plugin API reference. Wählen Sie im neuen Browserfenster in der linken Navigationsleiste BASE > Agent based API ("Check API") aus:

Hinweis für Benutzer der bis zur Version 1.6.0 gültigen Check-API: Falls Sie noch Check-Plugins haben, die mit der alten API entwickelt wurden, sollten Sie diese bald auf die neue Check-API migrieren. Zwar wird die alte Check-API für eine Übergangszeit weiterhin unterstützt — aber auch diese Zeit wird einmal enden. Den einmaligen Aufwand zur Migration machen die Vorteile der neuen Check-API wett, denn diese ist konsistenter, logischer, besser dokumentiert und zukunftssicher. Im Blogpost zur Migration von Check-Plugins informieren wir Sie ausführlich über die notwendigen Schritte.

Wenn Sie Lust haben, sich mit dem Programmieren von Check-Plugins zu befassen, benötigen Sie folgendes:

Zwar ist hier immer die Rede von einem Check-Plugin und davon, dieses zu schreiben. Aber genau genommen benötigen Sie immer zwei Plugins, das Agentenplugin auf dem überwachten Host und das Check-Plugin auf dem Checkmk-Server. Beide müssen geschrieben und aufeinander abgestimmt werden. Nur so funktionieren sie hinterher reibungsfrei.

Am Anfang jeder Plugin-Programmierung steht: die Recherche! Das bedeutet, dass Sie herausfinden müssen, wie Sie überhaupt an die Informationen kommen, die Sie für die Überwachung brauchen.

Für das gewählte Beispiel nutzen wir die Tatsache, dass der Checkmk-Server zugleich der Host ist. Damit genügt zunächst ein Abruf der Statusdaten via Livestatus, also der in Tabellen organisierten Daten, die Checkmk über die überwachten Hosts und Services im flüchtigen Speicher vorhält.

Melden Sie sich als Instanzbenutzer an und fragen Sie die Informationen zu den Host-Gruppen mit folgendem Befehl ab:

Die erste Zeile der Ausgabe enthält die Spaltennamen der abgefragten Tabelle hostgroups. Als Trennzeichen fungiert das Semikolon. In den folgenden Zeilen folgen dann die Inhalte sämtlicher Spalten, ebenfalls durch Semikolons getrennt.

Die Ausgabe ist bereits für dieses kleine Beispiel relativ unübersichtlich und enthält Informationen, die für unser Beispiel nicht relevant sind. Generell sollten Sie zwar die Interpretation der Daten Checkmk überlassen. Allerdings kann eine Vorfilterung auf dem Host den Umfang der zu übertragenden Daten reduzieren, wenn diese gar nicht gebraucht werden. Also schränken Sie in diesem Fall die Abfrage auf die relevanten Spalten (Columns) ein — auf die Namen der Host-Gruppen (name) und die in den Gruppen befindlichen Hosts (members):

Die Livestatus-Schnittstelle erwartet alle Befehle und Header in jeweils einer eigenen Zeile. Die daher notwendigen Zeilenumbrüche machen Sie durch \n kenntlich.

In diesem Beispiel existieren aktuell drei Host-Gruppen: zwei Gruppen für die Standorte sowie die Gruppe check_mk. Diese enthält einen Host namens localhost.

Die Host-Gruppe check_mk stellt eine Besonderheit innerhalb der Host-Gruppen dar. Sie haben diese nämlich nicht selbst angelegt. Und Sie können auch keinen Host aktiv in diese Gruppe aufnehmen. Woher also stammt diese Host-Gruppe? Da in Checkmk per Definition jeder Host einer Gruppe angehören muss, weist Checkmk jeden Host, den Sie keiner Gruppe zuweisen, der „speziellen“ Gruppe check_mk zu.

Sobald Sie einen Host einer Ihrer eigenen Host-Gruppen zuweisen, wird er aus der Gruppe check_mk entfernt. Auch gibt es keinen Weg, einen Host erneut der Host-Gruppe check_mk zuzuweisen.

Genau diese Eigenschaften der Gruppe check_mk werden nun für unser Beispiel genutzt: Da jeder Host einem Standort zugeordnet sein soll, müsste die Host-Gruppe check_mk leer sein. Ist sie nicht leer, so besteht Handlungsbedarf, sprich darin befindliche Hosts müssen den Host-Gruppen und damit den Standorten zugeordnet werden.

Bis jetzt haben Sie sich mit dem lq-Befehl als Instanzbenutzer die Informationen anzeigen lassen. Das ist hilfreich, um sich einen Einblick in die Daten zu verschaffen.

Damit Sie diese Daten vom Checkmk-Server aus abrufen können, muss der neue Befehl jedoch Teil vom Checkmk-Agenten auf dem überwachten Host werden. Theoretisch könnten Sie nun direkt den Checkmk-Agenten in der Datei /usr/bin/check_mk_agent editieren und diesen Teil einbauen. Das hätte aber den Nachteil, dass Ihr neuer Befehl bei einem Software-Update des Agenten wieder verschwindet, weil die Datei ersetzt wird.

Besser ist es daher, ein Agentenplugin zu erstellen. Alles was Sie dafür brauchen, ist eine ausführbare Datei, die den Befehl enthält und im Verzeichnis /usr/lib/check_mk_agent/plugins/ liegt.

Und noch eins ist wichtig: Die Daten können nicht einfach so ausgegeben werden. Sie brauchen noch einen Sektions-Header (section header). Das ist eine speziell formatierte Zeile, die den Namen des neuen Agentenplugins enthält. An diesem Sektions-Header kann Checkmk später erkennen, wo die Daten des Agentenplugins beginnen und die des vorherigen aufhören. Am einfachsten ist es, wenn Sektions-Header und Check-Plugin den gleichen Namen tragen — auch wenn dies nicht verpflichtend ist.

Also brauchen Sie jetzt erst einmal einen sinnvollen Namen für Ihr neues Check-Plugin. Dieser Name darf nur Kleinbuchstaben (nur a-z, keine Umlaute, keine Akzente), Unterstriche und Ziffern enthalten und muss eindeutig sein. Vermeiden Sie Namenskollisionen mit vorhandenen Check-Plugins. Wenn Sie neugierig sind, welche Namen es schon gibt, können Sie diese in einer Checkmk-Instanz auf der Kommandozeile mit cmk -L auflisten lassen:

Die Ausgabe zeigt nur die ersten Zeilen der sehr langen Liste. Durch die Verwendung von Präfixen ist die Zugehörigkeit vieler Check-Plugins hier bereits gut zu erkennen. Auch für Ihre eigenen Check-Plugins empfiehlt sich daher die Verwendung von Präfixen. Die zweite Spalte zeigt übrigens an, wie das jeweilige Check-Plugin seine Daten bezieht.

Ein für unser Beispiel passender Name für das neue Check-Plugin ist zum Beispiel myhostgroups.

Nun haben Sie alle Informationen zusammen, um das Skript mit dem Agentenplugin zu erstellen. Legen Sie als root-Benutzer eine neue Datei myhostgroups im Verzeichnis /usr/lib/check_mk_agent/plugins/ an:

Was bedeutet das nun im Einzelnen?

Die erste Zeile enthält den „Shebang“ (das ist eine Abkürzung für sharp und bang, wobei Letzteres eine Abkürzung für das Ausrufezeichen ist), an dem Linux erkennt, dass es das Skript mit der angegebenen Shell ausführen soll.

Um das Skript erweiterbar zu halten, werden als nächstes zwei Variablen eingeführt:

Mit dem echo-Befehl geben Sie den Sektions-Header aus. Da die Spalten der Tabelle mit dem Semikolon getrennt werden, legen Sie gleichzeitig mit dem Zusatz sep(59) fest, dass das Semikolon als Trennzeichen (separator) für die Daten in der Agentenausgabe genutzt wird. 59 steht für das ASCII-Zeichen Nummer 59, das Semikolon. Ohne diesen Zusatz würde als Standard das Leerzeichen (ASCII-Zeichen 32) als Trennzeichen verwendet werden.

Um den lq-Befehl, der Ihnen als Instanzbenutzer zur Verfügung steht, auch in einem Skript nutzen zu können, das vom root-Benutzer ausgeführt wird, stellen Sie ein su voran.

Hinweis: Es kann vorkommen, dass der Zugriff auf lq per su Probleme bereitet. Sie können alternativ als root-Benutzer auch direkt auf Livestatus in der Shell mit printf oder echo -e über einen Unix-Socket zugreifen. Im Artikel zu Livestatus erfahren Sie, wie das geht.

Eines ist noch sehr wichtig, sobald Sie die Datei erstellt haben. Machen Sie die Datei ausführbar:

Sie können das Agentenplugin direkt von Hand ausprobieren, indem Sie den kompletten Pfad als Befehl eingeben:

Host-Gruppen, die keine Hosts enthalten, werden hierbei nicht aufgeführt.

Test und Fehlersuche sind am wichtigsten, um zu einem funktionierenden Agentenplugin zu gelangen. Am besten gehen Sie in drei Schritten vor:

Das lokale Testen des Agenten ist sehr einfach. Rufen Sie als root den Befehl check_mk_agent auf:

Irgendwo in der sehr langen Ausgabe muss die neue Sektion erscheinen. Agentenplugins werden vom Agenten zum Schluss ausgegeben.

Durch Anhängen von less können Sie in der Ausgabe blättern (drücken Sie die Leertaste zum Blättern, / zum Suchen und q zum Beenden):

Oder Sie durchsuchen die Ausgabe nach den interessanten Zeilen. So hat grep mit -A eine Option, nach jedem Treffer noch einige Zeilen mehr auszugeben. Damit können Sie bequem die Sektion suchen und ausgeben:

Der dritte und letzte Test ist dann direkt von der Checkmk-Instanz aus. Nehmen Sie den Host ins Monitoring auf (zum Beispiel als localhost), melden Sie sich als Instanzbenutzer an und rufen Sie dann die Agentendaten mit cmk -d ab:

Hier sollte die gleiche Ausgabe kommen wie beim vorherigen Befehl.

Wenn das funktioniert, ist Ihr Agent vorbereitet. Und was haben Sie dafür gemacht? Sie haben ein kurzes Skript unter dem Pfad /usr/lib/check_mk_agent/plugins/myhostgroups erzeugt und ausführbar gemacht.

Alles was nun folgt, geschieht nur noch auf dem Checkmk-Server: Dort schreiben Sie das Check-Plugin.

Für Ihre eigenen Check-Plugins finden Sie ein Verzeichnis vorbereitet in der local-Hierarchie des Instanzverzeichnisses. Dieses lautet ~/local/lib/check_mk/base/plugins/agent_based/. Hier im Pfad meint base den Teil von Checkmk, der für das eigentlich Monitoring und die Benachrichtigungen zuständig ist. Der Ordner agent_based beinhaltet alle Plugins, die sich auf den Checkmk-Agenten beziehen (also zum Beispiel nicht Benachrichtigungs-Plugins). Am besten wechseln Sie zum Arbeiten dort hinein:

Das Verzeichnis gehört dem Instanzbenutzer und ist daher für Sie schreibbar. Sie können Ihr Check-Plugin mit jedem auf dem Linux-System installierten Texteditor bearbeiten.

Legen Sie also die Datei myhostgroups.py für das Check-Plugin hier an. Konvention ist, dass der Dateiname den Namen der Agentensektion wiedergibt. Pflicht ist, dass die Datei mit .py endet, denn ab Version 2.0.0 von Checkmk handelt es sich bei den Check-Plugins immer um echte Python-Module.

Ein lauffähiges Grundgerüst (Download bei GitHub), das Sie im Folgenden Schritt für Schritt weiter ausbauen werden, sieht so aus:

Als erstes müssen Sie die für die Check-Plugins nötigen Funktionen und Klassen aus Python-Modulen importieren. Die einfachste Methode dafür ist import *, allerdings sollten Sie das vermeiden, da so verschleiert wird, welche Namensräume tatsächlich verfügbar gemacht wurden.

Für unser Beispiel wird also nur das importiert, was im weiteren Verlauf des Artikels genutzt wird:

Die Parse-Funktion hat die Aufgabe, die „rohen“ Agentendaten zu „parsen“, das heißt zu analysieren und zu zerteilen, und in eine logisch aufgeräumte Form zu bringen, die für alle weiteren Schritte einfach zu verarbeiten ist.

Wie im Abschnitt zum Testen des Agenten gezeigt, hat die vom Agentenplugin gelieferte Sektion die folgende Struktur:

Checkmk zerlegt bereits die Zeilen der vom Agentenplugin gelieferten Sektion anhand des Trennzeichens im Sektions-Header (im Beispiel ;) in eine Liste von Zeilen, die ihrerseits wiederum Listen von Worten sind. In Checkmk steht daher statt der Rohdaten des Agentenplugins die folgende Datenstruktur zur Verfügung:

In der inneren Liste enthält das jeweils erste Element den Namen der Host-Gruppe und das zweite die Namen der der Gruppe angehörenden Hosts.

Diese Informationen können Sie zwar alle ansprechen, aber jeweils nur über ihre Position im Datensatz. Sie müssten also immer angeben, die wievielte eckige Klammer und den wievielten Inhalt innerhalb der jeweiligen Klammer Sie brauchen. Bei größeren Datenmengen gestaltet sich dies komplex und es wird immer schwieriger, den Überblick zu behalten.

An diesem Punkt bietet die Parse-Funktion durch die von ihr erzeugte Struktur deutliche Vorteile. Durch sie wird der Code leichter lesbar, die Zugriffe werden performanter und Sie behalten viel einfacher den Überblick. Sie transformiert die von Checkmk gelieferte Datenstruktur so, dass man jeden der einzelnen Werte wahlfrei durch einen Namen (oder Schlüssel) ansprechen kann und nicht darauf angewiesen ist, den Bereich (array) iterativ zu durchlaufen, um das zu finden, was man sucht:

Konvention ist, dass die Parse-Funktion nach der Agentensektion benannt wird und mit parse_ beginnt. Sie bekommt als einziges Argument string_table. Beachten Sie, dass Sie hier nicht frei in der Wahl des Arguments sind. Es muss wirklich so heißen.

Mit def geben Sie in Python an, dass nachfolgend eine Funktion definiert wird. parsed = {} erzeugt das Dictionary mit der verbesserten Datenstruktur. In unserem Beispiel wird jede Zeile Element für Element durchgegangen. Aus jeder Zeile wird die Host-Gruppe gefolgt von den Mitgliedern der Host-Gruppe genommen und zu einem Eintrag für das Dictionary zusammengesetzt.

Mit return parsed wird dann das Dictionary zurückgegeben.

Hinweis: Im oben gezeigten Beispiel finden Sie zwei auskommentierte Zeilen. Wenn Sie diese später beim Testen des Check-Plugins einkommentieren, werden Ihnen die Daten vor und nach der Ausführung der Parse-Funktion auf der Kommandozeile angezeigt. So können Sie überprüfen, ob die Funktion auch wirklich das tut, was sie soll.

Damit das Ganze auch etwas bewirken kann, müssen Sie die Parse-Funktion, und überhaupt die neue Agentensektion, bei Checkmk bekannt machen. Dazu rufen Sie eine Registrierfunktion auf:

Hier ist es wichtig, dass der Name der Sektion wirklich exakt mit dem Sektions-Header in der Agentenausgabe übereinstimmt. Von diesem Moment an bekommt jedes Check-Plugin, das die Sektion myhostgroups benutzt, den Rückgabewert der Parse-Funktion übergeben. In der Regel wird das das gleichnamige Check-Plugin sein. Aber auch andere Check-Plugins können dieses Sektion abonnieren, wie wir bei der Erweiterung des Check-Plugins noch zeigen werden.

Übrigens: Wenn Sie es ganz genau wissen wollen, können Sie an dieser Stelle einen Blick in die Check-API-Dokumentation werfen. Dort finden Sie die detaillierte Beschreibung dieser Registrierfunktion — und auch der Funktionen und Objekte, die später im Artikel noch verwendet werden.

Damit Checkmk weiß, dass es ein neues Check-Plugin gibt, muss dieses registriert werden. Dies geschieht durch den Aufruf der Funktion register.check_plugin. Dabei müssen Sie immer mindestens vier Dinge angeben:

Für das Check-Plugin sieht das dann also so aus:

Versuchen Sie am besten noch nicht, das gleich auszuprobieren, denn Sie müssen die Funktionen discover_myhostgroups und check_myhostgroups vorher noch schreiben. Und diese müssen im Quellcode vor obiger Registrierung erscheinen.

Eine Besonderheit von Checkmk ist die automatische Erkennung von zu überwachenden Services. Damit dies klappt, muss jedes Check-Plugin eine Funktion definieren, welche anhand der Agentenausgabe erkennt, ob ein Service dieses Typs bzw. welche Services des Typs für den betreffenden Host angelegt werden sollen.

Die Discovery-Funktion wird immer dann aufgerufen, wenn für einen Host die Service-Erkennung durchgeführt wird. Sie entscheidet dann ob, bzw. welche Services angelegt werden sollen. Im Standardfall bekommt sie genau ein Argument mit dem Namen section. Dieses enthält die Daten der Agentensektion in einem durch die Parse-Funktion aufbereiteten Format.

Daher implementieren Sie folgende simple Logik: Wenn die Agentensektion myhostgroups vorhanden ist, dann legen Sie auch einen passenden Service an. Dann erscheint dieser automatisch auf allen Hosts, auf denen das Agentenplugin verteilt ist.

Bei Check-Plugins, die pro Host nur einen Service erzeugen, benötigt man keine weiteren Angaben:

Die Discovery-Funktion muss für jeden anzulegenden Service mittels yield ein Objekt vom Typ Service zurückgeben (nicht mit return). yield hat in Python die gleiche Aufgabe wie return – beide geben einen Wert an die aufrufende Funktion zurück. Der entscheidende Unterschied besteht darin, dass sich bei einem yield gemerkt wird, wie weit die Funktion in einer Datenverarbeitung gekommen ist. Beim nächsten Aufruf wird nach der letzten yield-Anweisung weiter gemacht - und nicht wieder am Anfang begonnen. Dadurch wird nicht nur der erste Treffer ausgelesen (wie es beim return der Fall wäre), sondern sukzessive alle Treffer (dieser Vorteil wird später in unserem Beispiel bei der Service-Erkennung noch relevant).

Somit können Sie nun zur eigentlichen Check-Funktion kommen, welche anhand der aktuellen Agentenausgabe entscheidet, welchen Zustand der Service annehmen soll und weitere Informationen ausgeben kann.

Ziel der Check-Funktion ist es, eine Prüfung aufzusetzen, mit der kontrolliert werden kann, ob für keinen Host vergessen wurde, eine Host-Gruppe zuzuweisen. Dazu wird überprüft, ob die Host-Gruppe check_mk Hosts enthält. Wenn das der Fall ist, soll der Service den Zustand CRIT erhalten. Wenn nicht, ist alles OK und der Zustand des Services auch.

Hier ist die Implementierung:

Und nun die Erklärung dazu: Die Funktion check_myhostgroups() holt als erstes den zum Schlüssel check_mk gehörenden Wert in die Variable attr. Dann wird die Variable hosts mit dem members-Wert verknüpft, wenn dieser vorhanden ist. Gibt es keine members, so bleibt hosts leer.

Jetzt folgt eine if-Abfrage für die eigentliche Auswertung:

Mit der Erstellung der Check-Funktion ist das Check-Plugin fertig.

Das Check-Plugin und auch das Agentenplugin haben wir auf GitHub bereitgestellt.

Test und Aktivierung werden auf der Kommandozeile mit dem Befehl cmk erledigt.

Probieren Sie zunächst die Service-Erkennung mit der Option -I aus. Durch Zugabe der Option v (für verbose) werden ausführliche Ausgaben angefordert. Das --detect-plugins beschränkt die Befehlsausführung auf dieses Check-Plugin und durch localhost auf eben diesen Host:

Wie geplant, erkennt die Service-Erkennung einen neuen Service im Check-Plugin myhostgroups.

Jetzt können Sie den im Check-Plugin enthaltenen Check ausprobieren:

Durch Ausführung des Checks wird der Zustand des zuvor gefundenen Services bestimmt.

Wenn soweit alles wie erwartet abgelaufen ist, können Sie die Änderungen aktivieren. Falls nicht, finden Sie im Kapitel zur Fehlerbehebung Hinweise.

Aktivieren Sie zum Abschluss die Änderungen durch einen Neustart des Monitoring-Kerns:

Im Monitoring von Checkmk finden Sie nun beim Host localhost den neuen Service Host group check_mk:

Wir gratulieren Ihnen zur erfolgreichen Erstellung des ersten Check-Plugins!

Das gerade frisch fertiggestellte erste Check-Plugin soll nun schrittweise erweitert werden. Bisher hat das Agentenplugin nur die Informationen über die Namen und die Mitglieder der Host-Gruppen geliefert. Um etwa die Zustände der Hosts und der auf ihnen laufenden Services auswerten zu können, braucht es mehr Daten.

Im Beispiel haben Sie einen sehr einfachen Check gebaut, der auf einem Host einen Service erzeugt. Ein sehr üblicher Fall ist aber auch, dass es von einem Check mehrere Services auf einem Host geben kann.

Das häufigste Beispiel dafür sind die Dateisysteme eines Hosts. Das Check-Plugin mit dem Namen df legt pro Dateisystem auf dem Host einen Service an. Um diese Services zu unterscheiden, wird der Mount-Punkt des Dateisystems (zum Beispiel /var) bzw. der Laufwerksbuchstabe (zum Beispiel C:) in den Namen des Services eingebaut. Das ergibt dann als Service-Name zum Beispiel Filesystem /var oder Filesystem C:. Das Wort /var bzw. C: wird hier als Item bezeichnet. Wir sprechen also auch von einem Check mit Items.

Wenn Sie einen Check mit Items bauen möchten, müssen Sie folgende Dinge umsetzen:

Um dies praktisch auszuprobieren, werden Sie für jede existierende Host-Gruppe einen eigenen Service erzeugen.

Da das im vorherigen Kapitel erstellte Check-Plugin myhostgroups zur Überprüfung der Standardgruppe check_mk weiterhin funktionieren soll, bleibt dieses Check-Plugin so, wie es ist. Für die Erweiterung erstellen Sie in der Datei myhostgroups.py ein neues Check-Plugin — im ersten Schritt so wie zuvor durch die Registrierung des Plugins.

Wichtig: Die neue Registrierung wird zusätzlich zur bereits vorhandenen vorgenommen, die im vorherigen Kapitel gezeigte bleibt unverändert enthalten. Hier nur der neue Code:

Damit man das neue vom alten Check-Plugin unterscheiden kann, erhält es mit myhostgroups_advanced einen eindeutigen Namen. Der Parameter sections bestimmt die Sektionen der Agentenausgabe, die das Check-Plugin abonniert. Mit myhostgroups wird hier festgelegt, dass das neue Check-Plugin die gleichen Daten nutzt wie das alte: die durch die Parse-Funktion aufbereitete Sektion des Agentenplugins. Der Service-Name enthält jetzt den Platzhalter %s. An dieser Stelle wird später dann von Checkmk der Name des Items eingesetzt. In den letzten beiden Zeilen werden schließlich die Namen für die neue Discovery-Funktion und die neue Check-Funktion festgelegt, die beide noch geschrieben werden wollen.

Zuerst zur Discovery-Funktion, die jetzt die Aufgabe hat, die zu überwachenden Items zu ermitteln – auch diese wird zusätzlich zur vorhandenen eingetragen:

Wie zuvor bekommt die Discovery-Funktion das Argument section. Mit einer Schleife werden die einzelnen Host-Gruppen durchlaufen. Hier interessieren alle Host-Gruppen — mit Ausnahme von check_mk, denn um diese spezielle Host-Gruppe kümmert sich bereits das existierende Check-Plugin myhostgroups. Immer, wenn ein Item gefunden wurde, wird es mit yield zurück gegeben, wobei ein Objekt vom Typ Service erzeugt wird, das den Host-Gruppennamen als Item übergeben bekommt.

Wenn später der Host überwacht wird, dann wird die Check-Funktion für jeden Service — und damit für jedes Item — separat aufgerufen. Womit Sie bereits bei der Definition der Check-Funktion für das neue Check-Plugin myhostgroups_advanced angekommen sind. Die Check-Funktion bekommt zusätzlich zur Sektion das Argument item übergeben. Die erste Zeile der Funktion sieht dann so aus:

Der Algorithmus für die Check-Funktion ist einfach: Wenn die Host-Gruppe existiert, wird der Service auf OK gesetzt und Anzahl und Namen der Hosts in der Gruppe aufgelistet. Die komplette Funktion dazu:

Das Check-Ergebnis wird geliefert, indem ein Objekt der Klasse Result per yield zurückgeben wird. Dieses benötigt die Parameter state und summary. Dabei legt state den Zustand des Services fest (im Beispiel OK) und summary den Text, der in dem Summary des Services angezeigt wird. Er ist rein informativ und wird von Checkmk nicht weiter ausgewertet. Mehr dazu erfahren Sie im nächsten Abschnitt.

So weit, so gut. Was passiert aber, wenn das gesuchte Item nicht gefunden wird? Das kann passieren, wenn in der Vergangenheit ein Service für eine Host-Gruppe bereits erzeugt wurde, diese Host-Gruppe aber nun verschwunden ist — entweder weil die Host-Gruppe in Checkmk noch existiert, aber keinen Host mehr enthält, oder weil sie gleich ganz gelöscht wurde. In beiden Fällen ist diese Host-Gruppe in der Agentenausgabe nicht (mehr) präsent.

Die gute Nachricht: Checkmk kümmert sich darum! Wird ein gesuchtes Item nicht gefunden, so erzeugt Checkmk automatisch für den Service das Resultat UNKNOWN - Item not found in monitoring data. Das ist so gewollt und gut so. Wenn ein gesuchtes Item nicht gefunden wird, so können Sie Python einfach aus der Funktion herauslaufen und Checkmk seine Arbeit erledigen lassen.

Checkmk weiß nur, dass das Item, das vorher da war, nun weg ist. Den Grund dafür kennt Checkmk nicht — Sie aber schon. Darum ist es legitim, Ihr Wissen nicht für sich zu behalten und diesen Fall in der Check-Funktion abzufangen und dabei eine hilfreiche Meldung ausgeben zu lassen.

Was hat sich geändert? Der Fehlerfall wird jetzt zuerst abgehandelt. Daher überprüfen Sie im if-Zweig, ob das Item nicht existiert, setzen den Status auf CRIT und verlassen mit return die Funktion. In allen anderen Fällen geben Sie, wie zuvor, OK zurück.

Damit haben Sie in der Check-Funktion den Fall der verschwundenen Host-Gruppen übernommen. Statt UNKNOWN wird der zugehörige Service nun CRIT sein und die Information über die Ursache des kritischen Zustands beinhalten.

Damit ist das neue Check-Plugin als Erweiterung des alten fertiggestellt. Das erweiterte Agentenplugin und die erweiterte Datei für die Check-Plugins finden Sie wieder auf GitHub. Letztere enthält das einfache Check-Plugin myhostgroups aus dem vorherigen Kapitel, die erweiterte Parse-Funktion und die Komponenten des neuen Check-Plugins myhostgroups_advanced mit der Registrierung, der Discovery-Funktion und der Check-Funktion. Beachten Sie, dass die Funktionen immer vor dem Registrieren definiert werden müssen, damit es keine Fehler wegen nicht definierter Funktionsnamen gibt.

Da das neue Check-Plugin myhostgroups_advanced neue Services zur Verfügung stellt, müssen Sie eine Service-Erkennung für dieses Check-Plugin durchführen und die Änderungen aktivieren, um die Services im Monitoring zu sehen:

Gehen Sie dabei so vor, wie es im Kapitel für das einfache Check-Plugin beschrieben ist.

Im Monitoring von Checkmk hat jeder Service neben dem Status — OK, WARN usw. — auch eine Zeile Text. Diese steht in der Spalte Summary — wie im vorherigen Screenshot zu sehen ist — und hat also die Aufgabe einer knappen Zusammenfassung des Zustands. Die Idee ist, dass dieser Text eine Länge von 60 Zeichen nicht überschreitet. Das sorgt dann immer für eine übersichtliche Tabellendarstellung ohne störende Zeilenumbrüche.

Daneben gibt es noch das Feld Details, in dem alle Details zum Zustand des Services angezeigt werden, wobei alle Informationen des Summary auch in den Details enthalten sind. Nach Anklicken des Services wird die Service-Seite geöffnet, in der neben vielen anderen auch die beiden Felder Summary und Details zu sehen sind.

Beim Aufruf von yield Result(...) können Sie bestimmen, welche Informationen so wichtig sind, dass sie im Summary angezeigt werden sollen, und bei welchen es genügt, dass diese in den Details erscheinen.

In unserem Beispiel haben Sie bisher immer einen Aufruf der folgenden Art verwendet:

Dieser führt dazu, dass der als summary festgelegte Text immer im Summary erscheint — und zusätzlich auch in den Details. Dies sollten Sie also nur für wichtige Informationen verwenden. Enthält eine Host-Gruppe viele Hosts, kann die Liste sehr lang werden — länger als die empfohlenen 60 Zeichen. Ist eine Information eher untergeordnet, so können Sie mit details festlegen, dass der Text nur in den Details erscheint:

Im obigen Beispiel wird die Liste der Hosts daher nur noch in den Details angezeigt. Im Summary steht dann nur die Anzahl der Hosts in der Gruppe:

Es gibt neben summary und details noch einen dritten Parameter. Mit notice bestimmen Sie, dass ein Text für einen Service im Zustand OK nur in den Details angezeigt wird — aber zusätzlich im Summary für alle anderen Zustände. Somit wird dann aus dem Summary sofort klar, warum der Service nicht OK ist. Der Parameter notice ist nicht besonders sinnvoll, wenn Texte fest an Zustände gebunden sind, wie bisher in unserem Beispiel.

Zusammengefasst bedeutet das:

Um die Anzahl der Services auf einem Host nicht ins Unermessliche steigen zu lassen, sind in einem Service oft mehrere Teilresultate zusammengefasst. So prüft zum Beispiel der Service Memory unter Linux nicht nur RAM- und Swap-Nutzung, sondern auch geteilten Speicher (shared memory), Page-Tabellen und alles Mögliche andere.

Die Check-API bietet dafür eine sehr komfortable Schnittstelle. So darf eine Check-Funktion einfach beliebig oft ein Ergebnis mit yield erzeugen. Der Gesamtstatus des Services richtet sich dann nach dem schlechtesten Teilergebnis in der Reihenfolge OK → WARN → UNKNOWN → CRIT.

Nutzen Sie diese Möglichkeit, um in unserem Beispiel für jeden Service der Host-Gruppen zu dem bestehenden Resultat zwei weitere zu definieren. Diese werten den Prozentsatz der Hosts im Zustand UP und der Services im Zustand OK aus. Dabei nutzen Sie die zuvor in der Agentenausgabe und der Parse-Funktion festgelegten zusätzlichen Spalten der Host-Gruppentabelle.

Erweitern Sie die Check-Funktion nun sukzessive von oben nach unten:

Der if-Zweig bleibt unverändert, das heißt auch die neuen Teilresultate gelten nur für Host-Gruppen, die auch existieren. Anschließend definieren Sie fünf Variablen für die in der Sektion enthaltenen Spalten der Host-Gruppentabelle. Dies erhöht zum einen im folgenden die Lesbarkeit und nebenbei können Sie für die vier Spalten, mit denen noch gerechnet werden soll, die ausgelesenen Strings mit int() in Zahlen umwandeln.

Auch das bisher einzig existierende Resultat bleibt (fast) unverändert:

Nur der Zugriff im Python-„F-String“ auf den Ausdruck, der den Wert liefert, ist nun einfacher als zuvor, da das attr bereits in den Variablendefinitionen steckt.

Nun zum eigentlichen Kern der Erweiterung, der Definition eines Resultats, das die folgende Aussage umsetzt: „Der Service der Host-Gruppe ist WARN, wenn 90 % der Hosts UP sind, und CRIT bei 80 % der Hosts.“ Dabei gilt die Konvention, dass der Check bereits beim Erreichen der Schwelle — und nicht erst beim Überschreiten — auf WARN bzw. CRIT geht. Für den Vergleich eines ermittelten Werts mit Schwellwerten stellt die Check-API die Hilfsfunktion check_levels bereit.

In der ersten Zeile wird aus Gesamtzahl und Zahl der Hosts im Zustand UP der Prozentsatz berechnet und in der Variablen hosts_up_perc gespeichert. Durch den einfachen Schrägstrich (/) wird eine Gleitkommadivison ausgeführt, die sicherstellt, das das Ergebnis ein Float-Wert ist. Das ist sinnvoll, weil einige im weiteren Verlauf verwendete Funktionen Float als Eingabe erwarten.

In der zweiten Zeile wird dann das Ergebnis der Funktion check_levels als Objekt vom Typ Result zurückgegeben. Die Funktion wird gefüttert mit dem gerade berechneten Prozentsatz als Wert (hosts_up_perc), den beiden unteren Schwellwerten (levels_lower), einer Bezeichnung, die der Ausgabe vorangestellt wird (label) und schließlich mit notice_only=True.

Der letzte Parameter nutzt den im vorherigen Abschnitt für das Objekt Result() bereits vorgestellten Parameter notice. Mit notice_only=True legen Sie fest, dass der Text für den Service nur dann im Summary angezeigt wird, wenn der Zustand nicht OK ist. Allerdings werden Teilergebnisse, die zu einem WARN oder CRIT führen, sowieso immer im Summary sichtbar werden — unabhängig davon, welchen Wert notice_only hat.

Schließlich definieren Sie analog zum zweiten das dritte Resultat, das den Prozentsatz der Services im Zustand OK auswertet:

Damit ist die Check-Funktion komplett.

Der Service für eine Host-Gruppe wertet jetzt drei Resultate aus und zeigt aus diesen den schlechtesten Zustand im Monitoring an, wie im folgenden Beispiel:

Nicht immer, aber oft befassen sich Checks mit Zahlen. Und sehr oft handelt es sich bei diesen Zahlen um gemessene oder berechnete Werte. In unserem Beispiel sind die Zahl der Hosts in der Host-Gruppe (num_hosts) und die Zahl der Hosts im Zustand UP (num_hosts_up) die Messwerte. Der Prozentsatz der Hosts im Zustand UP (hosts_up_perc) ist ein daraus berechneter Wert. Wenn dann solch ein Wert im zeitlichen Verlauf dargestellt werden kann, wird er auch als Metrik bezeichnet.

Mit seinem Graphing-System hat Checkmk eine Komponente, um solche Zahlen zu speichern, auszuwerten und darzustellen. Das geht dabei völlig unabhängig von der Berechnung der Zustände OK, WARN und CRIT.

Sie werden in diesem Beispiel die beiden berechneten Werte hosts_up_perc und services_ok_perc als Metriken definieren. Metriken werden in der grafischen Benutzeroberfläche von Checkmk sofort sichtbar, ohne dass Sie etwas dafür tun müssen. Pro Metrik wird automatisch ein Graph erzeugt.

Metriken werden von der Check-Funktion ermittelt und als zusätzliches Ergebnis zurückgegeben. Am einfachsten ist es, der Funktion check_levels() im Aufruf die Metrikinformationen mitzugeben.

Zur Erinnerung folgt die Zeile mit dem Funktionsaufruf von check_levels() aus dem vorherigen Abschnitt:

Die beiden neuen Argumente für die Metrik sind metric_name und boundaries:

Um es schön einfach und aussagekräftig zu halten, nehmen Sie als Namen der Metrik den Namen der Variabel, in der der Prozentsatz als Wert gespeichert ist.

Mit boundaries können Sie dem Graphing-System die Information über den möglichen Wertebereich mitgeben. Damit ist der kleinste und größte mögliche Wert gemeint. Bei einem Prozentsatz sind die Grenzen mit 0.0 und 100.0 nicht allzu schwer zu bestimmen. Es sind sowohl Gleitkommazahlen (Float) als auch Ganzzahlen (Integer, die intern wiederum in Gleitkommazahlen umgewandelt werden) erlaubt, aber keine Strings. Falls nur eine Grenze des Wertebereichs definiert ist, tragen Sie für die andere einfach None ein, also zum Beispiel boundaries=(0.0, None).

Durch diese Erweiterung gibt die Funktion check_levels nun per yield zusätzlich zum Result auch noch ein Objekt vom Typ Metric zurück.

Analog können Sie jetzt auch die Metrik services_ok_perc definieren. Die letzten Zeilen der Check-Funktion sehen dann so aus:

Mit der so erweiterten Check-Funktion sind die beiden Graphen im Monitoring sichtbar. In der Service-Liste zeigt nun das Symbol , dass es Graphen zum Service gibt. Wenn Sie mit der Maus auf das Symbol zeigen, werden die Graphen als Vorschau eingeblendet.

Eine Übersicht aller Graphen inklusive Legende und mehr finden Sie in den Service-Details.

Was macht man aber, wenn der Wert für die gewünschte Metrik gar nicht mit der Funktion check_levels() definiert wurde? Sie können selbstverständlich eine Metrik auch unabhängig von einem Funktionsaufruf festlegen. Dazu dient das Objekt Metric(), welches Sie auch direkt über seinen Konstruktor erzeugen können. Die alternative Definition einer Metrik für den Wert hosts_up_perc sieht so aus:

Die Argumente von Metric() sind sehr ähnlich zu denen im oben gezeigten Funktionsaufruf: Verpflichtend sind die ersten beiden Argumente für den Metriknamen und den Wert. Zusätzlich gibt es noch zwei optionale Argumente: levels für die Schwellwerte WARN und CRIT und boundaries für den Wertebereich.

Wichtig: Die Angabe von levels dient hier lediglich als Information für die Darstellung des Graphen. Im Graphen werden die Schwellwerte üblicherweise als gelbe und rote Linien eingezeichnet. Für die Überprüfung ist die Funktion check_levels mit den dort festgelegten Schwellwerten verantwortlich.

Nutzen Sie nun die Möglichkeit, nicht nur die beiden berechneten Werte, sondern mit Metric() alle Messwerte als Metriken zu definieren — in unserem Beispiel also die vier Messwerte aus der Host-Gruppentabelle. Beschränken Sie sich dabei auf die beiden obligatorischen Angaben von Metrikname und Wert. Die vier neuen Zeilen komplettieren die Erweiterung der Check-Funktion für Metriken:

Das erhöht schon einmal die Zahl der Graphen pro Service, bietet Ihnen aber zum Beispiel auch die Möglichkeit, mehrere Metriken in einem Graphen zu kombinieren. Wir zeigen diese und andere Möglichkeiten im Abschnitt Darstellung von Metriken anpassen weiter unten.

In der Beispieldatei auf GitHub finden Sie wieder die gesamte Check-Funktion.

Im erweiterten Check-Plugin myhostgroups_advanced haben Sie den Zustand WARN erzeugt, wenn nur 90 % der Hosts UP sind, und CRIT bei 80 %. Dabei sind die Zahlen 90 und 80 direkt in der Check-Funktion fest einprogrammiert oder, wie Programmierer sagen würden, hart codiert. In Checkmk ist man allerdings als Benutzer gewohnt, dass man solche Schwellwerte und andere Check-Parameter per Regel konfigurieren kann. Denn hat zum Beispiel eine Host-Gruppe nur vier Mitglieder, dann passen die beiden Schwellwerte von 90 und 80 % nicht wirklich gut, da bereits beim Ausfall des ersten Hosts der Prozentsatz auf 75 % sinkt und der Zustand — ohne Umweg über WARN — direkt auf CRIT geht.

Daher soll das Check-Plugin nun so verbessert werden, dass es über die Setup-Oberfläche konfigurierbar ist. Dazu benötigen Sie einen Regelsatz. Falls es in Checkmk bereits einen passenden Regelsatz gibt, dann können Sie diesen verwenden. Da Check-Funktion und Regelsatz zusammenpassen müssen, wird dies in aller Regel nicht der Fall sein. Weiter unten finden Sie mehr Informationen zu vorhandenen Regelsätzen.

Hinweis: Beachten Sie, dass die in diesem Abschnitt vorgestellten Beispiele nicht durch die Check-API abgedeckt sind.

Bevor Sie eine neue Metrikdefinition erstellen, sollten Sie zunächst prüfen, ob Checkmk nicht bereits eine geeignete Definition mitbringt. Die vordefinierten Metrikdefinitionen finden Sie im Verzeichnis ~/lib/check_mk/gui/plugins/metrics/.

In der Datei cpu.py finden Sie beispielsweise die Metrik mit dem Namen util für die CPU-Auslastung (CPU utilization):

Falls Ihr Check-Plugin die CPU-Auslastung in Prozent misst, können Sie diese Metrikdefinition problemlos verwenden. Sie müssen lediglich in Ihrer Check-Funktion "util" als den Namen für die Metrik einsetzen. Alles andere leitet sich dann automatisch davon ab.

Falls keine passende Metrikdefinition dabei ist, legen Sie einfach selbst eine an.

Für unser Beispiel definieren Sie nun eine eigene Metrik für die Anzahl der Services im Zustand OK. Dazu legen Sie eine Datei in ~/local/share/check_mk/web/plugins/metrics an:

Hier die Erklärung dazu:

Diese Definition in der Metrikdatei sorgt jetzt dafür, dass Titel, Einheit und Farbe der Metrik angepasst dargestellt werden.

Analog zur Erstellung einer Regelsatzdatei muss die Metrikdatei erst gelesen werden, bevor die Änderung in der GUI sichtbar ist. Das macht der Neustart des Apache der Instanz:

Der Metrikgraph sieht dann in der Checkmk-GUI ungefähr so aus:

Möchten Sie mehrere Metriken in einem Graphen kombinieren (was oft sehr sinnvoll ist), benötigen Sie eine Graphdefinition, die Sie der im vorherigen Abschnitt erstellten Metrikdatei hinzufügen können. Dies geschieht über das globale Dictionary graph_info.

Für unser Beispiel sollen die beiden Metriken num_services_ok und num_services in einem Graphen dargestellt werden. Die Metrikdefinitionen dazu sehen wie folgt aus:

Fügen Sie nun einen Graphen an, der diese beiden Metriken als Linien einzeichnet:

Der erste Eintrag unter metrics legt fest, welche Metrik für den Titel des Graphen genommen wird. Das Resultat ist der kombinierte Graph in der Checkmk-GUI:

Möchten Sie zu einer Metrik noch ein Perf-O-Meter in der Zeile der Service-Liste anzeigen? Das könnte zum Beispiel so aussehen:

Um so ein Perf-O-Meter zu erstellen, benötigen Sie eine weitere Datei, diesmal im Verzeichnis ~/local/share/check_mk/web/plugins/perfometer:

Perf-O-Meter sind etwas trickreicher als Graphen, da es keine Legende gibt. Daher ist die Darstellung des Wertebereichs schwierig. Da das Perf-O-Meter nicht wissen kann, welche Werte denn überhaupt möglich sind, und der Platz sehr begrenzt ist, verwenden viele eingebaute Check-Plugins eine logarithmische Darstellung. Dies ist auch im obigen Beispiel der Fall:

Der Vorteil dieser Methode: Wenn Sie eine Liste von Services gleicher Art mit gleichartigen Perf-O-Metern ausstatten, können Sie die Perf-O-Meter untereinander optisch schnell vergleichen, da alle die gleiche Skala nutzen. Und trotz der kleinen Darstellungsform können Sie sowohl bei sehr kleinen als auch bei sehr großen Werten die Unterschiede gut erkennen. Dafür sind die Werte allerdings nicht maßstabsgetreu.

Das obige Perf-O-Meter zeigt zwar eine Metrik, aber nicht diejenige, die für den Zustand des Services verantwortlich ist. Nicht die Anzahl der Services im Zustand OK, sondern ihr Prozentsatz bestimmt den Zustand des gezeigten Services der Host-Gruppe.

Um die Metrik des Prozentsatzes (services_ok_perc) darzustellen, können Sie ein lineares Perf-O-Meter verwenden. Das ist immer dann sinnvoll, wenn es einen bekannten Maximalwert gibt. Das sähe dann zum Beispiel in der Datei so aus:

Und so in der GUI:

Das ist schon einmal eine Verbesserung. Allerdings wird der Zustand des Services nicht nur durch den Prozentsatz der Services im Zustand OK, sondern auch durch den Prozentsatz der Hosts im Zustand UP bestimmt. Um mehrere Metriken in einem Perf-O-Meter zu kombinieren, gibt es verschiedene Möglichkeiten. Eine davon sieht so aus:

Dies sorgt dafür, dass sich die beiden Metriken den Balken des Perf-O-Meters teilen und nebeneinander angezeigt werden:

Auch zu diesem Thema finden Sie viele Beispiele in den von Checkmk ausgelieferten Check-Plugins — in der Datei ~/lib/check_mk/gui/plugins/metrics/perfometers.py.

Absolute Zeitangaben (Zeitstempel) werden mit render.date() oder render.datetime() formatiert. Die Angaben erfolgen immer als Unix-Zeit, also in Sekunden ab dem 1. Januar 1970, 00:00:00 UTC — dem Beginn der Unix-Epoche. Dies ist auch das Format, mit dem die Python-Funktion time.time() arbeitet.

Vorteil an dieser Darstellung ist, dass sich damit sehr einfach rechnen lässt, also zum Beispiel die Berechnung des Zeitraums, wenn Start- und Endzeit bekannt sind. Die Formel ist dann einfach duration = end - start. Und diese Berechnungen funktionieren unabhängig von der Zeitzone, Sommerzeitumstellungen oder Schaltjahren.

render.date() gibt nur das Datum aus, render.datetime() fügt noch die Uhrzeit hinzu. Die Ausgabe erfolgt dabei gemäß der aktuellen Zeitzone desjenigen Checkmk-Servers, welcher den Check ausführt. Beispiele:

Wundern Sie sich jetzt nicht, dass render.datetime(0) als Uhrzeit nicht 00:00, sondern 01:00 ausgibt. Das liegt daran, dass wir dieses Handbuch in der Zeitzone von Deutschland schreiben — und die ist der Standardzeit UTC eine Stunde voraus (zumindest während der Normalzeit, denn der 1. Januar liegt ja bekanntlich nicht in der Sommerzeit).

Für Zeiträume (oder Zeitspannen) gibt es noch die Funktion render.timespan(). Diese bekommt eine Dauer in Sekunden und gibt das menschenlesbar aus. Bei größeren Zeitspannen werden Sekunden oder Minuten weggelassen. Wenn Sie eine Zeitspanne in einem TimeDelta-Objekt vorliegen haben, lesen Sie aus diesem mit der Funktion total_seconds() die Zahl der Sekunden als Fließkommazahl aus.

Eine Frequenz ist quasi der Kehrwert der Zeit. Die kanonische Einheit ist Hz, was das gleiche bedeutet wie 1 / sec. Einsatzgebiet ist zum Beispiel die Taktrate einer CPU:

Überall wo es um Arbeitsspeicher, Dateien, Festplatten, Dateisysteme und dergleichen geht, ist die kanonische Einheit das Byte. Da Computer so etwas meist in Zweierpotenzen organisieren, also zum Beispiel in Einheiten zu 512, 1024 oder 65 536 Bytes, hatte sich dabei von Beginn an eingebürgert, dass ein Kilobyte nicht 1000, und damit das Tausendfache der Einheit ist, sondern 1024 (2 hoch 10) Bytes. Das ist zwar unlogisch, aber sehr praktisch, weil so meist runde Zahlen herauskommen. Der legendäre Commodore C64 hatte eben 64 Kilobyte Speicher und nicht 65,536.

Leider kamen irgendwann Festplattenhersteller auf die Idee, die Größen ihrer Platten in 1000er-Einheiten anzugeben. Da bei jeder Größenordnung der Unterschied zwischen 1000 und 1024 immerhin 2,4 % ausmacht, und diese sich aufmultiplizieren, wird so aus einer Platte der Größe 1 GB (1024 mal 1024 mal 1024) auf einmal 1,07 GB. Das verkauft sich besser.

Diese lästige Verwirrung besteht bis heute und sorgt immer wieder für Fehler. Als Linderung wurden von der internationalen elektrotechnischen Kommission (IEC) neue Präfixe auf Grundlage des Binärsystems festgelegt. Demnach ist heute offiziell ein Kilobyte 1000 Bytes und ein Kibibyte 1024 Bytes (2 hoch 10). Außerdem soll man Mebibyte, Gibibyte und Tebibyte sagen. Die Abkürzungen lauten dann KiB, MiB, GiB und TiB.

Checkmk passt sich an diesen Standard an und hilft Ihnen mit mehreren angepassten Render-Funktionen dabei, dass Sie immer korrekte Ausgaben machen. So gibt es speziell für Festplatten und Dateisysteme die Funktion render.disksize(), welche die Ausgabe in 1000er-Potenzen macht.

Bei der Größe von Dateien ist es oft üblich, die genaue Größe in Bytes ohne Rundung anzugeben. Dies hat den Vorteil, dass man so sehr schnell sehen kann, wenn sich eine Datei auch nur minimal geändert hat oder dass zwei Dateien (wahrscheinlich) gleich sind. Hierfür ist die Funktion render.filesize() verantwortlich:

Wenn Sie eine Größe ausgeben möchten, die keine Festplatten- oder Dateigröße ist, dann verwenden Sie einfach das generische render.bytes(). Hier bekommen Sie die Ausgabe in klassischen 1024er-Potenzen in der offiziellen Schreibweise:

Die Netzwerker haben ihre eigenen Begriffe und Arten, Dinge auszudrücken. Und wie immer gibt sich Checkmk Mühe, in jeder Domäne die dort übliche Art zu kommunizieren, zu übernehmen. Deswegen gibt es für Datenraten und Geschwindigkeiten gleich drei verschiedene Render-Funktionen. Alle haben gemeinsam, dass die Raten in Bytes pro Sekunde übergeben werden, selbst dann, wenn die Ausgabe in Bits erfolgt!

render.nicspeed() stellt die Maximalgeschwindigkeit einer Netzwerkkarte oder eines Switchports dar. Da es keine Messwerte sind, muss auch nicht gerundet werden. Obwohl kein Port einzelne Bits versenden kann, sind die Angaben aus historischen Gründen in Bits.

Wichtig: Trotzdem müssen Sie auch hier Bytes pro Sekunde übergeben!

render.networkbandwidth() ist gedacht für eine tatsächlich gemessene Übertragungsgeschwindigkeit im Netzwerk. Eingabewert ist wieder Bytes pro Sekunde:

Wo es nicht ums Netzwerk geht und dennoch Datenraten ausgegeben werden, sind wieder Bytes üblich. Prominentester Fall sind IO-Raten von Festplatten. Dafür gibt es die Funktion render.iobandwidth(), die in Checkmk mit 1000er-Potenzen arbeitet:

Die Funktion render.percent() stellt einen Prozentsatz dar — auf zwei Nachkommastellen gerundet. Sie ist insofern eine Ausnahme zu den anderen Funktionen, als hier nicht der eigentlich natürliche Wert — also das Verhältnis — übergeben wird, sondern wirklich die Prozentzahl. Wenn also etwas zum Beispiel zur Hälfte voll ist, müssen Sie nicht 0.5 sondern 50 übergeben.

Weil es manchmal interessant sein kann, zu wissen, ob ein Wert beinahe Null oder exakt Null ist, werden Werte durch Anfügen eines „<“ Zeichens markiert, die größer als Null, aber kleiner als 0,01 Prozent sind.

Hier folgt zum Abschluss die Übersicht über alle Render-Funktionen:

Tritt eine Exception im Monitoring oder während der Service-Erkennung im Setup auf, enthält das Summary Hinweise auf den eben erstellten Absturzbericht (crash report). Das sieht dann zum Beispiel so aus:

Durch einen Klick auf das Icon wird eine Seite mit Details angezeigt, auf der Sie:

Der Traceback hilft Ihnen als Programmierer zu entscheiden, ob ein Fehler im Programm vorliegt (beispielsweise der Aufruf einer nicht vorhandenen Funktion) oder Agentendaten vorliegen, die nicht wie erwartet verarbeitet werden konnten. Im ersten Fall werden Sie den Fehler beheben wollen, im zweiten Fall ist es häufig sinnvoll, nichts zu tun.

Das Einsenden des Reports ist natürlich nur für Check-Plugins sinnvoll, die offiziell Teil von Checkmk sind. Falls Sie eigene Plugins Dritten zugänglich machen, können Sie Ihre Anwender bitten, Ihnen die Daten zukommen zu lassen.

Wenn Sie Ihr Check-Plugin auf der Kommandozeile ausführen, erhalten Sie keinen Hinweis auf die ID des erzeugten Absturzberichts. Sie sehen nur die zusammengefasste Fehlermeldung:

Hängen Sie die Option --debug als zusätzlichen Aufrufparameter an, dann bekommen Sie den Traceback des Python-Interpreters:

Tritt der Fehler beim Aufruf mit --debug beim nächsten Mal nicht mehr auf, zum Beispiel, weil eine neue Agentenausgabe bereitsteht, können Sie die letzten Absturzberichte auch im Dateisystem einsehen:

In jedem dieser Ordner liegen zwei Dateien:

In den oben gezeigten Beispielen verwenden wir die Funktion print(), um für Sie als Programmierer den Inhalt von Variablen oder die Struktur von Objekten auszugeben. Diese Funktionen für Debug-Ausgaben müssen aus dem fertigen Check-Plugin wieder entfernt werden.

Alternativ zur Entfernung können Sie Ihre Debug-Ausgabe auch nur ausgeben lassen, wenn das Check-Plugin in der Konsole im Debug-Modus aufgerufen wird. Dafür importieren Sie das Debug-Objekt aus der Checkmk-Werkzeugkiste und gegebenenfalls die Formatierungshilfe pprint(). Sie können nun Debug-Ausgaben abhängig vom Wert des Debug-Objektes vornehmen:

Beachten Sie, dass verbleibende Debug-Ausgaben sparsam verwendet und auf Hinweise beschränkt sein sollten, die den späteren Benutzern bei der Fehlersuche helfen. Offensichtliche und abzusehende Fehler des Benutzers (zum Beispiel, dass die Inhalte der Agentensektion darauf hindeuten, dass das Agentenplugin falsch konfiguriert ist) sollten Sie mit dem Zustand UNKNOWN und aussagekräftigen Hinweisen im Summary beantworten.

Die Frage ist, wie Sie reagieren sollen, wenn die Ausgaben vom Agenten nicht die Form haben, die Sie eigentlich erwarten — egal ob vom Checkmk-Agenten oder per SNMP erhalten. Angenommen, Sie erwarten pro Zeile immer drei Worte. Was sollen Sie tun, falls nur zwei kommen?

Nun, wenn das ein erlaubtes und bekanntes Verhalten des Agenten ist, dann müssen Sie das natürlich abfangen und mit einer Fallunterscheidung arbeiten. Falls das aber eigentlich nicht sein darf, dann tun Sie am besten so, als ob die Zeile immer aus drei Worten besteht, also zum Beispiel mit folgender Parse-Funktion:

Sollte jetzt mal eine Zeile dabei sein, die nicht aus genau drei Worten besteht, wird eine Exception erzeugt und Sie bekommen den gerade erwähnten sehr hilfreichen Absturzbericht.

Falls Sie auf Schlüssel in einem Dictionary zugreifen, die gelegentlich erwartbar fehlen, kann es natürlich sinnvoll sein, darauf entsprechend zu reagieren. Das kann erfolgen, indem Sie den Service auf CRIT oder UNKNOWN setzen und im Summary einen Hinweis auf die nicht auswertbare Agentenausgabe unterbringen. In jedem Fall ist es besser, Sie verwenden hierfür die get()-Funktion des Dictionaries als die KeyError Exception abzufangen. Denn get() liefert bei Nichtvorhandensein des Schlüssels ein Objekt vom Typ None oder einen optional als zweiten Parameter zu übergebenden Ersatz:

Was ist, wenn der Agent korrekte Daten ausgibt, aber das Item fehlt, das überprüft werden soll? Also zum Beispiel auf diese Art:

Ist das gesuchte Item nicht dabei, so wird die Schleife durchlaufen und Python fällt am Ende der Funktion einfach hinten raus, ohne dass ein Resultat per yield zurückgegeben wurde. Und das ist genau das Richtige! Denn daran erkennt Checkmk, dass das zu überwachende Item fehlt und erzeugt mit UNKNOWN den richtigen Status und einen passenden Standardtext dazu.

Wenn Sie bestimmte Agentenausgaben simulieren wollen, sind Spool-Dateien sehr hilfreich. Diese können Sie nutzen, um sonst schwer nachzustellende Grenzfälle zu testen. Oder Sie verwenden direkt die Agentenausgabe, welche zu einem Absturzbericht geführt hat, zur Prüfung von Änderungen an einem Check-Plugin.

Deaktivieren Sie zunächst Ihr reguläres Agentenplugin, beispielsweise indem Sie ihm die Ausführungsberechtigung entziehen. Erstellen Sie dann eine Datei im Verzeichnis /var/lib/check_mk_agent/spool/, welche die von Ihrem Check-Plugin erwartete Agentensektion (oder erwarteten Agentensektionen) inklusive Sektions-Header enthält und auf Newline endet. Beim nächsten Aufruf des Agenten wird dann der Inhalt der Spool-Datei statt der Ausgabe des Agentenplugins übertragen.

Bei einigen Check-Plugins, die Items nutzen, ist es auf größeren Servern durchaus möglich, dass einige hundert Services erzeugt werden. Wenn keine eigene Parse-Funktion verwendet wird, hat dies zur Folge, dass für jedes der hunderten Items die gesamte Liste von hunderten Zeilen durchlaufen werden muss. Die zum Suchen benötigte Zeit steigt also im Quadrat mit der Zahl der Listenelemente, bei hunderten Services bedeutet das zigtausende Vergleiche. Ist dagegen die geschachtelte Liste in ein Dictionary überführt, steigt der Aufwand für die Suche eines Elements nur linear mit der Größe des Dictionaries.

Im Python-Wiki finden Sie eine Übersicht der Kosten für die Suche in verschiedenen Datentypen, inklusive Erläuterung und O-Notation. Mit der Parse-Funktion reduzieren die Komplexität der Suche von O(n) auf O(1).

Da ältere Versionen dieses Artikels keinen Gebrauch von der Parse-Funktion gemacht haben, sollten Sie derartige Check-Plugins identifizieren und diese auf Verwendung einer Parse-Funktion umschreiben.