Tutorial: Debuggen von CheckMK-Checks

Das Debuggen von CheckMK-Checks hat mich schon viele graue Haare gekostet. Inzwischen habe ich mir für unterschiedliche Situationen Techniken angeeignet, die ich mit Dir teilen möchte. Damit wenigstens Deine Haare noch länger ihre Farbe behalten...

Zwei Wege, wie Du CheckMK-Checks nicht debuggen solltest

na(t)ive Ausführung des Checks

Die Scripte, die wir in CheckMK unterhalb der checks-Verzeichnisse finden, heißen deswegen "Checks", weil sie nur für die Auswertung der Monitoring-Daten verantwortlich sind. Erhoben wurden die Daten bereits in den Agenten, die auf den Hosts installiert sind.

Was so ein Agent nach seinem Aufruf in CheckMK reinkippt, ist bei bloßer Betrachtung ein richtiges Durcheinander, nämlich ein ellenlanges Textsnippet mit je einem Abschnitt pro Check-Typ und dazwischen Daten. Kostprobe gefällig?

telnet foohost 6556
...
...
<<<tcp_conn_stats>>>
01 13
0A 27
06 3
<<<diskstat>>>
1590958578
 8 0 sda 2356123 248021 142890654 598776 1728548 1419646 87541101 5413436 0 755282 6011728
 8 1 sda1 226 167 5519 44 1 0 1 0 0 32 44
 8 2 sda2 443 0 47564 189 28 0 4257 43 0 200 232
 8 3 sda3 2355384 247854 142833291 598529 1652880 1419646 87536843 5334686 0 709185 5932716
 253 0 dm-0 886774 0 35962342 183162 997154 0 22444569 6531899 0 366289 6715582
 253 1 dm-1 853331 0 6830352 138971 1246280 0 9970240 13460441 0 67739 13611117
 253 2 dm-2 865651 0 100037381 338000 829774 0 55122034 3627502 0 343929 3965586
[dmsetup_info]
<<<kernel>>>
1590958578
nr_free_pages 61219
nr_alloc_batch 3864

Und wer soll das jetzt verstehen?

Ganz einfach: das erledigen für uns die "Checks" auf dem CheckMK-Server. Jeder Check versteht genau den Kauderwelsch in "seinem" Abschnitt. Für einen Agenten-Output mit bspw. 18 Abschnitten sind also auch 18 verschiedene Checks zuständig.

Die Checks nun jeweils einzeln zu starten/zu parametrisieren, wäre natürlich die Performance-Hölle. CheckMK liest stattdessen bereits beim Start alle verfügbaren Checks in seinen Speicher. Genauer gesagt: es erweitert seinen eigenen Python-Code mit dem Code der Checks, indem es diesen jeweils als Modul einbindet. Wie viele das sind, variiert je nach CheckMK-Version - bei einer 1.6.9 sind es über 1.700 Checks:

OMD[cmk]:~/share/check_mk/checks$ cmk -L | wc -l
1774

Über den Abschnittsnamen im Agenten-Output kann CheckMK also ins richtige Check-Modul springen und diesem die Daten im Abschnitt zur Auswertung übergeben.

Allerdings sind die Agenten-Abschnitts-Daten nicht das einzige, was der Check bekommt. Ebenfalls zur Laufzeit muss der Check wissen, ob WATO-Regeln für diesen Host bzw. für diesen Service existieren. Die beeinflussen ggf. die Schwellwerte.

So viel also vorab zum Verständnis für Dich, warum Du CheckMK-Checks nicht direkt auf der Bash bzw. mit dem Python-Interpreter ausführen kannst: es fehlt der Kontext in Form von Agenten-Daten und ggf. WATO-Regeln (in Wirklichkeit ist es etwas komplexer, aber das soll für hier genügen).

Frickelei mit __main__()

Nun könnte man auf die Idee kommen, all das einfach zu faken, was CheckMK zur Laufzeit dem Check übergibt und dann händisch (!) die Funktionen für Inventory und Check aufzurufen. Praktisch an dieser Methode ist vielleicht noch, dass man relativ offen mit den Testdaten hantieren kann. Der folgende Codeblock wird Dir dennoch, solltest Du ihn vervollständigen und benutzen, körperliche Schmerzen bereiten. Lass es und lies ganz schnell weiter. 🙂

if __name__ == "__main__": 
 global check_info
 check_info = {}

check_info['robotmk'] = {
 "parse_function": parse_robot,
 "inventory_function": inventory_robot,
 "check_function": check_robot,
 "service_description": "Robot",
 "group": "robotmk",
 "has_perfdata": True
}

if __name__ == "__main__":
 # eigene Variablen...
 # Setzen globaler CMK-Variablen, Einlesen eigener Testdaten... 
 global inventory_robotmk_rules
 inventory_robotmk_rules = ast.literal_eval(
 open('test/fixtures/inventory_robotmk_rules/discovery_slvel_%d.py' % debugset['discovery_level']).read())
 # Faken der Agenten-Daten
 testdaten = 'test/fixtures/robot/%s/output.json' % debugset['suite']
 mk_output = ast.literal_eval(open(datafile, 'r').read())
 # PARSE
 parsed = parse_robot(mk_output)
 # INVENTORY
  inventory = inventory_robot(parsed)
 # CHECK
 state, msg, perfdata = check_robot("1S 3S 2S 3T", checkgroup_parameters, parsed)
 print "ENDE---"

Brot und Butter: debuggen mit "cmk" und "print"

Python-Debugger

Puristisch: CheckMK und der Python-Debugger "pdb"

Bevor wir hier einsteigen: Was zeichnet überhaupt einen "Debugger" aus? Debugger schimpft sich, was mir u.a. folgendes erlaubt:

• den Code Zeile für Zeile ausführen
• sämtliche Code-Bestandteile (Variablen, Funktionen, Klassen etc.) ansehen und verändern
• den Code bis zu einem Haltepunkt (Breakpoint) laufen und dann stoppen zu lassen

Python bringt hierzu das Modul pdb mit:

python -m pdb mein_script.py

Und schon sind wir quasi mitten im laufenden Code und können uns alles in Ruhe ansehen.

Stop... den Check im Debugger auszuführen ist nicht die Lösung. Denn auch mit Debugger werden wir am fehlenden Kontext von CheckMK scheitern (siehe oben).

Dankenswerterweise ist das cmk-Kommando ebenfalls ein Python-Script, was es uns erlaubt, den kompletten Aufruf im Debugger zu starten. Alles was wir zuvor benötigen, ist der Pfad, an dem cmk abgelegt ist:

OMD[cmk]:~$ which cmk
~/bin/cmk
OMD[cmk]:~$ python -m pdb bin/cmk --debug -nv --checks=robotmk robothost1
[2] > /opt/omd/sites/cmk/bin/cmk(34)<module>()
-> import os
(Pdb++)

Der Debugger hält cmk nun an der ersten ausführbaren Zeile an und wartet darauf, dass wir mit

• "n": nächste Zeile ausführen
• "s": in Funktion hineinspringen 
• "r": laufen lassen bis zum Aussprungpunkt der aktuellen Routine

durch den Code marschieren.

Noch sind wir aber nicht in unserem Code-Teil und wir kennen die exakte Stelle im Code von cmk nicht, an der die Funktionen in unserem Check ausgeführt werden (und die wollen wir auch nicht suchen).

Deshalb setzen wir im laufenden Debugger einfach einen Breakpoint mit "b" auf die erste ausführbare Zeile (27) unseres Codes. (Achtung, relative Pfade sind nicht erlaubt).

"r" lässt den Debugger dann so lange rennen, bis unser Haltepunkt erreicht ist. Jetzt sind wir mitten in unserem eigenen Code und können ihn schrittweise durchgehen oder auch mit veränderten Daten testen.

"q" beendet den Debugger. "h" bietet eine schnelle Übersicht über die wichtigsten Befehle; das Netz ist voll von Tutorials um den Debugging-Dinosaurier "pdb".

...
# Breakpoint setzen: stoppe in Zeile 27 unseres Checks
(Pdb++) b /omd/sites/cmk/local/share/check_mk/checks/robotmk:27 
(Pdb++) r
[6] > /omd/sites/cmk/local/share/check_mk/checks/robotmk(27)<module>()
-> myvar = "easy" # manuelles Editieren einer Variable
(Pdb++) n
[6] > /omd/sites/cmk/local/share/check_mk/checks/robotmk(28)<module>()
-> print "----> Debugging ist %s" % myvar
(Pdb++) myvar = "not so hard!"
(Pdb++) n
----> Debugging ist not so hard!

Alternativ zum Setzen des Breakpoints zur Laufzeit kann dieser auch im Code verankert werden; der Debugger hält dann automatisch an dieser Stelle an. Die Breakpoints lassen sich ein/auskommentieren und verschieben - das ist wesentlich einfacher, als bei jedem Start des Debuggers erst wieder die Haltepunkte zu setzen.

Achtung: man pfuscht aber im Code herum, und das auch noch zusätzlich im import-Header. Ich habe mir angewöhnt, solche temporären Änderungen immer noch mit einer weiteren Kommentarzeile zu flaggen, damit ich am Ende meiner Debugging-Session alle "Häufchen" entfernen kann: 

# DEBUG
import pdb
...
...
pdb.set_trace() # <--- Breakpoint

Komfortabel: CheckMK und der interaktive Python-Debugger "ipdb"

Überholspur: CheckMK Remote Debugging mit VS Code Studio

Nach der Installation zeigt die Toolbar links das Icon des "Remote Explorers" an:

Wenn ich daraufklicke, sehe ich sämtliche Verbindungen, die in meiner SSH-Config definiert sind - inklusive der zuletzt angelegten, die sich per Rechtsklick jetzt aktivieren lässt:

Bei der erstmaligen Verbindung kann es ca. 30 Sekunden dauern, bis VSC im Homedir des Remote-Users (cmk) das entsprechende Gegenstück (.vscode-server, NodeJS-basiert) installiert hat.

Dass der Remote-Server läuft und Dein VSC mit ihm verbunden ist, sieht man jetzt links unten in der Statusleiste:

Ab diesem Zeitpunkt kann es auch sein, dass bestimmte andere Plugins, die normalerweise links in der Toolbar zu sehen sind, verschwunden sind. Das ist normal. Das liegt daran, dass der "Server"-Teil von VSC jetzt auf dem Host eldev läuft. Der "Client"-Teil von VSC auf meinem Mac dient lediglich als Anzeige-Frontend.

Arbeitsverzeichnis öffnen

Als nächstes binde ich das komplette Home-Dir der OMD-Site ein: dazu klicke ich auf "Open Folder" und wähle wie vorgeschlagen /omd/sites/cmk aus:

Debugging-Konfiguration "launch.json" anlegen

Jetzt, wo ich die Python-Erweiterung installiert habe, kann ich den Debugger öffnen:

Der allerdings möchte noch konfiguriert werden; dazu benutze ich den vorgeschlagenen Link "create a launch.json file" und wähle darauf folgend "Python File" als Konfigurations-Typ:

Mit der JSON-Datei "launch.json" teile ich Visual Studio Code genau mit, welche Datei ich mit welchem Interpreter und welchen Argumenten debuggen will. Ich kann beliebig viele solcher Debug-Konfigurationen anlegen. Die einfachste, nämlich das aktuell geöffnete File zu debuggen, ist bereits vorhanden.

Für unseren "Spezialfall" ~/bin/cmk mitsamt seinen Argumenten lege ich mir eine weitere Konfiguration namens cmk - robot an:

{
 "version": "0.2.0",
 "configurations": [
 {
 "name": "Python: Current File",
 "type": "python",
 "request": "launch",
 "program": "${file}",
 "console": "integratedTerminal"
 },
 // meine neue Check-Debug-Config
 {
 "name": "cmk - robot",
 "type": "python",
 "request": "launch",
 "program": "${workspaceFolder}/bin/cmk",
 "args": [
 "-v",
 "-n",
 "--checks=robotmk",
 "robothost1"
 ],
 "console": "integratedTerminal",
 "pythonPath": "${workspaceFolder}/bin/python"
 }
 ]
}

Zur Erklärung:

• type - dürfte klar sein
• request - neben "launch" gibt es auch "test", um Unittests zu fahren
• program - das zu startende Programm. Beachte die Variable für den Workspace-Folder
• args - jedes Argument (siehe oben) ist ein eigenes Listenelement
• console - wo soll die Ausgabe landen
• pythonPath - ganz wichtig: welches Python soll benutzt werden? Natürlich das von OMD!

Debugger starten

Nun ist es an der Zeit, den Debugger laufen zu lassen. Ich setze vorher aber noch einen Haltepunkt in "robotmk", indem ich die Zeile anklicke und "F9" (Set Breakpoint) drücke. Der rote Punkt zeigt mir das an:

Der Debugger startet, indem ich die soeben erstellte Debugging-Config cmk - robot auswähle und den grünen Pfeil daneben anklicke (oder "F5" drücke):

Und wie erwartet stoppt der Debugger am Haltepunkt mitten in meinem Check, mit dem kompletten CheckMK-Kontext außenherum! 

Man hat ziemlich schnell den Dreh raus, wo Haltpunkte Sinn machen. Ist ein Haltepunkt erreicht, kann ich mit "F11" z.B. Funktionen, die zu CheckMK gehören, hinabsteigen und sehe genau, was sie dort ausführen. Besonders das finde ich wichtig, denn die (ansonsten hervorragende) Dokumentation von CheckMK ist bezüglich Entwicklung ein großer weißer Fleck. Die meisten Funktionen und Module sind im Code aber bereits dokumentiert. 

Der Variableninspektor links zeigt immer den aktuellen lokalen und globalen Variablen-Scope. Per Mouseover wird mir der Wert von Variablen an jeder Stelle im Code angezeigt.

Die Debug Console im unteren Bereich gibt mir darüber hinaus die Möglichkeit, im aktuellen Kontext eigene Python-Schnipsel zu testen. Es ist also nicht notwendig, zwischen SSH-Terminal und VSC hin- und her zu springen:

Zusammenfassung

Selbstverständlich ist man mit dieser Methode nicht auf CheckMK-Checks beschränkt. Um z.B. ein Plugin zu debuggen, muss lediglich eine SSH-Verbindung hergestellt werden, mit der es möglich ist, das Plugin in /usr/lib/check_mk_agent/plugins/ zu editieren.

Welche der hier vorgestellten Debugging-Techniken für Dich passt, hängt davon ab, welchen Code Du zu debuggen hast und in welcher Umgebung Du Dich befindest.

Kleinere Fixes lassen sich locker noch mit ipdb (oder sofern gar nichts nachinstalliert werden darf, pdb) erschlagen. Für die Entwicklung eigener Checks und Plugins ist der Python-Debugger in VSC aber ein unschlagbar gutes Werkzeug. Dazu brauchst Du eine Desktop-Oberfläche (Win/Linux/Mac), in der Visual Studio Code gestartet wird.

Bonus

Falls Du CheckMK-Checks mit PyTest entwickelst: das Python-Plugin in VSC bietet den besonderen Leckerbissen, auf die gleiche wie die hier vorgestellte Art und Weise PyTest-Tests zu debuggen. Bei RobotMK hilft mir das, bereits während der Entwicklung zu sehen, wo ich mir evtl. gerade ins Knie schieße, wenn Tests auf rot gehen 🙂