More Uses for PrtgAPI: Create Multiple Sensors, Clean Up Deprecated Sensors, and Configure Sensor Factories

 Originally published on March 29, 2019 by Shaun Behrens
Last updated on March 03, 2022 • 10 minute read

In a previous article, we covered one use case for PrtgAPI, a C#/PowerShell library for managing PRTG: Adding multiple devices. But PrtgAPI has a lot more uses than just that, and it's one of the reasons why we at Paessler are such fans of it. It's one thing to have smart, innovative users like lordmilko, but when they develop tools like PrtgAPI, we tend to geek out a bit.

This post covers a few more examples of what you can do with PrtgAPI, and how: deploy multiple sensors, clean up deprecated sensors, and define sensor factory sensors.

New call-to-action

iDisclaimer: PrtgAPI is developed by an independent PRTG user. As the solution described in this post is not part of PRTG itself, it is not officially supported by Paessler or PRTG Technical Support.

Batch Deploy Sensors

Let's say you want to create a sensor factory showing the user load across all of your terminal servers. This can be done by creating a WMI Terminal Services sensor on each terminal server device. You could do this manually, but who has time for that? The Clone-Object cmdlet can be used to either clone multiple objects to a single location, or a single object to multiple locations.

 

# Clone the WMI Terminal Services sensor with ID 1001 to every device whose name contains "-ts-"

Get-Device *-ts-* | Clone-Object -SourceId 1001
 
 

This will work fine for most of your devices, but if the sensor being cloned already exists on one of these servers, then that server will end up with two WMI Terminal Services sensors. You can either clean this up manually, or skip it using PowerShell:

 

Get-Device *-ts-* | where Id -ne 2003 | Clone-Object -SourceId 1001

 

If you don't have an existing sensor to clone however, you can instead create the sensor from scratch. First, identify the internal ID of the sensor type you wish to create:

SensorCreation_GetType

Then, query a compatible device to get the sensor parameters required to create the object

SensorCreation_GetParams

Finally, apply the sensor parameters to all desired devices

SensorCreation_AddSensor

Clean Up Deprecated Sensors

In 2016, Paessler initiated the PRTG sensor cleanup. While each deprecated sensor was replaced by a newer version, tracking down all of the deprecated sensors was not exactly straightforward. Luckily, every deprecated sensor had its display name changed to include "DEPRECATED", providing the perfect means to identify these sensors.

 

Get-Sensor | where DisplayType -like *deprecated* | Pause-Object -Forever -Message "Deprecated sensor type; recreating"

 

You then have two options. Either you can open all of these sensors to recreate them:

 

Get-Sensor | where DisplayType -like *deprecated* | Open-PrtgObject

 

Or delegate the task to other colleagues:

 

Get-Sensor | where DisplayType -like *deprecated* | foreach { "prtg.contoso.com" + $_.url }

 

prtgapi_Deprecated_All

Create Sensor Factory Definitions

Here's a hypothetical situation: you've created a dozen WMI Terminal Services sensors, but now you want to create a sensor factory out of them. Ideally, you want to show the number of connected and disconnected users across your cluster, as well as the total number of users in each category. Don't forget you'll need to update this whenever you add a new server! Additionally, you'd probably like to do the same thing for CPU Usage, Memory and Uptime for each client. Doing all of this would create a lot of manual work. 

Sensor factory definitions for an arbitrary number of sensors can easily be created using the New-SensorFactoryDefinition cmdlet. New-SensorFactoryDefinition can operate in one of two modes:

  • Create an individual channel from each input sensor
  • Create a single aggregate channel from all input sensors

To create individual channels per sensor, specify the sensors, name and channel ID to use for each channel. The name of each sensor is specified as an expression, allowing you to generate a unique name for each channel

 

# Get all WMI Terminal Services sensors from your Terminal Servers
C:\> $sensors = Get-Device *-ts-* | Get-Sensor -Tags wmiterm* | sort Device
 
# Create a channel from each sensor, naming each sensor after the sensor's device name
# and targeting Channel ID 0 on each source sensor
C:\> $sensors | New-SensorFactoryDefinition { $_.Device } 0 -StartId 2
 
#2:fab-ts-01
channel(1001,0)
#3:fab-ts-02
channel(2003,0)
#4:fab-ts-03
channel(1004,0)

 

Since we'll be generating a "Total" channel as well, start at ID 2 instead of the default ID 1.

To generate the "Total" channel, simply specify how to combine the results using the -Aggregator parameter:

 

# Determine the total number of Active Sessions across all terminal servers
C:\> $sensors | New-SensorFactoryDefinition { "Active Sessions" } -Aggregator { "$acc + $expr" } 1
 
#1:Active Sessions
channel(1001,1) + channel(2002,1) + channel(1010,1) ...

 

To perform some additional processing on each channel definition (for example, inverting the percent amount of memory "free" to be the amount of memory "used") is also possible.

From PrtgAPI 0.9.6 (due out in the next few days), you'll be able to create your per-sensor and summary channel definitions in a single line, and then even create a sensor out of it! If you are using the new version, you can use the following:

$sensors | New-Sensor -Factory “Terminal Services Overview” { $_.Device } 1 –SummaryName “Active Sessions” –SummaryExpression Sum –DestinationId 1001
 

 

We still have one more blog post about PrtgAPI, coming up in the next few weeks, where we'll explain how you can create notification triggers using it. In the meantime, enjoy trying out the three use cases above. If you have any thoughts or questions (we know lordmilko reads this blog), then write a comment below!