put_metric_alarm ( $alarm_name, $metric_name, $namespace, $statistic, $period, $evaluation_periods, $threshold, $comparison_operator, $opt )

Creates or updates an alarm and associates it with the specified Amazon CloudWatch metric. Optionally, this operation can associate one or more Amazon Simple Notification Service resources with the alarm.

When this operation creates an alarm, the alarm state is immediately set to INSUFFICIENT_DATA. The alarm is evaluated and its StateValue is set appropriately. Any actions associated with the StateValue is then executed.

When updating an existing alarm, its StateValue is left unchanged.

Access

public

Parameters

Parameter

Type

Required

Description

$alarm_name

string

Required

The descriptive name for the alarm. This name must be unique within the user’s AWS account

$metric_name

string

Required

The name for the alarm’s associated metric.

$namespace

string

Required

The namespace for the alarm’s associated metric. [Constraints: The value must be between 1 and 255 characters, and must match the following regular expression pattern: [^:].*]

$statistic

string

Required

The statistic to apply to the alarm’s associated metric. [Allowed values: SampleCount, Average, Sum, Minimum, Maximum]

$period

integer

Required

The period in seconds over which the specified statistic is applied.

$evaluation_periods

integer

Required

The number of periods over which data is compared to the specified threshold.

$threshold

double

Required

The value against which the specified statistic is compared.

$comparison_operator

string

Required

The arithmetic operation to use when comparing the specified Statistic and Threshold. The specified Statistic value is used as the first operand. [Allowed values: GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, LessThanOrEqualToThreshold]

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • AlarmDescription - string - Optional - The description for the alarm.
  • ActionsEnabled - boolean - Optional - Indicates whether or not actions should be executed during any changes to the alarm’s state.
  • OKActions - string|array - Optional - The list of actions to execute when this alarm transitions into an OK state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only action supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy. Pass a string for a single value, or an indexed array for multiple values.
  • AlarmActions - string|array - Optional - The list of actions to execute when this alarm transitions into an ALARM state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only action supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy. Pass a string for a single value, or an indexed array for multiple values.
  • InsufficientDataActions - string|array - Optional - The list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the only action supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy. Pass a string for a single value, or an indexed array for multiple values.
  • Dimensions - array - Optional - The dimensions for the alarm’s associated metric.
    • x - array - Optional - This represents a simple array index.
      • Name - string - Required - The name of the dimension.
      • Value - string - Required - The value representing the dimension measurement
  • Unit - string - Optional - The unit for the alarm’s associated metric. [Allowed values: Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, Megabits, Gigabits, Terabits, Percent, Count, Bytes/Second, Kilobytes/Second, Megabytes/Second, Gigabytes/Second, Terabytes/Second, Bits/Second, Kilobits/Second, Megabits/Second, Gigabits/Second, Terabits/Second, Count/Second, None]
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Create or update a new metric alarm.

$cw = new AmazonCloudWatch();

$response = $cw->put_metric_alarm(
	'my-alarm',         // Alarm name
	'CPUUtilization',            // Metric name
	'AWS/EC2',                   // Namespace
	'Average',                   // Statistic
	1800,                        // Period
	3,                           // Evaluation periods
	50,                          // Threshold
	'LessThanOrEqualToThreshold' // Comparison operator
);

// Success?
var_dump($response->isOK());
Result:
bool(true)

Create or update a new metric alarm.

$cw = new AmazonCloudWatch();

$response = $cw->put_metric_alarm(
	'my-other-alarm',         // Alarm name
	'CPUUtilization',             // Metric name
	'AWS/EC2',                    // Namespace
	'Average',                    // Statistic
	1800,                         // Period
	3,                            // Evaluation periods
	50,                           // Threshold
	'LessThanOrEqualToThreshold', // Comparison operator
array(
	'AlarmDescription' => 'This is a description of the alarm.',
	'ActionsEnabled' => 'true',
	'Unit' => 'Seconds'
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Related Methods

Source

Method defined in services/cloudwatch.class.php | Toggle source view (50 lines) | View on GitHub

public function put_metric_alarm($alarm_name, $metric_name, $namespace, $statistic, $period, $evaluation_periods, $threshold, $comparison_operator, $opt = null)
{
    if (!$opt) $opt = array();
    $opt['AlarmName'] = $alarm_name;
    $opt['MetricName'] = $metric_name;
    $opt['Namespace'] = $namespace;
    $opt['Statistic'] = $statistic;
    $opt['Period'] = $period;
    $opt['EvaluationPeriods'] = $evaluation_periods;
    $opt['Threshold'] = $threshold;
    $opt['ComparisonOperator'] = $comparison_operator;
    
    // Optional list (non-map)
    if (isset($opt['OKActions']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'OKActions' => (is_array($opt['OKActions']) ? $opt['OKActions'] : array($opt['OKActions']))
        ), 'member'));
        unset($opt['OKActions']);
    }
    
    // Optional list (non-map)
    if (isset($opt['AlarmActions']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'AlarmActions' => (is_array($opt['AlarmActions']) ? $opt['AlarmActions'] : array($opt['AlarmActions']))
        ), 'member'));
        unset($opt['AlarmActions']);
    }
    
    // Optional list (non-map)
    if (isset($opt['InsufficientDataActions']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'InsufficientDataActions' => (is_array($opt['InsufficientDataActions']) ? $opt['InsufficientDataActions'] : array($opt['InsufficientDataActions']))
        ), 'member'));
        unset($opt['InsufficientDataActions']);
    }
    
    // Optional list + map
    if (isset($opt['Dimensions']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'Dimensions' => $opt['Dimensions']
        ), 'member'));
        unset($opt['Dimensions']);
    }

    return $this->authenticate('PutMetricAlarm', $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback