1// Code generated by smithy-go-codegen DO NOT EDIT. 2 3package cloudwatch 4 5import ( 6 "context" 7 awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware" 8 "github.com/aws/aws-sdk-go-v2/aws/signer/v4" 9 "github.com/aws/aws-sdk-go-v2/service/cloudwatch/types" 10 "github.com/aws/smithy-go/middleware" 11 smithyhttp "github.com/aws/smithy-go/transport/http" 12) 13 14// Creates or updates an alarm and associates it with the specified metric, metric 15// math expression, or anomaly detection model. Alarms based on anomaly detection 16// models cannot have Auto Scaling actions. When this operation creates an alarm, 17// the alarm state is immediately set to INSUFFICIENT_DATA. The alarm is then 18// evaluated and its state is set appropriately. Any actions associated with the 19// new state are then executed. When you update an existing alarm, its state is 20// left unchanged, but the update completely overwrites the previous configuration 21// of the alarm. If you are an IAM user, you must have Amazon EC2 permissions for 22// some alarm operations: 23// 24// * The iam:CreateServiceLinkedRole for all alarms with 25// EC2 actions 26// 27// * The iam:CreateServiceLinkedRole to create an alarm with Systems 28// Manager OpsItem actions. 29// 30// The first time you create an alarm in the AWS 31// Management Console, the CLI, or by using the PutMetricAlarm API, CloudWatch 32// creates the necessary service-linked rolea for you. The service-linked roles are 33// called AWSServiceRoleForCloudWatchEvents and 34// AWSServiceRoleForCloudWatchAlarms_ActionSSM. For more information, see AWS 35// service-linked role 36// (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). 37func (c *Client) PutMetricAlarm(ctx context.Context, params *PutMetricAlarmInput, optFns ...func(*Options)) (*PutMetricAlarmOutput, error) { 38 if params == nil { 39 params = &PutMetricAlarmInput{} 40 } 41 42 result, metadata, err := c.invokeOperation(ctx, "PutMetricAlarm", params, optFns, addOperationPutMetricAlarmMiddlewares) 43 if err != nil { 44 return nil, err 45 } 46 47 out := result.(*PutMetricAlarmOutput) 48 out.ResultMetadata = metadata 49 return out, nil 50} 51 52type PutMetricAlarmInput struct { 53 54 // The name for the alarm. This name must be unique within the Region. 55 // 56 // This member is required. 57 AlarmName *string 58 59 // The arithmetic operation to use when comparing the specified statistic and 60 // threshold. The specified statistic value is used as the first operand. The 61 // values LessThanLowerOrGreaterThanUpperThreshold, LessThanLowerThreshold, and 62 // GreaterThanUpperThreshold are used only for alarms based on anomaly detection 63 // models. 64 // 65 // This member is required. 66 ComparisonOperator types.ComparisonOperator 67 68 // The number of periods over which data is compared to the specified threshold. If 69 // you are setting an alarm that requires that a number of consecutive data points 70 // be breaching to trigger the alarm, this value specifies that number. If you are 71 // setting an "M out of N" alarm, this value is the N. An alarm's total current 72 // evaluation period can be no longer than one day, so this number multiplied by 73 // Period cannot be more than 86,400 seconds. 74 // 75 // This member is required. 76 EvaluationPeriods *int32 77 78 // Indicates whether actions should be executed during any changes to the alarm 79 // state. The default is TRUE. 80 ActionsEnabled *bool 81 82 // The actions to execute when this alarm transitions to the ALARM state from any 83 // other state. Each action is specified as an Amazon Resource Name (ARN). Valid 84 // Values: arn:aws:automate:region:ec2:stop | arn:aws:automate:region:ec2:terminate 85 // | arn:aws:automate:region:ec2:recover | arn:aws:automate:region:ec2:reboot | 86 // arn:aws:sns:region:account-id:sns-topic-name | 87 // arn:aws:autoscaling:region:account-id:scalingPolicy:policy-id:autoScalingGroupName/group-friendly-name:policyName/policy-friendly-name 88 // | arn:aws:ssm:region:account-id:opsitem:severity Valid Values (for use with IAM 89 // roles): arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Stop/1.0 90 // | arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Terminate/1.0 91 // | arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Reboot/1.0 92 AlarmActions []string 93 94 // The description for the alarm. 95 AlarmDescription *string 96 97 // The number of data points that must be breaching to trigger the alarm. This is 98 // used only if you are setting an "M out of N" alarm. In that case, this value is 99 // the M. For more information, see Evaluating an Alarm 100 // (https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarm-evaluation) 101 // in the Amazon CloudWatch User Guide. 102 DatapointsToAlarm *int32 103 104 // The dimensions for the metric specified in MetricName. 105 Dimensions []types.Dimension 106 107 // Used only for alarms based on percentiles. If you specify ignore, the alarm 108 // state does not change during periods with too few data points to be 109 // statistically significant. If you specify evaluate or omit this parameter, the 110 // alarm is always evaluated and possibly changes state no matter how many data 111 // points are available. For more information, see Percentile-Based CloudWatch 112 // Alarms and Low Data Samples 113 // (https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#percentiles-with-low-samples). 114 // Valid Values: evaluate | ignore 115 EvaluateLowSampleCountPercentile *string 116 117 // The percentile statistic for the metric specified in MetricName. Specify a value 118 // between p0.0 and p100. When you call PutMetricAlarm and specify a MetricName, 119 // you must specify either Statistic or ExtendedStatistic, but not both. 120 ExtendedStatistic *string 121 122 // The actions to execute when this alarm transitions to the INSUFFICIENT_DATA 123 // state from any other state. Each action is specified as an Amazon Resource Name 124 // (ARN). Valid Values: arn:aws:automate:region:ec2:stop | 125 // arn:aws:automate:region:ec2:terminate | arn:aws:automate:region:ec2:recover | 126 // arn:aws:automate:region:ec2:reboot | 127 // arn:aws:sns:region:account-id:sns-topic-name | 128 // arn:aws:autoscaling:region:account-id:scalingPolicy:policy-id:autoScalingGroupName/group-friendly-name:policyName/policy-friendly-name 129 // Valid Values (for use with IAM roles): 130 // >arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Stop/1.0 | 131 // arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Terminate/1.0 | 132 // arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Reboot/1.0 133 InsufficientDataActions []string 134 135 // The name for the metric associated with the alarm. For each PutMetricAlarm 136 // operation, you must specify either MetricName or a Metrics array. If you are 137 // creating an alarm based on a math expression, you cannot specify this parameter, 138 // or any of the Dimensions, Period, Namespace, Statistic, or ExtendedStatistic 139 // parameters. Instead, you specify all this information in the Metrics array. 140 MetricName *string 141 142 // An array of MetricDataQuery structures that enable you to create an alarm based 143 // on the result of a metric math expression. For each PutMetricAlarm operation, 144 // you must specify either MetricName or a Metrics array. Each item in the Metrics 145 // array either retrieves a metric or performs a math expression. One item in the 146 // Metrics array is the expression that the alarm watches. You designate this 147 // expression by setting ReturnData to true for this object in the array. For more 148 // information, see MetricDataQuery 149 // (https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDataQuery.html). 150 // If you use the Metrics parameter, you cannot include the MetricName, Dimensions, 151 // Period, Namespace, Statistic, or ExtendedStatistic parameters of PutMetricAlarm 152 // in the same operation. Instead, you retrieve the metrics you are using in your 153 // math expression as part of the Metrics array. 154 Metrics []types.MetricDataQuery 155 156 // The namespace for the metric associated specified in MetricName. 157 Namespace *string 158 159 // The actions to execute when this alarm transitions to an OK state from any other 160 // state. Each action is specified as an Amazon Resource Name (ARN). Valid Values: 161 // arn:aws:automate:region:ec2:stop | arn:aws:automate:region:ec2:terminate | 162 // arn:aws:automate:region:ec2:recover | arn:aws:automate:region:ec2:reboot | 163 // arn:aws:sns:region:account-id:sns-topic-name | 164 // arn:aws:autoscaling:region:account-id:scalingPolicy:policy-id:autoScalingGroupName/group-friendly-name:policyName/policy-friendly-name 165 // Valid Values (for use with IAM roles): 166 // arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Stop/1.0 | 167 // arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Terminate/1.0 | 168 // arn:aws:swf:region:account-id:action/actions/AWS_EC2.InstanceId.Reboot/1.0 169 OKActions []string 170 171 // The length, in seconds, used each time the metric specified in MetricName is 172 // evaluated. Valid values are 10, 30, and any multiple of 60. Period is required 173 // for alarms based on static thresholds. If you are creating an alarm based on a 174 // metric math expression, you specify the period for each metric within the 175 // objects in the Metrics array. Be sure to specify 10 or 30 only for metrics that 176 // are stored by a PutMetricData call with a StorageResolution of 1. If you specify 177 // a period of 10 or 30 for a metric that does not have sub-minute resolution, the 178 // alarm still attempts to gather data at the period rate that you specify. In this 179 // case, it does not receive data for the attempts that do not correspond to a 180 // one-minute data resolution, and the alarm might often lapse into 181 // INSUFFICENT_DATA status. Specifying 10 or 30 also sets this alarm as a 182 // high-resolution alarm, which has a higher charge than other alarms. For more 183 // information about pricing, see Amazon CloudWatch Pricing 184 // (https://aws.amazon.com/cloudwatch/pricing/). An alarm's total current 185 // evaluation period can be no longer than one day, so Period multiplied by 186 // EvaluationPeriods cannot be more than 86,400 seconds. 187 Period *int32 188 189 // The statistic for the metric specified in MetricName, other than percentile. For 190 // percentile statistics, use ExtendedStatistic. When you call PutMetricAlarm and 191 // specify a MetricName, you must specify either Statistic or ExtendedStatistic, 192 // but not both. 193 Statistic types.Statistic 194 195 // A list of key-value pairs to associate with the alarm. You can associate as many 196 // as 50 tags with an alarm. Tags can help you organize and categorize your 197 // resources. You can also use them to scope user permissions by granting a user 198 // permission to access or change only resources with certain tag values. If you 199 // are using this operation to update an existing alarm, any tags you specify in 200 // this parameter are ignored. To change the tags of an existing alarm, use 201 // TagResource 202 // (https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_TagResource.html) 203 // or UntagResource 204 // (https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_UntagResource.html). 205 Tags []types.Tag 206 207 // The value against which the specified statistic is compared. This parameter is 208 // required for alarms based on static thresholds, but should not be used for 209 // alarms based on anomaly detection models. 210 Threshold *float64 211 212 // If this is an alarm based on an anomaly detection model, make this value match 213 // the ID of the ANOMALY_DETECTION_BAND function. For an example of how to use this 214 // parameter, see the Anomaly Detection Model Alarm example on this page. If your 215 // alarm uses this parameter, it cannot have Auto Scaling actions. 216 ThresholdMetricId *string 217 218 // Sets how this alarm is to handle missing data points. If TreatMissingData is 219 // omitted, the default behavior of missing is used. For more information, see 220 // Configuring How CloudWatch Alarms Treats Missing Data 221 // (https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data). 222 // Valid Values: breaching | notBreaching | ignore | missing 223 TreatMissingData *string 224 225 // The unit of measure for the statistic. For example, the units for the Amazon EC2 226 // NetworkIn metric are Bytes because NetworkIn tracks the number of bytes that an 227 // instance receives on all network interfaces. You can also specify a unit when 228 // you create a custom metric. Units help provide conceptual meaning to your data. 229 // Metric data points that specify a unit of measure, such as Percent, are 230 // aggregated separately. If you don't specify Unit, CloudWatch retrieves all unit 231 // types that have been published for the metric and attempts to evaluate the 232 // alarm. Usually, metrics are published with only one unit, so the alarm works as 233 // intended. However, if the metric is published with multiple types of units and 234 // you don't specify a unit, the alarm's behavior is not defined and it behaves 235 // predictably. We recommend omitting Unit so that you don't inadvertently specify 236 // an incorrect unit that is not published for this metric. Doing so causes the 237 // alarm to be stuck in the INSUFFICIENT DATA state. 238 Unit types.StandardUnit 239} 240 241type PutMetricAlarmOutput struct { 242 // Metadata pertaining to the operation's result. 243 ResultMetadata middleware.Metadata 244} 245 246func addOperationPutMetricAlarmMiddlewares(stack *middleware.Stack, options Options) (err error) { 247 err = stack.Serialize.Add(&awsAwsquery_serializeOpPutMetricAlarm{}, middleware.After) 248 if err != nil { 249 return err 250 } 251 err = stack.Deserialize.Add(&awsAwsquery_deserializeOpPutMetricAlarm{}, middleware.After) 252 if err != nil { 253 return err 254 } 255 if err = addSetLoggerMiddleware(stack, options); err != nil { 256 return err 257 } 258 if err = awsmiddleware.AddClientRequestIDMiddleware(stack); err != nil { 259 return err 260 } 261 if err = smithyhttp.AddComputeContentLengthMiddleware(stack); err != nil { 262 return err 263 } 264 if err = addResolveEndpointMiddleware(stack, options); err != nil { 265 return err 266 } 267 if err = v4.AddComputePayloadSHA256Middleware(stack); err != nil { 268 return err 269 } 270 if err = addRetryMiddlewares(stack, options); err != nil { 271 return err 272 } 273 if err = addHTTPSignerV4Middleware(stack, options); err != nil { 274 return err 275 } 276 if err = awsmiddleware.AddRawResponseToMetadata(stack); err != nil { 277 return err 278 } 279 if err = awsmiddleware.AddRecordResponseTiming(stack); err != nil { 280 return err 281 } 282 if err = addClientUserAgent(stack); err != nil { 283 return err 284 } 285 if err = smithyhttp.AddErrorCloseResponseBodyMiddleware(stack); err != nil { 286 return err 287 } 288 if err = smithyhttp.AddCloseResponseBodyMiddleware(stack); err != nil { 289 return err 290 } 291 if err = addOpPutMetricAlarmValidationMiddleware(stack); err != nil { 292 return err 293 } 294 if err = stack.Initialize.Add(newServiceMetadataMiddleware_opPutMetricAlarm(options.Region), middleware.Before); err != nil { 295 return err 296 } 297 if err = addRequestIDRetrieverMiddleware(stack); err != nil { 298 return err 299 } 300 if err = addResponseErrorMiddleware(stack); err != nil { 301 return err 302 } 303 if err = addRequestResponseLogging(stack, options); err != nil { 304 return err 305 } 306 return nil 307} 308 309func newServiceMetadataMiddleware_opPutMetricAlarm(region string) *awsmiddleware.RegisterServiceMetadata { 310 return &awsmiddleware.RegisterServiceMetadata{ 311 Region: region, 312 ServiceID: ServiceID, 313 SigningName: "monitoring", 314 OperationName: "PutMetricAlarm", 315 } 316} 317