<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> 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.

i_round_redThe multi-platform probe currently does not support all custom sensor types. For more information, see the Knowledge Base: What is the multi-platform probe and how can I use it?

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.

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

i_round_blueFor 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

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

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

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

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

i_round_blueEXE 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

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

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

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

i_speechExample

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

i_round_redValue 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

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

i_speechExamples

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"
          }
         }

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

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

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

i_round_redThis parameter is required and must be unique for the sensor.

Any string

<Value>

Yes

The value as integer or float.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Any string

Maximum length: 2000 characters

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

i_round_redThis 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)

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

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

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

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

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

More

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

 

i_square_blueKNOWLEDGE BASE

Custom sensors

Guide for PowerShell-based custom sensors

What is the multi-platform probe and how can I use it?

 

i_square_bluePAESSLER WEBSITE

You can find scripts for custom sensors that were written by dedicated PRTG customers in the PRTG Sensor Hub.