PRTG Manual: Mini Probe API

Important Notice

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

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

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

i_round_redBecause 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.
i_square_cyanFor more details, see the Knowledge Base: How can I disable SSL for Mini Probes?

i_podThe Mini Probe API is not available in PRTG hosted by Paessler.

In this section:

Differences Between Probe Types

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

Functionality

Local and Remote Probes

Mini Probe

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

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

i_round_redThe data format of some HTTP fields has to be JavaScript Object Notation (JSON) encoded. See JSON Definitions 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 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.

i_square_cyanFor more details, see section Core and 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 have to 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.

i_square_cyanFor 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

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

i_round_redIf 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 have to be run by the mini probe.

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

i_square_cyanSee 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:

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.

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

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

i_round_blueSee 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

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

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

i_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, 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.

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

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

i_round_blueThis data comes from PRTG, so the mandatory JSON objects are included automatically.

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

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

i_round_blueSee Parameters for Data Definitions: Channel Result Values for more information.

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

i_round_redMake sure that it matches the provided value, otherwise PRTG shows 0 values.

Integer, float, or counter

Unit

The unit of the value.

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

i_round_blueThe 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 tables option.

i_round_blueThe 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).

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

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

i_square_cyanSee section Define Lookups for more information.

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

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

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

i_round_blueProvide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section.

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

i_round_blueProvide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section.

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

i_round_blueProvide the value for the limit in the unit of the base data type as it is used in the <Value> element of this section.

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

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

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

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

i_round_blueThe 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

i_square_blueKNOWLEDGE BASE

How can I disable SSL for Mini Probes?

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

Application Programming Interface (API) Definition