Content Previous Next

PRTG Manual: Custom Sensors

<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: Custom Sensors

Custom sensors allow a number of monitoring tasks to be performed that go far beyond the standard sensor set. Apart from parameterized versions of SNMP, Packet Sniffer, and NetFlow sensors, you can create your own sensors using WQL or Python, by compiling an EXE file, using any Windows software development tool, and you can request any REST API that returns JSON or XML and map the results to sensor channels.

The following documentation describes the custom EXE/Script, Python Script, and SSH Script sensors. The defined XML and JSON formats for the advanced sensors are also used for advanced HTTP data sensors and the REST Custom sensor.

For more information about custom sensors based on SNMP, WMI, Packet Sniffing, and xFlow, see the respective custom sensor types.

For each sensor interval, PRTG can run an external process. The process can be a Windows EXE file, or a DLL, BAT, CMD, VBS, or PowerShell file, as well as a Python or SSH script.

Here are quick links for ease of use.

Standard and Advanced EXE/Script Sensor

You must create the sensor as a file and place it in a specific folder on the system running the PRTG probe. This means that if you are using remote probes, the files must be copied to the remote system, in a PRTG cluster setup on each cluster node.

Place executables (.EXE, .DLL), batchfiles (.CMD, .BAT), VBS scripts (.VBS), or PowerShell scripts (.PS1) into a subfolder of the PRTG program directory. For the standard EXE/Script sensor, this is the following subfolder of your PRTG program directory:

Custom Sensors\EXE

If your executable or script returns XML or JSON, you will use it with the EXE/Script Advanced sensor. In this case, store your file in the following subfolder of the PRTG program directory:

Custom Sensors\EXEXML

You will find a sample set of demo sensors in these folders, too. As soon as a file is placed into the folders mentioned above, you can create your own custom EXE sensor and select the new file from the list of files.

The probe will then execute the file on the probe system using the account configured for the PRTG probe service ("system" is the default). The local probe will run the file on the local PRTG core server system. For remote probes, the file will actually run on the remote system.

If your custom sensor code relies on other files (for example, DLLs, .NET framework, Windows PowerShell) you must copy/install these files on the probe machine manually!

EXE sensors will fail if they attempt to open any graphical user interface windows using the Win32 APIs. This is not allowed for processes that are started by a system service.

Standard and Advanced SSH Script Sensor

You must create the sensor as an SSH script and place it in a specific folder on the target system running your Linux/Unix installation where the script will be executed.

Place your SSH script files for the standard SSH Script sensor in the following directory of the target system:

/var/prtg/scripts

If your SSH script returns XML or JSON, you will use it with the SSH Script Advanced sensor. In this case, store your file in the following directory of the target system:

/var/prtg/scriptsxml

As soon as a file is placed into the respective folder, you can create your own SSH script sensor and select the new script file from the list of scripts.

With each scanning interval, PRTG will execute the script on the target system and receive the result as a sensor result.

Interface Definition for EXE/BAT/CMD/VBS/PowerShell/SSH Sensors

Every time the sensor is run, the selected file is executed. The string entered in the Parameters field of the sensor's settings is used as command line (you can use placeholders, see Command Line Parameters). The executable file must send the results to the Standard OUT. For the format of returned data, see below.

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.

Example

sensorexe parameter > result.txt

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

Remarks

For PowerShell scripts, make sure that they may be executed by either signing the files or changing the security policy for Powershell.exe accordingly.
In SSH scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings in the Parameters field of the sensor's settings.
The API interface for custom EXE sensors is compatible with the custom EXE sensors provided by PRTG Network Monitor.

Return Values for EXE/BAT/CMD/VBS/PowerShell/SSH Sensors

The expected return values are different, depending on the type of EXE/Script sensor used. The standard sensor needs a simple value:message pair; the EXE/Script Advanced sensor processes an XML or JSON return value. When using the standard SSH Script sensor, it will expect returncode:value:message as result. See details below.

Standard EXE/Script Sensor

The returned data for standard EXE/Script sensors must be in the following format:

value:message

Value has to be a 64-bit integer or float. It will be used as the resulting value for this sensor (for example, bytes, milliseconds) and stored in the database. The message can be any string (maximum length: 2000 characters).

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

Value	Description
0	OK
1	WARNING
2	System Error (for example, a network/socket error)
3	Protocol Error (for example, web server returns a 404)
4	Content Error (for example, a web page does not contain a required word)

Standard SSH Script Sensor

The returned data for standard SSH Script sensors must be in the following format:

returncode:value:message

The SSH script returncode has to be one of the following values:

Value	Description
0	OK
1	WARNING
2	System Error (for example, a network/socket error)
3	Protocol Error (for example, web server returns a 404)
4	Content Error (for example, a web page does not contain a required word)

Advanced Script, HTTP Data, and REST Custom Sensors

The returned data for the EXE/Script Advanced, Python Script Advanced, SSH Script Advanced, HTTP Push Data Advanced, HTTP Data Advanced, and HTTP IoT Push Data Advanced sensors must be in XML or JSON format, the REST configuration file for the REST Custom sensor must be available as JSON template. Most parameters have a default value and are not required.

The following minimum examples leave most parameters to their default values and return two static channel values.

Examples

XML Return Format: Minimum Example:

            <prtg>
            <result>
            <channel>First channel</channel>
            <value>10</value>
            </result>
            <result>
            <channel>Second channel</channel>
            <value>20</value>
            </result>
            </prtg>

To return an error, the XML format is:

              <prtg>
              <error>1</error>
              <text>Your error message</text>
              </prtg>

JSON Return Format: Minimum Example

{
  "prtg": {
   "result": [
    {
     "channel": "First channel",
     "value": "10"
    },
    {
     "channel": "Second channel",
     "value": "20"
    }
   ]
  }
}

To return an error, the JSON format is:

{
  "prtg": {
   "error": "1",
   "text": "Your error message"
  }
}

You can find a more detailed demo script for the EXE/Script Advanced sensor in the Custom Sensors\EXEXML subfolder of your PRTG installation. You will find demo files for other sensors in the Custom Sensors folder as well.

Advanced Script, HTTP Data, and REST Custom Sensors: Elements

You can optionally define the encoding of your XML file at the beginning of the document. For example, to define UTF-8, you would use:

<?xml version="1.0" encoding="UTF-8" ?>

The following elements can be used in the section between <result> and </result>. In each section, you can return one sensor channel. You may define a maximum of 50 sensor channels.

If you exceed this limit, PRTG will try to display all sensor channels. However, be aware that this is an unsupported procedure and you will experience limited usability and performance.

The tag names are not case-sensitive. For example, "VALUE" and "value" can both be used.

Tag (Case Insensitive)	Mandatory	Description	Possible Content
<Channel>	Yes	Name of the channel as displayed in user interfaces. This parameter is required and must be unique for the sensor.	Any string
<Value>	Yes	The value as integer or float. Make sure the <Float> setting matches the kind of value provided. Otherwise PRTG will show 0 values.	Integer or float value
<Unit>	No	The unit of the value. Default is Custom. This is useful for PRTG to be able to convert volumes and times.	BytesBandwidth BytesDisk Temperature Percent TimeResponse TimeSeconds Custom Count CPU: This is a % unit that is accounted to the CPU load in index graphs. BytesFile SpeedDisk SpeedNet TimeHours
<CustomUnit>	No	If Custom is used as unit, this is the text displayed behind the value.	Any string (keep it short)
<SpeedSize> <VolumeSize>	No	Size used for the display value. For example, if you have a value of 50000 and use Kilo as size, the display is 50 kilo #. Default is One (value used as returned). For the Bytes and Speed units, this is overridden by the setting in the user interface.	One Kilo Mega Giga Tera Byte KiloByte MegaByte GigaByte TeraByte Bit KiloBit MegaBit GigaBit TeraBit
<SpeedTime>	No	See above, used when displaying the speed. Default is Second.	Second Minute Hour Day
<Mode>	No	Select if the value is an absolute value or counter. Default is Absolute.	Absolute Difference
<Float>	No	Define if the value is a float. Default is 0 (no). If set to 1 (yes), use a dot as decimal separator in values. Define decimal places with the <DecimalMode> element.	0 (= no, integer) 1 (= yes, float)
<DecimalMode>	No	Init value for the Decimal Places option. If 0 is used in the <Float> element (use integer), the default is Auto; otherwise (for float) the default is All. You can change this initial setting later in the sensor's channel settings.	Auto All
<Warning>	No	If enabled for at least one channel, the entire sensor is set to "Warning" status. Default is 0 (no).	0 (= no) 1 (= yes)
<ShowChart>	No	Init value for the Show in graphs option. Default is 1 (yes). The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	0 (= no) 1 (= yes)
<ShowTable>	No	Init value for the Show in tables option. Default is 1 (yes). The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	0 (= no) 1 (= yes)
<LimitMaxError>	No	Define an upper error limit for the channel. If enabled, the sensor will be set to a "Down" status if this value is overrun and the LimitMode is activated. Provide the limit value in the unit of the base data type, just as used in the <Value> element of this section. While a sensor shows a "Down" status triggered by a limit, it will still receive data in its channels. The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Integer
<LimitMaxWarning>	No	Define an upper warning limit for the channel. If enabled, the sensor will be set to a "Warning" status if this value is overrun and the LimitMode is activated. Provide the limit value in the unit of the base data type, just as used in the <Value> element of this section. While a sensor shows a "Down" status triggered by a limit, it will still receive data in its channels. The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Integer
<LimitMinWarning>	No	Define a lower warning limit for the channel. If enabled, the sensor will be set to a "Warning" status if this value is undercut and the LimitMode is activated. Provide the limit value in the unit of the base data type, just as used in the <Value> element of this section. While a sensor shows a "Down" status triggered by a limit, it will still receive data in its channels. The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Integer
<LimitMinError>	No	Define a lower error limit for the channel. If enabled, the sensor will be set to a "Down" status if this value is undercut and the LimitMode is activated. Provide the limit value in the unit of the base data type, just as used in the <Value> element of this section. While a sensor shows a "Down" status triggered by a limit, it will still receive data in its channels. The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Integer
<LimitErrorMsg>	No	Define an additional message. It will be added to the sensor's message when entering a "Down" status that is triggered by a limit. The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Any string
<LimitWarningMsg>	No	Define an additional message. It will be added to the sensor's message when entering a "Warning" status that is triggered by a limit. The values defined with this element will be considered only on the first sensor scan, when the channel is newly created; they are ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Any string
<LimitMode>	No	Define if the limit settings defined above will be active. Default is 0 (no; limits inactive). If 0 is used the limits will be written to the sensor channel settings as predefined values, but limits will be disabled. This setting will be considered only on the first sensor scan, when the channel is newly created; it is ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	0 (= no) 1 (= yes)
<ValueLookup>	No	Define if you want to use a lookup file (for example, to view integer values as status texts). Enter the ID of the lookup file you want to use, or omit this element to not use lookups. This setting will be considered only on the first sensor scan, when the channel is newly created; it is ignored on all further sensor scans (and may be omitted). You can change this initial setting later in the sensor's channel settings.	Any string
<NotifyChanged>	No	If a returned channel contains this tag, it will trigger a change notification that you can use with the Change Trigger to send a notification.	No content required

The following elements can be used in the section between <prtg> and </prtg>, outside the <result> section.

The tag names are not case-sensitive. For example, "TEXT" and "text" can both be used.

Tag (Case Insensitive)	Mandatory	Description	Possible Content
<Text>	No	Text the sensor returns in the Message field with every scanning interval. There can be one message per sensor, regardless of the number of channels. Default is OK. This element has to be provided outside of the <result> element.	Any string; Maximum length: 2000 characters
<Error>	No	If enabled, the sensor will return an error status. This element can be combined with the <Text> element in order to show an error message. Default is 0. This element has to be provided outside of the <result> element. A sensor in this error status cannot return any data in its channels; if used, all channel values in the <result> section will be ignored.	0 (= no) 1 (= yes, set sensor to error; ignore <result> section)

Tag (Case Insensitive)

Mandatory

Description

Possible Content

<Text>

Text the sensor returns in the Message field with every scanning interval. There can be one message per sensor, regardless of the number of channels. Default is OK.

This element has to be provided outside of the <result> element.

Any string;

Maximum length: 2000 characters

<Error>

If enabled, the sensor will return an error status. This element can be combined with the <Text> element in order to show an error message. Default is 0.

This element has to be provided outside of the <result> element. A sensor in this error status cannot return any data in its channels; if used, all channel values in the <result> section will be ignored.

0 (= no)

1 (= yes, set sensor to error; ignore <result> section)

Each run (sensor scan) may return either any number of channels (<result>...</result>) or one error response. It is not possible to mix result and error entries.

You can either write the XML output to standard OUT line by line, or give back the entire expression in one line without breaks.

Interface Definition for DLL Sensors

Every time the sensor is to be checked, a function in 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 (for example, 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 conform to the same rules as the EXE exit code mentioned above.

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.

Command Line Parameters

In the parameter field you can use the following placeholders:

Placeholder	Description
%sensorid	The ID of the EXE/Script sensor.
%deviceid	The ID of the device the sensor is created on.
%groupid	The ID of the group the sensor is created in.
%probeid	The ID of the probe the sensor is created on.
%host	The IP address/DNS name entry of the device the sensor is created on.
%device	The name of the device the sensor is created on.
%group	The name of the group the sensor is created in.
%probe	The name of the probe the sensor is created on.
%name or %sensor	The name of the EXE/Script sensor.
%windowsdomain	The domain for Windows access (may be inherited from parent).
%windowsuser	The user name for Windows access (may be inherited from parent).
%windowspassword	The password for Windows access (may be inherited from parent).
%linuxuser	The user name for Linux access (may be inherited from parent).
%linuxpassword	The password for Linux access (may be inherited from parent).
%snmpcommunity	The community string for SNMP v1 or v2 (may be inherited from parent).

You need to escape special characters and whitespaces in your parameters and surround them with double quotes. See section Escape Special Characters and Whitespaces in Parameters for details. In Secure Shell (SSH) scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings.

See section Inheritance of Settings for more information on inherited settings.

Escape Special Characters and Whitespaces in Parameters

You need to escape special characters in parameters that you pass to an executable or script and surround them with quotation marks to make sure the characters are interpreted correctly. Especially PowerShell scripts require adequate escaping so that the parameters are passed in a valid PowerShell syntax. To make escaping easy and secure, PRTG automatically does most of the escaping for you.

Please follow these rules to escape special characters and whitespaces in the parameters fields:

Use quotes for parameters that contain whitespaces.

-name "Mr John Q Public"
-name 'Mr John Q Public'

Use double quotes for parameters that contain single quotes.

-name "Mr 'John Q' Public"

Use single quotes for parameters that contain double quotes.

-name 'Mr "John Q" Public'

Use a backslash (\) to escape and pass a literal double quote.

-name pub\"lic

Use double quotes for parameters that contain double and single quotes and escape double quotes.

-name "pu'b\"lic"

In Secure Shell (SSH) scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings.

We recommend that you do not pass passwords in parameters. Use PRTG placeholders instead. See section Custom Sensors for details.

Environment Values

If the Set placeholders as environment values option is enabled in the sensor's settings, the values of all placeholders available for command-line parameters are additionally provided as "Environment Variables" during runtime, so you can use them in your executable or script file. The variables' names are the same as for placeholders mentioned above, with the prefix prtg_ and without the % character. For example, refer to the sensor's own name by using the variable prtg_name.

Additionally, the following variables are available:

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 primary channel (1 if not set).

PRTG Script World

Find useful scripts for custom sensors in the PRTG Script World, written by dedicated PRTG customers around the world and Paessler!

You can find sample projects for these custom sensors and more information about custom scripts here:

In the PRTG Network Monitor\custom sensors\EXE subfolder of your PRTG installation.
In the Knowledge Base on the Paessler website at https://kb.paessler.com (tag custom-script-exe).
This Knowledge Base article will help you set up your PowerShell sensors: Guide for PowerShell Based Custom Sensors.

Application Programming Interface (API) Definition—Topics

Keywords: