Interface Definition for Custom EXE Sensors

Note: Please read the general introduction to Custom Sensors first.

This section will give you an overview of the usage of "Custom EXE/Script" sensors. Every time the sensor is run, the selected EXE, script or DLL file is executed.

The EXE/Script sensor supports following file types:

• EXE
• DLL
• VBScript
• Powershell script
• CMD/BAT script

EXE Sensors

The string entered in the parameter field of the sensor's settings is placed in the command line. The EXE file must send the results to the Standard OUT. The data must be in the following format:

value:message

Value has to be a 32 bit integer and will be used as the resulting value for this sensor (e.g. bytes, milliseconds, etc.), message can be any string and will be stored in the database.

The EXE's exit code has to be one of the following values:

• 0: ok
• 1: warning
• 2: system error (e.g. a network/socket error)
• 3: protocol error (e.g. web server returns a 404)
• 4: content error (e.g. a web page does not contain a required word)

If the EXE does not return control to the PRTG process it is killed as soon as the timeout value set for this sensor is reached.

You can test the EXE file you want to use for the sensor very easily on the command line (cmd.exe). Simply start the EXE file and pipe the results into a file, e.g.:

sensorexe parameter > result.txt

The results are then written into the file result.txt and you can check the results with notepad or any other text editor.

As "parameter" variable you can also use the following placeholders:

• "%device": Device name.
• "%host": Device IP/DNS.
• "%name": Sensor name.
• "%probe": Probe name.
• "%sensorid": Sensor ID number.

Please make sure you write the placeholders in quotes to ensure that they are working properly if their values contain blanks.

CMD/BAT files

The CMD/BAT file must send the results to the Standard OUT. The data must be in the following format:

value:message

Value has to be a 32 bit integer and will be used as the resulting value for this sensor (e.g. bytes, milliseconds, etc.), message can be any string and will be stored in the database.

The script's exit code has to be one of the following values:

• 0: ok
• 1: warning
• 2: error

If the EXE does not return control to the PRTG process it is killed as soon as the timeout value set for this sensor is reached.

A simple sample batch file would look like this:

echo 100:Everything OK
exit 0

 

DLL sensors

Every time the sensor is to be checked the selected DLL file is called. The DLL must export one function:

function perform(para,msg:pchar):integer; stdcall;

para and msg are zero terminated strings. The allocated buffer for msg is 255 bytes, the DLL must make sure that fewer bytes are returned. Msg must be in the following format:

value:message

Value has to be an 32 bit integer and will be used as the resulting value for this sensor (e.g. bytes, milliseconds, etc.), message can be any string and will be stored in the database.

The integer return value of the perform function has to be one of the following values:

• 0: ok
• 1: warning
• 2: system error (e.g. a network/socket error)
• 3: protocol error (e.g. web server returns a 404)
• 4: content error (e.g. a web page does not contain a required word)

Warning: If the function call in the DLL does not return control it could block the whole PRTG system. Make sure to handle your own timeouts and build in a reliable error management. For this reason EXE sensors are recommended.

Links

Sample projects for these Custom sensors can be found:

• In the "PRTG Network Monitor\custom sensors\EXE" subfolder of your PRTG installation.
• In the Knowledge Base on the Paessler website at http://www.paessler.com/kb
• On the prtg7addons website on the open source platform Google Code: http://code.google.com/p/prtg7addons/

Continue