-
-
Notifications
You must be signed in to change notification settings - Fork 38
Tree Creation
PrtgAPI enables you to retrieve trees that may already exist automatically, or manually construct trees describing settings you may wish to apply and objects you may wish to create. PrtgAPI can even export your trees as PowerShell code enabling you to easily export existing objects and their settings to other PRTG servers.
The tree of a PRTG Object can be retrieved via the GetTree method.
//Model the tree of the object with ID 1
var tree = client.GetTree(1);//Model the tree of a specified device
var tree = client.GetTree(device);GetTree automatically traverses all descendants of the specified object, constructing PrtgNode objects for each item encountered. For large PRTG Trees, this can potentially be quite time consuming. Progress can be monitored by implementing a custom ITreeProgressCallback.
For creating PRTG Trees for rearranging PRTG Objects, PrtgAPI provides two mechanisms for creating arbitrary PrtgNode objects
-
PrtgNodefactory methods -
PrtgNodeFactoryinstance methods
Similar to the Expression class in System.Linq.Expressions, PrtgNode serves as both the base class of all PRTG node types but also defines static factory methods that can be used for generating a new instance of a node type from a specified ITreeValue and optional children.
//Construct a tree where the sensor with ID 2002 is a child of the device with ID 1001
var device = client.GetDevice(1001);
var sensor = client.GetSensor(2002);
var node = PrtgNode.Device(device,
PrtgNode.Sensor(sensor)
);PrtgNodeFactory is similar to the SyntaxFactory class found in Roslyn. It is a completely separate type from the more familiar PrtgNode type and is capable of executing API requests and constructing PrtgNode objects for you, all in one go.
//Construct a tree where the sensor with ID 2002 is a child of the device with ID 1001
var factory = new PrtgNodeFactory(client);
var node = factory.Device(1001,
factory.Sensor(2002)
);If you wish to retrieve and encapsulate multiple objects at once, PrtgNodeFactory defines simple Property, object overloads for filtering objects by a specified value.
//Create SensorNode objects for all sensors named "Ping"
var node = factory.Sensors(Property.Name, "Ping");PrtgNodeFactory methods always return at least one object. Methods that retrieve a single object (Sensor, Device, Group, etc) assert that only one object was found, similar to how their equivalent methods on PrtgClient perform (GetSensor, GetDevice, etc).
For methods that perform more advanced filtering that could potentially return a collection of objects, PrtgNodeFactory simply asserts that at least one object was returned. This behavior protects you against creating a tree where mandatory nodes are actually missing.
Constructing a PrtgNode tree from an entire PRTG Object hierarchy can be an extremely time consuming progress. You can monitor the progress of this process however by defining a custom progress callback for retrieving notifications of progress as PrtgAPI traverses the tree. This is done by defining an implementation of an ITreeProgressCallback.
ITreeProgressCallback defines four members that must be implemented by your type
| Name | Description |
|---|---|
DepthManager |
Tracks the depth at which PrtgAPI has traversed and makes adjustments to the progress output device as required |
OnLevelBegin |
Called when a new level has begun, specifying the level we're now at and information about the object whose children we'll be retrieving |
OnLevelWidthKnown |
Called when the total number of items that exist at the current level is finally known |
OnProcessValue |
Called when the next object at the current level is to be processed |
The following provides a simple example of how a progess callback can be used for writing to the console
internal class ConsoleTreeProgressCallback : ITreeProgressCallback
{
public DepthManager DepthManager { get; } = new DepthManager();
public void OnLevelBegin(ITreeValue parent, PrtgNodeType parentType, int depth) =>
WriteLine($"OnLevelBegin: Parent = {parent}, Type = {parentType}, Depth = {depth}");
public void OnLevelWidthKnown(ITreeValue parent, PrtgNodeType parentType, int width) =>
WriteLine($"OnWidthKnown: Parent = {parent}, Type = {parentType}, Width = {width}");
public void OnProcessValue(ITreeValue value) =>
WriteLine($"OnProcessValue: {value}");
private void WriteLine(string str)
{
var indent = new string(' ', (DepthManager.Depth - 1) * 4);
Console.WriteLine($"{indent}{str}");
}
}Output:
OnLevelBegin: Parent = Root, Type = Group, Depth = 1
OnWidthKnown: Parent = Root, Type = Group, Width = 1
OnProcessValue: Local Probe
OnLevelBegin: Parent = Local Probe, Type = Probe, Depth = 2
OnWidthKnown: Parent = Local Probe, Type = Probe, Width = 2
OnProcessValue: Probe Device
OnLevelBegin: Parent = Probe Device, Type = Device, Depth = 3
OnWidthKnown: Parent = Probe Device, Type = Device, Width = 6
OnProcessValue: System Health
OnLevelBegin: Parent = System Health, Type = Sensor, Depth = 4
...Trees can be retrieved via the Get-PrtgTree cmdlet. If no parameters are specified, Get-PrtgTree will retrieve the entire object hierarchy, starting from the root node (ID: 0).
# Construct a tree containing the root node, as well as all child probes, groups, devices and sensors
Get-PrtgTreeThe tree of a specific object can be retrieved by piping in the desired root object, or specifying an object ID
# Construct a tree consisting of the device with ID 1001 and all of its descendants
Get-Device -Id 1001 | Get-PrtgTree# Construct a tree consisting of the object with ID 1001 and all of its descendants
Get-PrtgTree -Id 1001For maximum performance, by default Get-PrtgTree only retrieves probes, groups, devices and sensors (the Common objects). A specific subset of objects can be retrieved by specifying alternative -Options
# Construct a tree consisting of the object with ID 1001 and all of its descendants, including properties
Get-PrtgTree -Id 1001 -Options Common,Properties# Construct a tree consisting of all probes, groups, devices, sensors,
notification triggers, channels and properties within PRTG
Get-PrtgTree -Options AllYou can easily visualize your tree by passing it to the Show-PrtgTree cmdlet
Root
└──Local Probe
├──Probe Device
│ ├──Core Health
│ ├──Probe Health
│ └──System Health
└──Servers
├──dc-1
│ ├──Ping
...Depending on the type of tree emitted, Show-PrtgTree may colorize your output to signify different types of nodes or statuses. In the case of a standard PrtgNode tree, Show-PrtgTree will visualize the sensor Status (Up, Down, Paused, etc) of each of your sensors.
PrtgAPI provides a sophisticated modelling system that enables you to describe the "desired state" you would like to have within your PRTG installation. PrtgAPI is then able to compare this state against the actual state of the PRTG server, resulting in a task plan that can then be further evaluated or even executed against the PRTG server.
PrtgAPI provides several cmdlets that enable constructing nodes that describe hierarchies that can exist within PRTG
New-ChannelNodeNew-SensorNodeNew-DeviceNodeNew-GroupNodeNew-ProbeNodeNew-TriggerNode
As a shorthand, PrtgAPI allows you to eschew the New- prefix at the start of each cmdlet (i.e. rather than typing New-SensorNode, you can simply type SensorNode).
These cmdlets enable you to encapsulate values that you may already have
# Create a new SensorNode for all sensors named "ping"
Get-Sensor ping | New-SensorNodeor retrieve these values for you, and encapsulate them in a node
# Create a new SensorNode for the sensor with ID 1001
New-SensorNode -Id 1001If you have any existing children you want to wrap up, PrtgAPI can help you there as well
# Retrieve all non-inherited notification triggers from the sensor with ID 1001,
# and then add these as children of SensorNode encapsulating said sensor
New-TriggerNode -ObjectId 1001 | New-SensorNode -Id 1001However the true power of PrtgAPI's node cmdlets lies in their ability to model, declaratively, the desired state that should exist within a PRTG server. For more information, please see Infrastructure As Code.