PRTG Manual: REST Custom v2 Sensor
The REST Custom v2 sensor queries a JavaScript Object Notation (JSON) or Extensible Markup Language (XML) Representational State Transfer (REST) application programming interface (API) endpoint and maps the JSON or XML result to sensor values.
This sensor is in beta status. The operating methods and the available settings are still subject to change. Do not expect that all functions work properly, or that this sensor works as expected at all.
For a detailed list and descriptions of the channels that this sensor can show, see section Channel List.
- Dutch: REST Aangepast v2
- French: REST personnalisé v2
- German: REST (Benutzerdefiniert) v2
- Japanese: REST カスタム v2
- Portuguese: REST (customizado) v2
- Russian: Специальные настройки REST v2
- Simplified Chinese: REST 自定义 v2
- Spanish: REST (personalizado) v2
Consider the following remarks and requirements for this sensor:
Remark |
Description |
---|---|
Enabled Beta Sensors experimental feature |
This sensor requires that the Beta Sensors experimental feature is enabled.
|
JSONPath and XPath version |
This sensor supports JSONPath and XPath 1.0. |
Smart URL replacement |
This sensor supports smart URL replacement. |
IPv6 |
This sensor supports IPv6. |
Performance impact |
This sensor has a very low performance impact. |
Lookups |
This sensor uses lookups to determine the status values of one or more channels. |
Credentials |
You can define credentials for REST API in settings that are higher in the object hierarchy. |
Multi-platform probe |
You can add this sensor to a multi-platform probe. |
- Strings that contain angled brackets (< and >) cannot be mapped manually. This affects the following settings: Channel #x Strings mapped to the 'Up' status, Channel #x Strings mapped to the 'Warning' status, and Channel #x Strings mapped to the 'Down' status. We are already working on a solution.
Setting |
Description |
---|---|
Channel #2 - #10 |
You can define up to 10 channels. You must define at least one channel, so you see all available settings for Channel #1. Specify how to handle all other possible channels:
|
Channel #x JSONPath/XPath |
Enter the JSONPath or XPath of the JSON or XML result that you want to monitor. JSONPath example: $.store.book[0].year XPath example: /store/book[1]/year |
Channel #x Name |
Enter a name for the channel. Enter a string. For example, Total.
|
Channel #x Unit |
Enter the unit for the value that this sensor monitors. For example, #.
|
The sensor has the following default tags that are automatically predefined in the sensor's settings when you add the sensor:
- rest
For more information about basic sensor settings, see section Sensor Settings.
Setting |
Description |
---|---|
Request URL |
Enter the URL of the JSON or XML REST API endpoint that you want to request. Example URL: https://:1616/api/health?token=%restbearertoken&name=%restusername&refresh=true
https://127.0.0.1:1616/api/health?token=%restbearertoken&name=%restusername&refresh=true |
Request Method |
Select the HTTP request method that the sensor uses to request the REST API:
|
POST Body |
This setting is only visible if you select POST above. Enter the data part for the POST request.
|
Custom Headers |
Enter a list of custom HTTP headers with their respective values that you want to transmit to the target URL. The syntax of a header-value pair is header1:value1. Custom header example: host:host1.example.com
|
Timeout (Sec.) |
Enter a timeout in seconds for the request. Enter an integer. The maximum timeout value is 900 seconds (15 minutes).
|
Content Type |
Select the type of the content that the sensor queries:
|
Custom Sensor Message |
Enter the JSONPath or XPath from which you want to receive a string that the sensor shows as the permanent sensor message. JSONPath example: $.store.book[0].title XPath example: /store/book[1]/title |
Setting |
Description |
---|---|
Channel #x JSONPath/XPath |
Enter the JSONPath or XPath of the JSON or XML result that you want to monitor. JSONPath example: $.store.book[0].year XPath example: /store/book[1]/year |
Channel #x Name |
Enter a name for the channel. Enter a string. For example, Total. PRTG dynamically generates channels with this name as the identifier.
|
Channel #x Value Type |
Select the value type that the channel displays:
|
Channel #x Unit |
This setting is only visible if you select Absolute (integer), Absolute (float), or Delta (counter) as Channel #x Value Type. Select the unit that the channel displays:
|
Channel #x Custom Unit |
This setting is only visible if you select Custom (default) as Channel #x Unit. Enter the custom unit of the value of this channel. Enter a string. |
Channel #x Strings mapped to the 'Up' status |
This setting is only visible if you select Status (string) as Channel #x Value Type. Enter the strings that the sensor maps to the Up status in a comma-separated list.
|
Channel #x Strings mapped to the 'Warning' status |
This setting is only visible if you select Status (string) as Channel #x Value Type. Enter the strings that the sensor maps to the Warning status in a comma-separated list.
|
Channel #x Strings mapped to the 'Down' status |
This setting is only visible if you select Status (string) as Channel #x Value Type. Enter the strings that the sensor maps to the Down status in a comma-separated list.
|
Channel #x Handling of Unknown Strings |
This setting is only visible if you select Status (string) as Channel #x Value Type. Select the status to which the sensor maps all unknown strings in the returned result that are not manually mapped to the Up, the Warning, or the Down status:
|
Channel #x Lookup ID |
This setting is only visible if you select Lookup as Channel #x Value Type. Enter the ID of the lookup you wish to use. You can find the ID in the ValueLookup parameter in the lookup file.
|
Channel #2 - #10 |
You can define up to 10 channels. You must define at least one channel, so you see all available settings for Channel #1. Specify how to handle all other possible channels:
|
Setting |
Description |
---|---|
Primary Channel |
Select a channel from the list to define it as the primary channel. In the device tree, PRTG displays the last value of the primary channel below the sensor's name. The available options depend on what channels are available for this sensor.
|
Graph Type |
Define how this sensor shows different channels:
|
Stack Unit |
This setting is only visible if you select Stack channels on top of each other above. Select a unit from the list. PRTG stacks all channels with this unit on top of each other. By default, you cannot exclude single channels from stacking if they use the selected unit. However, there is an advanced procedure to do so. |
Setting |
Description |
---|---|
Result Handling |
Define what PRTG does with the sensor result:
|
By default, all of these settings are inherited from objects that are higher in the hierarchy. We recommend that you change them centrally in the root group settings if necessary. To change a setting for this object only, click under the corresponding setting name to disable the inheritance and to display its options.
For more information, see section Inheritance of Settings.
The REST Custom v2 sensor uses JSONPath to assign values from the returned JSON to channels. With JSONPath, you provide the path to the value in the JSON source that you want to monitor in a channel.
The JSONPath implementation that PRTG uses for the REST Custom v2 sensor might differ from other JSONPath implementations. To test simple JSONPath expressions and calculations, you can use JSONPath Online Evaluator - jsonpath.com, for example. Note that this tool might not work properly with complex JSONPath expressions that PRTG supports.
To demonstrate the practical usage of JSONPath, we use this JSON example that a REST query might have returned as reference in this section. { |
Root |
The dollar sign ($) matches the root element of the JSON data. |
Child |
You can match a child with .<key> or [<key>].
This expression matches 35985021 in the example above: $.devices.0.networks.a.rx_bytes You get the same result with this expression: $["devices"][0]["networks"]["a"]["rx_bytes"] If an element contains a hyphen (-), the .<key> notation does not work. Use the [<key>] notation in this case: $["data"][0]["system-stats"]["temps"]["Board (CPU)"] |
Wildcard |
To match multiple values, you can use the asterisk symbol (*).
This expression matches 35985021 and 40085321 in the example above: $.devices[0].networks.*.rx_bytes |
Recursive Descent |
You can match all subitems of a node with two dots (..).
This expression matches 7229493 and 55294975 and 7229472 in the example above: $..tx_bytes |
Union |
You can match multiple children with [<key1>,<key2>,<...>].
This expression matches 35985021 and 7229493 in the example above: $.devices.0.networks.a["rx_bytes","tx_bytes"] |
Slice |
You can match multiple children of an array with [<begin>:<end>] or [<begin>:<end>:<step>].
This expression matches 63685865 and 7229472 in the example above: $.devices[-1:].networks.a[rx_bytes,tx_bytes] |
Current |
The @ symbol matches the current element.
This expression matches 63685865 and 7229472 in the example above: $.devices[(@.length-1)].networks.a.rx_bytes |
Filter |
You can filter matches with [?<expression>].
This expression matches 35985021 in the example above because the first device is the only one with a beta channel: $.devices[?(@.firmware.channel=="beta")].networks.a.rx_bytes |
Constant |
|
Functions |
You can use functions on top level or in filters. This expression returns the number items in the element devices in the example above: length($.devices)
|
Operator |
|
For more information about JSONPath, see JsonCons JSONPath.
To demonstrate the practical usage of XPath, we use this XML example that a REST query might have returned as reference in this section. <?xml version="1.0" encoding="UTF-8" ?> |
Root |
The slash symbol (/) matches the root element of the XML data. |
Child |
You can match a child by its name with /<key> or [<key>] or by its index with [<index>].
This expression matches 35985021 in the example above: /root/devices[1]/networks/a/rx_bytes This expression matches major in the example above: /root/devices[1]/firmware/id[1]/@type |
Wildcard |
To match multiple values, you can use the asterisk symbol (*).
This expression matches 35985021 and 40085321 in the example above: /root/devices[1]/networks/*/rx_bytes |
Recursive Descent |
You can match all subitems of a node with two slashes (//).
This expression matches 7229493 and 55294975 and 7229472 in the example above: //tx_bytes |
Union |
You can match multiple queries by combining them with the vertical bar symbol (|).
This expression matches 35985021 and 7229493 in the example above: /root/devices[1]/networks/a/rx_bytes | /root/devices[1]/networks/a/tx_bytes |
Filter |
You can filter matches with [<expression>].
This expression matches 35985021 in the example above because the first device is the only one with a beta channel: /root/devices[firmware/channel='beta']/networks/a/rx_bytes This expression matches 0 in the example above: /root/devices[1]/firmware[1]/id[@type='major'] |
Constant |
|
Functions |
You can use functions on top level or in filters. This expression returns the number of items in the devices element in the example above: count(/root/devices[position() < 3])
|
Operator |
|
For more information about XPath, see XML Path Language (XPath).
The REST Custom v2 sensor supports the following arithmetic:
- Addition (+)
- Subtraction (-)
- Multiplication (*)
- Division (div, /)
- Equal (=)
- Not equal (!=)
|
XML |
JSON |
Description |
Result (XML) |
Result (JSON) |
---|---|---|---|---|
/root/one + /root/two |
eval($.root.one + $.root.two) |
Addition of the numbers |
3 |
3 |
n/a |
eval($.root.one + to_number($.root.two_string)) |
Addition of a number and a string |
n/a |
3 |
/root/one + /root/two/@value_int |
n/a |
Addition of a number and an attribute value |
3 |
n/a |
/root/four div /root/two |
eval($.root.four / $.root.two) |
Division of two integers. The expected result is an integer |
2 |
2 |
/root/one div /root/two |
eval($.root.one / $.root.two) |
Division of two integers, the expected result is a floating-point number |
0.5 |
0 |
n/a |
eval($.root.one / $.root.two * 1.0) |
Division of two integers with a floating point number as result |
n/a |
0.5 |
/root/one div /root/two_point5 |
eval($.root.one / $root.two_point5) |
Division of a float and an integer |
0.4 |
0.4 |
/root/one = /root/two |
eval($.root.one == $.root.two) |
If entries are equal |
0 (false) |
0 (false) |
Instead of entering a complete address in the Request URL field of the REST Custom v2 sensor, you can only enter the protocol followed by a colon and three forward slashes (this means that you can enter either http:/// or https:///, or even a simple forward slash / as the equivalent for http:///). PRTG automatically fills in the parent device's IP Address/DNS Name in front of the third forward slash.
Whether this results in a valid URL or not depends on the IP address or Domain Name System (DNS) name of the parent device. In combination with cloning devices, you can use smart URL replacement to create many similar devices.
For example, if you create a device with the DNS name www.example.com and you add a REST Custom v2 sensor to it, you can provide values in the following ways:
- If you enter https:/// in the Request URL field, PRTG automatically creates the URL https://www.example.com/
- If you enter /help in the Request URL field, PRTG automatically creates the URL http://www.example.com/help
- It is also possible to provide a port number in the Request URL field. It is taken over by the device's DNS name and is internally added, for example, https://:1616/
Smart URL replacement does not work for sensors that run on the probe device.
Which channels the sensor actually shows might depend on the target device, the available components, and the sensor setup.
Channel |
Description |
---|---|
Downtime |
In the channel table on the Overview tab, this channel never shows any values. PRTG uses this channel in graphs and reports to show the amount of time in which the sensor was in the Down status |
HTTP Status |
The HTTP status that the requested URL returns
|
[Value] |
The values that a REST API returns in several channels |
KNOWLEDGE BASE
What are beta sensors and how can I use them?
What security features does PRTG include?
Can I create a sensor to monitor the number of paused or unknown sensors?
MISCELLANEOUS
JSONPath Online Evaluator
JsonCons JSONPath
Stefan Gössner JSONPath