Interface Definition for Custom EXE Sensors

Every time the sensor is run, the selected EXE or DLL file is executed.

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.

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:

Continue

Keywords: Custom Sensor,EXE,BAT,CMD,PS1