Skip to content

State Manipulation

Jump to bottom
lordmilko edited this page Apr 3, 2019 · 17 revisions

Contents

Overview

PrtgAPI is capable of performing a variety of state manipulation operations against PRTG, including the following:

  • Pausing objects for a specified duration (or indefinitely)
  • Acknowledging sensors in a Down status for a specified duration (or indefinitely)
  • Simulating an error status on sensors
  • Resuming monitoring on objects that have previously been paused, or have been put into a simulated error state

When manipulating object states, the state reported by PRTG may not update until the object has next refreshed. As such, if you wish to for the status to update immediately you can invoke the RefreshObject method (C#) or Refresh-Object cmdlet (PowerShell).

C#

Pause

Sensors, Devices, Groups and Probes can all be paused using the PauseObject method.

//Pause the object with ID 1234 for 10 minutes
client.PauseObject(1234, 10, "Restarting the server");

When pausing an object, the duration and pause message are optional. If a duration is not specified or is null, the object will be paused indefinitely.

//Pause the object 1001 indefinitely. No reason!
client.PauseObject(1001);

Certain PauseObject overloads allow you to specify a value of type Either<IPrtgObject, int>. Either an IPrtgObject or an int can be specified. This is useful if you already have a reference to the object you wish to pause.

//Pause an object using an object reference
client.PauseObject(sensor);

Multiple objects can be paused in a single request by specifying an array of object IDs

//Pause all sensors
client.PauseObject(client.GetSensors().Select(s => s.Id).ToArray());

Acknowledge

Sensors can be acknowledged with the AcknowledgeSensor method.

//Acknowledge all Down sensors for 15 minutes
var downSensors = client.GetSensors(Status.Down);

foreach(var sensor in downSensors)
{
    client.AcknowledgeSensor(sensor, 15, "Go away!");
}

Like PauseObject, the duration and message are optional. If the duration is not specified or is null, the sensor will be acknowledged indefinitely. Overloads that operate on a single sensor will accept either a Sensor object reference or the numeric sensor ID. Multiple objects can be acknowledged in a single request by specifying an array of object IDs.

Regardless of how long a sensor is acknowledged for, PRTG will continue attempting to monitor it. If the sensor returns to an Up status, in the event the sensor goes Down again the sensor will need to be re-acknowledged.

If you wish to remove an acknowledged state from a sensor, this can be done indirectly by pausing and then resuming the sensor. For more information, see the Pause and Resume sections above and below.

Simulate Error

Sensors can be put into a simulated error state (for testing notification triggers) with the SimulateError method

//Simulate an error on the sensor with ID 1001
client.SimulateError(1001);

When a sensor has been put into a simulated error state, it will remain in that state (even if it becomes paused) the sensor has been resumed (using the PRTG UI, or via the ResumeObject method). Even if the sensor is manually paused and resumed, the sensor will still need to receive an additional resume command to clear the simulated error status.

Multiple objects can be put into a simulated error state in a single request by specifying an array of object IDs.

Resume

Monitoring of an object that has been paused or put into a simulated error state can be resumed via the ResumeObject method

//Resume monitoring of all sensors that may have been directly paused (i.e. not by having
//paused their parent object going down). If the parent object was manually paused, any
//child objects will be PausedByUser as well
var pausedSensors = client.GetSensors(Status.PausedByUser);

foreach(var sensor in pausedSensors)
{
    client.ResumeObject(sensor.Id);
}

Multiple objects can be resumed in a single request by specifying an array of object IDs.

Refresh

Sensor objects will automatically periodically refresh themselves according to their defined Interval. If you wish to manually force a refresh of a sensor however (or on all child sensors of a parent object) this can be performed via the RefreshObject method

//Refresh the object with ID 3002
client.RefreshObject(3002);

Multiple objects can be refreshed in a single request by specifying an array of object IDs.

PowerShell

By default, all state manipulation cmdlets operate in batch mode. For information on batch mode, please see Batch Requests.

Pause

Sensors, Devices, Groups and Probes can be paused via the Pause-Object cmdlet

# Pause all devices named "dc-1" for 10 minutes
Get-Device dc-1 | Pause-Object -Duration 10 -Message "Restarting server"

Pause-Object allows you to specify the duration to pause for in three different ways

  • -Duration (in minutes)
  • -Until a specified DateTime
  • -Forever (until the object is manually unpaused)
# Pause all devices whose name contains "exch" until this time tomorrow
Get-Device *exch* | Pause-Object -Until (Get-Date).AddDays(1)
# Pause all ping sensors forever
Get-Sensor ping | Pause-Object -Forever -Message "Nobody needs ping sensors anyway"

Acknowledge

Sensors can be acknowledged via the Acknowledge-Sensor cmdlet

# Acknowledge all Down sensors for 10 minutes
Get-Sensor -Status Down | Acknowledge-Sensor -Duration 10 -Message "Nothing to see here"

Like Pause-Object, Acknowledge-Sensor allows you to specify the duration to acknowledge for in three different ways

  • -Duration (in minutes)
  • -Until a specified DateTime
  • -Forever (until the object returns Up, or is manually paused (clearing the acknowledged status))
# Acknowledge the sensor with ID 3134 until this time tomorrow
Get-Sensor -Id 3134 | Acknowledge-Sensor -Until (Get-Date).AddDays(1)
# Acknowledge all Down sensors whose device name contains "exch" forever
Get-Device *exch* | Get-Sensor -Status Down | Acknowledge-Sensor -Forever -Message "Who needs email anyway?"

Simulate Error

Sensors can be put into a simulated error status (for testing notification triggers) with the Simulate-ErrorStatus cmdlet

# Simulate an error status on the sensor with ID 1001
Get-Sensor -Id 1001 | Simulate-ErrorStatus

When a sensor has been put into a simulated error state, it will remain in that state (even if it becomes paused) the sensor has been resumed (using the PRTG UI, or via the Resume-Object cmdlet). Even if the sensor is manually paused and resumed, the sensor will still need to receive an additional resume command to clear the simulated error status.

Resume

Monitoring of an object that has been paused or put into a simulated error state can be resumed via the Resume-Object cmdlet

# Resume monitoring of all sensors that may have been directly paused (i.e. not by having
# paused their parent object going down). If the parent object was manually paused, any
# child objects will be PausedByUser as well
Get-Sensor -Status PausedByUser | Resume-Object
# Resume all objects in a simulated error state
flt message contains simulated | Get-Sensor | Resume-Object

Refresh

Sensor objects will automatically periodically refresh themselves according to their defined Interval. If you wish to manually force a refresh of a sensor however (or on all child sensors of a parent object) this can be performed via the Refresh-Object cmdlet

# Refresh the sensor with ID 3002
Get-Sensor -Id 3002 | Refresh-Object

See Also

Project Overview

User Guide

Utilities

Clone this wiki locally