Statusdaten abrufen via Livestatus

Der Zugriff zum Livestatus erfolgt über einen Unix-Socket unter Benutzung der Livestatus Query Language (LQL). Diese ist in ihrer Syntax an HTTP angelehnt.

Sie können auf der Kommandozeile auf verschiedene Arten auf die Schnittstelle zugreifen. Eine Möglichkeit ist es, über die Kommandos printf und unixcat den Befehl an den Socket zu leiten. Checkmk liefert für den Instanzbenutzer das Tool unixcat bereits mit. Wichtig: Alle Eingaben an den Socket unterscheiden Groß- und Kleinschreibung, so dass diese immer eingehalten werden muss:

Die Schnittstelle erwartet alle Befehle und Header in jeweils einer eigenen Zeile. Markieren Sie daher jeden Zeilenumbruch mit einem \n. Als Alternative zu dem Kommando oben können Sie auch den Skriptbefehl lq nutzen, welcher Ihnen einiges bei der Eingabe abnimmt:

Oder Sie starten den interaktiven Eingabe-Stream und geben dann den Befehl und die Header nacheinander ein. Mit einer Leerzeile führen Sie den Befehl mit seinen Headern aus und eine weitere Zeile beendet den Zugriff auf den Socket. Beachten Sie, dass in dem Beispiel alles vor der ersten Leerzeile zum dem Befehl gehört und alles zwischen der ersten und zweiten Leerzeile die Antwort ist:

Die folgenden Beispiele werden immer mit dem lq-Befehl ausgeführt; in direkter Form, wenn der Aufruf kurz ist und als Eingabe-Stream bei einem längeren.

Da Checkmk sehr stark auf Python aufbaut, bieten sich Skripten in dieser Sprache an. Für den Zugriff auf den Socket des Livestatus können Sie das folgende Skript als Ausgangsbasis nutzen:

Checkmk stellt auch eine API für die Programmiersprachen Python, Perl und C++ zur Verfügung, welche den Zugriff auf den Livestatus vereinfachen. Zu jeder Sprache steht Ihnen Beispielcode zur Verfügung, welcher die Nutzung erläutert. Die Pfade zu diesen Beispielen finden Sie in dem Kapitel Dateien und Verzeichnisse.

Bisher wurden in den Beispielen alle Informationen zu allen Hosts abgefragt. In der Praxis möchten Sie aber wahrscheinlich nur bestimmte Informationen (Spalten) haben. Mit dem bereits erwähnten Header Columns können Sie die Ausgabe auf diese Spalten eingrenzen. Die einzelnen Spaltennamen werden durch ein einfaches Leerzeichen getrennt.

Wie Sie sehen, erfolgt die Trennung der einzelnen Werte einer Zeile wiederum durch ein Semikolon.

Wichtig: Wenn Sie diesen Header benutzen, werden die Kopfzeilen in der Ausgabe unterdrückt. Sie können diese aber mit dem Header ColumnHeaders der Ausgabe wieder hinzufügen.

Um die Abfrage nur auf bestimmte Zeilen einzugrenzen, können Sie Spalten auf bestimmte Inhalte filtern. Wenn Sie also nur Services mit einem bestimmten Status suchen, können Sie das durch einen Filter realisieren:

In dem Beispiel wird nach allen Services gesucht, deren Status CRIT ist; anschließend werden der Hostname, die Servicebeschreibung und dessen Status ausgegeben. Sie können solche Filter natürlich auch kombinieren und weiter einschränken auf Services, deren Status CRIT ist und noch nicht bestätigt wurde:

Wie Sie sehen, kann man auch nach Spalten filtern, die nicht in Columns aufgelistet sind.

Mit dem Header OrderBy können Sie die Ausgabe nach den Inhalten beliebiger Spalten oder auch den Werten beliebiger Dictionary-Schlüssel sortieren. So lässt sich bspw. eine alphabetische Auflistung aller Host erstellen:

Implizit wird die Ausgabe erwartungsgemäß aufsteigend sortiert (asc). Sie können die gewünschte Sortierung aber auch explizit angeben und durch die Angabe von desc umdrehen:

Mit etwas längeren Abfragen und bspw. einer Sortierung nach Performance-Daten, können interessante Ranglisten entstehen. Im folgenden Beispiel werden die Hosts absteigend nach ihrer Uptime sortiert ausgegeben:

Manche Spalten einer Tabelle liefern nicht nur einen Wert zurück, sondern gleich eine ganze Liste davon. Damit Sie auch diese effektiv durchsuchen können, haben die Operatoren hier eine andere Bedeutung. Eine vollständige Liste der Operatoren finden Sie bei den Operatoren für Listen. So hat z.B. der Operator >= die Bedeutung „enthält“. Mit diesem können Sie z.B. nach einem bestimmten Kontakt suchen:

Wie Sie in dem Beispiel sehen, werden die Kontakte in der Spalte contacts kommasepariert aufgelistet. Dadurch lassen sie sich eindeutig von dem Beginn einer neuen Spalte unterscheiden. Eine Besonderheit stellt bei den Listen der Gleichheitsoperator dar. Er prüft, ob eine Liste leer ist:

Bereits vorher wurden mehrere Filter kombiniert. Dabei erscheint es intuitiv, dass die Daten alle Filter passieren müssen, um angezeigt zu werden. Die Filter werden also mit einem logischen und verknüpft. Um bestimmte Filter mit einem logischen oder zu verknüpfen, können Sie am Ende der Filterreihe ein Or: gefolgt von einer Ganzzahl einfügen. Der Counter bestimmt, wie viele der letzten Zeilen zu einem oder zusammengefasst werden. Dadurch können Sie Gruppen bilden und diese beliebig kombinieren. Ein einfaches Beispiel ist das folgende. Hier werden zwei Filter so kombiniert, dass alle Services angezeigt werden, die entweder den Status WARN oder UNKNOWN haben:

Sie können das Ergebnis einer Kombination aber auch negieren oder Gruppen wiederum zu Gruppen zusammenfassen. In dem Beispiel werden alle Services angezeigt, deren Status nicht OK ist und deren Beschreibung entweder nicht mit Filesystem anfängt oder einen anderen Status als UNKNOWN hat:

Sie können das Ausgabeformat auf zwei verschiedene Arten festlegen. Zum einen können Sie die Separatoren der Standardausgabe neu definieren. Zum anderen kann die Ausgabe auch Python- oder JSON-konform erfolgen.

Es wird Situationen geben, in denen Sie gar nicht daran interessiert sind, wie der Status eines einzelnen oder einer Gruppe von Services ist. Vielmehr ist die Anzahl der Services wichtig, welche gerade WARN sind oder die Anzahl der überwachten Datenbanken. Livestatus ist in der Lage mit Stats Statistiken zu erstellen und auszugeben.

Der Overview bekommt seine Daten, indem er über Livestatus Statistiken zu Hosts, Services und Events abruft und dann in der Oberfläche von Checkmk darstellt. Mit dem direkten Zugriff auf Livestatus können Sie ebenfalls eigene Aufsummierungen erstellen:

Solche Statistiken lassen sich übrigens auch mit allen Filtern kombinieren.

Auch Statistiken lassen sich mit and/or zusammenfassen. Die Header heißen dann StatsAnd oder StatsOr. Wenn Sie die Ausgabe umkehren wollen, benutzen Sie StatsNegate. In dem Beispiel wird die Gesamtzahl der Hosts ausgegeben (das erste Stats) und dazu die Anzahl derer, die als stale markiert wurden und sich nicht in einer Downtime befinden (Stats 2 und 3 werden mit einem logischen UND verknüpft):

Verwechseln Sie nicht die unterschiedlichen Möglichkeiten, die Ergebnisse der Filter und Statistiken zusammenzufassen. Während bei dem Header Filter alle Hosts ausgegeben werden, auf die die Bedingungen zutreffen, wird bei den Statistiken die Summe ausgegeben, wie oft die Stats-Filter zutreffen.

Sie können auch Berechnungen an Werten durchführen und z.B. den Durchschnittswert oder das Maximum ausgeben lassen. Eine vollständige Liste der möglichen Operatoren finden Sie hier.

In dem folgenden Beispiel wird die durchschnittliche, minimale und maximale Zeit ausgegeben, welche die Check-Plugins eines Hosts für die Berechnung eines Status benötigen:

Berechnungen von Metriken werden etwas besonders behandelt. Auch hier sind alle Funktionen des Stats-Header möglich. Diese werden jedoch auf alle Metriken eines Service einzeln angewandt. Nachfolgend werden als Beispiel die Metriken der CPU-Benutzung einer Host-Gruppe aufsummiert:

Über die Tabelle log im Livestatus haben Sie direkten Zugriff auf die Monitoring-Historie des Cores, so dass Sie mit der LQL bequem nach bestimmten Ereignissen filtern können. Verfügbarkeiten werden zum Beispiel auf Basis dieser Tabelle berechnet. Um die Übersicht zu erhöhen und eine Abfrage thematisch einzugrenzen, haben Sie auf die folgenden Log-Klassen zugriff:

Mit Hilfe dieser Log-Klassen können Sie bereits sehr gut eingrenzen, welche Art von Einträgen angezeigt werden soll. Zusätzlich dazu wird der Zeitraum eingeschränkt, der bei der Abfrage berücksichtigt werden soll. Das ist wichtig, da andernfalls die gesamte Historie der Instanz durchsucht wird. Das kann logischerweise das System aufgrund der Informationsflut stark ausbremsen.

Eine weitere sinnvolle Einschränkung der Ausgabe sind die Spalten (Columns), die zu einem Eintrag angezeigt werden sollen. In dem folgenden Beispiel wird nach allen Benachrichtigungen gesucht, welche in der letzten Stunde geloggt wurden:

Wichtig: Achten Sie darauf, dass Sie im interaktiven Modus des Eingabe-Streams keine Variablen wie in dem Beispiel nutzen können. Und schränken Sie die Abfragen immer auf einen Zeitraum ein.

Sie haben die Möglichkeit, die Rotation der Dateien und deren maximale Größe zu beeinflussen. Zusätzlich können Sie auch bestimmen, wie viele Zeilen einer Datei eingelesen werden sollen, bevor Checkmk abbricht. Das alles kann, abhängig von dem Aufbau der Instanz, Auswirkungen auf die Performance Ihrer Abfragen haben. Es stehen dabei die folgenden drei Parameter zur Verfügung, welche Sie in unter Setup > General > Global Settings > Monitoring Core finden und anpassen können:

Um über das Netzwerk auf den Livestatus zuzugreifen, können Sie den Unix-Socket des Livestatus an einen TCP-Port binden. Auf diese Weise können Sie Skripte über das auf entfernten Maschinen ausführen und die Daten direkt dort erheben, wo sie auch verarbeitet werden sollen.

Den Zugriff über TCP aktivieren Sie bei abgeschalteter Site mit dem omd-Befehl:

Nach dem Start der Instanz ist Livestatus per TCP in der Regel auf dem Standardport 6557 aktiv. Bei Checkmk-Servern mit mehreren Sites, die Livestatus per TCP nutzen, wird der nächsthöhere freie Port gewählt.

Alle Einstellungen wie Port und berechtigte IP-Adressen können Sie per omd config vornehmen. Alternativ sind diese Einstellungen im Setup möglich. In Checkmk ist SSL-Verschlüsselung der Livestatus-Kommunikation standardmäßig aktiviert:

Wenn Zugriff auf Livestatus von außerhalb Ihres lokalen Netzwerkes erforderlich ist, mag Zugriffsschutz alleine auf Basis von IP-Adressen nicht praktikabel sein. Der einfachste Weg, authentifizierten Zugriff zu erlangen, ist hier die Verwendung der Secure Shell.

Mit SSH haben Sie die Möglichkeit, ein Kommando zu übergeben, welches auf dem entfernten Server ausgeführt wird:

Alternativ können Sie den Livestatus-Port per SSH-Tunnel auf den Host weiterleiten, auf dem Sie aktuell arbeiten:

Wenn die Verbindung steht, können Sie in einer zweiten Konsolensitzung testen, ob mit openssl s_client Zugriff möglich ist:

Klappt dieser Test, können Sie jedes Skript, dass Sie für direkten Livestatus-Netzwerkzugriff geschrieben haben, auf localhost einsetzen.

Sie können Livestatus nicht nur für die Abfrage von Daten nutzen, sondern auch, um Kommandos live und direkt an den Core (CMC oder Nagios) zu schicken. Ein korrektes Kommando enthält immer einen Zeitstempel. Dieser kann zwar beliebig sein. Da er aber in den Logs dazu benutzt wird, den Zeitpunkt der Ausführung nachzuvollziehen, ist es sinnvoll, möglichst die exakte Zeit anzugeben. Kommandos mit fehlendem Zeitstempel werden ohne Fehlermeldung und lediglich mit einem Eintrag im cmc.log verworfen!

Damit der Zeitstempel so genau, wie möglich ist, bietet es sich an, das Kommando nicht über den Eingabe-Stream zu setzen, sondern direkt zu übergeben. Sie haben in diesem Fall auch Zugriff auf Variablen und können automatisch die gerade aktuelle Zeit übergeben:

Dieses Format funktioniert sowohl mit dem Nagios-Core von Checkmk Raw, als auch mit dem CMC der kommerziellen Editionen. Allerdings überschneiden sich bei den beiden Cores nur teilweise die Kommandos. Eine vollständige Liste der Kommandos für den Nagios-Core finden Sie direkt auf der Internetseite von Nagios. Die für Checkmk relevanten und für den CMC verfügbaren Kommandos finden Sie in der Befehlsreferenz.

In der Liste der Kommandos werden Sie die Syntax in der folgenden Form vorfinden:

Wie Sie gelernt haben, benutzt Checkmk ein sehr viel einfacheres Format für die Übergabe des Kommandos. Um dieses Format für Checkmk kompatibel zu übertragen, benötigen Sie lediglich das Kommando, den Zeitstempel und gegebenenfalls die Variablen: