<%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 application programming interface (API) in PRTG. 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?

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 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 PRTG User Can Create

Yes

No

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.

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.

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

Example

"name":"value" pairs that define radio button options:

{
 "1":"This is option 1",
 "2":"This is option 2",
 "XYZ":"Another option"
}

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

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

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

sensorid

X

The ID of a specific sensor.

Integer

time

—

The time of measurement in Coordinated Universal Time (UTC)/GMT timezone 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 an 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"
 }
]

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.

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

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

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 a Down status if this value is overrun and the LimitMode is activated.

Provide 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 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 a Warning status if this value is overrun and the LimitMode is activated.

Provide the limit value in the unit of the base data type, just as 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 a Warning status if this value is undercut and the LimitMode is activated.

Provide the limit value in the unit of the base data type, just as 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 a Down status if this value is undercut and the LimitMode is activated.

Provide the limit value in the unit of the base data type, just as 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 a 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 a 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 sensor 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 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