PRTG Manual: Mini Probe API

Important Notice

We do not further develop the Mini Probe API because we plan major changes to the underlying API in PRTG. You can still use the Mini Probe API "as is" but please note that it may be deprecated at any time.

icon-book-bulbKnowledge Base: Where can I find PRTG Mini Probes which are ready to use?

PRTG Mini Probes allow PRTG 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 help 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.

Basically, this takes the Custom Sensors concept to a higher level; you will have a very broad range of possibilities and you can implement amazing functions to get an even better network monitoring experience!

icon-i-roundWith 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. Please note that there are major changes planned to the underlying API in PRTG. Therefore, any code you write now will likely need 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. We will provide further news about changing interfaces as soon as there are more detailed plans available.

icon-i-round-redBecause the PRTG Mini Probe requires an 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 will be transferred between probe and core. So it is important to encrypt the connection even on internal routes. If your network setup ensures security in another way (for example, VPN), you can use a registry key option for disabling SSL in order to get a connection to your Mini Probe.
icon-book-bulbFor more details, see this Knowledge Base article: How can I disable SSL for Mini Probes?

icon-prtg-on-demandThe Mini Probe API is not available in PRTG hosted by Paessler.

Here are quick links for ease of use.

PRTG Mobile Probe for Android

Initially we released a mobile probe for Android devices to gather local monitoring data with mobile devices. This mobile probe is a subtype of the Mini Probe. With the PRTG Mobile Probe for Android, you can monitor, for example, wireless LAN (WLAN) coverage, location, battery, HTTP response times, and environmental data such as temperature, pressure, humidity, or light intensity. The available data depends on the available measurement components on the device.

PRTG Mobile Probes for Android usually connect via WLAN and monitor your network from the mobile perspective.

Differences Between Probe Types

The following table shows technical specifications of the two probe types in PRTG.

Functionality

Local and Remote Probes

PRTG Mini Probe

Connection Protocol from Probe to Core

Protocol from PRTG

HTTPS

Security

Data is secured with SSL and an access key. New probe connections must be approved by the PRTG administrator. IP and GUID filtering is possible.

The same security level as for local and remote probes.

Estimated Limit for Sensors per Probe

Several thousand sensors

Less than 100 sensors

Estimated Limit for Probes per Installation

Hundreds of probes

Less than 100 probes

Estimated Minimum Scanning Interval

Some seconds

At least 60 seconds

Estimated Number of Sensor Types

More than 200

A few

Updates to New PRTG Versions by the 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 Supports Pre-Scans for Available Measurements

Yes

No

Sensors Support Inheritance of Settings

Yes

No

Limitations by Administrator for Allowed Sensor Types that a PRTG User Can Create

Yes

No

The PRTG Mini 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.

icon-i-round-redPRTG Mini Probes are not intended for high performance monitoring and support only the sensor types that you implement.

The PRTG Mini Probe Protocol—Communication and Security

The PMPP uses GET and POST requests via HTTPS in order to communicate with the PRTG server. All requests are sent to the defined TCP port for the common PRTG web server (default is 443 for SSL), or you specify an extra port explicitly for Mini Probe connections in the PRTG System Administration—Core & Probes. PRTG 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.

icon-i-round-redThe data format of some HTTP fields has to be JSON encoded. See Data Format: JSON Definitions for data definitions that require JSON. All exchanged data is secured with SSL.

The PRTG Mini Probe Protocol—Authentication

The PMPP uses the same authentication methods as the common PRTG remote probes. The authentication includes the following steps:

  • Allow and deny IPs filter
  • Deny GIDs 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 PRTG Probe connection settings! Additionally, you have to provide the Mini Probe's IP in the Allow IPs field (or enter any).

There are no sessions on the server: Every request must contain the required authentication information.

icon-book-arrowsFor more details, see section System Administration—Core and Probes.

The PRTG Mini Probe Protocol—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. Afterwards, 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 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 have to update this field to a new value.
  • key: An access key as defined in the probe settings of the PRTG 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.

icon-book-arrowsFor 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. The target URL is https://<yourPRTGserver>/probe/announce

icon-i-round-redThis 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 number, 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.
    icon-book-arrowsSee Data Format: JSON Definitions—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.
    icon-book-bulbFor details, see our Knowledge Base article How can I add my own device icons for use in the PRTG web interface?

icon-i-redIf you change the definition of a sensor that has already been announced, these changes will only be active after the next start of PRTG. An existing 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 an existing sensor with a new one that uses another 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 have to be run by the Mini Probe.

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

icon-book-arrowsSee Data Definition for more information.

Data Format: JSON Definitions

All data definitions of sensors, tasks, and result data of PRTG 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.

Data Format: JSON Definitions—Sensor Definition

This section shows how you can define the available sensor types for your Mini Probe. Sensor definitions are given in the HTTP field "sensors" of the announce request.

Basic Structure

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:

Name

Mandatory

Description

Possible Value

kind

X

Unique identifier for the sensor type in the Mini Probe. Used in the tasks definition to identify the sensor type.

icon-i-round-redUnderscore "_" 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 will not be 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 will automatically be added to the sensor.

Any string

default

A sensor of this type will automatically be 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.

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

Mandatory

Description

Possible Value

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.

icon-i-roundSee Parameters for Setting Fields for more information.

Parameters for Setting Fields

The following table shows available JSON name/value pairs for setting fields:

Name

Mandatory

Description

Available in Type

Possible Value

type

X

Type of the field. This defines the possible content.

All

Edit

Password

Integer

Radio

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

icon-i-roundYou can use limited BBCode: "[b]" and "[/b]" for bold, "[i]" and "[/i]" for italics, and "[br]" for linebreak.

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.

icon-speechExample

"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, PRTG 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.

icon-speechExample

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

Data Format: JSON Definitions—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:

Name

Mandatory

Description

Possible Value

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

icon-i-roundThis data comes from PRTG, so the mandatory JSON objects are included automatically.

icon-speechExample

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 Format: JSON Definitions—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:

Name

Mandatory

Description

Possible Value

sensorid

X

The ID of a specific sensor.

Integer

time

The time of measurement in UTC/GMT timezone as JSON number in 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 gray sensors.

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

icon-i-roundSee Parameters for Data Definitions: Channel Result Values for more information.

icon-speechExamples

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

Mandatory

Description

Possible Value

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.

icon-i-round-redMake sure that it matches the provided value, otherwise PRTG will show 0 values.

Integer, float, or counter

Unit

The unit of the value.

icon-i-roundSetting the correct unit type instead of custom units helps PRTG display received values in a better way.

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.

icon-i-roundThe values defined with this element will be considered only on 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 tables option.

icon-i-roundThe values defined with this element will be considered only on 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 #. Default is One (value used as returned).

icon-i-round-redFor 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. 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) default is All.

icon-i-roundYou 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 integer values as status texts). Enter the ID of the lookup file you want to use, or omit this element to not use lookups.

icon-book-arrowsSee section Define Lookups for more information.

icon-i-roundThis setting will be considered only 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 will be 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 will still receive data in its channels.

icon-i-roundThe values defined with this element will be considered only on 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 will be 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.

icon-i-roundThe values defined with this element will be considered only on 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 will be 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.

icon-i-roundThe values defined with this element will be considered only on 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 will be 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.

icon-i-roundThe values defined with this element will be considered only on 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 will be 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 will be considered only on 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 will be 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 will be considered only on 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 will be active. Default is 0 (no; limits inactive). If 0 is used, the limits will be written to the sensor channel settings as predefined values, but limits will be disabled.

icon-i-roundThe values defined with this element will be considered only on 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 Warning status. 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. Default is OK.

Any string

Error

The type of error.

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

Knowledge Base: Where can I find PRTG Mini Probes which are ready to use?

 

Application Programming Interface (API) Definition—Topics