Eigene Check-Plugins schreiben

Welche Möglichkeiten haben Sie also, hier dennoch eine sinnvolle Überwachung zu implementieren? Nun — natürlich können Sie sich an unseren Support wenden und ein geeignetes Plugin entwickeln lassen. Aber Sie können sich auch selbst helfen. Dabei haben Sie erst einmal vier Möglichkeiten:

Dieser Artikel zeigt Ihnen, wie Sie echte Checkmk-Checkplugins entwickeln können — mit allem was dazugehört. Dabei zeigen wir Ihnen, wie Sie die in Version 2.0.0 von Checkmk neu entwickelte API für die Pluginprogrammierung nutzen.

Haben Sie schon Erfahrung mit dem Entwickeln von Checkplugins für die Checkmk-Version 1.6.0 oder früher? Dann finden Sie hier eine knappe Übersicht über alle Änderungen, welche die ab 2.0.0 verfügbare neue Check-API mit sich bringt:

Ja, die bis zu Version 1.6.0 von Checkmk gültige API für die Entwicklung von Checkplugins wird mit einigen kleinen Einschränkungen noch etliche Jahre unterstützt werden, da mit ihr sehr sehr viele Plugins entwickelt wurden. Während dieser Zeit wird Checkmk beide APIs parallel anbieten. Einzelheiten erfahren Sie in Werk #10601.

Trotzdem empfehlen wir für die Entwicklung von neuen Plugins die neue API, da diese konsistenter und logischer ist, besser dokumentiert und langfristig zukunftssicher.

Checkplugins werten die Daten der Checkmk-Agenten aus. Bevor wir uns ins Geschehen stürzen, sollten wir uns deshalb zunächst einen Überblick darüber verschaffen, welche Arten von Agenten Checkmk eigentlich kennt:

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

Als Vorbereitung sind außerdem folgende Artikel gut:

Am Anfang jeder Checkprogrammierung steht: die Recherche! Das bedeutet, dass wir herausfinden, wie wir überhaupt an die Informationen kommen, die wir für die Überwachung brauchen. Bei Linux sind das oft Kommandozeilenbefehle, bei Windows hilft die PowerShell, VBScript oder WMI und bei SNMP müssen wir die richtigen OIDs finden (dazu gibt es ein eigenes Kapitel).

Für das Herausfinden des richtigen Befehls gibt es leider kein allgemeines Vorgehen und so wollen wir uns auch nicht all zulange mit dem Thema aufhalten, erklären aber kurz, wie das mit dem USB-Stick funktioniert.

Zunächst loggen wir uns also auf dem zu überwachenden Host ein. Unter Linux läuft der Agent per Default als root-Benutzer. Deswegen machen wir auch alle unsere Tests als root. Für unsere Aufgabe mit dem USB-Stick gibt es praktischerweise symbolische Links im Verzeichnis /dev/disk/by-id. Diese zeigen auf alle Linux-Block-Devices. Und ein solches ist auch ein eingesteckter USB-Stick. Außerdem kann man an der ID am Präfix usb- erkennen, wenn ein Block-Device ein USB-Gerät ist.

Folgender Befehl listet alle Einträge in diesem Verzeichnis auf:

So. Und das Ganze jetzt mit eingestecktem USB-Stick:

Eigentlich wären wir damit fertig und könnten diese ganze Ausgabe per Checkmk-Agent zum Checkmk-Server transportieren und dort analysieren lassen. Denn im Checkmk gilt immer folgende Empfehlung: lassen Sie die komplexe Arbeit immer den Server erledigen. Halten Sie das Agentenplugin so einfach wie möglich.

Aber: Hier ist trotzdem noch zu viel heiße Luft drin. Es ist immer gut, unnötige Daten nicht zu übertragen. Das spart Netzwerkverkehr, Speicher, Rechenzeit und macht alles auch übersichtlicher. Das geht besser!

Als erstes können wir das -l weglassen. Damit ist die Ausgabe von ls schon deutlich schlanker:

Jetzt wiederum stört der mehrspaltige Aufbau, der aber nur deshalb erfolgt, weil der ls-Befehl erkennt, dass er in einem interaktiven Terminal läuft. Später als Teil vom Agenten wird er die Daten einspaltig ausgeben. Das können wir aber auch ganz einfach hier mit der Option -1 (für *ein*spaltige Ausgabe) erzwingen:

Wenn Sie genau hinsehen, werden Sie nicht nur die Blockgeräte selbst sehen, sondern auch dort vorhandene Partitionen. Dies sind die Einträge, die auf -part1, -part2 usw. enden. Diese brauchen wir für unseren Check nicht und bekommen sie ganz einfach weg mit einem grep. Dort nehmen wir die Option -v für eine negative Logik:

Hier sieht man jetzt auch viel deutlicher, dass es in unserem Beispiel genau drei Geräte sind, falls der USB-Stick eingesteckt ist:

Perfekt! Jetzt haben wir eine übersichtliche Liste aller Blockgeräte, die mit einem einfachen Befehl ermittelt wird. Mehr brauchen wir nicht.

Das -1 haben wir im letzten Kommando wieder weggelassen, weil ls jetzt in eine Pipe schreibt und von sich aus einspaltig ausgibt. Und grep braucht das --, da es sonst das Wort -part als die vier Optionen -p, -a, -r und -t interpretieren würde.

Übrigens: Warum „greppen“” wir nicht gleich noch nach usb? So dass nur noch USB-Geräte ausgegeben werden? Nun, natürlich könnten wir das tun. Aber zum einen wird dann unser Beispiel zunehmend langweilig und außerdem ist es irgendwie beruhigender, im Normalfall irgendeinen Inhalt in der Sektion zu bekommen und nicht einfach nur nichts. So kann man auf dem Checkmk-Server sofort erkennen, dass das Agentenplugin korrekt funktioniert.

Damit wir vom Checkmk-Server aus diese Daten abrufen können, müssen wir den neuen Befehl Teil vom Checkmk-Agenten auf dem überwachten System machen. Wir könnten dazu natürlich einfach dort die Datei /usr/bin/check_mk_agent editieren und das einbauen. Das hätte dann aber den Nachteil, dass bei einem Softwareupdate des Agenten unser Befehl wieder verschwindet, weil die Datei ersetzt wird.

Besser ist daher, wenn wir ein Agentenplugin machen. Das ist sogar noch einfacher. Alles was wir brauchen, ist eine ausführbare Datei mit unserem Befehl im Verzeichnis /usr/lib/check_mk_agent/plugins.

Und noch eins ist wichtig: Wir können unsere Daten nicht einfach so ausgeben. Was wir noch brauchen, ist ein Sektionskopf (section header). Das ist eine speziell formatierte Zeile, in der der Name unseres neuen Checks steht. An diesen Sektionsköpfen kann Checkmk später erkennen, wo die Daten des Plugins beginnen und die des vorherigen aufhören.

Also brauchen wir jetzt erst einmal einen sinnvollen Namen für unseren neuen Check. 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 zweite Spalte zeigt an, wie das jeweilige Checkplugin seine Daten bezieht.

Wählen wir für unser Beispiel den Namen linux_usbstick. In diesem Fall muss der Sektionskopf so aussehen:

Den können wir einfach mit echo ausgeben. Wenn wir dann noch den „Shebang“ nicht vergessen (das ist kein giftiger Stachel aus dem Wüstenplaneten sondern 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 Shell ausführen soll, dann sieht unser Plugin so aus:

Als Dateiname haben wir jetzt einfach auch linux_usbstick verwendet, auch wenn der eigentlich egal ist. Aber eines ist noch sehr wichtig: Machen Sie die Datei ausführbar!

Natürlich können Sie das Plugin ganz einfach von Hand ausprobieren, indem Sie den kompletten Pfad als Befehl eingeben:

Wie immer sind Test und Fehlersuche am wichtigsten. 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 Ausgabe muss die neue Sektion erscheinen:

Hier ist ein Ausschnitt der Ausgabe, welcher die neue Sektion enthält:

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):

Der dritte Test ist dann direkt von der Checkmk-Instanz aus. Nehmen Sie den Host ins Monitoring auf (z.B. als myserver01) und rufen Sie die Agentendaten dann mit cmk -d ab. Hier sollte die gleiche Ausgabe kommen:

Übrigens: grep hat mit -A eine Option, nach jedem Treffer noch einige Zeilen mehr auszugeben. Damit können Sie bequem die Sektion suchen und ausgeben:

Wenn das funktioniert, ist Ihr Agent vorbereitet! Und was haben wir dafür gemacht? Wir haben lediglich ein dreizeiliges Skript mit dem Pfad /usr/lib/check_mk_agent/plugins/linux_usbstick erzeugt und ausführbar gemacht!

Alles was nun folgt, geschieht nur noch auf dem Checkmk-Server: Dort schreiben wir das eigentliche Checkplugin.

Das Vorbereiten des Agenten ist zwar der komplizierteste Teil, aber nur die halbe Miete. Jetzt müssen wir Checkmk noch beibringen, wie es mit den Informationen und der neuen Agentensektion umgehen soll, welche Services es erzeugen soll, wann diese auf OK oder CRIT gehen sollen usw. All dies machen wir durch die Programmierung eines Checkplugins in Python.

Für Ihre eigenen Checkplugins finden Sie ein Verzeichnis vorbereitet in der local-Hierarchie des Instanzverzeichnisses. Dieses lautet local/lib/check_mk/base/plugins/agent_based/. Hier im Pfad bedeutet base den Teil von Checkmk, der für das eigentlich Monitoring und die Alarmierung zuständig ist. Das agent_based ist für alle Plugins, die sich auf den Checkmk-Agenten beziehen (also z.B. nicht Alarmierungsplugins). Am einfachsten, Sie wechseln zum Arbeiten dort hinein:

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

Legen wir also unser 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 Plugins immer um echte Pythonmodule.

Als erstes müssen wir die für die Plugins nötigen Funktionen aus anderen Pythonmodulen importieren. Die einfachste Methode dafür ist die mit einem *. Wie Sie vielleicht ahnen können, steckt hier auch eine Versionsnummer der API für die Pluginprogrammierung. Diese ist bis auf weiteres Version 1, was hier durch v1 abgekürzt ist:

Diese Versionierung ermöglicht es uns in Zukunft eventuell neue Versionen der API parallel zu den bisherigen bereitzustellen, so dass bestehende Checkplugins weiterhin problemlos funktionieren.

Im einfachsten Fall überspringen Sie das explizite deklarieren der Sektion. Wenn Sie eine Parsefunktion implementieren möchten (wozu Ihnen professionelle Entwickler immer raten würden), finden Sie im Abschnitt über Parsefunktionen mehr Informationen.

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

Für unseren Check sieht das dann also so aus:

Versuchen Sie am besten noch nicht, das gleich auszuprobieren, denn natürlich müssen wir die Funktionen discover_linux_usbstick und check_linux_usbstick vorher noch schreiben. Und diese müssen im Quellcode vor obiger Deklaration erscheinen.

Eine Besonderheit von Checkmk ist die automatische Erkennung von zu überwachenden Services. Damit dies klappt, muss jedes Checkplugin eine Funktion definieren, welche anhand der Agentenausgaben 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 Serviceerkennung durchgeführt wird. Sie entscheidet dann ob, bzw. welche Services angelegt werden sollen. In Standardfall bekommt sie genau ein Argument mit dem Namen section. Dieses enthält die Daten der Agentensektion in einem geparsten Format (dazu später mehr).

Wir implementieren folgende simple Logik: Wenn die Agentensektion linux_usbstick vorhanden ist, dann legen wir auch einen passenden Service an. Dann erscheint dieser automatisch auf allen Hosts, wo unser Agentenplugin ausgerollt ist. Das Vorhandensein der Sektion erkennen wir ganz einfach daran, dass unsere Discovery überhaupt aufgerufen wird!

Die Discovery-Funktion muss für jeden anzulegenden Service mittels yield ein Objekt vom Typ Service zurückgeben (nicht mit return). Bei Checks, die pro Host nur einmal auftreten können, benötigt man keine weitere Angaben:

Somit können wir nun zur eigentlichen Check-Funktion kommen, welche anhand aktueller Agentenausgaben endlich entscheidet, welchen Zustand ein Service annehmen soll. Da unser Check keine Parameter hat und es auch immer nur einen pro Host gibt, wird unsere Funktion ebenfalls mit dem einzigen Argument section aufgerufen.

Da wir diesmal den Inhalt auch wirklich brauchen, müssen wir uns mit dem Format dieses Arguments befassen. Solange Sie keine explizite Parsefunktion definiert haben, zerlegt Checkmk jede Zeile der Sektion anhand von Leerzeichen in eine Liste von Worten. Das Ganze wird dann wiederum eine Liste dieser Wortlisten. Als Endergebnis haben wir also immer eine Liste von Listen.

Im einfachen Fall, in dem unser Agentenplugin nur zwei Devices findet, sieht das dann z.B. so aus (hier gibt es pro Zeile nur ein Wort):

Die Check-Funktion geht nun Zeile für Zeile durch und sucht nach einer Zeile, deren erstes (und einziges) Wort mit usb-SCSI_DISK beginnt. Wenn das der Fall ist, wird der Zustand CRIT. Hier ist die Implementierung:

Und hier die Erklärung:

Und hier ist das ganze Plugin nochmal komplett:

Und das hier war das Plugin für den Linux-Agenten:

In unserem Beispiel haben wir einen sehr einfachen Check gebaut, der auf einem Host einen Service erzeugt — oder eben nicht. Ein sehr üblicher Fall ist aber natürlich 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 Plugin mit dem Namen df legt pro Dateisystem auf dem Host einen Service an. Um diese Services zu unterscheiden, wird der Mountpunkt des Dateisystems (z.B. /var) bzw. der Laufwerksbuchstabe (z.B. C:) in den Namen des Services eingebaut. Das ergibt dann als Servicename z.B. 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 das ganze praktisch ausprobieren zu können, bauen wir uns einfach eine weitere Agentensektion, die nur Spieldaten ausgibt. Dazu genügt ein kleines Shell-Skript. Die Sektion soll hier im Beispiel foobar heißen:

Von foobar gibt es hier drei Sektoren: West, East und North (was immer auch das bedeuten mag). In jedem Sektor gibt es eine Anzahl von Plätzen von denen einige belegt sind (z.B. sind in West 100 von 100 Plätzen belegt).

Nun legen wir dazu ein passendes Checkplugin an. Die Registrierung ist wie gehabt, allerdings mit dem wichtigen Unterschied, dass der Servicename jetzt genau einmal ein %s enthält. An dieser Stelle wird später dann von Checkmk der Name des Items eingesetzt:

Die Discovery-Funktion hat jetzt die Aufgabe, die zu überwachenden Items zu ermitteln. Wie gehabt bekommt sie das Argument section. Und auch hier handelt es sich um eine Liste von Zeilen, welche ihrerseits wiederum Listen von Worten sind. Diese sieht in unserem Beispiel aus aus:

So eine Liste kann man mit Python prima in einer Schleife durchlaufen und den drei Worten pro Zeile gleich sinnvolle Namen geben:

In jeder Zeile ist das erste Wort — hier der Sektor — unser Item. Immer wenn wir ein Item gefunden haben, geben wir das mit yield zurück, wobei wir ein Objekt vom Typ Service erzeugen, welches den Sektornamen als Item bekommt. Der Unterstrich zeigt an, dass uns die beiden andere Spalten in der Ausgabe erst einmal egal sind, denn bei der Discovery ist es schließlich unerheblich, wie viele Slots belegt sind. Insgesamt sieht das dann so aus:

Es wäre natürlich ein Leichtes, hier anhand von beliebigen Kriterien manche Zeilen auszulassen. Vielleicht gibt es ja Sektoren, welche die Größe 0 haben und die man grundsätzlich nie überwachen möchte? Lassen Sie solche Zeilen einfach aus und „yielden“” Sie dafür kein Item.

Wenn dann später der Host überwacht wird, dann wird die Check-Funktion für jeden Service — und damit für jedes Item — separat aufgerufen. Sie bekommt deswegen zusätzlich zur Sektion das Argument item mit dem jeweils gesuchten Item. Jetzt gehen wir wieder alle Zeilen der Reihe nach durch. Dabei suchen wir diejenige Zeile heraus, die zum gewünschten Item gehört:

Jetzt fehlt nur noch die eigentliche Logik, welche festlegt, wann das Ding denn überhaupt OK, WARN oder CRIT sein soll. Wir machen es hier so:

Die belegten und die verfügbaren Slots kommen ja immer als Wort zwei und drei in jeder Zeile vor. Aber: es handelt sich hier um Strings, nicht um Zahlen. Diese brauchen wir aber, um vergleichen und rechnen zu können. Daher wandeln wir die Strings mit int() in Zahlen um.

Das Checkergebnis liefern wir dann, indem wir ein Objekt vom Typ Result per yield liefern. Dieses benötigt die Parameter state und summary:

Dazu noch folgende Hinweise:

Übrigens gibt es für den häufigen Fall, dass Sie eine einfache Metrik auf Schwellwerte prüfen wollen, die Hilfsfunktion check_levels. Diese Hilfsfunktion wird in der Check-API-Dokumentation erläutert, die Sie in Checkmk über Help > Plugin API reference > Agent based API (“Check API”) aufrufen können.

Probieren wir jetzt zunächst die Discovery aus. Der Übersicht halber beschränken wir das ganze mit der Option --detect-plugins=foobar auf unser Plugin:

Und jetzt können wir auch gleich das Checken ausprobieren (ebenfalls auf foobar begrenzt):

Und hier nochmal das ganze Beispiel komplett. Damit es keine Fehler wegen nicht definierter Funktionsnamen gibt, müssen die Funktionen immer vor dem Registrieren definiert werden.

Nicht immer, aber oft befassen sich Checks mit Zahlen. Mit seinem Graphingsystem hat Checkmk eine Komponente, um solche Zahlen zu speichern, auszuwerten und darzustellen. Das geht dabei völlig unabhängig von der Berechnung der Zuständige OK, WARN und CRIT.

Solche Messwerte — oder auch Metriken genannt — werden von der Check-Funktion ermittelt und einfach als zusätzliches Ergebnis zurückgegeben. Dazu dient das Objekt Metric, welches mindestens die beiden Argumente name und value benötigt. Hier ist ein Beispiel:

Weiterhin gibt es noch zwei optionale Argumente. Mit dem Argument levels können Sie eine Information zu Schwellwerten für WARN und CRIT mitgeben, und zwar in Form eines Paares von zwei Zahlen. Diese wird dann üblicherweise im Graphen als gelbe und rote Linie eingezeichnet. Die erste Zahl steht für die Warnschwelle, die zweite für die kritische. Dabei gilt die Konvention, dass der Check beim Erreichen der Warnschwelle bereits auf WARN geht (bei CRIT analog).

Das sieht dann z.B. so aus (hier mit hartkodierten Schwellwerten):

Hinweise:

Analog zu den Schwellwerten können Sie dem Graphingsystem auch die Information über den möglichen Wertebereich mitgeben. Damit ist der kleinste und größte mögliche Wert gemeint. Das geschieht im Argument boundaries, wobei auch hier optional für eine der beiden Grenzen None eingesetzt werden kann. Beispiel:

Und jetzt unsere Check-Funktion aus dem obigen Beispiel nochmal, aber diesmal mit der Rückgabe von Metrikinformation inklusive Schwellwerte und Wertebereich (diesmal natürlich nicht mit fixen sondern mit berechneten Werten):

Die korrekte Behandlung von Fehlern nimmt (leider) einen großen Teil der Programmierarbeit ein. Die gute Nachricht ist: die API von Checkmk erledigt dabei bereits die meiste Arbeit. Meistens ist für Sie daher wichtig, dass Sie Fehler einfach gar nicht behandeln.

Wenn Python in eine Situation kommt, die in irgendeiner Form unerwartet ist, reagiert es mit einer sogenannten Exception. Hier sind ein paar Beispiele:

Hier gilt die generelle wichtige Regel: Fangen Sie Exceptions nicht selbst ab! Denn Checkmk übernimmt das für Sie in einer sinnvollen immer gleichen Art und Weise. Und zwar meist mit einem Crashreport. Das sieht dann z.B. so aus:

Durch einen Klick auf das Icon gelangt der Anwender dann auf eine Seite, auf der er:

Das Einsenden des Reports macht natürlich nur Sinn für Checkplugins, welche offiziell Teil von Checkmk sind. Aber Sie können Ihre Anwender bitten, Ihnen die Daten einfach zukommen zu lassen. Diese werden Ihnen beim Finden des Fehlers helfen. Oft ist es ja so, dass das Checkplugin bei Ihnen selbst funktioniert, aber es bei anderen Anwendern vielleicht sehr sporadisch zu Fehlern kommt. Diese können Sie dann so meist sehr leicht finden.

Falls Sie stattdessen die Exception selbst abfangen würden, wären diese ganzen Informationen nicht verfügbar. Sie würden vielleicht den Service auf UNKNOWN setzen und eine Fehlermeldung ausgeben. Aber die ganzen Umstände, wie es dazu kam (z.B. die Daten vom Agenten), wäre verschleiert.

Falls Sie ihr Plugin auf der Kommandozeile ausführen, werden keine Crashreports erzeugt. Sie sehen nur die zusammengefasste Fehlermeldung:

Aber: hängen Sie einfach die Option --debug dran. Dann bekommt Sie den Python-Stacktrace:

Die Frage ist, wie Sie reagieren sollen, wenn die Ausgaben vom Agenten nicht die Form haben, die Sie eigentlich erwarten würden - egal ob es der „echte“ Agent ist oder die Daten per SNMP kommen. Nehmen wir an, dass Sie pro Zeile immer drei Worte erwarten. 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 z.B. mit:

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

Was ist, wenn der Agent korrekte Daten ausgibt, aber das Item fehlt, das überprüft werden soll? Also z.B. 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 „geyieldet“ 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.

Das Entwickeln von Checks, die mit SNMP arbeiten, läuft sehr ähnlich zu den agentenbasierten, nur dass Sie hier noch angeben müssen, welche SNMP-Bereiche (OIDs) der Check benötigt. Falls Sie noch keine Erfahrung mit SNMP haben, so empfehlen wir Ihnen an dieser Stelle als Vorbereitung unbedingt den Artikel über das Monitoring via SNMP.

Der Ablauf der Discovery und des Checkens via SNMP ist etwas anders als beim normalen Agenten. Denn anders also dort — wo der Agent von sich aus alle interessanten Informationen sendet — müssen wir bei SNMP selbst genau sagen, welche Datenbereiche wir benötigen. Ein Komplettabzug aller Daten wäre zwar theoretisch möglich (via SNMP-Walk), dauert aber bei schnellen Geräten eher im Bereich von Minuten und bei komplexen Switches gern auch über eine Stunde. Daher scheidet das beim Checken und sogar auch bei der Discovery aus. Checkmk geht deswegen etwas zielgerichteter vor.

Bevor wir weitermachen wollen wir hier noch ein Wort zu den berüchtigten SNMP-MIBs verlieren, denn über diese gibt es viele Vorurteile. Gleich zu Beginn eine gute Nachricht: Checkmk benötigt sie nicht. Wirklich! Sie sind aber eine wichtige Hilfe, um einen SNMP-Check entwickeln zu können.

Was ist nun eine MIB? Wörtlich bedeutet die Abkürzung Management Information Base — etwas nichtssagend. Konkret ist eine MIB eine ganz gut lesbare Textdatei, welche einen bestimmten Teilbaum der SNMP-Welt beschreibt. Und zwar steht hier, welcher Ast im Baum — also welche OID — welche Bedeutung hat. Das umfasst einen Namen für die OID, einen Hinweis, welche Werte diese annehmen kann (z.B. bei enumerierten Datentypen, wo dann Dinge wie 1=up, 2=down, etc. festgelegt sind) und manchmal auch noch einen nützlichen Kommentar.

Checkmk liefert eine Reihe von frei verfügbaren MIB-Dateien mit aus. Diese beschreiben sehr allgemeine Bereiche im globalen OID-Baum, enthalten aber keine herstellerspezifischen Bereiche. Daher helfen sie für selbst entwickelte Checks nicht viel weiter.

Versuchen Sie also, die für Ihr spezielle Gerät relevanten MIB-Dateien irgendwo auf den Webseiten vom Hersteller oder sogar auf dem Management-Interface des Geräts zu finden und installieren Sie diese in der Checkmk-Instanz nach local/share/check_mk/mibs. Dann können Sie in SNMP-Walks OID-Nummern in Namen umrechnen lassen und so schneller finden, wo die für das Monitoring interessanten Daten sind. Wie gesagt, enthalten die MIBs außerdem interessante Informationen in den Kommentaren — wenn sie sorgfältig gemacht sind. Sie können eine MIB-Datei einfach mit einem Texteditor oder mit less ansehen.

Die entscheidende Voraussetzung, um ein Plugin zu entwickeln, ist natürlich, dass Sie wissen, welche OIDs die notwendigen Informationen enthalten. Der erste Schritt dabei ist (falls das Gerät das nicht verweigert), einen kompletten SNMP-Walk zu ziehen. Dabei werden alle per SNMP verfügbaren Daten abgerufen.

Checkmk kann das sehr einfach für Sie erledigen. Nehmen Sie dazu zunächst das Gerät (oder eines der Geräte), für das Sie ein Plugin entwickeln wollen, ins Monitoring auf. Sagen wir es heißt mydevice01. Stellen Sie sicher, dass dieses in den Grundfunktionen überwacht werden kann. Zumindest müssen die Services SNMP Info und Uptime gefunden werden und wahrscheinlich auch noch mindestens ein Interface. So stellen Sie sicher, dass der SNMP-Zugriff sauber funktioniert.

Wechseln Sie dann auf die Kommandozeile der Checkmk-Instanz. Hier können Sie mit folgendem Befehl einen kompletten Walk ziehen. Dabei empfehlen wir, gleich die Option -v (verbose) zu verwenden:

Wie bereits erwähnt, kann so ein Komplettwalk Minuten oder sogar Stunden dauern (auch wenn letzteres eher selten ist). Werden Sie also nicht nervös, wenn es hier etwas dauert. Der Walk wurde nun in der Datei var/check_mk/snmpwalks/mydevice01 gespeichert. Es handelt sich dabei um eine gut lesbare Textdatei, die etwa so beginnt:

In jeder Zeile steht eine OID und danach deren Wert. Und gleich in der ersten Zeile finden Sie die wichtigste, nämlich die sysDescr.

Nun sind die OIDs nicht sehr aussagekräftig. Wenn die richtigen MIBs installiert sind, können Sie diese in einem zweiten Schritt mit dem Befehl cmk --snmptranslate in Namen umrechnen lassen. Am besten leiten Sie das Ergebnis, was ansonsten im Terminal käme, in eine Datei um:

Die Datei translated liest sich wie der ursprüngliche Walk, hat aber in jeder Zeile nach dem --> einen übersetzten Wert für die OID:

Beispiel: die OID .1.3.6.1.2.1.1.4.0 hat den übersetzten Namen SNMPv2-MIB::sysContact.0. Dies ist ein wichtiger Hinweis, der Rest ist dann Übung, Erfahrung und natürlich experimentieren.

Wenn Sie also die notwendigen OIDs herausgefunden haben, geht es an die eigentliche Entwicklung des Plugins. Das geschieht in drei Schritten:

Die ersten beiden Schritte erfolgen durch die Registrierung einer SNMP-Sektion. Dies erledigen Sie durch den Aufruf von register.snmp_section(). Hier geben Sie mindestens drei Argumente an: den Namen der Sektion (name), die Angaben für die SNMP-Detection detect und die benötigten OID-Zweige für das eigentlich Monitoring (fetch). Hier ist ein Beispiel für ein fiktives Checkplugin mit dem Namen foo:

Die wichtigste Stelle der SNMP-Deklaration ist die Angabe, welche OIDs für das Monitoring geholt werden sollen. In fast allen Fällen benötigt ein Plugin dazu nur ausgewählte Äste aus einer einzigen Tabelle. Betrachten wir folgendes Beispiel:

Das Schlüsselwort base gibt hier einen OID-Präfix an. Alle nötigen Daten liegen unterhalb. Bei oids geben Sie dann eine Liste von Sub-OIDs an, die ab dort geholt werden sollen. In obigem Beispiel werden dann insgesamt drei SNMP-Walks gemacht, nämlich ausgehend von den OIDs .1.3.6.1.4.1.35424.1.2.4.0, .1.3.6.1.4.1.35424.1.2.5.0 und .1.3.6.1.4.1.35424.1.2.8.0. Dabei ist es wichtig, dass diese Walks die gleiche Anzahl von Variablen holen und dass diese auch einander entsprechen. Damit ist gemeint, dass z.B. das n-te Element aus jedem der Walks dem selben überwachten Objekt entspricht.

Hier ist ein Beispiel vom Checkplugin snmp_quantum_storage_info:

Hier wird pro Storage-Gerät jeweils die Vendor ID, die Product ID, die Product Revision und die Seriennummer geholt.

Der Discovery- und Check-Funktion werden diese Daten als Tabelle präsentiert, also als Liste von Listen. Dabei wird die Tabelle so gespiegelt, dass Sie pro Eintrag in der äußeren Liste alle Daten zu einem Item haben. Jeder Eintrag hat so viele Elemente, wie Sie bei oids angegeben haben. So können Sie die Liste sehr praktisch mit einer Schleife durchlaufen, z.B.

Bitte beachten Sie:

Hier beschreiben wir in Zukunft noch:

In der Summary oder den Details eines Services werden oft Zahlen ausgegeben. Um Ihnen eine schöne und korrekte Formatierung möglichst einfach zu machen, und um auch die Ausgaben von allen Checkplugins zu vereinheitlichen, gibt es Hilfsfunktionen für die Darstellung von verschiedenen Arten von Größen. Alle diese sind Unterfunktionen vom Modul render und werden folglich mit render. aufgerufen. Z.B. ergibt render.bytes(2000) den Text 1.95 KiB.

Allen diesen Funktionen ist gemein, dass Sie ihren Wert in einer sogenannten kanonischen oder natürlichen Einheit bekommen. So muss man nie nachdenken und es gibt keine Schwierigkeiten oder Fehler bei der Umrechnung. Z.B. werden Zeiten immer in Sekunden angegeben und Größen von Festplatten, Dateien, etc. immer in Bytes und nicht in Kilobytes, Kibibytes, Blöcken oder sonstigem Durcheinander.

Bitte verwenden Sie diese Funktionen auch dann, wenn Ihnen die Darstellung nicht so gut gefällt. Immerhin ist diese dann für den Benutzer einheitlich. Und zukünftige Versionen von Checkmk können die Darstellung möglicherweise ändern oder sogar konfigurierbar für den Benutzer machen. Davon wird dann Ihr Checkplugin auch profitieren.

Nach der ausführlichen Beschreibung aller Darstellungsfunktionen (Renderfunktionen) finden Sie eine Zusammenfassung in Form einer übersichtlichen Tabelle.

Absolute Zeitangaben (Zeitstempel) werden mit render.date() oder render.datetime() formatiert. Die Angaben erfolgen immer in Sekunden ab dem 1. Januar 1970, 00:00:00 UTC — der sogenannten Epochenzeit. Dies ist auch das Format, mit dem die Pythonfunktion time.time() arbeitet. Vorteil an dieser Darstellung ist, dass sich damit sehr einfach rechnen lässt, also z.B. die Dauer eines Vorgangs, 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 dabei 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:

Bitte wundern Sie sich jetzt nicht, dass render.date(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 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.

Eine Frequenz ist quasi der Kehrwert der Zeit. Die kanonische Einheit ist Hz, was das gleiche bedeutet wie 1 / sec. Einsatzgebiet ist z.B. 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 z.B. in Einheiten zu 512, 1024 oder 65536 Bytes, hatte sich dabei von Beginn an eingebürgert, dass ein Kilobyte nicht 1000, sondern 1024 Bytes ist. An sich sehr praktisch, weil so meist runde Zahlen rauskamen. 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 1000’er-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 * 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 neue Präfixe auf Grundlage des Binärsystems festgelegt. Demnach ist heute offiziell ein Kilobyte 1000 Byte und ein Kibibyte 1024 Byte (2 hoch 10). Außerdem soll man Mebibyte und Gibitbyte und Tebibyte sagen (schon mal gehört?). Die Abkürzungen lauten (Achtung, hier auf einmal immer i, statt e!) KiB, MiB, GiB und TiB.

Checkmk passt sich an diesen Standard an und hilft Ihnen mit mehreren angepassten Renderfunktionen dabei, dass Sie immer korrekte Ausgaben machen. So gibt es speziell für Festplatten und Dateisysteme die Funktion render.disksize(), welche die Ausgabe in 1000’er-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 Platten- oder Dateigröße ist, dann verwenden Sie einfach das generische render.bytes(). Hier bekommen sie die Ausgabe in klassischen 1024’er-Potenzen in der neuen 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 Renderfunktionen. 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. Achtung: trotzdem müssen Sie auch hier Bytes pro Sekunde übergeben! Beispiele:

render.networkbandwidth() ist für eine tatsächlich gemessene Übertragungsgeschwindigkeit im Netzwerk. Eingabewert sind wieder Bytes pro Sekunde (Oder „Oktette“, wie der Netzwerker sagen würde):

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 Renderfunktion render.iobandwidth(), die in Checkmk mit 1000’er-Potzenzen arbeitet:

Die Funktion render.percent() stellt einen Prozentwert dar — auf zwei Nachkommastellen gerundet. Es 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 z.B. 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 sind.

Hier ist nochmal eine Übersicht über alle Renderfunktionen:

In einem unserer bisherigen Beispiele haben wir den Zustand WARN erzeugt, falls nur noch 10 oder weniger Slots frei waren. Dabei war die Zahl 10 direkt in der Checkfunktion fest einprogrammiert - hart codiert, wie Programmierer sagen würden. In Checkmk ist man allerdings als Anwender eher gewohnt, dass man solche Schwellwerte und Parameter per Regel konfigurieren kann. Deswegen wollen wir uns als nächstes ansehen, wie auch Sie Ihren Check so verbessern können, dass er über die Setup-Oberfläche konfigurierbar ist.

Dazu müssen wir zwei Fälle unterscheiden:

Die ausgelieferten Regelsätze für Parameter von Checks finden Sie im Verzeichnis lib/check_mk/gui/plugins/wato/check_parameters/. Nehmen wir als Beispiel die Datei memory_simple.py. Diese deklariert einen Regelsatz mit folgendem Abschnitt:

Entscheidend für Sie ist dabei das Schlüsselwort check_group_name, welches hier auf "memory_simple" gesetzt ist. Damit wird die Verbindung zum Checkplugin hergestellt. Das machen Sie beim Registrieren des Checks mit dem Schlüsselwort check_ruleset_name, zum Beispiel:

Zwingend notwendig ist dabei auch die Definition von Defaultparametern über das Schlüsselwort check_default_parameters. Diese Parameter gelten für Ihren Check dann, wenn der Benutzer noch keine Regel angelegt hat. Falls es keine verpflichtenden Parameter gibt, können Sie einfach das leere Dictionary {} als Wert nehmen.

Wie der jeweils vom Benutzer konfigurierte Wert dann bei der Checkfunktion ankommt, werden wir dann weiter unten sehen.

Falls es keinen passenden Regelsatz gibt (was wohl eher der Normalfall ist), müssen wir uns selbst einen neuen erzeugen. Dazu legen wir eine Datei im Verzeichnis local/share/check_mk/web/plugins/wato an. Der Name der Datei sollte sich an dem des Checks orientieren und er muss wie alle Plugindateien die Endung .py haben.

Sehen wir uns den Aufbau so einer Datei Schritt für Schritt an. Zunächst kommen einige Importbefehle. Falls die Texte in Ihrer Datei in andere Sprachen übersetzbar sein sollen, importieren Sie _ (Unterstrich). Dies ist eine Funktion und fungiert als Markierung für alle übersetzbaren Texte. Im Weiteren schreiben Sie dann z.B. anstelle von "Threshold for warn" ein _("Threshold for warn") für den Funktionsaufruf.

Das Übersetzungssystem von Checkmk, welches auf gettext basiert, findet solche Texte und übernimmt sie in die Liste der zu übersetzenden Texte auf. Falls Sie den Check nur für sich selbst bauen, können Sie darauf auch verzichten und brauchen den folgenden Importbefehl nicht:

Als nächstes importieren wir sogenannte ValueSpecs. Ein ValueSpec ist ein sehr praktisches und universelles Werkzeug, das Checkmk an vielen Stellen verwendet. Es dient dem Generieren von angepassten Eingabemasken, der Darstellung und Validierung der eingegebenen Werte und der Umwandlung in Python-Datenstrukturen. In folgendem Beispiel werden Dictionary, Integer und TextInput importiert.

Das Dictionary benötigen Sie auf jeden Fall. Denn seit Version 2.0.0 von Checkmk ist es zwingend vorgeschrieben, dass Checkparameter Python-Dictionaries sein müssen. Früher konnte es z.B. auch ein Paar (Tupel aus zwei Zahlen) sein (z.B. Warn/Crit).

Integer ist für die Eingabe einer Zahl ohne Kommastellen verantwortlich und TextInput für einen Unicode-Text.

Als nächstes werden noch Symbole importiert, die beim Registrieren benötigt werden:

Falls Ihr Check kein Item hat, importieren Sie stattdessen CheckParameterRulespecWithoutItem. Zur RulespecGroup…​. schreiben wir weiter unten noch etwas.

Nun kommen die eigentlichen Definitionen. Zunächst deklarieren wir ein Eingabefeld, mit dem der Benutzer das Item des Checks angeben kann. Dies ist für die Regelbedingung notwendig, und auch für das manuelle Anlegen von Checks, welche ohne Discovery funktionieren sollen. Das erledigen wir mit TextInput. Dieses bekommt per title einen Titel zugewiesen, welcher dann in der Regel als Überschrift für das Eingabefeld angezeigt wird:

Den Namen der Funktion, welche diese ValueSpec zurückgibt, können Sie frei wählen, er wird nur an der Stelle weiter unten benötigt. Damit er nicht über die Modulgrenze hinaus sichtbar wird, sollte er mit einem Unterstrich beginnen.

Als nächstes kommt das ValueSpec für die Eingabe des eigentlichen Checkparameters. Auch hierfür legen wir eine Funktion an, welche dieses erzeugt. Das return Dictionary(…​) ist vorgeschrieben. Innerhalb dessen legen Sie mit elements=[…​] die Liste der Unterparameter für diesen Check an. In unserem Beispiel gibt es nur einen: die Warnschwelle für die freien Slots. Dies soll eine Ganzzahl sein, also verwenden wir hier ein Integer.

Zu guter Letzt registrieren wir jetzt mithilfe der importierten und selbstdefinierten Dinge einen neuen Regelsatz. Dazu gibt es die Funktion rulespec_registry.register():

Dazu noch einige Hinweise:

Damit die Regel zum Greifen kommt, müssen wir dem Checkplugin erlauben, Checkparameter entgegenzunehmen und ihm sagen, welche Regel benutzt werden soll. Dazu muss bei der Registrierung der Eintrag check_default_parameters unbedingt vorhanden sein. Im einfachsten Fall übergeben wir ein leeres Dictionary.

Als zweites übergeben wir der Registrierungsfunktion noch den check_ruleset_name, also den Namen, den wir oben mittels check_group_name an den Regelsatz vergeben haben. So weiß Checkmk aus welchem Regelsatz die Parameter bestimmt werden sollen.

Das Ganze sieht dann z.B. so aus:

Nun wird Checkmk versuchen, der Checkfunktion Parameter zu übergeben. Damit das klappen kann, müssen wir die Checkfunktion so erweitern, dass sie als zweites das Argument params erwartet. Diese schiebt sich zwischen item und section (Falls Sie einen Check ohne Item bauen, entfällt das item natürlich und params steht am Anfang):

Es ist sehr empfehlenswert, sich jetzt als ersten Test den Inhalt der Variable params mit einem print ausgeben zu lassen (oder pprint, wenn Sie es etwas komfortabler haben wollen). Legen Sie verschiedene Regeln an, probieren Sie, welche Werte bei params ankommen:

Und ganz wichtig: Wenn alles fertig ist, entfernen Sie unbedingt die print-Befehle wieder! Diese können die interne Kommunikation von Checkmk durcheinanderbringen.

Nun passen wir unsere Checkfunktion an, so dass der übergebene Parameter seine Wirkung entfalten kann. Wir holen uns den Wert mit dem in der Regel gewählten Key (hier "warning_lower") aus den Parametern:

Falls eine Regel konfiguriert ist, können wir nun die „freien Slots“ in unserem Beispiel überwachen. Wenn allerdings keine Regel definiert ist, wird diese Checkfunktion crashen: Da die Default-Parameter des Plugins nicht befüllt sind, wird das Plugin bei Abwesenheit einer Regel einen KeyError erzeugen.

Dieses Problem können wir beheben, indem wir bei der Registrierung einen passenden Parameter einfügen:

Sie sollten Defaultwerte immer auf diese Weise übergeben (und den Fall fehlender Parameter nicht im Checkplugin abfangen), da diese Defaultparameter auch in der Setup-Oberfläche angezeigt werden können. Dazu gibt es z.B. auf der Servicekonfigurationsseite eines Hosts im Menu Display den Eintrag Show Check parameters.

Ein einzelner Wert als Schwellwert ist in Checkmk übrigens sehr unüblich. Da Services in den Zuständen OK, WARN, CRIT sein können, ist es naheliegend die Parameter immer als Tuple mit zwei Einträgen zu definieren, also als Paar von Schwellen für WARN und CRIT. Dazu passen wir den Regelsatz wie folgt an:

Beachten Sie, dass eine solche Änderung des Datentyps eine inkompatible Änderung darstellt: Existierende Regeln können jetzt nicht mehr von der Oberfläche geladen werden. Und auch die Checkfunktion kann auf Probleme stoßen, wenn anstelle eines erwarteten Paar von zwei Zahlen eine einzelne Zahl in params steht. Sie können solche Regeln einfach editieren. Beim erneuten Speichern wird dann das neue Format verwendet.

In Checkmk gibt es zahlreiche ValueSpecs für alle möglichen Situationen. Hier sind noch ein paar nützliche:

In unserem obigen Beispiel haben wir das Plugin foobar die Metrik fooslots erzeugen lassen. Metriken werden in der grafischen Oberfläche von Checkmk sofort sichtbar, ohne dass Sie etwas dafür tun müssten. Pro Metrik wird bei den Servicedetails automatisch ein Graph erzeugt.

Allerdings gibt es dabei ein paar Einschränkungen:

Um die Darstellung Ihrer Metriken in diesen Belangen zu vervollständigen, benötigen Sie noch einige Definitionen in einer weiteren Datei.

Bevor Sie das tun, sollten Sie — ähnlich wie beim Regelsatz für die Parameter — zunächst prüfen, ob Checkmk nicht bereits eine geeignete Metrikdefinition mitbringt. Die vordefinierten Metrikendefinitionen finden Sie im Verzeichnis lib/check_mk/gui/plugins/metrics/. In der Datei cpu.py finden Sie beispielsweise eine Metrik für freien Platz eines Dateisystems:

Falls diese für Ihr Plugin geeignet ist, müssen Sie lediglich in Ihrem Aufruf der Metric()-Klasse den Namen "util" verwenden. Alles andere leitet sich dann automatisch davon ab.

Falls keine passende Metrik dabei ist, legen Sie einfach selbst eine an. In unserem Beispiel wollen wir einen eigene Metrik für unsere fooslots definieren. Dazu legen wir eine Datei in local/share/check_mk/web/plugins/metrics an`:

Dazu einige Hinweise:

Diese Definition sorgt jetzt dafür, dass Farbe, Titel und Einheit der Metrik nach unsere Wünschen angezeigt werden.

Möchten Sie mehrere Metriken in einem Graphen kombinieren (was oft sehr sinnvoll ist), benötigen Sie, einfach in der gleichen Datei, eine Graphdefinition. Dies geschieht über das globale Dictionary graph_info.

Nehmen wir dazu als Beispiel an, unser Check hätte zwei Metriken und zwar fooslots und fooslots_free. Die Metrikdefinitionen wären z.B.:

Nun fügen wir einen Graphen an, der diese beiden Metriken als Linien einzeichnet:

Hinweise dazu:

Möchten Sie zu unserer Metrik noch ein Perf-O-Meter in der Servicezeile anzeigen, benötigen Sie eine weitere Datei, diesmal im Verzeichnis local/share/check_mk/web/plugins/perfometer.

Beispiel:

Perf-O-Meter sind etwas trickreicher als Graphen, da es keine Legende gibt. Und deswegen ist das mit dem Wertebereich schwierig. Da das arme Perf-O-Meter nicht wissen kann, welche Messwerte denn überhaupt möglich sind und der Platz sehr begrenzt ist, verwenden viele eingebaute Checkplugins eine logarithmische Darstellung. Dies ist auch in unserem Beispiel so. half_value ist der Messwert, welcher genau in der Mitte des Perf-O-Meters angezeigt wird. Bei einem Wert von 5, wäre also hier der Balken halb gefüllt. Und exponent beschreibt den Faktor, welcher notwendig ist, damit weitere 10% des Bereichs gefüllt würden. Also würde hier im Beispiel ein Messwert von 10 bei 60% und einer von 20 bei 70% angezeigt werden.

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

Alternativ können Sie auch ein lineares Perf-O-Meter verwenden. Das ist immer dann sinnvoll, wenn es einen bekannten Maximalwert gibt. Ein typischer Fall sind Messwerte, welche Prozente von 0 bis 100 darstellen. Das sähe dann z.B. so aus:

Hier gibt es noch einen weiteren Unterschied zur logarithmischen Darstellung: segments ist hier eine Liste und erlaubt das nebeneinander Darstellen von mehreren Metriken.

Wie immer finden Sie Beispiele in den vielen von Checkmk ausgelieferten Plugins. Diese sind ebenfalls in den Dateien im Verzeichnis lib/check_mk/gui/plugins/metrics.

Die beiden Funktionen saveint() und savefloat() sind weggefallen. Zur Erinnerung: saveint(x) liefert 0 wenn sich x nicht vernünftig in eine Zahl konvertieren lässt, z.B. weil es ein leerer String ist oder nicht nur aus Ziffern besteht.

Auch wenn es dafür einige wenige gute Anwendungsfälle gab, wurde es doch in der Mehrheit der Fälle falsch verwendet und hat dazu geführt, dass so viele Fehler verschleiert wurden.

Für den Fall, dass Sie bei einem Leerstring eine 0 bekommen möchten, also den häufigsten „guten“ Anwendungsfall von saveint(x), können Sie einfach Folgendes schreiben:

Für savefloat() gilt alles analog.

Wenn Sie genau hinsehen, dann erkennen Sie, dass es sich hier um verschachtelte Listen handelt. Im Argument string_table bekommen Sie eine Liste, welche pro Zeile der Agentenausgabe eine Liste von Worten beinhaltet. Dabei werden die Zeilen an Folgen von Leerzeichen getrennt. Da unsere Sektion pro Zeile nur ein Wort enthält, bestehen ergo die inneren Listen aus nur jeweils einem Eintrag.

Folgendes Beispiel macht die Struktur noch etwas klarer:

Die Ausgabe sieht dann so aus:

Für unser Beispiel benötigen wir einfach nur eine einfache Liste der Devicenamen. Also machen wir unsere Parsefunktion so, dass sie aus jeder Zeile das eine Wort auspackt und in eine hübsche neue Liste verpackt:

Die Debugausgabe sieht dann so aus (bitte schauen Sie genau hin, es gibt jetzt nur noch ein einziges paar eckiger Klammern):

Damit die Parsefunktion vollständig ist, müssen wir jetzt noch die Debugmeldung entfernen und — ganz wichtig — das neue Ergebnis mit return zurückgeben:

Natürlich müssen von diesem Moment an alle betroffenen Plugins mit dem neuen Datenformat arbeiten können.