AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Invokes the PutMetricAlarm operation against Amazon CloudWatch.

Syntax

Write-CWMetricAlarm
-AlarmName <String>
-AlarmDescription <String>
-ActionsEnabled <Boolean>
-AlarmAction <String[]>
-ComparisonOperator <ComparisonOperator>
-Dimension <Dimension[]>
-EvaluateLowSampleCountPercentile <String>
-EvaluationPeriod <Int32>
-ExtendedStatistic <String>
-InsufficientDataAction <String[]>
-MetricName <String>
-Namespace <String>
-OKAction <String[]>
-Period <Int32>
-Statistic <Statistic>
-Threshold <Double>
-TreatMissingData <String>
-Unit <StandardUnit>
-PassThru <SwitchParameter>
-Force <SwitchParameter>

Description

Creates or updates an alarm and associates it with the specified metric. Optionally, this operation can associate one or more Amazon SNS 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 state is set appropriately. Any actions associated with the state are then executed. When you update an existing alarm, its state is left unchanged, but the update completely overwrites the previous configuration of the alarm. If you are an IAM user, you must have Amazon EC2 permissions for some operations:
  • ec2:DescribeInstanceStatus and ec2:DescribeInstances for all alarms on EC2 instance status metrics
  • ec2:StopInstances for alarms with stop actions
  • ec2:TerminateInstances for alarms with terminate actions
  • ec2:DescribeInstanceRecoveryAttribute and ec2:RecoverInstances for alarms with recover actions
If you have read/write permissions for Amazon CloudWatch but not for Amazon EC2, you can still create an alarm, but the stop or terminate actions are not performed. However, if you are later granted the required permissions, the alarm actions that you created earlier are performed. If you are using an IAM role (for example, an EC2 instance profile), you cannot stop or terminate the instance using alarm actions. However, you can still see the alarm state and perform any other actions such as Amazon SNS notifications or Auto Scaling policies. If you are using temporary security credentials granted using AWS STS, you cannot stop or terminate an EC2 instance using alarm actions. You must create at least one stop, terminate, or reboot alarm using either the Amazon EC2 or CloudWatch consoles to create the EC2ActionsAccess IAM role. After this IAM role is created, you can create stop, terminate, or reboot alarms using a command-line interface or API.

Parameters

-ActionsEnabled <Boolean>
Indicates whether actions should be executed during any changes to the alarm state.
Required?False
Position?Named
Accept pipeline input?False
-AlarmAction <String[]>
The actions to execute when this alarm transitions to the ALARM state from any other state. Each action is specified as an Amazon Resource Name (ARN).Valid Values: arn:aws:automate:region:ec2:stop | arn:aws:automate:region:ec2:terminate | arn:aws:automate:region:ec2:recoverValid Values (for use with IAM roles): arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Stop/1.0 | arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Terminate/1.0 | arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Reboot/1.0
Required?False
Position?Named
Accept pipeline input?False
-AlarmDescription <String>
The description for the alarm.
Required?False
Position?2
Accept pipeline input?False
-AlarmName <String>
The name for the alarm. This name must be unique within the AWS account.
Required?False
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-ComparisonOperator <ComparisonOperator>
The arithmetic operation to use when comparing the specified statistic and threshold. The specified statistic value is used as the first operand.
Required?False
Position?Named
Accept pipeline input?False
-Dimension <Dimension[]>
The dimensions for the metric associated with the alarm.
Required?False
Position?Named
Accept pipeline input?False
-EvaluateLowSampleCountPercentile <String>
Used only for alarms based on percentiles. If you specify ignore, the alarm state does not change during periods with too few data points to be statistically significant. If you specify evaluate or omit this parameter, the alarm is always evaluated and possibly changes state no matter how many data points are available. For more information, see Percentile-Based CloudWatch Alarms and Low Data Samples.Valid Values: evaluate | ignore
Required?False
Position?Named
Accept pipeline input?False
-EvaluationPeriod <Int32>
The number of periods over which data is compared to the specified threshold. An alarm's total current evaluation period can be no longer than one day, so this number multiplied by Period cannot be more than 86,400 seconds.
Required?False
Position?Named
Accept pipeline input?False
-ExtendedStatistic <String>
The percentile statistic for the metric associated with the alarm. Specify a value between p0.0 and p100.
Required?False
Position?Named
Accept pipeline input?False
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?False
-InsufficientDataAction <String[]>
The actions to execute when this alarm transitions to the INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Name (ARN).Valid Values: arn:aws:automate:region:ec2:stop | arn:aws:automate:region:ec2:terminate | arn:aws:automate:region:ec2:recoverValid Values (for use with IAM roles): arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Stop/1.0 | arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Terminate/1.0 | arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Reboot/1.0
Required?False
Position?Named
Accept pipeline input?False
-MetricName <String>
The name for the metric associated with the alarm.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Namespace <String>
The namespace for the metric associated with the alarm.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-OKAction <String[]>
The actions to execute when this alarm transitions to an OK state from any other state. Each action is specified as an Amazon Resource Name (ARN).Valid Values: arn:aws:automate:region:ec2:stop | arn:aws:automate:region:ec2:terminate | arn:aws:automate:region:ec2:recoverValid Values (for use with IAM roles): arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Stop/1.0 | arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Terminate/1.0 | arn:aws:swf:us-east-1:{customer-account}:action/actions/AWS_EC2.InstanceId.Reboot/1.0
Required?False
Position?Named
Accept pipeline input?False
-PassThru <SwitchParameter>
Returns the value passed to the AlarmName parameter. By default, this cmdlet does not generate any output.
Required?False
Position?Named
Accept pipeline input?False
-Period <Int32>
The period, in seconds, over which the specified statistic is applied. Valid values are 10, 30, and any multiple of 60.Be sure to specify 10 or 30 only for metrics that are stored by a PutMetricData call with a StorageResolution of 1. If you specify a Period of 10 or 30 for a metric that does not have sub-minute resolution, the alarm still attempts to gather data at the period rate that you specify. In this case, it does not receive data for the attempts that do not correspond to a one-minute data resolution, and the alarm may often lapse into INSUFFICENT_DATA status. Specifying 10 or 30 also sets this alarm as a high-resolution alarm, which has a higher charge than other alarms. For more information about pricing, see Amazon CloudWatch Pricing.An alarm's total current evaluation period can be no longer than one day, so Period multiplied by EvaluationPeriods cannot be more than 86,400 seconds.
Required?False
Position?Named
Accept pipeline input?False
-Statistic <Statistic>
The statistic for the metric associated with the alarm, other than percentile. For percentile statistics, use ExtendedStatistic.
Required?False
Position?Named
Accept pipeline input?False
-Threshold <Double>
The value against which the specified statistic is compared.
Required?False
Position?Named
Accept pipeline input?False
-TreatMissingData <String>
Sets how this alarm is to handle missing data points. If TreatMissingData is omitted, the default behavior of missing is used. For more information, see Configuring How CloudWatch Alarms Treats Missing Data.Valid Values: breaching | notBreaching | ignore | missing
Required?False
Position?Named
Accept pipeline input?False
-Unit <StandardUnit>
The unit of measure for the statistic. For example, the units for the Amazon EC2 NetworkIn metric are Bytes because NetworkIn tracks the number of bytes that an instance receives on all network interfaces. You can also specify a unit when you create a custom metric. Units help provide conceptual meaning to your data. Metric data points that specify a unit of measure, such as Percent, are aggregated separately.If you specify a unit, you must use a unit that is appropriate for the metric. Otherwise, the CloudWatch alarm can get stuck in the INSUFFICIENT DATA state.
Required?False
Position?Named
Accept pipeline input?False

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required? False
Position? Named
Accept pipeline input? False
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required? False
Position? Named
Accept pipeline input? False
-ProfileLocation <String>

Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)

If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials. Note that the encrypted credential file is not supported on all platforms. It will be skipped when searching for profiles on Windows Nano Server, Mac, and Linux platforms.

If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.

As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.

Required? False
Position? Named
Accept pipeline input? False
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required? False
Position? Named
Accept pipeline input? False
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required? False
Position? Named
Accept pipeline input? False
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required? False
Position? Named
Accept pipeline input? False
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required? False
Position? Named
Accept pipeline input? False
-Region <String>
The system name of the AWS region in which the operation should be invoked. For example, us-east-1, eu-west-1 etc.
Required? False
Position? Named
Accept pipeline input? False
-EndpointUrl <String>

The endpoint to make the call against.

Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.

Required? False
Position? Named
Accept pipeline input? False

Inputs

You can pipe a String object to this cmdlet for the AlarmName parameter.

Outputs

None or System.String
When you use the PassThru parameter, this cmdlet outputs the value supplied to the AlarmName parameter. Otherwise, this cmdlet does not return any output. The service response (type Amazon.CloudWatch.Model.PutMetricAlarmResponse) can be referenced from properties attached to the cmdlet entry in the $AWSHistory stack.

Supported Version

AWS Tools for PowerShell: 2.x.y.z