Advanced Topics > Application Programming Interface (API) Definition

Previous Next

PRTG Manual: Custom Sensors

Custom sensors can perform a number of monitoring tasks that extend the standard sensor set. Apart from parameterized versions of Simple Network Management Protocol (SNMP), Packet Sniffer, and NetFlow sensors, you can create your own sensors using Windows Management Instrumentation Query Language (WQL) or Python, by compiling an .exe file, using any Windows software development tool, and you can request any Representational State Transfer (REST) application programming interface (API) that returns JavaScript Object Notation (JSON) or Extensible Markup Language (XML) and map the results to channels.

The multi-platform probe currently does not support all custom sensor types. For more information, see the Multi-Platform Probe for PRTG (PDF) manual.

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, Windows Management Instrumentation (WMI), Packet Sniffing, and Flow (NetFlow, jFlow, sFlow, IPFIX), see the respective custom sensors.

For each sensor interval, PRTG can run an external process. The process can be a Windows .exe file, or a .bat, .cmd, .vbs, or PowerShell file, as well as a Python or Secure Shell (SSH) script.

In this section:

Standard and Advanced EXE/Script Sensor

You must create the sensor as a file and store it in a specific subfolder on the probe system. In a cluster, you must store it on each cluster node.

Place executables (.exe), batch files (.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 the PRTG program directory:

Custom Sensors\EXE

If your executable or script returns XML or JSON, you 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 find a sample set of demo sensors in these subfolders, too. As soon as a file is placed into the subfolders mentioned above, you can create your own custom EXE sensor and select the new file from the list of files.

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

If you use a PowerShell script (.ps1) and if the PowerShell Security Enhancement experimental feature is enabled, scripts that use the write-host cmdlet to provide their output to PRTG do not work. Use the write-output cmdlet instead.

We recommend that you not edit the demo files. Create your own new files and make sure to give them unique names that do not start with Demo, for example.

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

EXE sensors 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 directory on the target system running your Linux/Unix installation where the script is 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 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 directory, you can create your own SSH script sensor and select the new script file from the list of scripts.

With each scanning interval, PRTG executes the script on the target system and receives 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 executable file 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 that you want to use for the sensor via the command line (cmd.exe). To do so, 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 are 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.

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 expects 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 is 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 executable file 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)

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 the PRTG program directory. You 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" ?>

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

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

For XML output, the tag names are not case-sensitive. For example, you can use both "VALUE" and "value". For JSON output, the tag names are case-sensitive but you can also use lowercase. For example, you can use both "CustomUnit" and "customunit".

Tag	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 shows 0 values.	Integer or float value
<Unit>	No	The unit of the value. The default is Custom. This is useful for PRTG 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 #. The 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. The default is Second.	Second Minute Hour Day
<Mode>	No	Select if the value is an absolute value or counter. The default is Absolute.	Absolute Difference
<Float>	No	Define if the value is a float. The 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 the Warning status. The default is 0 (no).	0 (= no) 1 (= yes)
<ShowChart>	No	Init value for the Show in graphs option. The default is 1 (yes). The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can 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. The default is 1 (yes). The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can 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 is set to the Down status if this value is exceeded and the LimitMode is activated. Provide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section. When a sensor shows the Down status triggered by a limit, it still receives data in its channels. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can be omitted). You can change this initial setting later in the sensor's channel settings.	String with numbers
<LimitMaxWarning>	No	Define an upper warning limit for the channel. If enabled, the sensor is set to the Warning status if this value is exceeded and the LimitMode is activated. Provide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section. When a sensor shows the Down status triggered by a limit, it still receives data in its channels. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can be omitted). You can change this initial setting later in the sensor's channel settings.	String with numbers
<LimitMinWarning>	No	Define a lower warning limit for the channel. If enabled, the sensor is set to the Warning status if this value falls below the defined limit and the LimitMode is activated. Provide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section. When a sensor shows the Down status triggered by a limit, it still receives data in its channels. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can be omitted). You can change this initial setting later in the sensor's channel settings.	String with numbers
<LimitMinError>	No	Define a lower error limit for the channel. If enabled, the sensor is set to the Down status if this value falls below the defined limit and the LimitMode is activated. Provide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section. When a sensor shows the Down status triggered by a limit, it still receives data in its channels. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can be omitted). You can change this initial setting later in the sensor's channel settings.	String with numbers
<LimitErrorMsg>	No	Define an additional message. It is added to the sensor's message when entering the Down status that is triggered by a limit. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can be omitted). You can change this initial setting later in the sensor's channel settings.	Any string
<LimitWarningMsg>	No	Define an additional message. It is added to the sensor's message when entering the Warning status that is triggered by a limit. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can 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 are active. The default is 0 (no; limits inactive). If 0 is used, the limits are written to the channel settings as predefined values, but limits are disabled. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can 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 integers as status texts). Enter the ID of the lookup file that you want to use, or omit this element to not use lookups. The values defined with this element are only considered during the first sensor scan when the channel is newly created. They are ignored on all further sensor scans (and can 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 triggers a change notification that you can use with the change trigger to send a notification.	No content required

You can use the following elements in the section between <prtg> and </prtg>, outside the <result> section.

For XML output, the tag names are not case-sensitive. For example, you can use both "TEXT" and "text". For JSON output, the tag names are case-sensitive but you can also use lowercase. For example, you can use both "Text" and "text".

Tag	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. The default message is OK. This element has to be provided outside of the <result> element.	Any string Maximum length: 2000 characters PRTG does not support the number sign (#) in sensor messages. If a message contains a number sign, PRTG clips the message at this point.
<Error>	No	If enabled, the sensor returns the Down status. This element can be combined with the <Text> element to show an error message. The 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 are ignored.	0 (= no) 1 (= yes, set sensor to error; ignore <result> section)

Tag

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. The default message is OK.

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

Any string

Maximum length: 2000 characters

PRTG does not support the number sign (#) in sensor messages. If a message contains a number sign, PRTG clips the message at this point.

<Error>

If enabled, the sensor returns the Down status. This element can be combined with the <Text> element to show an error message. The 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 are ignored.

0 (= no)

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

Each run (sensor scan) might 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.

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 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	The name of the EXE/Script sensor.
%windowsdomain	The domain for Windows access (can be inherited from parent).
%windowsuser	The user name for Windows access (can be inherited from parent).
%windowspassword	The password for Windows access (can be inherited from parent).
%linuxuser	The user name for Linux access (can be inherited from parent).
%linuxpassword	The password for Linux access (can be inherited from parent).
%snmpcommunity	The community string for SNMP v1 or v2 (can be inherited from parent).

You need to escape placeholders that you use in the parameter field with quotation marks so that they can be correctly resolved from the command line.

You need to escape special characters and whitespaces in your parameters and surround them with double quotation marks ("). See section Escape Special Characters and Whitespaces in Parameters for details.

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

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