<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: Mini Probe API
|
We do not further develop the Mini Probe API because we plan major changes to the underlying PRTG Application Programming Interface (PRTG API). You can still use the Mini Probe API "as is" but note that it may be deprecated at any time.
Knowledge Base: Where can I find PRTG mini probes which are ready to use?
|
Mini probes allow users to create small probes on any device to meet specific needs. In general, probes are the part of PRTG that run monitoring processes and deliver monitoring results back to the PRTG core server. Mini probes gather monitoring data from platforms where it is not possible or is inapplicable to use the common local and remote probes of PRTG. Mini probes have a less complex implementation than standard probes so that you can create them on any platform. The only requirement is HTTPS connectivity to send monitoring data to your PRTG core server.
With the current version of PRTG, you can use the mini probe interface with your custom code to implement solutions to special scenarios that you might have in your network. Note that there are major changes planned to the underlying PRTG API. Therefore, any code you write now likely needs to be changed later, so it can be used for future versions of PRTG. For example, if the available HTTP Push sensors are not sufficient for your needs, you can still use the Mini Probe API.
Because the mini probe requires a Secure Sockets Layer (SSL) secured connection to the PRTG core server, it is not possible by default to connect if SSL is deactivated for PRTG. This is necessary because probably unencrypted passwords are transferred between the probe and the PRTG core server. So it is important to encrypt the connection even on internal routes. If your network setup ensures security in a different way (for example, a VPN), you can use a registry key option for disabling SSL to get a connection to your mini probe.
For more details, see the Knowledge Base: How can I disable SSL for Mini Probes?
The Mini Probe API is not available in PRTG Hosted Monitor
In this section:
Differences Between Probe Types
The following table shows technical specifications of the two probe types in PRTG.
|
|
|
Connection Protocol from Probe to PRTG Core Server
|
Protocol from PRTG
|
HTTPS
|
Security
|
Data is secured with SSL and an access key. New probe connections must be approved by an administrator. IP address and globally unique identifier (GUID) filtering is possible.
|
The same security level as for local and remote probes.
|
Estimated Limit for Sensors per Probe
|
Several thousand sensors
|
Fewer than 100 sensors
|
Estimated Limit for Probes per Installation
|
Hundreds of probes
|
Fewer than 100 probes
|
Estimated Minimum Scanning Interval
|
Some seconds
|
At least 60 seconds
|
Estimated Number of Sensors
|
More than 200
|
A few
|
Updates to New PRTG Versions by the PRTG Core Server
|
Yes
|
No
|
Complexity
|
High
|
Very low
|
Documented API
|
No
|
Yes
|
Supported Platforms
|
Windows 7 or later (32-bit/64-bit)
|
Any platform
|
Scheduling of Sensor Requests Performed by
|
Probe
|
Probe
|
Code Managed by
|
Paessler AG
|
Writer of the probe
|
Probe Scans for Available Measurements Beforehand
|
Yes
|
No
|
Sensors Support Inheritance of Settings
|
Yes
|
No
|
Limitations by Administrator for Allowed Sensors that a User Can Create
|
Yes
|
No
|
The PRTG Mobile Probe Protocol
The PRTG Mini Probe Protocol (PMPP) is a simple, lightweight protocol that extends PRTG with custom remote probes. It can be implemented in a variety of programming languages and runs on any kind of platform. These include, for example, Linux, Android, macOS, and iOS.
Mini probes are not intended for high performance monitoring and support only the sensors that you implement.
Communication and Security
The PMPP uses GET and POST requests via HTTPS to communicate with the PRTG core server. All requests are sent to the defined Transmission Control Protocol (TCP) port for the common PRTG web server (the default is 443 for SSL), or you specify an extra port explicitly for mini probe connections in the Core & Probes settings. Mini probes use the GET method to receive tasks, and the POST method to send information about the probe and the monitoring results to the PRTG core server.
The data format of some HTTP fields has to be JavaScript Object Notation (JSON) encoded. See JSON Definition for data definitions that require JSON. All exchanged data is secured with SSL.
Authentication
The PMPP uses the same authentication methods as the common remote probes in PRTG. The authentication includes the following steps:
- Allow and deny IPs filter
- Deny global ID (GID) filter
- Access key
- Unique GID that must be approved in the PRTG web interface
- In addition, mini probes must be allowed to connect in the probe connection settings in PRTG. Additionally, you must provide the mini probe's IP address in the Allow IP Addresses field (or enter any).
There are no sessions on the server: Every request must contain the required authentication information.
For more details, see section Core & Probes.
HTTP Requests
The PMPP includes three different HTTP requests that are sent to the PRTG web server:
- announce: An announce request is sent once when the probe starts. Afterward, the task and data commands are run in a scheduled manner.
- tasks: With a tasks request, the probe requests a list of tasks to perform.
- data: The data request sends the monitoring results to the core.
All requests of the mini probe to the PRTG core server must contain the following HTTP fields:
- gid: The unique GID of the probe. We recommend a GUID that is generated by the operating system. This identifier must stay the same for as long as the probe installation exists. You can use any string. If you clone a probe, you must update this field to a new value.
- key: An access key as defined in the probe settings of the PRTG core server. The key has to be encoded in SHA1 hash (for example, key=a94a8fe5ccb19ba61c4c0873d391e987982fbbd3).
- protocol: The version of the protocol you use. Currently, this value is "1"
All requests return common HTTP response codes.
For more information, see section HTTP API.
Announce Request
The announce request uses the POST method and provides all required information about the capabilities of the mini probe for the PRTG core server. The target URL is https://<yourPRTGserver>/probe/announce.
This HTTP request must be sent at least once to be able to add sensors. We recommend you send this request every time the probe starts. You should NOT send it with every scanning interval.
The announce request must contain the following HTTP fields:
- name: The name of the mini probe. PRTG uses this name to create a corresponding node in the device tree.
- version: The version number of the mini probe you have implemented. This is a single integer, for example, 1.
- baseinterval: The number of seconds between two calls of the task/data requests. We recommend 60 or 300 seconds. Depending on the usage, higher or lower values are possible.
- sensors: The definition of supported sensors in JSON format.
See Sensor Definition for more information.
- icon (optional): You can optionally send the file name of a device icon to show it for the mini probe device in the PRTG web interface.
If you change the definition of a sensor that has already been announced, these changes are only active after the next start of PRTG. A definition never changes while PRTG is running. However, there is one exception: Setting the "deprecated" flag works without any restart. Because of this, you can replace a sensor with a new one that uses a different definition.
Tasks Request
The tasks request uses the GET method and is sent from your mini probe in the defined scheduler interval to the PRTG core server (for example, every 5 minutes). The target URL is
https://<PRTGserver>/probe/tasks
This HTTP request returns a list of tasks in JSON format that need to be run by the mini probe.
See Tasks Definition for more information.
Data Request
The data request uses the POST method and contains the HTTP field data. This HTTP field contains any number of sensor results in JSON format. The target URL is
https://<PRTGserver>/probe/data
You can split the results of one tasks list into several result requests (for example, if some sensors are faster than others). The mini probe should combine as many results as possible into one request but keep the time between measurement and reporting of the value at a low level.
See Data Definition for more information.
JSON Definition
All data definitions of sensors, tasks, and result data of mini probes are JSON encoded. JSON is a language-independent data format that is used to transmit data objects consisting of attribute-value pairs between a server and an application. Refer to the JSON documentation for a general overview of this data format.
Sensor Definition
This section shows how you can define the available sensors for your mini probe. Sensor definitions are specified in the HTTP field "sensors" of the announce request. The sensor types definition is a JSON array where each sensor type is defined in one array element as a JSON object. A JSON object denoting a sensor definition consists of the following JSON name/value pairs:
|
|
|
|
kind
|
X
|
Unique identifier for the sensor type in the mini probe. Used in the tasks definition to identify the sensor type.
Underscore "_" is not allowed here.
|
Any string
|
name
|
X
|
The display name of the sensor.
|
Any string
|
deprecated
|
—
|
You can flag the sensor to status deprecated. A flagged sensor can still run but this kind of sensor is not shown when you add new sensors to the probe.
|
1 (= deprecated)
0 (= not deprecated)
|
description
|
—
|
A short description of the sensor that is shown in the Add Sensor dialog in the PRTG web interface.
|
Any string
|
help
|
—
|
A help text that is shown in a popup in the Add Sensor dialog in the PRTG web interface.
|
Any string
|
tag
|
—
|
A default tag for the sensor that is automatically added to the sensor.
|
Any string
|
default
|
—
|
A sensor of this type is automatically created with the probe if set to "default".
|
(= set to default)
0 (= not default)
|
groups
|
—
|
In the "groups" array, available settings for this sensor type are defined.
|
An array of grouped settings JSON objects.
See Definition of Setting Groups Objects for more information.
|
Definition of Setting Groups Objects
One settings group definition (one element of the "groups" array) consists of three elements:
|
|
|
|
name
|
X
|
The internal name of the settings group.
|
Any unique string
|
caption
|
X
|
The label of the settings group as shown in the PRTG web interface.
|
Any string
|
fields
|
X
|
The available settings of the settings group.
|
An array of field definition objects.
See Parameters for Setting Fields for more information.
|
Parameters for Setting Fields
The following table shows available JSON name/value pairs for setting fields:
|
|
|
|
|
type
|
X
|
Type of the field. This defines the possible content.
|
All
|
Edit
Password
Integer
Radio
See Definition of Setting Fields: Field Types for more information.
|
name
|
X
|
The internal name of the field. The name has to be unique per sensor. It is sent with the settings of the probe in the task request.
|
All
|
Any unique string
|
caption
|
X
|
The label of the field. It is displayed left of the field.
|
All
|
Any string
|
required
|
—
|
If a field is defined as required, this field has to be set when adding or editing the sensor settings. The default is not required.
|
All
|
0 (= not required)
1 (= required)
|
default
|
—
|
The default value of the field.
|
All
|
Any string or integer (depending on the field type)
|
help
|
—
|
A help text that is displayed right of the field.
You can use limited BBCode: "[b]" and "[/b]" for bold, "[i]" and "[/i]" for italics, and "[br]" for line break.
|
All
|
Any string
|
maximum
|
—
|
The maximum value that is allowed for this field.
|
Integer
|
Integer
|
minimum
|
—
|
The minimum value that is allowed for this field.
|
Integer
|
Integer
|
options
|
—
|
A JSON array that provides several radio buttons to choose a desired option.
|
Radio
|
"name":"value" pairs. See Example below.
|
Example
"name":"value" pairs that define radio button options:
{
"1":"This is option 1",
"2":"This is option 2",
"XYZ":"Another option"
}
|
Definition of Setting Fields: Field Types
A sensor type can have any number of setting fields that are organized in groups of settings. One field is one element in the "fields" array of a settings group. Currently, mini probes support four different field types for settings:
- edit: One line edit field.
- password: An edit field with masked characters.
- integer: A number field with optional minimum/maximum selection.
- radio: A selection of multiple options with radio buttons.
Example
The following is a detailed example that shows the JSON object definition of a sensor type that is used in the HTTP field sensors of the announce request.
This sensor type is called Sample Sensor and is from the type Sample. It has a description, a help text, and a default tag. There are two setting groups, Group and group2, with several setting fields (six in the first group, one in the second group). The example also shows how you can use the available JSON name/value pairs in the fields array object.
[
{
"kind":"Sample",
"name":"Sample Sensor",
"description":"This is a sample demo sensor",
"help":"This is the help text of the demo sensors",
"tag":"demosensor",
"groups":[
{
"name":"Group",
"caption":"Group",
"fields":[
{
"type":"edit",
"name":"simpleedit",
"caption":"Edit Field",
},
{
"type":"edit",
"name":"extendededit",
"caption":"Edit Field 2",
"required":"yes",
"default":"Default Value",
"help":"Help text displayed to the right of the field"
},
{
"type":"integer",
"name":"simplenumber",
"caption":"Number",
},
{
"type":"integer",
"name":"number2",
"caption":"Number 2",
"required":"1",
"minimum":23,
"maximum":99,
"help":"Number field with limit 23-99"
},
{
"type":"password",
"name":"password",
"caption":"Password",
"help":"This is a password field"
},
{
"type":"radio",
"name":"radiotest",
"caption":"Radio test",
"help":"This is a radio selection field",
"options":{
"1":"This is option 1",
"2":"This is option 2",
"3":"This is option 3"
},
"default":"2"
},
]
},
{
"name":"group2",
"caption":"Group 2",
"fields":[
{
"name":"testfield2",
"caption":"Test2",
"type":"edit"
}
]
}
]
}
]
|
Tasks Definition
A tasks definition is a JSON array where each task is one object. Tasks contain all name/value pairs as defined in the sensor settings definition, which are filled with the values you have provided. Additionally, the following information is included:
|
|
|
|
kind
|
X
|
The type of the sensor.
|
String
|
sensorid
|
X
|
The ID of the sensor.
|
Integer
|
host
|
X
|
The IP address/DNS name of the parent device as specified for this device. For the probe device, it is 127.0.0.1 by default.
|
IP address/DNS name
|
all defined fields
|
X
|
All fields that are defined in the sensor setting group objects are included in the tasks definition as name/value pairs.
|
name/value pairs
|
This data comes from PRTG, so the mandatory JSON objects are included automatically.
Example
Definition of two tasks, the first one is the simplest possible one without any values, and the second one uses the sensor settings objects as defined above:
[
{
"sensorid":"2009",
"kind":"ping",
"host":"www.google.com"
}
{
"sensorid":"2010",
"kind":"sample",
"host":"www.paessler.com",
"simpleedit":"Test2",
"extendededit":"Extended Test",
"simplenumber":"3",
"number2":"42",
"password":"masked text",
"radiotest":"1",
"testfield2":"This is test 3"
}
]
|
Data Definition
A data definition is a JSON array where each result of a task is one object. Every array element contains the following name/value pairs:
|
|
|
|
sensorid
|
X
|
The ID of a specific sensor.
|
Integer
|
time
|
—
|
The time of measurement in Coordinated Universal Time (UTC)/GMT time zone as a JSON number in the Unix time format (in milliseconds since Unix epoch, which is 00:00:00 UTC on January 1, 1970). Time values must be strictly chronological, so the Unix time of each measurement must be greater than the one before. The time values should be close to the current time (which is now) to prevent sensors in the Unknown status.
If no time value is provided, the current time (now) is used.
|
JSON number defining Unix time
|
message
|
—
|
An optional text message.
|
Any string
|
channel
|
X
|
The channel result values.
|
An array of name/value pairs.
See Parameters for Data Definitions: Channel Result Values for more information.
|
Examples
Data definition object with sensor status OK:
[
{
"sensorid":"2003",
"message":"Optional Message",
"channel":[
{
"name":"Time",
"mode":"integer",
"unit":"TimeResponse",
"value":6
"showchart":1
"showtable":1
}
{
"name":"Pages",
"mode":"counter",
"unit":"Custom",
"customunit":"Pages",
"value":99
}
]
}
]
Data definition object with sensor status error:
[
{
"sensorid":"2003",
"error":"Response",
"code":10,
"message":"Error Message"
}
]
|
Parameters for Data Definitions: Channel Result Values
The following table shows name/value pairs that can be used in the "channel" array objects of data definition objects:
|
|
|
|
Name
|
X
|
The name of the channel as displayed in user interfaces.
|
Any string
|
Value
|
X
|
Any number without quotation marks.
|
An integer, float, or counter value
|
Mode
|
—
|
The type of the value.
Make sure that it matches the provided value, otherwise PRTG shows 0 values.
|
Integer, float, or counter
|
Unit
|
—
|
The unit of the value.
If you set the correct unit type instead of using custom units, PRTG can display received values better.
|
BytesBandwidth
BytesMemory
BytesDisk
BytesFile
TimeResponse
TimeSeconds
TimeHours
Temperature
Percent
Count
CPU: This is a % unit that is accounted to the CPU load in index graphs.
Custom (define the name of the unit using the additional field customunit)
|
ShowChart
|
—
|
Init value for the Show in graphs option.
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
0 (= do not show graph)
1 (= show graph)
|
ShowTable
|
—
|
Init value for the Show in graphs option.
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
0 (= do not show table)
1 (= show table)
|
SpeedSize
VolumeSize
|
—
|
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
|
—
|
See above, used when displaying the speed. The default is Second.
|
Second
Minute
Hour
Day
|
decimalMode
|
—
|
Init value for the Decimal Places option. If 0 is used in the float mode (use integer), the default is Automatic. Otherwise (for float), the default is All.
You can change this initial setting later in the sensor's channel settings.
|
Automatic
All
Custom
|
decimalDigits
|
—
|
If you define Custom as decimalMode, specify the number of digits after the delimiter.
|
Integer
|
ValueLookup
|
—
|
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.
See section Define Lookups for more information.
This setting is only considered on the first sensor scan, when the channel is newly created. It is 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
|
LimitMaxError
|
—
|
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
Integer
|
LimitMaxWarning
|
—
|
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.
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
Integer
|
LimitMinWarning
|
—
|
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.
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
Integer
|
LimitMinError
|
—
|
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.
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
Integer
|
LimitErrorMsg
|
—
|
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
Any string
|
LimitWarningMsg
|
—
|
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
Any string
|
LimitMode
|
—
|
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 may be omitted). You can change this initial setting later in the sensor's channel settings.
|
0 (= no)
1 (= yes)
|
Warning
|
—
|
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)
|
Message
|
—
|
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.
|
Any string
|
Error
|
—
|
The type of error.
The type is not necessarily shown in PRTG.
|
Data: The monitored device returned a value but the sensor could not process it.
Response: The monitored device reported an error. This includes timeouts, HTTP response codes, etc.
Exception: Error in sensor handling.
Socket: Socket error.
|
Code
|
—
|
The error code that is stored in the database.
|
Integer
|
More
Knowledge Base
How can I disable SSL for Mini Probes?
Where can I find PRTG mini probes which are ready to use?