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

icon-book-arrowsFor more information about custom sensors based on SNMP, Windows Management Instrumentation (WMI), Packet Sniffing, and xFlow (NetFlow, jFlow, sFlow, IPFIX), see the respective custom sensors.

icon-i-roundFor 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 Secure Shell (SSH) script.

Here are quick links for ease of use.

Standard and Advanced EXE/Script Sensor

icon-i-round-redYou must create the sensor as a file and place it in a specific folder on the probe system. 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), 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 your 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 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 then executes the file on the probe system using the account configured for the PRTG probe service ("system" is the default). The local probe runs the file on the local PRTG core server system. For remote probes, the file actually runs on the remote system.

icon-i-blueIf your custom sensor code relies on other files (for example, .dll files, .NET framework, Windows PowerShell) you must manually copy or install these files on the probe machine.

icon-i-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

icon-i-round-redYou 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 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 folder, you can create your own SSH script sensor and select the new script file from the list of scripts.

icon-i-roundWith 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.

icon-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). Just start the .exe file and pipe the results into a file.

icon-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 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 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

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

Standard SSH Script Sensor

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

returncode:value:message

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

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

icon-i-roundYou can find a more detailed demo script for the EXE/Script Advanced sensor in the Custom Sensors\EXEXML subfolder of your PRTG installation. 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" ?>

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.

icon-i-round-redIf you exceed this limit, PRTG tries to display all sensor channels. However, be aware that this is an unsupported procedure and you experience limited usability and performance.

icon-i-roundFor XML output, the tag names are not case-sensitive. For example, "VALUE" and "value" can both be used. For JSON output, the tag names are case-sensitive but lowercase can also be used. For example, "CustomUnit" and "customunit" can both be used.

Tag

Mandatory

Description

Possible Content

<Channel>

Yes

Name of the channel as displayed in user interfaces.

icon-i-round-redThis parameter is required and must be unique for the sensor.

Any string

<Value>

Yes

The value as integer or float.

icon-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 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 #.

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.

icon-i-roundDefine 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.

icon-i-roundYou 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. The default is 0 (no).

0 (= no)

1 (= yes)

<ShowChart>

No

Init value for the Show in graphs option. The default is 1 (yes).

icon-i-roundThe 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 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. The default is 1 (yes).

icon-i-roundThe 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 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 is set to a Down status if this value is overrun and the LimitMode is activated.

icon-i-roundProvide 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 still receives data in its channels.

icon-i-roundThe 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 may be omitted). You can change this initial setting later in the sensor's channel settings.

String with numbers, surrounded by quotation marks (")

<LimitMaxWarning>

No

Define an upper warning limit for the channel. If enabled, the sensor is set to a Warning status if this value is overrun and the LimitMode is activated.

icon-i-roundProvide 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 still receives data in its channels.

icon-i-roundThe 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 may be omitted). You can change this initial setting later in the sensor's channel settings.

String with numbers, surrounded by quotation marks (")

<LimitMinWarning>

No

Define a lower warning limit for the channel. If enabled, the sensor is set to a Warning status if this value is undercut and the LimitMode is activated.

icon-i-roundProvide 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 still receives data in its channels.

icon-i-roundThe 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 may be omitted). You can change this initial setting later in the sensor's channel settings.

String with numbers, surrounded by quotation marks (")

<LimitMinError>

No

Define a lower error limit for the channel. If enabled, the sensor is set to a Down status if this value is undercut and the LimitMode is activated.

icon-i-roundProvide 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 still receives data in its channels.

icon-i-roundThe 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 may be omitted). You can change this initial setting later in the sensor's channel settings.

String with numbers, surrounded by quotation marks (")

<LimitErrorMsg>

No

Define an additional message. It is added to the sensor's message when entering a Down status that is triggered by a limit.

icon-i-roundThe 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 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 is added to the sensor's message when entering a Warning status that is triggered by a limit.

icon-i-roundThe 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 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 are active. The default is 0 (no; limits inactive). If 0 is used, the limits are written to the sensor channel settings as predefined values, but limits are disabled.

icon-i-roundThe 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 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 that you want to use, or omit this element to not use lookups.

icon-i-roundThe 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 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 triggers 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.

icon-i-roundFor XML output, the tag names are not case-sensitive. For example, "TEXT" and "text" can both be used. For JSON output, the tag names are case-sensitive but lowercase can also be used. 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. The default is OK.

icon-i-round-redThis element has to be provided outside of the <result> element.

Any string

Maximum length: 2000 characters

icon-i-blueThe number sign (#) is not supported in sensor messages. If a message contains a number sign, the message is clipped at this point.

<Error>

No

If enabled, the sensor returns an error status. This element can be combined with the <Text> element to show an error message. The default is 0.

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

icon-i-roundEach 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.

icon-i-roundYou 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 file 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 file 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 is used as the resulting value for this sensor (for example, bytes, milliseconds, etc.), message can be any string and is stored in the database.

icon-i-round-redThe integer return value of the perform function has to conform to the same rules as the EXE exit code mentioned above.

icon-i-redIf the function call in the .dll file 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

The name of the EXE/Script sensor.

%windowsdomain

The domain for Windows access (may be inherited from parent).

%windowsuser

The username for Windows access (may be inherited from parent).

%windowspassword

The password for Windows access (may be inherited from parent).

%linuxuser

The username 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).

icon-i-round-redYou 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 SSH scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings.

icon-book-arrowsSee section Inheritance of Settings for more information on inherited settings.

Escape Special Characters and Whitespaces in Parameters

icon-toolsYou need to escape special characters in parameters that you pass to an executable or script and surround them with quotation marks to make sure that the characters are correctly interpreted. PowerShell scripts in particular 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.

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 SSH scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings.

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

PRTG Script World

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

More

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

Knowledge Base: Custom sensors

Knowledge Base: Guide for PowerShell-based Custom sensors

Application Programming Interface (API) Definition—Topics

Keywords: