Skip to content

Sensor Targets

Jump to bottom
lordmilko edited this page Nov 13, 2021 · 35 revisions

Contents

Overview

Many sensors within PRTG can apply to dynamic resources, based on the capabilities of a PRTG Probe or target device. PrtgAPI is capable of enumerating certain sensor targets, to assist in the creation of object parameters for creating new sensors.

PrtgAPI theoretically supports retrieving sensor targets for all sensor types supported by PRTG, including those that require additional information to be provided before initiating a query (such as SNMP Library, IPMI Sensor and Oracle Tablespace).

C#

PrtgAPI provides native support for retrieving the targets of a number of different sensor types. For types not currently supported by PrtgAPI, a general purpose GetSensorTargets method can be used to retrieve a generic set of sensor parameters that can still be used for creating new sensors.

Method Sensor Type Description
GetExeXmlFiles ExeXml Retrieve EXE/Script files from a device's probe
GetWmiServices WmiService Retrieve WMI Services installed on a device
GetSqlServerQueries SqlServerDB Retrieve SQL query files from a device's probe
GetSensorTargets Any Retrieve the targets of any raw sensor type

All target resolution methods can be accessed via the PrtgClient's Targets property.

Note: when using DynamicSensorParameters there is no need to call any sensor target retrieval methods described on this page, as DynamicSensorParameters automatically include all available targets under their special Targets property. For more information, see DynamicSensorParameters: Targets.

Supported Types

//Create new WMI Service sensors for all services whose name contains "PRTG"
//on the device with ID 1001
var deviceId = 1001;

var services = client.Targets.GetWmiServices(deviceId).Where(s => s.Name.Contains("PRTG")).ToArray();
var parameters = new WmiServiceSensorParameters(services);

var sensors = client.AddSensor(deviceId, parameters);

Targets that are resolved from a device can be utilized for creating sensors on any device. In the event the sensor target is not valid for the specified device, PRTG will create the sensor anyway, where it will behave as if the target used to exist but has since been deleted, displaying an error on the sensor that the target cannot be found.

For sensor targets whose internal string representation is simple (such as EXE/Script sensors), PrtgAPI supports implicit conversions from strings to these types. For parameter types that support specifying a number of targets in a single request (such as WMI Service sensors), PRTG will fail to fully process the request in the event the request is of an excessive size (generally 60 items or greater). To prevent this from happening, PrtgAPI automatically splits your request into a series of smaller requests, however if you find yourself experiencing issues, this is something to be aware of.

//Implicitly convert the string "test.ps1" to an ExeFileTarget
var parameters = new ExeXmlSensorParameters("test.ps1");

Unsupported Types

Sensor Targets for sensor types not currently supported by PrtgAPI can still be retrieved via the GetSensorTargets method. In order to use GetSensorTargets, a raw sensor type name must be specified. Raw sensor type names can be identified via the GetSensorTypes method.

//Identify all sensor types whose name or raw ID contains "exchange"
var types = client.GetSensorTypes().Where(t => t.Id.Contains("exchange") || t.Name.Contains("exchange")).ToList();
//Get all Exchange Databases supported by the device with ID 1001
var targets = client.Targets.GetSensorTargets(1001, "exchangepsdatabase");

By default, GetSensorTargets will try and guess the table name the raw sensor targets are contained in within the PRTG Sensor Creation page. In the event more than one table is found, PrtgAPI will throw an exception specifying the possible table names available. A table name can then be specified to the tableName parameter of GetSensorTargets

var targets = client.Targets.GetSensorTargets(1001, "exexml", "exefile");

For sensor types that require additional information be provided before initiating a query (such as SNMP Library, IPMI Sensor and Oracle Tablespace) PrtgAPI allows you to specify this information via a sensor query target.

//Retrieve the sensor targets for an SNMP Library sensor using the OIDLIB "APC UPS.oidlib"
var oidlib = client.GetSensorTypes(1001).First(t => t.Id == "snmplibrary").QueryTargets.First(t => t.Value.Contains("UPS"));
var targets = client.Targets.GetSensorTargets(1001, "snmplibrary", queryParameters: oidlib)
var qp = new SensorQueryTargetParameters
{
    ["database"] = "XE",
    ["sid_type"] = 0,
    ["prefix"] = 0
}

var targets = client.Targets.GetSensorTargets(1001, "oracletablespace", queryParameters: qp);

For more information on sensor query targets, please see Sensor Query Targets.

PowerShell

Sensor Targets for use in creating new sensors can be identified in PowerShell via the the Get-SensorTarget cmdlet.

Supported Types

Get-SensorTarget can be used in three different ways to assist in creating new sensors

  • The slow way
  • The fast way
  • The awesome way!
# List all EXE/Script files that can be used for creating EXE/Script Advanced sensors
# on the device with ID 2002
C:\> Get-Device -Id 2002 | Get-SensorTarget ExeXml

Name                       Type
----                       ---
Get-VeeamBackupStatus.ps1  Script
PagerDutyAlertCount.exe    Application
...

These parameters can then be filtered and passed to New-SensorParameters

# Using Get-SensorTarget the slow way
C:\> $files = Get-Device -Id 2002 | Get-SensorTarget ExeXml
C:\> $veeamFile = $files | where name -like "*veeam*"
C:\> $params = New-SensorParameters "Servers" $veeamFile
C:\> $params.ExeParameters = "veeam-1 Servers"

Get-SensorTarget is capable of filtering by the name of the sensor target by specifying a wildcard pattern to the -Name parameter.

C:\> Get-Device -Id 2002 | Get-SensorTarget ExeXml *veeam*

Name                       Type
----                       ---
Get-VeeamBackupStatus.ps1  Script

For added convenience, Get-SensorTarget can automatically create a set of sensor parameters for you by specifying the -Parameters parameter (alias: -Params)

# Using Get-SensorTarget the slightly faster way
C:\> Get-Device -Id 2002 | Get-SensorTarget ExeXml *veeam* -Params

ExeFile                    : Get-VeeamBackupStatus.ps1
ExeParameters              :
SetExeEnvironmentVariables : False
UseWindowsAuthentication   : False
Mutex                      :
Name                       : XML Custom EXE/Script Sensor
...

When specifying -Params, if the sensor type supports specifying a name, the default sensor name will be used. You will most likely want to change this on the parameters object before attempting to add the sensor.

Objects that are resolved from a device can be utilized for creating sensors on any device. In the event the sensor target is not valid for the specified device, PRTG will create the sensor anyway, where it will behave as if the target used to exist but has since been deleted, displaying an error on the sensor that the target cannot be found.

For sensor targets whose internal string representation is simple (such as EXE/Script sensors), PrtgAPI supports implicit conversions from strings to these types.

# Create an ExeFileTarget using the custom string "test.ps1"
C:\> $params.ExeFile = "test.ps1"

For parameter types that support specifying a number of targets in a single request (such as WMI Service sensors), PRTG will fail to fully process the request in the event the request is of an excessive size (generally 60 items or greater). To prevent this from happening, PrtgAPI automatically splits your request into a series of smaller requests, however if you find yourself experiencing issues, this is something to be aware of.

# Create a sensor for every WMI Service on the device with ID 2002. If the device
# has 200 services, PrtgAPI will split this up into batches of 30 to ensure each
# request succeeds.

C:\> $device = Get-Device -Id 2002
C:\> $params = $device | Get-SensorTarget WmiService -Params
C:\> $device | Add-Sensor $params

Sensor Parameters created by Get-SensorTarget record the Device the parameters were originally created for in their special Source property. If you don't wish to modify your parameters created by Get-SensorTarget before applying them to your device, you can pass these parameters directly to Add-Sensor

# The fastest way to use Get-SensorTarget
C:\ Get-Device -Id 2002 | Get-SensorTarget WmiService *prtg* -Params | Add-Sensor

Parameters created normally through New-SensorParameters cannot be piped to Add-Sensor in this way, and instead should be specified as argument to an Add-Sensor call that has piped from one or more devices (for usage examples see Sensor Creation).

Unsupported Types

Sensor targets for unsupported sensor types can be retrieved via the -RawType property. The Get-SensorType cmdlet can be used to identify the raw type name of the sensor type you wish to query

C:\> Get-SensorType *exchange*

Id                         Name                                Description
--                         ----                                -----------
exchangepsbackup           Exchange Backup (Powershell)        Monitors backups of an...
exchangepsdatabase         Exchange Database (Powershell)      Monitors database info...
exchangepsdatabasedag      Exchange Database DAG (Powershell)  Monitors the DAG statu...
exchangepsmailqueue        Exchange Mail Queue (Powershell)    Monitors the number of...
...
C:\> Get-Device exch-1 | Get-SensorTarget -RawType exchangepsbackup

Name                           Value                          Properties
----                           -----                          ----------
Mailbox Database 1             47d45d42-a06a-4569-b98e-746... {47d45d42-a06a-4569-b98e...

When a -RawType is specified, Get-SensorTarget returns a GenericSensorTarget representing the name and value of the target item. For sensor targets that include additional properties (such as WMI Volume) these can be accessed via the Properties array.

By default, Get-SensorTarget will try and guess the table name the raw sensor targets are contained in within the PRTG Sensor Creation page. In the event more than one table is found, PrtgAPI will throw an exception specifying the possible table names available. A table name can then be specified to the -Table parameter of Get-SensorTarget

Get-Device -Id 3002 | Get-SensorTarget -rt exexml -Table exefile

For sensor types that require additional information be provided before initiating a query (such as SNMP Library, IPMI Sensor and Oracle Tablespace) PrtgAPI allows you to specify this information via a sensor query target.

# Retrieve the sensor targets for an SNMP Library sensor using the OIDLIB "APC UPS.oidlib"
$targets = Get-Device -Id 1001 | Get-SensorTarget -rt snmplibrary -qt *ups*
# Retrieve the sensor targets for an Oracle Tablespace sensor using a set of
# sensor query target parameters that specify the database to connect to
$targets = Get-Device -Id 1001 | Get-SensorTarget -rt oracletablespace -qp @{
    database = "XE"
    sid_type = 0
    prefix = 0
}

For more information on sensor query targets, please see Sensor Query Targets.

See Also

Project Overview

User Guide

Utilities

Clone this wiki locally