PRTG - Custom Sensor

PRTG lässt sich relativ einfach erweitern. Das Programm ruft beliebige BAT, CMD, VBS oder PowerShell-Skripte aus, kann alternative Anmeldedaten und Parameter übergeben und erwartet einfach das oder die Ergebnisse per STDOUT zurück. Die einfache Skriptvariante kann nur genau einen Wert zurück geben. Dazu wird die Zahl einfach ausgegeben und mit einem ":OK" beendet. Über das Trennzeichen ":" können auch andere Statusmeldungen zurück gegeben werden. Wer mehr Funktionen möchte, muss eine XML-Struktur zurückgeben, die auch mehrere "Kanäle" erlaubt. Zuletzt wertet PRTG noch den Errorlevel aus, um den Erfolg des Sensors zu können.

Lösen Sie sich mal von dem reinen Monitoring von Netzwerkdaten. Auch andere Datenquellen können interessante numerische Werte liefern. Wie wär es mit einem Skript, welches aus dem Messagetracking sich die letzten 5 Minuten ausliest und die "Anzahl Send/Receive" und "Kilobyte Send/Receive" ausgibt?

Beachten Sie dazu die Besonderheiten eines Custom Sensor Scripts per PowerShell auf PRTG - PS Custom Sensor

Einbindung und Aufruf

Eigene Sensoren werden über die PRTG-Verwaltung einfach hinzu gefügt. Wenn Sie nach "EXE" Filtern, dann sehen Sie schon dein einfachen EXE/Script-Sensor und den EXE/Script Advanced.

Beide Sensoren können COM, EXE, BAT, VBS und PS1-Dateien aufrufen, die sowohl Parameter von PRTG bekommen können und natürlich per STDOUT eine Rückgabe der Werte bewerkstelligen.

Wichtiger Hinweis:
Der Name des Skripts kann nachträglich NICHT mehr geändert werde. Vermeiden Sie daher z.B. Versionsnummern im Dateinamen etc., wenn Sie später das Skript weiter entwickeln wollen.

“... once the sensor is created there is no way of changing the used script...”
Quelle: http://www.paessler.com/knowledgebase/en/topic/47233-how-can-i-change-the-script-an-exe-monitor-calls 

Einfacher EXE-Sensor

Wenn Sie einen eigenen Sensor schreiben, dann müssen Sie sich überlegen, wie Sie die Daten "zurück" übergeben. PRTG erwartet, dass das aufgerufene Programm die Daten über STDOUT ausgibt, um Sie so abzurufen. Die Art des Sensors bestimmt das erwartete Format. In dem Sensorverzeichnis gibt es zwei relevante Unterverzeichnisse, die zugleich das Rückgabeformat vorgeben:

Die Sensoren werden als Datei im Verzeichnis "C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML" abgelegt, wenn die Rückgabe eine XML-Datei ist, ansonsten im Verzeichnis EXE.

Note: Please do not use the folder \Custom Sensors\PowerShell Scripts to store your files. This remant from previous software versions is not used any more and may usually be deleted
Quelle: http://www.paessler.com/manuals/prtg/exe_script_advanced_sensor

Der "einfache" Sensor kann dabei genau einen Wert als "Value" zurückgeben. Die "Message" wird später in PRTG angezeigt und kann z.B. Details bei einem Fehler beschreiben:

value:message

Zum Testen reicht also auch ein einfaches ECHO in einem CMD-Script.

prtgcustomsensor-exe.cmd

Wie dann aber die "Message" interpretiert wird, geben Sie in bei der Anlage des Sensors mit an:

Fehlermeldung per Exit-Code

Als Weg um einen Fehler an PRTG zu melden, wird der Exit-Code genutzt.

Nicht beim XML-Sensor
Dieser Code wird nur beim einfachen EXE-Sensor ausgewertet. Er wird NICHT beim EXEXML-Sensor genutzt. Dort müssen Sie in der XML-Datei den Status melden, wobei auch da nur 0=OK oder 1=Error möglich ist. Der Exit-Code ist hier nur als Gesamtergebnis für den Aufruf des Sensors zu sehen und nicht um den Sensor aufgrund von Daten in einen anderen Status zu versetzen. Nutzen Sie dazu die Limits pro Channel um den jeweiligen Channel in einen Warnzustand zu versetzen.

Vorgesehen sind folgende Meldungen:

Exitcode Bedeutung Beschreibung

0

OK

Fehlerfreie Ausführung. Nutzen Sie doch das Feld "Message" um vielleicht mehr Details zu melden

1

Warnung

Das Skript kann so melden, dass z.B. ein Sensor an einer Warngrenze ist.

Gemeldete Werte werden als "0" erfasst.

2

Critical
Systemfehler

Die Werte sind über den "Critical" Grenzwert oder der Sensor konnte keine Daten erhalten, z.B. weil das Zielsystem nicht erreichbar ist, falsche Parameter angegeben wurden o.ä. Ein guter Sensor schreibt in die Message die Details zum Fehler.

Gemeldete Werte werden als Fehler ignoriert und die Zeit wird als "Ausfallzeit" gewertet

3

Protokollfehler

Mit diesem Fehler sollte ein Sensor melden, wenn er zwar die angesprochene API erreicht hat, aber z.B. aufgrund von Berechtigungen keine Daten zur Auswertung gewinnen konnte.

Gemeldete Werte werden als Fehler ignoriert und die Zeit wird als "Ausfallzeit" gewertet

4

Contentfehler

Mit diesem Fehler sagt ein Sensor, wenn er erfolgreich Daten erhalten hat (Verbindung und Anmeldung ok) aber die Werte nun gar keinen Sinn machen. Sie können außerhalb der erwarteten Bandbreite sein oder enthalten nicht die erwarteten Inhalte.

Gemeldete Werte werden als Fehler ignoriert und die Zeit wird als "Ausfallzeit" gewertet

Der Exit-Code setzt den Sensor in den entsprechenden Fehlerzustand, so dass Alarme auch ohne Pflege von Grenzwerten in der Sensordefinition gemeldet werden. Allerdings hat diese Art der Alarmierung und Warnung das Problem, dass die vielleicht sinnvollen Werte nicht erfasst werden. Sie sollten den Error-Level daher wirklich nur nutzen, um z.B. den Status zu melden und die Werte dann nicht wichtig sind. Ansonsten ist es besser, wenn der Sensor immer ein "OK" meldet und Sie in PRTG selbst die Grenzwerte für Warnung und Fehler konfigurieren. Wenn genau genommen gibt es ja noch mehr Varianten:

  1. Sensor wird aufgerufen und kann Werte lesen und Wert < Warnschwelle -> GRÜN
  2. Sensor wird aufgerufen und kann Werte lesen und Warnschwelle < Wert < Alarmschwelle -> GELB
  3. Sensor wird aufgerufen und kann Werte lesen und Wert > Alarmschwelle -> ROT
  4. Sensor wird aufgerufen und kann KEINE Werte lesen z.B. Server nicht da, falscher Hostname -> „anderes“ ROT
  5. Sensor kann nicht gestartet werden, z.B. weil PS1-Datei gelöscht wurde oder SyntaxError hat -> „noch ein anderes“ ROT

Die Rückgabe des Standard-Sensors und die Bewertung des EXIT-Code ist übrigens sehr ähnlich zu Nagios:


Quelle: Nagios Plug-ins Development Guidelines - Plug-in Return Codes
https://nagios-Plugins.org/doc/guidelines.html#AEN78

Allerdings kennt Nagios nicht den Fehler 4.

EXEXML - mehr Komfort und mehr Funktionen

Sehr viel leistungsfähiger ist der EXEXML-Sensor. Wie der Name schon verrät erwartet PRTG eine XML-Datei, die aber zum einen mehrere Messwerte gleichzeitig übergeben kann und zudem pro Wert in der XML-Datei die Einheit, der Typ (Ganzzahl oder Float) und die Berechnung (Absolut oder Differenz) angegeben werden kann.

Eine Ausgabe auf den Bildschirm ist für ein automatisch gestartetes Skript natürlich nicht hilfreich. PRTG erwartet die Ausgabe über STDOUT und wenn ich mehrere Messwerte übergeben will, am besten per XML-Datei. Hier ein Muster für einen Float-Wert.

<?xml version="1.0" encoding="UTF-8" ?>
<prtg>
   <result>
      <channel>Demo Minimum Example</channel>
      <value>3.2</value>
      <float>1</float>
   </result>
   <text>Diese Info erscheint im Statusbalken</text>
</prtg>

Beispielskript mit verschiedenen Typen
prtgcustomsensor-xml.ps1

Komma, Float und Integer

Abhängig von der Einstellung des Wertetyp müssen Sie auch die Daten an PRTG übermitteln. Für "Float" ist die Trennung von Dezimalen aber nicht das deutsche "Komma", sondern der amerikanische "." (Punkt). Beim Wert "Ganzzahl" sind sowieso nur Zahlen erlaubt. PRTG erfasst aber nicht nur das Ergebnis sondern auch die Ausführungszeit. Die Angaben ob es sich bei dem Wert aber nun um "Prozent", "Grad" oder eine andere Einheit handelt, müssen Sie in PRTG konfigurieren.

Hinweis
Die Einstellung "Delta" ermitteln den echten Wert immer anhand der Subtraktion des vorherigen Wert von dem aktuellen Wert. Diese Einstellung eignet sich für Zähler, die immer weiter aufsummieren während Sie die Differenz suchen. Dies trifft z.B. für Stromzähler oder Zähler bei Ethernet-Schnittstellen zu.

Wertetyp 123 12,3 12.3 Beschreibung

Ganzzahl

123

Error

Error

Ganzzahlen verarbeiten keine Float-Zahlen

Fließkomma

123

Error

12.3

Beachten Sie, dass ein "Komma" kein Trenner bei Float ist

Delta

123

Error

Error

Beachten Sie, dass Delta nur mit Ganzzahlen funktioniert

Achtung: Delta kann immer nur von "Ganzzahlen" rechnen. Wenn ihr Sensor also eine "Float"-Zahl liefert, dann sehen sie keine Ergebnisse. "Differenz" ist also nur für Zählerstände aber nicht für den Anstieg von Temperaturen oder anderen "ungeraden" Werten geeignet.

Beachten Sie hier auch eine Besonderheit der PowerShell, wenn Sie einen "Double" direkt oder über Write-Host" ausgeben:

[double]$test=12.34
$test
write-host "$($test)"

Einmal wird ein "." (Punkt) ausgegeben und das andere mal ein "," (Komma)

Difference/Counter/Gauge

Das Auswerten von absoluten Werten ist relative einfach. Es gibt aber auch Werte, die kontinuierlich hochzählen. Das ist nicht nur bei Routern und Switchen der Fall mit Bytes und Paketen pro Interface. Auch Stromzähler erhöhen immer weiter ihren Wert, was in einer PRTG-Grafik dann natürlich eine ansteigende Linie liefert. Manchmal möchte man, dass PRTG die Differenz von einem vorherigen Messwert ermittelt. Für den Fall definieren Sie den Sensor als "<mode>Difference</mode>".

Hinweis:
Anscheinend subtrahiert PRTG bei der Funktion "Difference" nicht nur den vorherigen Wert vom aktuellen Wert sondern teil ihn auch noch durch die Zeit zwischen der Messung. Das Ergebnis ist dann immer ein "Wert pro Sekunde". Wenn Sie absolute Werte so errechnen müssen, dann geht das wohl nur durch eine eigene Berechnung im Skript oder über eine Sensor Fabric.

Um der Funktion des "Difference" besser zu verstehen, habe ich ein paar Werte mit unterschiedlichen Schreibweisen an PRTG eingetütet und das Ergebnis betrachtet. Dazu habe ich einen kleinen EXEMXML-Sensor mit folgendem PowerShell-Script gefüllt, welches Daten in unterschiedlichen Schreibweisen an PRTG meldet. Eine Zahl wird als "123,  1,23 und 1.23" geschrieben.

Nur die grün markierten Zeilen liefern auswertbare Daten. PRTG akzeptiert "Ganzzahlen" mit jedem Sensor (Grün). Zahlen mit einem "," (Komma) als Dezimalzeichen werden gar nicht verarbeitet. Der Wert ist immer "0" statt "$null" und Werte, die als "Ganzzahl" definiert sind, akzeptieren auch nur ganze Zahlen.

 Natürlich können mehrere "Channels" als "Result"-Einträge addiert werden. Interessant sind nun aber die Kombinationen von der Betriebsart, der Float-Einstellung und der gelieferten Zahl.

Float Mode Zahl Ergebnis

1

Absolute (Default)

3

OK Absoluter Wert

1

Difference

3

OK Differenz

1

Absolute (Default)

3.5

OK Absoluter Wert

1

Difference

3.5

0 !!

0 (Default)

Absolute (Default)

3

OK Absoluter Wert

0 (Default)

Difference

3

OK Differenz

0 (Default)

Absolute (Default)

3.5

0 !!

0 (Default)

Difference

3.5

0 !!

Sie sehen auch hier wieder gut, dass die "Differenz" nur mit Ganzzahlen funktioniert, dann aber auch wenn "Float" angegeben ist aber doch nur Ganzzahlen kommen. Hier einmal der Überblick:

Damit gilt für Differenz wieder das gleiche wie beim einfachen EXE-Sensor. Immer nur "Ganzzahlen" verwenden. Die Deklaration selbst ist dann irrelevant.

Etwas irritieren kann, dass PRTG ohne weitere Definitionen auch die Standardeinheiten anwendet und bei jedem "Difference" Ergebnis einmal die "Summe" und die "Geschwindigkeit/Sek" anzeigt. Man kann mit Volumesize und eine CustomUnit die Beschriftung ändern:

<VolumeSize>One</VolumeSize>
<Unit>Custom</Unit>
<CustomUnit>Wh</CustomUnit>

Das verhindert aber nicht, dass "Differenzwerte" immer als Summe und als Geschwindigkeit in der Tabellenansicht mit ausgegeben werden:

PRTG kann selbst, abgesehen von 10er stellen (Kilo, Mega, Giga etc.) die Werte nicht weiter umrechnen. Wenn Sie 0,5W/Impuls bekommen, dann müssen Sie selbst vorher schon die Zahlen anpassen. Denken Sie aber wieder daran, dass für die Berechnung von Differenzen nur Ganzzahlen genutzt werden können.

Bei der Nutzung der Differenzfunktion kann natürlich bei der allerersten Messung nach der Einrichtung kein Wert ermittelt werden.

Bei der Erstellung der Rückgabe ist mir eine Besonderheit aufgefallen, die vielleicht so nicht gewollt war aber ich sehr gut finde. PRTG scheint in der Ausgabe alle Texte zu ignorieren, bis ein "<prtg>"-Zeichen kommt. Vermutlich parst PRTG die XML-Struktur manuell und nutzt nicht die Microsoft-Klassen MSXML. Zudem ist PRTG nicht "Case-Sensibel" bezüglich der XML-Tags.

Das hat den Vorteil, dass ich in PowerShell-Skripten durchaus eine "Debug-Ausgabe" mit Write-Host ausgeben kann, die später bei der der Fehlersuche hilfreich sein kann. Die XML-Ausgabe muss dann einfach am Ende angehängt werden:

Start PRTG Sensor
 Creating Exchange Remote Session
 Import Exchange Remote Session Commandlets
WARNING: Some imported command names include unapproved verbs which might make 
them less discoverable. Use the Verbose parameter für more detail or type 
Get-Verb to see the list of approved verbs.
MBSize List: frank.carius@msxfaq.de
Processing Mailbox:frank.carius@msxfaq.de
End: ExitCode  0
Sending Result to output pipeline
<prtg>
  <result>
    <channel>frank.carius@msxfaq.de</channel>
    <value>46</value>
    <unit>Custom</unit>
    <customunit>MB</customunit>
    <mode>Absolute</mode>
  </result>
</prtg>

So kann man gleich zwei Fliegen mit einer Klappe schlagen und in der Ausgabe sowohl die Diagnoseinformationen unterbringen und das Ergebnis.

Fehlersuche

Wenn ein Sensor einmal nicht so will, wie erwartet, dann sollten Sie zuerst auf dem Sensor die Ausgabe in einer Datei aktivieren. Dann schreibt PRTG all was, was der Sensor über "STDOUT" an PRTG zurück gegeben hat, in eine Datei.

Wenn Sie schon den Sensor bearbeiten, dann sollten Sie in der Übersicht sich gleich die SensorID merken:

Diese Nummer taucht nämlich im Dateinamen entsprechend auf:

Mit einem gewöhnlichen Text-Editor können Sie die Ausgaben dann analysieren.

BuildIn Sensoren

Dass PRTG selbst für einige eingebaute Sensoren diese API nutzt, können Sie an den Programmen im Verzeichnis "C:\Program File (x86)\PRTG\ Network Monitor\Sensor System\" sehen.

Öffnen Sie einfach mal eine CMD-Shell und starten Sie eine der Programme. Bei meinem Tests haben alle Programme nach dem Start eine Hilfe mit den Parametern angezeigt.

Wenn Sie dann den Sensor mit den passenden Parametern aufrufen, sehen Sie auf der Bildschirmausgabe am Ende auch den Wert, wie ihn der PRTG-Server auswerten kann.

Ideen für Sensoren

PRTG kann nahezu alles, was sich in Zahlen umsetzen kann, auch wieder visualisieren. Und da gibt es ganz viele Datenquellen, die durch Skripte etc. angezapft werden können.

  • Exchange Messagetracking (Siehe PRTG ExTracking)
    Allein durch die numerische Auswertung der empfangenen und gesendeten Mails (Anzahl und Megabyte) im 5 Minuten Abstand erhält man eine gute Datenbasis für die vergangene Nutzung und kann auch Spitzen und Ruhezeiten recht einfach erkennen. Wenn erforderlich könnte die Auswertung auch noch nach Intern/Extern etc. verfolgen. Es wird aber wenig Sinn machen, eine Statistik nach einzelnen Mailadressen oder externen Domänen anzulegen. Eine Trennung nach internen Bereichen könnte wieder interessant sind
  • Exchange ActiveSync Partnerschaften, Mailboxen, PublicFolder (siehe PRTG ExMetric)
    Auch die absoluten Benutzerzahlen sind natürlich interessant. Sicher muss dieser Wert nicht alle 5 Minuten ermittelt werden. Ein Wachstum von Datenbanken, Postfachanzahlen und mobilen Anwendern kann auch einmal am Tag oder alle 6h sinnvoll erfasst werden
  • Exchange TransactionLogs (Siehe PRTG:ExDBLog)
    Mit dem "Folder Sensor" kann schon von hause aus z.B. das Verzeichnis überwacht werden, in dem die Transaktionsprotokolle abgelegt werden. Wird der Wert z.B. alle 15 Minuten ermittelt, dann kann schön das Wachstum der Logs und das Abschneiden durch das Backup dargestellt werden. Hier ist natürlich auch die Obergrenze interessant, was dann auf Probleme beim Backup hinweist und ein Volllaufen der Disk verhindern kann.
  • IISLog-Auswertungen
    Immer mehr Dienste nutzen den IIS als Schnittstelle. Der IIS protokolliert schön alle Zugriffe, so dass aus dem IISLog relativ einfach interessante Kennzahlen ermittelt werden können, z.B. Anzahl von 2xx,3xx,4xx,5xx Meldungen. Warnung bei vielen 5xx. Ermitteln der absoluten Request und Megabyte quasi "neartime". Aber auch die verschiedenen URLs (RPC, ActiveSync, OWA, EWS, OAB etc. können so einfach zeitnah analysiert werden.
  • PurgeIISLogs
    Die IISLogs haben die unschöne Eigenschaft, dass kein eingebauter Prozess alte Dateien entfernt. Ein Server füllt sich also immer weiter auf. Ein Sensor könnte zum einen die Größe der Dateien ermitteln aber zugleich auch etwas aufräumarbeit machen.
  • AD-Änderungen (Siehe PRTG USNChange)
    Der Wert der höchsten USN bei einem Domaincontroller ist ein guter Indikator für die Anzahl der Änderungen im AD und ganz einfach auszulesen.

Wenn man aber so viele Exchange Auswertungen macht, dann wäre doch mal zu überlegen, welche wie oft gestartet werden müssen. Eine Auswertung der Datenbankgrößen oder Anzahl der ActiveSync-Geräte muss nicht im 5 Minuten Intervall erfolgen. Wenn jeder Sensor bei jedem Aufruf eine "Remote PowerShell" startet, dann ist das vielleicht nicht optimal. Interessant wäre hier, wenn ein PowerShell-Script die Daten für alle Sensoren ermittelt und abspeichert. Dann müssen die Skripte beim Sensor diese Daten nur noch auslesen und an PRTG übergeben.

Leider kenne ich keinen Weg, wie man selbst direkt Daten in die PRTG-Datenbank importieren kann. Ein Sensor kann auch nur "seine" Werte schreiben. Ich kann also nicht ein Skript nutzen, welches dann bei verschiedenen "Sensoren" die Daten in einem Aufruf liefert.

Hinweis und Warnung zur Performance

Überlegen Sie genau, welche Skripte wie oft aufgerufen werden und welche Last damit verursacht wird. Die Auswertung einer Dateigröße ist schnell erfolgt. Eine PowerShell-Abfrage um z.B. die Mailboxgrößen zu ermitteln, kann bei großen Umgebungen einige Zeit dauern. Bedenken Sie dabei immer:

  • Laufzeit
    Sie sollten daher zum einen eine Obergrenze definieren, wann PRTG einen Sensor abwürgt.
  • Wiederholungsintervall
    und natürlich das Wiederholinterfall anpassen. Nicht alle Werte müssen wirklich mit 5 Minuten "Auflösung" ermittelt werden. Da kann auch mal ein Aufruf pro Stunde oder Tag ausreichen, was zugleich die Datenbank entlastet.

Gerade bei Abfragen von Exchange wäre zu prüfen, ob die verschiedenen Sensorskripte die Werte nur aus einer Datei auslesen und an PRTG übergeben und die Generierung der Daten nur bei Bedarf gestartet wird. Wenn ein Sensor also z.B. das Ergebnis von "Get-Mailbox" in eine XML-Datei speichert und beim nächsten Start diese Daten von dort auch wieder holt, dann könnte dies deutlich schneller sein. Auch könnte ein Sensor mehrere Funktion beinhalten, die sich per Parameter aktivieren lassen. So könnten einmal ermittelte Daten mehrfach verwendet werden.

Wunschliste ?

Mit der Funktion beliebige EXE, COM, VBScript, PowerShell-Skripte o.ä. einzubinden, können Sie nahezu alle Tests ausführen, Messwerte erfassen oder Events überprüfen. Der Code wird dabei von der Probe ausgeführt, die für die Überwachung zuständig ist. Und genau das ist auch aktuell aus meiner Sicht noch eine Schwäche: Sie müssen den Code selbst auf die Probe kopieren, ehe Sie diesen dann auch ausführen können.

Hier würde ich mir wünschen, dass es ein zentrales Code-Repository auf dem PRTG Server gibt, den die Probes einfach lokal kopieren. Über den bestehenden TCP-Kanal sollte es recht einfach möglich sein.

Weitere Links

Hier die Links zu den API-Beschreibungen.