<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: REST Custom Sensor

The REST Custom sensor queries a REST Application Programming Interface (API) endpoint and maps the JSON or XML result to sensor values. The mapping rule has to be available as a REST configuration file in JSON format according to the PRTG API definition for custom sensors.

  • The sensor can show values returned by a REST API in multiple channels.

icon-book-arrowsFor details about the return value format, see section Application Programming Interface (API) Definition.

REST Custom Sensor

REST Custom Sensor

Click here to enlarge: https://media.paessler.com/prtg-screenshots/REST_Custom.png

Remarks

  • The REST configuration file that contains the mapping rules must be stored on the system of the probe the sensor is created on: If used on a remote probe, the file must be stored on the system running the remote probe. In a cluster setup, please copy the file to every cluster node.
  • This sensor does not support more than 50 channels officially.
  • icon-betaCurrently, this sensor type is in beta status. The methods of operating can change at any time, as well as the available settings. Do not expect that all functions will work properly, or that this sensor works as expected at all. Be aware that this type of sensor can be removed again from PRTG at any time.

icon-prtg-on-demandYou cannot add this sensor type to cloud probes in PRTG in the cloud. If you want to use this sensor type, please add it to a remote probe device.

Limited to 50 Sensor Channels

icon-i-bluePRTG does not support more than 50 sensor channels officially. Depending on the data used with this sensor type, you might exceed the maximum number of supported sensor channels. In this case, PRTG will try to display all sensor channels. However, please be aware that you will experience limited usability and performance.

Add Sensor

The Add Sensor dialog appears when you manually add a new sensor to a device. It only shows the setting fields that are required for creating the sensor. Therefore, you will not see all setting fields in this dialog. You can change (nearly) all settings in the sensor's Settings tab later.

The following settings for this sensor differ in the Add Sensor dialog in comparison to the sensor's settings page.

REST Specific

REST Configuration

Select a REST configuration from the list. The sensor will use it to map the JSON or XML result from the REST query into sensor values.

Default is channelDiscovery. If you choose this REST configuration, the sensor will parse the returned JSON or XML and automatically create channels based on available values: one channel for each number and boolean, for strings if they are convertible into numbers.

This list shows all available files in the \Custom Sensors\rest sub-directory of the probe system's PRTG program directory (see Data Storage). To appear in this list, store the files in JSON format (*.json) into this folder.

To show the expected values and sensor status, your files must return the expected JSON format. Values and message must be embedded in valid JSON.

icon-book-arrowsFor detailed information on how to build custom sensors and for the expected return format, see the API documentation in your PRTG installation. There, find detailed information on the Custom Sensors tab. See also manual section Application Programming Interface (API) Definition for more information.

icon-i-roundThere are several REST configuration files available by default. They are ready to use. You can also analyze them to see how to write your own REST configuration.

icon-i-round-redWhen using custom sensors on the Cluster Probe, please copy your files to every cluster node installation.

Sensor Settings

On the details page of a sensor, click the Settings tab to change its settings.

icon-i-roundUsually, a sensor connects to the IP Address or DNS Name of the parent device where you created this sensor. See the Device Settings for details. For some sensor types, you can define the monitoring target explicitly in the sensor settings. Please see below for details on available settings.

Basic Sensor Settings

Sensor Name

Enter a meaningful name to identify the sensor. By default, PRTG shows this name in the device tree, as well as in alarms, logs, notifications, reports, maps, libraries, and tickets.

Parent Tags

Shows Tags that this sensor inherits from its parent device, group, and probe. This setting is shown for your information only and cannot be changed here.

Tags

Enter one or more Tags, separated by spaces or commas. You can use tags to group sensors and use tag–filtered views later on. Tags are not case sensitive. We recommend that you use the default value.

You can add additional tags to the sensor if you like. Other tags are automatically inherited from objects further up in the device tree. These are visible above as Parent Tags.

Priority

Select a priority for the sensor. This setting determines where the sensor is placed in sensor lists. Top priority is at the top of a list. Choose from one star (low priority) to five stars (top priority).

REST Specific

Timeout (Sec.)

Enter a timeout in seconds for the request. If the reply takes longer than this value defines, the sensor will cancel the request and show a corresponding error message. Please enter an integer value. The maximum value is 900 seconds (15 minutes).

Request Method

Choose an HTTP request method to determine how the sensor will request the REST API.

  • GET (default): Use the GET method to request the REST API.
  • POST: Use the POST method to request the REST API.

Request Protocol

Define the security of the HTTP request. Choose between:

  • HTTP (default): Send the REST query via insecure HTTP.
  • HTTPS: Send the REST query via secure HTTPS.

Authentication Method

Select the authentication method for access to the REST API. Choose between:

  • No authentication (default): Do not use any authentication for the request.
  • Basic authentication: Use simple username and password authentication.
  • Token: Use a JSON Web Token (JWT) or OAuth2 Bearer Token for authentication.

User

This field is only visible if you enable basic authentication above. Enter a username for the REST API. Please enter a string.

Password

This field is only visible if you enable basic authentication above. Enter a password for the REST API. Please enter a string.

Token

This field is only visible if you enable token authentication above. Enter a JWT or OAuth2 Bearer Token that is required by the REST API for authentication.

HTTP Headers

Define if you want to send custom HTTP headers to the target URL. Choose between:

  • Do not use custom HTTP headers
  • Use custom HTTP headers

Custom HTTP Headers

This field is only available if you select using custom headers above. Enter a list of custom HTTP headers with theirs respective values that you want to transmit to the URL you define above, each pair in one line. The syntax of a header-value pair is header1:value1

icon-i-redThe sensor does not support the header field names user-agent, content-length, host.
 

icon-i-redEnsure the HTTP header statement is valid! Otherwise, the sensor request will not be successful.

REST Query

This field shows the REST query that this sensor executes. To change it, enter a valid query for the target REST API. The syntax is: [port:]/path[?var1=val1&...]