Einen Custom-Script-Check konfigurieren

Führe dein eigenes PowerShell- oder bash-Skript als Monitoring-Check aus, setze einen Ergebnisstatus und zeige die Werte im Dashboard an.

Geschrieben von Erdinc Akay

Zuletzt aktualisiert Vor 26 Tagen

Ein Custom-Script-Check führt ein von dir geschriebenes Skript aus — PowerShell unter Windows, bash unter Linux und macOS — in einem festen Intervall und meldet ein Ergebnis an octoja zurück. Verwende ihn, wenn keiner der eingebauten Checks zu dem passt, was du überwachen möchtest. Du baust den Check einmal unter Konfiguration → Eigene Checks; danach erscheint er neben den eingebauten Checks, wenn du Checks einem Gerät zuweist.

Bevor du beginnst

Du benötigst die Berechtigung Verwaltung benutzerdefinierter Checks, um den Check zu bauen.
Das Zuweisen des Checks an ein Gerät (Schritt 10) erfordert zusätzlich die Berechtigung Monitoring-Check-Verwaltung.
Du brauchst ein Zielgerät, auf dem der Agent installiert und verbunden ist.
Unter Linux muss jq auf dem Zielgerät installiert sein — der Skript-Wrapper des Agents nutzt es zum Lesen der Parameter und zum Serialisieren der Ausgabe. Unter macOS nutzt der Wrapper python3, das auf macOS vorinstalliert ist.
Jedes weitere Tool, das dein Skript aufruft (zum Beispiel awk, bc), muss ebenfalls auf dem Zielgerät installiert sein — der Agent bringt skript-seitige Abhängigkeiten nicht selbst mit.

Schritte

Öffne Konfiguration → Eigene Checks in der Seitenleiste.
Klicke auf Neuer Check.
Fülle den Erstellungsdialog aus — Check-ID (ein eindeutiger Bezeichner in Kebab-Case, z. B. disk-temperature; er kann später nicht geändert werden), Name (Englisch) und Name (Deutsch). Optional kannst du unter Klonen von einen bestehenden Check als Kopiervorlage wählen. Klicke auf Check erstellen.
Lasse im Tab Allgemein den Modus auf Erweitertes Skript (die Alternative Einfaches SNMP ersetzt die Skript-Tabs durch einen SNMP-Editor und ist nicht Teil dieser Anleitung). Setze Beschreibung, Symbol, Kategorie, Tags und das Check-Intervall in Minuten — Standard 5, erlaubter Bereich 5–1440.
Öffne den Tab Skript. Füge für jede Plattform, die du unterstützen möchtest (Windows / Linux / macOS), dein Skript ein — Beispiele weiter unten. Plattformen ohne Skript stehen nicht zur Zuweisung bereit. Schreibe nur deine Check-Logik: Der Agent ergänzt die Ein-/Ausgabe-Behandlung automatisch.
Öffne den Tab Parameter und definiere alle Eingabeparameter, die dein Skript benötigt (Schlüssel, Typ, Beschriftungen, Pflichtfeld, Standardwert). Sie erscheinen als konfigurierbare Felder, sobald der Check einem Gerät zugewiesen wird.
Öffne den Tab Ausgabe-Schema und deklariere die Felder, die dein Skript schreibt — Schlüssel, Typ, Einheit und Label. Über die Tabs Detail-Layout und Verlaufs-Layout legst du fest, wie diese Felder auf dem Checks-Tab des Geräts angezeigt werden.
Öffne den Tab Test, wähle ein verbundenes Gerät aus und klicke auf Test starten. Du siehst Ergebnis, Exit-Code, Laufzeit, die Ausgabe und Fehler des Skripts sowie die geparsten Ausgabefelder — ohne auf ein Check-Intervall zu warten.
Klicke auf Speichern.
Weise den Check zu: Gehe zu Geräte, öffne das Zielgerät, klicke auf den Tab Checks → Check hinzufügen, wähle deinen eigenen Check aus (er erscheint neben den eingebauten Checks), fülle die von dir definierten Parameter aus und klicke auf Check hinzufügen.

Das Ergebnis setzen

Dein Skript meldet seinen Status, indem es checkResult in der Ausgabe setzt — $output.checkResult in PowerShell, set_result in bash. Der Startwert ist 0 (OK); ein Skript, das nichts setzt, meldet also OK. Der Agent ordnet den Wert so zu:

Wert	Status
`0`	OK
`1`	Warnung
`2`	Kritisch
`3`	Failure (Skriptfehler)

Hinweis: Du kannst den Status auch per Name statt per Zahl setzen: $output.checkResult = "Critical" (PowerShell) oder set_result Critical (bash) — der Agent akzeptiert die Statusnamen Success, Warning, Critical und Failure.

Wie der Agent dein Skript ausführt

Diese Details brauchst du nicht, um einen Check zu bauen — aber sie erklären, was dich erwartet:

Der Agent lädt dein Skript inklusive des Ein-/Ausgabe-Wrappers vom Webservice herunter, speichert es als Datei und führt es mit powershell -ExecutionPolicy Bypass -File unter Windows bzw. bash unter Linux und macOS aus.
Die bei der Zuweisung konfigurierten Parameter werden dem Skript über die Standardeingabe übergeben; du liest sie über $checkInput (PowerShell) oder get_input (bash).
Der Status kommt aus dem checkResult-Wert deiner Ausgabe — nicht aus Text, den dein Skript ausgibt, und nicht aus dem Exit-Code. Alles andere, was auf stdout landet, wird ignoriert.
Ein Exit-Code ungleich Null lässt den Check Failure melden — unabhängig davon, was die Ausgabe sagt.
Jeder Lauf hat ein festes Zeitlimit von 5 Minuten (nicht konfigurierbar). Ein Skript, das länger läuft, wird gestoppt und der Check meldet Failure.
Ausgaben über 16 KB behalten ihren Status, aber die Feldwerte werden verworfen und das Ergebnis als gekürzt markiert.

Der vollständige Eingabe-, Ausgabe- und Helper-Vertrag ist in der unten verlinkten Custom-Script-Check-Referenz dokumentiert.

PowerShell (Windows)

Der Wrapper stellt $checkInput (die geparsten Eingabeparameter) und $output (eine Hashtable, vorbelegt mit checkResult = 0) bereit. Schreibe deine Ergebnisse in $output. Achtung: Die Variable heißt $checkInput, nicht $input — $input ist eine reservierte automatische PowerShell-Variable.

# Einen Eingabeparameter lesen (im Tab Parameter definiert)$threshold = $checkInput.threshold# Arbeit erledigen$cpuLoad = (Get-Counter '\Processor(_Total)\% Processor Time').CounterSamples.CookedValue# Ergebnisse in $output schreiben$output["cpuLoad"] = [math]::Round($cpuLoad, 1)if ($cpuLoad -ge $threshold) {    $output["checkResult"] = 2  # Kritisch    $output["message"] = "CPU-Auslastung $cpuLoad% überschreitet Schwellenwert $threshold%"} elseif ($cpuLoad -ge ($threshold * 0.8)) {    $output["checkResult"] = 1  # Warnung} else {    $output["checkResult"] = 0  # OK}

Bash (Linux)

Der Wrapper stellt drei Helper bereit (alle benötigen jq auf dem Gerät):

get_input "key" — einen Eingabeparameter lesen.
set_output "key" value — ein Ausgabefeld setzen.
set_result 0|1|2 — Kurzform für checkResult (0 = OK, 1 = Warnung, 2 = Kritisch).

THRESHOLD=$(get_input "threshold")LOAD=$(uptime | awk -F'load average:' '{print $2}' | awk -F',' '{print $1}' | xargs)set_output "loadAverage" "$LOAD"if (( $(echo "$LOAD > $THRESHOLD" | bc -l) )); then    set_result 2   # Kritisch    set_output "message" "Load Average $LOAD überschreitet Schwellenwert $THRESHOLD"else    set_result 0   # OKfi

Bash (macOS)

Unter macOS verwendet der Agent einen separaten Wrapper, der dieselben Helper bereitstellt — get_input, set_output, set_result —, aber auf python3 (auf macOS vorinstalliert) statt auf jq aufbaut und bash-Funktionen vermeidet, die das mit macOS ausgelieferte bash 3.2 nicht unterstützt. Dein Skript-Code sieht genauso aus wie im Linux-Beispiel oben.

Wenn du kein macOS-spezifisches Skript hinterlegst, führt der Agent dein Linux-Skript auch auf macOS aus. Das funktioniert für portables bash, scheitert aber, sobald du auf ein Linux-spezifisches Tool angewiesen bist.

Was du nicht tun solltest

Nicht tun	Warum
Parameter aus `$input` lesen (PowerShell)	`$input` ist eine automatische PowerShell-Variable und enthält nicht deine Parameter. Verwende `$checkInput`
`exit` / `return` aus dem Skript-Körper heraus aufrufen	Ein Exit-Code ungleich Null lässt den Check Failure melden — egal, was deine Ausgabe sagt. Setze `checkResult` und nutze if/else-Blöcke statt eines vorzeitigen Abbruchs — der Editor zeigt dieselbe Warnung
Dich darauf verlassen, dass stdout Werte zurück an octoja kommuniziert	Der Agent liest nur die strukturierte Ausgabe; alles andere auf stdout wird ignoriert. Verwende `set_output` / `$output[…]` — diese Felder sind typisiert, beschriftet und werden auf dem Checks-Tab des Geräts angezeigt
Länger als 5 Minuten laufen	Der Agent stoppt das Skript nach einem festen 5-Minuten-Limit und wertet den Check als Failure. Das Limit ist nicht konfigurierbar — optimiere das Skript oder teile es in mehrere kleinere Checks auf
Sehr große Ausgaben schreiben	Ausgaben über 16 KB behalten ihren Status, aber die Feldwerte werden verworfen und das Ergebnis als gekürzt markiert

Troubleshooting

Der Check zeigt Failure mit einer Fehlermeldung. Das Skript hat sich mit einem Exit-Code ungleich Null beendet, einen Fehler geworfen, oder eine Wrapper-Abhängigkeit fehlt auf dem Gerät — jq unter Linux (apt install jq, dnf install jq), python3 unter macOS. Führe das Skript über den Tab Test des Editors aus: Die Fehlerausgabe erscheint dort direkt.

Der Check zeigt OK, obwohl du Warnung oder Kritisch erwartet hast. Wahrscheinlich hast du vergessen, $output["checkResult"] (PowerShell) zu setzen oder set_result (bash) aufzurufen — der Standard ist 0 / OK. Prüfe außerdem die Werte: 1 ist Warnung und 2 ist Kritisch.

Der Check meldet Failure, nachdem er lange gelaufen ist. Das Skript hat das feste 5-Minuten-Limit überschritten. Das Limit lässt sich nicht erhöhen — mache das Skript schneller oder teile es in mehrere kleinere Checks auf.

Das Dashboard zeigt den Status, aber keine Werte. Die Feldschlüssel, die dein Skript schreibt, müssen den im Tab Ausgabe-Schema deklarierten Schlüsseln entsprechen, und sehr große Ausgaben (über 16 KB) werden auf den Status gekürzt.

Wie du prüfst, dass der Check läuft

Am schnellsten geht es über den Tab Test des Editors: Wähle ein verbundenes Gerät aus und klicke auf Test starten, um Ergebnis, Exit-Code, Laufzeit, Ausgabe und geparste Felder sofort zu sehen. Nachdem du den Check einem Gerät zugewiesen hast, führt octoja ihn im konfigurierten Intervall aus — öffne den Checks-Tab des Geräts, um das Ergebnis im von dir definierten Layout zu sehen. Liefert der Check dort kein Ergebnis, prüfe das Agent-Log auf dem Gerät auf Skriptfehler.

octoja GmbH