Defining Alarms Using the AlarmSpec Data Object

The AlarmSpec data object has properties for all aspects of an Alarm, including its expression and the action to take when the expression evaluates to true. The following properties define the alarm; see the API Reference for a complete list.

■	action – Action to initiate when the Alarm becomes active. Specify one of the Action subtypes. See Specifying Alarm Actions.

■	actionFrequency – Number of seconds that the Alarm remains in the state required to initiate the specified action.

■	expression – One or more AlarmExpression data objects combined in a way that evaluates to a true-false expression. See Specifying Alarm Trigger Conditions with AlarmExpression.

■	setting – Tolerance and frequency limits for the Alarm defined in the AlarmSetting data object. AlarmSetting contains two integer properties:

■	reportingFrequency, which specifies the number of seconds between activation of an alarm. Use 0 to specify that the alarm can activate as frequently as required.

■	toleranceRange, which specifies the acceptable range (measured in hundredth percentage) above and below the specified value defined in a MetricAlarmExpression.

Specifying Alarm Trigger Conditions with AlarmExpression

You use the AlarmExpression data object to specify the conditions under which you want the Alarm to become active. The AlarmExpression data object is an abstract type with several subtypes, which allow you to specify thresholds on objects, state of objects, or specify specific events to monitor.

AlarmExpression and Its Subtypes

AlarmExpression Types

By using the appropriate type of AlarmExpression, you can set alarms for different conditions, states, or events.

Alarm Expressions and Examples 

AlarmExpression	Description	Example
StateAlarmExpression	Specifies thresholds that trigger the alarm.	Triggered by a power state change of a virtual machine or state change of a distributed virtual switch.
MetricAlarmExpression	Specifies levels at which the alarm changes state. See Using MetricAlarmExpression.	Triggered when resource utilization metrics exceed a specified limit.
EventAlarmExpression	Specifies a type of event as the basis for the alarm.	Triggered by power on or power off events of primary or secondary virtual machines in a fault-tolerant cluster.
EventAlarmComparison	Specifies the property of the Event that should trigger the alarm and the operator to use as the basis for comparison.
AndAlarmExpression OrAlarmExpression	Combines one or more instances of the AndAlarmExpression and the OrAlarmExpression data objects into an expression that evaluates to true or false.

Using MetricAlarmExpression

The MetricAlarmExpression data object lets you set an alarm to monitor performance metrics. The vSphere Client uses the data object to indicate when hosts or clusters do not have sufficient resources in a DAS or DRS cluster environment. See the Resource Management Guide.

You set the metric property to the PerfMetricId of a performance metric that you want to monitor on the system. Set the red or yellow properties to identify the level at which the metric value moves from green, to yellow, to red. You must define red, yellow, or both properties. Use each of these properties with the isAbove or isBelow MetricAlarmOperator enumerations to complete the definition of the threshold.

In conjunction with red and yellow properties, you can use the redInterval or yellowInterval properties. These properties enable you to set the number of seconds that the performance metric must be in red or yellow state before the expression becomes true and triggers the defined action.

Specifying Alarm Actions

You specify the actions that the system should take by setting the action property of the AlarmSpec data object to the AlarmAction data object defined for the purpose.

The AlarmAction data object is an abstract type that has two descendent objects.

■

The AlarmTriggeringAction data object has an action property and a transitionSpecs property. AlarmTriggeringActionTransitionSpec allows you to define a starting state and a final state for the Alarm. You can limit the number of Alarm objects actually triggered to a single Alarm by specifying false for the repeats property of the AlarmTriggeringActionTransitionSpec.

■	The GroupAlarmAction data object is an array version of the AlarmAction base type. You can create a single AlarmAction instance or an array of AlarmAction instances to take effect when the conditions specified for your alarm are met on the system.

The system can respond to an alarm in several ways:

■	Invoking an operation. To invoke an operation, create a MethodAction data object.

■	Running a Script. To run a script, create an instance of the RunScriptAction data object that specifies the fully qualified path to the shell script on the vCenter Server.

■	Send an email message. To send an email message to a system administrator, use the SendEmailAction data object.

AlarmAction and Related Objects

For example, you can use the MethodAction data object type to invoke an operation on the server. The MethodAction data object contains the following properties:

■	name—Name of the operation that you want to invoke at the scheduled time.

■	argument—Specifies required parameters, if any, as an array of MethodArgumentAction data objects.

Depending on the entity associated with the alarm, the MethodAction.argument property might not be needed.

Deleting or Disabling an Alarm

An Alarm remains active until you delete it or disable it. To delete the alarm, obtain a managed object reference to the Alarm and invoke its RemoveAlarm operation.

To disable the Alarm, obtain managed object references to the AlarmManager and to the entity on which the Alarm is set. Call AlarmManager.EnableAlarmActions operation, passing the value false for the enabled parameter.