Filters

Contents

• Overview
  • Mode
• C#
• PowerShell

Overview

When requesting data from PRTG, often you wish to limit your results to items that match one or more search filters. PrtgAPI represents these filters using the SearchFilter object.

Search filters can be combined to create logical operations, according to the following rules

• Filtering on a property multiple times specifies a logical OR
• Filtering between multiple properties specifies a logical AND

A SearchFilter consists of three components

• The property to filter on
• The operator to filter with
• The value to filter for

The following operators are supported by PrtgAPI

• Equals
• NotEquals
• GreaterThan
• LessThan
• Contains

Care should be taken when deciding whether to filter by Equals or Contains. When properties such as Name are used in conjunction with many other properties, PRTG will treat an Equals filter case sensitively. As such, when you don't know the case of the specified search value, it can often be safer to filter based on Contains.

Mode

When a SearchFilter is transformed for use in a web request, PrtgAPI may perform a number of transformations on the filter Value based on the value type, as well as the required format specified by the filter's Property value. The extent to which PrtgAPI performs these transformations can be controlled by specifying the FilterMode of a search filter.

PrtgAPI specifies the following filter modes:

• Normal: perform all validations/transformations
• Illegal: specifies that filters that cannot be evaluated server side should be allowed
• Raw: specifies Illegal filters should be allowed and that no transformations on any values should be performed.

// C#
var filter = new SearchFilter(Property.LastValue, FilterOperator.Equals, 60, FilterMode.Raw);

# PowerShell
$filter = flt lastvalue eq 60 -Raw

Generally speaking, you should never need to specify a custom FilterMode. In the event you discover your PRTG server conforms to a different specification than implemented in PrtgAPI, these flags will allow you to specify your own custom formatted values without any interference.

C#

Objects such as Sensors, Devices, Groups and Probes support server side filters. Each object type contains a number of overloads to simplify common object filtering scenarios

Method	Description
GetSensors(Property, object)	Create a single SearchFilter, wherein the Property Equals Value
GetSensors(Property, FilterOperator, object)	Create a single SearchFilter, specifying the Property, Operator and Value
GetSensors(Property, FilterOperator, object, FilterMode)	Create a single SearchFilter, specifying the Property, Operator, Value and Filter Mode
GetSensors(params SearchFilter[])	Manually specify one or more SearchFilter objects to filter with

//Get all sensors under all probes named "Contoso (Head Office)"
var sensors = client.GetSensors(Property.Probe, "Contoso (Head Office)");

//Get all sensors with an ID greater than 1234
var sensors = client.GetSensors(Property.Id, FilterOperator.GreaterThan, 1234);

//Get all Ping sensors for devices whose name contains "dc" on the Perth Office probe.
//(Type equals "ping") AND (Device contains "dc") AND (Probe equals "Perth Office")
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);

//Get all ping sensors that belong to the devices with IDs 1001, 1002 and 1003
//(Parent ID equals 1001 OR 1002 OR 1003) AND (Name equals "ping")
var filters = new[]
{
    new SearchFilter(Property.ParentId, new[]{1001, 1002}),
    new SearchFilter(Property.ParentId, 1003),
    new SearchFilter(Property.Name, "ping")
}

var sensors = client.GetSensors(filters);

If a comma is specified in the string specified with FilterOperator.Contains, PRTG will perform a logical AND on all specified substrings

//Get all devices whose name contains both "xap" and "dc"
var devices = GetDevices(Property.Name, FilterOperator.Contains, "xap,dc");

When filtering based on relationship of an object to other objects, the ParentId property can be used to uniquely identify an objects parent (i.e. the device of a probe, the group of a device, etc). Note that Device, Group and Probe properties do not uniquely identify an object. These properties allow specifying the name of an object. As such, the following command

client.GetSensors(Property.Group, "Servers");

Will return any sensor under any group named "servers" (which could be an issue if multiple groups exist with the same name). This is fairly obvious in C#, however is much less obvious when piping with PowerShell (see below).

PowerShell

SearchFilter objects can be used with the Get-Sensor, Get-Device, Get-Group and Get-Probe cmdlets via the New-SearchFilter cmdlet (alias: flt)

flt id greaterthan 1234 | Get-Sensor

# Any method of creating an array will do

$a = New-SearchFilter name equals Ping # potentially case sensitive when used with another filter
$b = New-SearchFilter device contains dc

Get-Sensor -Filter ($a,$b)

# Use the unary operator , to pipe all items at once!
,($a,$b) | Get-Sensor

PrtgAPI internally uses SearchFilter objects for all specifiable parameters (such as -Name, -Id and -Tags) as well as when piping between cmdlets. As a result of this, limitations arise when attempting to filter using grandchild like relationships, such as in the following scenario:

1. You have group with ID 1234 ("Servers")
2. Other groups named "Servers" exist in the system
3. You request all sensors of group with ID 1234
4. In response, you get all the sensors of every group named Servers (filter used group name, not group ID)

PrtgAPI overcomes this issue via the -Recurse parameter (enabled by default). If not disabled (via -Recurse:$false) PrtgAPI will automatically retrieve all Device objects in between the Group and desired sensors, and then execute a request for all sensors belonging to the parent device IDs. These issues are not present when performing parent-child queries (get the sensors of the device, the devices of the probe, etc) as the ParentId property can be specified explicitly.