Skip to content

Sensors

Jump to bottom
lordmilko edited this page Mar 4, 2019 · 39 revisions

Contents

C#

Basic Requests

Sensors can be retrieved from a PRTG Server via the GetSensors method

var sensors = client.GetSensors();

Sensors of a specific status can be requested. GetSensors supports params, allowing you to specify multiple sensor statuses by adding a comma.

var sensors = client.GetSensors(Status.Warning, Status.Down);

If you wish to filter for sensors that meet certain search criteria you can specify a Property to filter on using one of several overloads

//Get sensors whose names match "Ping"
var sensors = client.GetSensors(Property.Name, "Ping");
//Get sensors whose device name contains "dc"
var sensors = client.GetSensors(Property.Device, FilterOperator.Contains, "dc");

Queries can also be specified via LINQ style query expressions, allowing high performance queries to be executed via dynamically generated request parameters.

var names = client.QuerySensors(s => s.LastUp > DateTime.Now.AddHours(-1))
                  .Select(s => s.Name)
                  .Take(20);

For more information on using LINQ style queries, see Queries.

When retrieving a particular sensor you insist should exist, it is possible to use the singular GetSensor method, returning a single Sensor rather than a List<Sensor> as with GetSensors.

var sensor = client.GetSensor(1234);

If a sensor with the specified object ID cannot be found (or somehow multiple objects were found) GetSensor will throw an InvalidOperationException. If you are not sure whether a sensor exists, you should use GetSensors instead and check for the presence of any results.

var sensor = client.GetSensors(Property.Id, 1234).FirstOrDefault();

if (sensor != null)
    Console.WriteLine($"Found sensor {sensor}!");

Advanced Filtering

Filters are implemented internally via the SearchFilter class. One or more SearchFilter objects can be specified to filter on multiple properties

//Get all Ping sensors for devices whose name contains "dc" on the Perth Office probe.
var filters = new[]
{
    new SearchFilter(Property.Type, "ping"),
    new SearchFilter(Property.Device, FilterOperator.Contains, "dc"),
    new SearchFilter(Property.Probe, "Perth Office")
};

var perthDCPingSensors = client.GetSensors(filters);

Note that special traversal logic may be required when requesting child sensors belonging to group objects. For more information, see Group Recursion.

Sensor Totals

If you simply wish to retrieve the total number of each sensor type in the server, you can use the GetSensorTotals method

var totals = client.GetSensorTotals();

Sensor Types

Types of sensors supported by your PRTG Server can be identified with the GetSensorTypes method

var types = client.GetSensorTypes();

Types can be filtered based on their identifier, full name, or description

//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();

The Id values defined on objects returned from GetSensorTypes can be used for filtering GetSensors by Property.Type, creating new sensors and retrieving sensor targets.

Creation

For information on creating new sensors please see Object Creation.

PowerShell

Basic Requests

Sensors can be retrieved with PowerShell via the Get-Sensor cmdlet. (Note: for complete instructions on using Get-Sensor, please see Get-Help Get-Sensor)

C:\> Get-Sensor

Name               Id      Device      Group           Probe           Status
----               --      ------      -----           -----           ------
Ping               2010    dc1         Servers         Local Probe     Up
CPU Usage          2011    dc1         Servers         Local Probe     Down
Memory             2012    exch1       Servers         Remote Probe    DownAcknowledged

PrtgAPI automatically formats Sensor objects in a table, displaying the most relevant properties. To view all properties of sensors, pipe your sensors to Format-List

Get all sensors named "memory" (case insensitive)

C:\> Get-Sensor memory

Name               Id      Device      Group           Probe           Status
----               --      ------      -----           -----           ------
Memory             2050    dc1         Servers         Local Probe     Up
Memory             2051    dc1         Servers         Local Probe     Up
Memory             2012    exch1       Servers         Remote Probe    DownAcknowledged

Wildcards can also be used

Get-Sensor *disk*

Get-Sensor can filter on a number of properties, including Id, Tags and Status

C:\> Get-Sensor *cpu* -Status Paused,Up

Name               Id      Device      Group           Probe           Status
----               --      ------      -----           -----           ------
CPU Usage          2060    dc1         Servers         Local Probe     PausedByUser
CPU Usage          2061    dc1         Servers         Local Probe     PausedByDependency
CPU                2015    exch1       Servers         Remote Probe    Up
# Get all WMI Pagefile sensors
Get-Sensor -Tags wmipagefilesensor

When filtering by tags, PrtgAPI provides two parameters that can be used

  • -Tags: Filter for objects that contain all specified tags
  • -Tag: Filter for objects that contain any specified tags
# Get all New York WMI CPU Load Sensors
Get-Sensor -Tags ny,wmicpu*

# Get all WMI CPU Load and WMI Memory Sensors
Get-Sensor -Tag wmicpu*,wmimem*

Get-Sensor accepts a variety of objects via the pipeline. This allows you to chain cmdlets together to filter down results

Get-Probe micro* | Get-Sensor
Get-Group | Select -First 1 | Get-Sensor -Status Warning

All properties found on Sensor objects (excluding InheritInterval and NotificationTypes, which do not work server side) can be specified as dynamic parameters to Get-Sensor

# Get all Ping or Exchange sensors that are the first
# or second sensor under a device
Get-Sensor -Position 1,2 -Type ping,exch*

Cmdlet parameters that are typically used for accepting pipeline input (e.g. -Device) can also be used for filtering by a single object name

# Get all sensors under all devices that start with "dc"
Get-Sensor -Device dc*

Advanced Filtering

To filter by custom fields the New-SearchFilter cmdlet can be used (alias: flt).

flt parentid eq 1234 | Get-Sensor

When chaining results, consider whether your results could be acquired quicker by constructing an array of filters containing the criteria you are after; i.e. you do not need to ask for probe, group and device objects before sensors if you know the name of the probes, groups and devices you'd like to find sensors under.

For more information on New-SearchFilter see the Filters page.

Sensor objects can also be used as the input to cmdlets (including cmdlets receiving channels and changing sensor states). For more information please see the See Also section below.

Note that PrtgAPI implements special traversal behavior when requesting child sensors belonging to group objects. For more information, see Group Recursion.

Sensor Totals

If you simply wish to retrieve the total number of each sensor type in the server, you can use the Get-SensorTotals cmdlet

C:\> Get-SensorTotals

TotalSensors            : 129
UpSensors               : 112
WarningSensors          : 4
DownSensors             : 6
DownAcknowledgedSensors : 3
PartialDownSensors      : 0
PausedSensors           : 2
UndefinedSensors        : 2

Sensor Types

Types of sensors supported by your PRTG Server can be identified with the Get-SensorType cmdlet

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

The Id values defined on objects returned from Get-SensorType can be used for filtering Get-Sensor by -Type, creating new sensors and retrieving sensor targets.

Creation

For information on creating new sensors please see Object Creation.

See Also

Project Overview

User Guide

Utilities

Clone this wiki locally