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 ?.

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

Bei Ganzzahl wird eine Zahl ohne Komma erwartet, während bei "Fließkomma" auch eine "real-Zahl" akzeptiert wird. Allerdings muss das Trennzeichen kein "Komma" sein, sondern der englische "Punkt". 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.

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.

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>
</prtg>

Beispielskript mit verschiedenen Type
prtgcustomsensor-xml.ps1

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>
<CustomUnit>Wh</CustomUnit>

Das verhindert aber nicht, dass "Differenzwerte" immer als Summer 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>
    <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.

Fehlermeldung per Exit-Code

Als Weg um einen Fehler an PRTG zu melden, wird der Exit-Code genutzt. 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

Systemfehler

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.. 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.

PowerShell als Sensor

Gerade Exchange und Lync eigenen sich natürlich dafür, immer mal wieder "Werte" zu ermitteln und über PRTG visualisieren zu lassen. Das ist mit PowerShell gar nicht schwer. Allerdings sollten Sie ein paar Dinge beim Einsatz mit PowerShell als EXEXML-Sensor beachten:

c:\windows\sysnative\windowsPowerShell\v1.0\PowerShell.exe `
    -file "C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML\64bitsensor.ps1"
  • Logging
    In den Sensor-Einstellungen kann ein Logging aktiviert werden, damit alle Ausgaben des Sensors in einer Datei landen. Je nach Windows landen die Logs in "C:\Users\All users\Paessler\PRTG Network Monitor\Logs (Sensors)" oder C:\Programm Data\PRTG\
  • Execution-Policy
    Sie müssen die Execution-Policy zumindest aus RemoteSigned oder unsicherer stellen, damit die Skripte überhaupt gestartet werden. Hinweis: Es gibt für 32bit und 64bit eigene ExecutionPolicies. Die Einstellung der 32bit Version ist relevant. Im Logfile finden Sie ansonsten folgendes:
File C:\Program Files (x86)\PRTG Network Monitor\custom sensors\EXEXML\sample.ps1 cannot be loaded
 because the execution of scripts is disabled on this system
. Please see "get-help about_signing" für more details.
At line:1 char:2
+ & <<<< 'C:\Program Files (x86)\PRTG Network Monitor\custom sensors\EXEXML\sample.ps1' ; exit $LASTEXITCODE
    + CategoryInfo          : NotSpecified: (:) [], PSSecurityException
    + FullyQualifiedErrorId : RuntimeException
REM Setzen der Policy für 32bit PowerShell
%SystemRoot%\SysWOW64\WindowsPowerShell\v1.0\PowerShell.exe "Set-ExecutionPolicy RemoteSigned"

REM Anzeige der Policy für 32bit PowerShell
%SystemRoot%\SysWOW64\WindowsPowerShell\v1.0\PowerShell.exe "Get-ExecutionPolicy -list"
  • Write-Host ist STDOUT
    Während in PowerShell selbst ein Write-Host zwar ausgegeben aber nicht in die Pipeline geschrieben wird, übernimmt PRTG auch diese Ausgaben, was natürlich die XML-Rückgabe unbrauchbar macht. Ein PS-Sensor sollte wirklich nur "Write-Warning" oder "Write-Error" verwenden oder die Ausgaben in eine Datei schreiben.

Kleiner Tipp: Man kann die Umgebungsvariable %prtg_version% abfragen um zu erkennen, dass es von PRTG aufgerufen wurde.

  • Import-PSSession und Remove-PSSession
    Es ist wichtig am Ende eines Skript unbedingt eventuell eingebundene PSSessions auch wieder sauber zu entfernen. bei einer Exchange Remote Session bleiben sonst ca. 4KB Temp-Files je Aufruf in C:\windows\temp übrig was sich pro tag schnell auf 1 GB summiert. siehe auch PS Remote
  • Set-PSDEBUG -strict
    Diese Option dürfen Sie im Skript nicht verwenden. Sie können Sie gerne aktivieren, wenn Sie das Skript außerhalb von PRTG zum Test aufrufen, aber innerhalb von PRTG kommt es zu folgenden Fehler, der in der Art des Aufrufs durch PRTG begründet ist.
    http://kb.paessler.com/en/topic/47443-PowerShell-with-set-psdebug-strict
# Aufruf der PowerShell von PRTG
'PowerShell.exe -Noninteractive -Command "&'''+exepath +'''" ' + params+ '; exit $LASTEXITCODE';
The variable '$LASTEXITCODE' cannot be retrieved because it has not been set.
At line:1 char:102
+ &'C:\Program Files (x86)\PRTG Network Monitor\custom sensors\EXEXML\cpuload.p
s1' ; exit $LASTEXITCODE <<<< 
    + CategoryInfo          : InvalidOperation: (LASTEXITCODE:Token) [], Runti 
   meException
    + FullyQualifiedErrorId : VariableIsUndefined
  • Default Verzeichnis "C:\Windows\SysWOW64"
    Wenn Sie im PowerShell eine Ausgabe z.B. mit export-clixml o.ä. nach ".\dateiname.ext" schreiben, dann landet dies im Verzeichnis "C:\Windows\SysWOW64". Wenn ein Script also Dateien speichern will, dann sollten Sie einen Pfad vorgeben.
  • Lokaler Admin
    Eine normale PowerShell kann schon viele Daten ermitteln. Es gibt aber Addons (z.B.: Exchange), die bestimmte Abfragen z.B. im Hintergrund doch per WMI durchführen und dazu lokale Admin sein müssen. Das kann Sie betreffen, wenn die Probe als LocalSystem läuft und Sie beim Sensor ein abweichendes Benutzerkonto angegeben haben.
  • Invoke-Webrequest
    Wenn Sie in einem Sensor eine Webseite mit "Invoke-Webrequest" abfragen wollen, dann denken Sie daran, dass die Umgebung "beschränkt" ist. Invoke-Webrequest nutzt IE-Module um den Inhalt zu rendern. Das ist aber bei Sensoren meist nicht erforderlich und funktioniert auch nicht. Der Parameter "-UseBasicParsing" löst beide Probleme.

Aber dann geht es relativ schnell, einen entsprechenden Sensor zu schreiben.

Gerade aus der 32/64bit Problematik und dass der Name des Skripts nachträglich nicht geändert werden kann, nutze ich in der Regel ein CMD-File als Starter, welches dann das eigentliche Skripte aufruft, mir zusätzliches Debugging und Eine Versionierung erlaubt und ganz generell auch einen Wechsel der Skriptsprache erleichtert. Hier ein Beispiel.

REM PRTG Starter Script
c:\windows\sysnative\windowsPowerShell\v1.0\PowerShell.exe ` -file "C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML\64bitsensor.ps1" %1 %2 %3 %4

Tipp:
Sie können die Skripte auch interaktiv starten. Dazu sollten Sie aber wie die PRTG-Probe auch eine 32bit Shell nutzen, die sie wie folgt starten können:
"%windir%\SysWoW64\cmd.exe"

Laufzeitumgebung

Ich habe einfach mal ein Skript erstellt, welches einige Daten exportiert, um die LaufzeitUmgebung zu ermitteln.

get-variable | Export-Clixml .\test.variable.xml
$host  | Export-Clixml .\test.host.xml
$input | Export-Clixml .\test.input.xml
Get-Childitem env: | Export-Clixml .\test.env.xml

Hier die Ausgabe von $host

Name             : ConsoleHost
Version          : 4.0
InstanceId       : bb3422f2-bd3a-49f2-a534-444782199be9 uI               : System.Management.Automation.Internal.Host.InternalHostUserInterface
CurrentCulture   : de-DE
CurrentUICulture : en-US
PrivateData      : Microsoft.PowerShell.ConsoleHost+ConsoleColorProxy
IsRunspacePushed : False
Runspace         : System.Management.Automation.Runspaces.LocalRunspace

Und hier die Ausgabe der Variablen

Name                           Value
----                           -----
$
?                              True
^
args                           {}
ConfirmPreference              High
ConsoleFileName
DebugPreference                SilentlyContinue
Error                          {}
ErrorActionPreference          Continue
ErrorView                      NormalView
ExecutionContext               System.Management.Automation.EngineIntrinsics
false                          False
FormatEnumerationLimit         4
HOME
Host                           System.Management.Automation.Internal.Host.InternalHost
input                          System.Collections.ArrayList+ArrayListEnumeratorSimple
MaximumAliasCount              4096
MaximumDriveCount              4096
MaximumErrorCount              256
MaximumFunctionCount           4096
MaximumHistoryCount            4096
MaximumVariableCount           4096
MyInvocation                   System.Management.Automation.InvocationInfo
NestedPromptLevel              0
null
OutputEncoding                 System.Text.ASCIIEncoding
PID                            3084
PROFILE                        WindowsPowerShell\Microsoft.PowerShell_profile.ps1
ProgressPreference             Continue
PSBoundParameters              {server}
PSCommandPath                  C:\Program Files (x86)\PRTG Network Monitor\custom sensors\EXEXML\prtg-excasuser.ps1
PSCulture                      de-DE
PSDefaultParameterValues       {}
PSEmailServer
PSHOME                         C:\Windows\SysWOW64\WindowsPowerShell\v1.0
PSScriptRoot                   C:\Program Files (x86)\PRTG Network Monitor\custom sensors\EXEXML
PSSessionApplicationName       wsman
PSSessionConfigurationName     http://schemas.microsoft.com/PowerShell/Microsoft.PowerShell
PSSessionOption                System.Management.Automation.Remoting.PSSessionOption
PSUICulture                    en-US
PSVersionTable                 {PSRemotingProtocolVersion, BuildVersion, PSCompatibleVersions, PSVersion...}
PPWD                            C:\Windows\system32
server                         nawex001
ShellId                        Microsoft.PowerShell
StackTrace
true                           True
VerbosePreference              SilentlyContinue
WarningPreference              Continue
WhatIfPreference               False

Leider setzt PRTG per Default keine eigenen Variablen, die dem Skript einen Hinweis auf die Laufzeitumgebung geben. Aber eine einfache IF-Abfrage auf "PSScriptRoot" ist meist ausreichend:

if ($PSScriptRoot.EndsWith("EXEXML")) {
    write-host "Check-ADFS: Assume PRTG EXEXML-Mode"
}
else {
    Set-PSDEBUG -strict  # enable strict variable checking. Not usable with PRTG
}

Sie können aber die PRTG-Einstellungen in der Konfiguration aktivieren. Diese sind per Default inaktiv aber können als Platzhalter bei der Parametrisierungen mit übergeben werden. Siehe dazu auch https://prtg.paessler.com/api.htm?username=demo&password=demodemo&tabid=7) Wenn Sie aber folgende Option aktivieren, dann werden die Parameter aber als Umgebungsvariablen gesetzt.

Dann finden sich auch die von PRTG gesetzten Werte in Variablen

prtg_device                    PRTGDEVICE
prtg_deviceid                  2020
prtg_groupid                   2171
prtg_host                      PRTGDEVICE.msxfaq.de
prtg_linuxpassword
prtg_linuxuser
prtg_name                      SENSORNAME
prtg_primarychannel            2
prtg_probe                     PROBENAME
prtg_probeid                   1
prtg_sensorid                  2089
prtg_snmpcommunity             public
prtg_URL                       https://prtg.msxfaq.de/
prtg_version                   13.4.7.3706
prtg_windowsdomain             MSXFAQ
prtg_windowspassword           DeMoPass
prtg_windowsuser               Administrator

Diese Werte können per "$ENV" dann natürlich auch einfach abgefragt werden. Paessler selbst ist hier sehr vorsichtig und schaltet diese Option per Default nicht ein, da so ein Script natürlich auch die Credentials ausgeben könnte.

Achten Sie daher genau darauf, wenn ein CustomSensor diese Daten in der Form von ihnen bekommen möchte.

Variable Description

prtg_version

The version number of your PRTG installation

prtg_URL

The IP address/DNS name of your PRTG installation

prtg_primarychannel

The ID of the sensor's current primäry channel (1 if not set)

Parameter mit PowerShell

Gerade wenn sie in einem Skript mehrere Module zusammen gefasst habe oder das gleiche Skript für mehrere Ziele eingesetzt wird, sind die Parameter unersetzlich. Sie können damit aus PRTG heraus Werte an den Sensor übergeben.

Damit die Übergabe aber funktioniert, muss im Skript auch der "Param"-Bereich beachtet werden. Wenn Sie am Anfang des Skripte einen "PARAM"-Bereich haben, dann matched die PowerShell die angegebenen Parametern auf die Felder. Nur Named Parameter, die nicht "gefunden werden, landen dann in der Variable $ARGS. Angenommen Sie haben folgenden Parameterkopf:

param (
   [string]$param1= "Wert1",
   [string]$param2= "Wert2"
)

Und übergeben folgende Parameter:

-param2:'test" -param3:"wert3"

Dann sind folgende Inhalte in den Variablen:

$param1 = "Wert1"     # Vorbelegung des Parameterkopf
$param2 = 'test'      # aus der Parameterzeile gelesen
$param3 = $null       # Die variable gibt es nicht
$args.count = 2       # es sind ZWEI Parameter, da der Doppelpunkt hier ein Trenner ist
$args[0] = "-param3"  # Das ist der erste Teil der nicht aufgelösten Parameter
$args[1] = "wert3"    # Das ist der zweite Teil der nicht aufgelösten Parameter 

Allerdings habe ich bei der Entwicklung von PRTG ExMetric ein paar komische Verhalten gesehen, die auch mit PowerShell zusammen hängen könnten.

Parameter Status Bemerkung

-switch

OK

Die einfache Übergabe eines Parameters als Switch funktioniert

-switch1 -switch2

OK

Das gleiche mit zwei Switches

-feld:wert

OK

Die einfache Übergabe eines Parameters mit einem Wert funktioniert

-feld:"wert1 wert2 wert3"

FAIL

Die Übergabe eines String mit mehreren Werten, die mit einem Leerzeichen getrennt waren, hat zumindest bei mir nicht funktioniert.

-feld:"wert1,wert2,wert3"

OK

Dafür konnte ich problemlos mit Komma als Trenner arbeiten

-feld:"wert1;wert2;wert3"

OK

Oder alternativ mit Semikolon

Ich habe nicht alle Varianten ausprobiert. Da ich meinem Sensor eine Liste von user, Servern o.ä. übergeben will und dabei sowohl Komma als auch Semikolon mir helfen, habe ich das nicht weiter verfolgt. Auf jeden Fall sollten sie Parameter, die sie übergeben, auch im Sensor nach der Auswertung entsprechende zur Fehlersuche ausgeben.

Hinweis:
Verwenden Sie nicht die "doppelten Anführungszeichen" sondern immer nur einfache und trennen Sie Arrays durch Komme oder Semikolon 

Sie können in der Konfiguration des Sensors aber auch vordefinierte Variablen mit übergeben (Stand Nov 2013).

Placeholder Description

%sensorid

ID des EXE/Script Sensor

%deviceid

ID des Geräts, auf dem der Sensor angelegt ist

%groupid

ID der Gruppe, in der der Sensor angelegt ist

%probeid

ID der Probe, unter der der Sensor angelegt wurde

%host

IP Adresse/DNS-Name des Devices, unter dem der Sensor angelegt ist

%device

Name des Devices, unter dem der Sensor angelegt ist

%group

Name der Gruppe in der das Device angelegt wurde

%probe

Name der Probe, unter der der Sensor angelegt wurde

%name oder %sensor

Name des EXE/Script Sensors

%windowsdomain

Windows Domäne der Anmeldedaten (kann vererbt sein)

%windowsuser

Windows username der Anmeldedaten (kann vererbt sein)

%windowspassword

Windows Kennwort der Anmeldedaten (kann vererbt sein)

%linuxuser

Linux username der Anmeldedaten (kann vererbt sein)

%linuxpassword

Linux Kennwort der Anmeldedaten (kann vererbt sein)

%snmpcommunity

SNMPV1 community string (kann vererbt sein)

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.