# PutLogAlarm
<a name="API_PutLogAlarm"></a>

Creates or updates a log alarm. A log alarm evaluates the results of a CloudWatch Logs scheduled query against the configured threshold and comparison operator to determine its state.

When you create a log alarm, the operation creates a service-managed CloudWatch Logs scheduled query that runs the query string you provide on the schedule you configure. Each scheduled query execution returns one or more aggregated values determined by the `AggregationExpression`, and each aggregated value is compared against the alarm `Threshold` to determine the alarm state. The alarm uses M-out-of-N evaluation: if `QueryResultsToAlarm` out of the most recent `QueryResultsToEvaluate` query results breach the threshold, the alarm transitions to `ALARM`.

Log alarms support the alarm states (`OK`, `ALARM`, `INSUFFICIENT_DATA`). Configure transition actions using `OKActions`, `AlarmActions`, and `InsufficientDataActions`.

If you call this operation with the name of an existing log alarm, the operation replaces the previous configuration of that alarm.

 **Permissions** 

To create or update a log alarm, you must have the `cloudwatch:PutLogAlarm` permission. The IAM role specified in `ScheduledQueryRoleARN` must grant the CloudWatch Alarms service permission to execute scheduled queries on the specified log groups. If you set `ActionLogLineCount`, the role specified in `ActionLogLineRoleArn` must grant permission to retrieve log events for inclusion in alarm notifications.

## Request Syntax
<a name="API_PutLogAlarm_RequestSyntax"></a>

```
{
   "ActionConfiguration": { 
      "AlarmTagsPropagation": { 
         "Enabled": {{boolean}},
         "ExcludedTagKeys": [ "{{string}}" ],
         "IncludedTagKeys": [ "{{string}}" ]
      }
   },
   "ActionLogLineCount": {{number}},
   "ActionLogLineRoleArn": "{{string}}",
   "ActionsEnabled": {{boolean}},
   "AlarmActions": [ "{{string}}" ],
   "AlarmDescription": "{{string}}",
   "AlarmName": "{{string}}",
   "ComparisonOperator": "{{string}}",
   "InsufficientDataActions": [ "{{string}}" ],
   "OKActions": [ "{{string}}" ],
   "QueryResultsToAlarm": {{number}},
   "QueryResultsToEvaluate": {{number}},
   "ScheduledQueryConfiguration": { 
      "AggregationExpression": "{{string}}",
      "LogGroupIdentifiers": [ "{{string}}" ],
      "QueryARN": "{{string}}",
      "QueryString": "{{string}}",
      "ScheduleConfiguration": { 
         "EndTimeOffset": {{number}},
         "ScheduleExpression": "{{string}}",
         "StartTimeOffset": {{number}}
      },
      "ScheduledQueryRoleARN": "{{string}}",
      "Tags": [ 
         { 
            "Key": "{{string}}",
            "Value": "{{string}}"
         }
      ]
   },
   "Tags": [ 
      { 
         "Key": "{{string}}",
         "Value": "{{string}}"
      }
   ],
   "Threshold": {{number}},
   "TreatMissingData": "{{string}}",
   "WarmUpConfiguration": { 
      "OnlyStartEvaluatingAfterWarmUpPeriodEnds": {{boolean}},
      "WarmUpPeriodDurationInMinutes": {{number}}
   }
}
```

## Request Parameters
<a name="API_PutLogAlarm_RequestParameters"></a>

For information about the parameters that are common to all actions, see [Common Parameters](CommonParameters.md).

The request accepts the following data in JSON format.

 ** [ActionConfiguration](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-ActionConfiguration"></a>
Settings that change the content of the notifications and events that the alarm sends when its state changes. These settings apply to the alarm's actions, whichever state triggers them.  
Type: [ActionConfiguration](API_ActionConfiguration.md) object  
Required: No

 ** [ActionLogLineCount](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-ActionLogLineCount"></a>
The number of log lines from the most recent scheduled query execution to include in alarm action notifications. Valid range is 0 through 50. The default is 0, which means no log lines are included.  
Type: Integer  
Required: No

 ** [ActionLogLineRoleArn](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-ActionLogLineRoleArn"></a>
The Amazon Resource Name (ARN) of an IAM role that CloudWatch assumes to retrieve log events for inclusion in alarm action notifications. Required when `ActionLogLineCount` is greater than 0.  
Type: String  
Required: No

 ** [ActionsEnabled](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-ActionsEnabled"></a>
Indicates whether actions should be executed during any changes to the alarm state. The default is `true`.  
Type: Boolean  
Required: No

 ** [AlarmActions](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-AlarmActions"></a>
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:  
 **Amazon SNS actions:**   
 `arn:aws:sns:region:account-id:sns-topic-name `   
 **Lambda actions:**   
+ Invoke the latest version of a Lambda function: `arn:aws:lambda:region:account-id:function:function-name ` 
+ Invoke a specific version of a Lambda function: `arn:aws:lambda:region:account-id:function:function-name:version-number ` 
+ Invoke a function by using an alias Lambda function: `arn:aws:lambda:region:account-id:function:function-name:alias-name ` 
 **Systems Manager actions:**   
 `arn:aws:ssm:region:account-id:opsitem:severity `   
Type: Array of strings  
Array Members: Maximum number of 5 items.  
Length Constraints: Minimum length of 1. Maximum length of 1024.  
Required: No

 ** [AlarmDescription](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-AlarmDescription"></a>
The description for the alarm.  
Type: String  
Length Constraints: Minimum length of 0. Maximum length of 1024.  
Required: No

 ** [AlarmName](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-AlarmName"></a>
The name for the alarm. This name must be unique within the AWS account and Region.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 255.  
Required: Yes

 ** [ComparisonOperator](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-ComparisonOperator"></a>
The arithmetic operation to use when comparing the aggregated query result and the threshold. The aggregated query result is used as the first operand. Valid values are `GreaterThanThreshold`, `GreaterThanOrEqualToThreshold`, `LessThanThreshold`, and `LessThanOrEqualToThreshold`.  
Type: String  
Valid Values: `GreaterThanOrEqualToThreshold | GreaterThanThreshold | LessThanThreshold | LessThanOrEqualToThreshold | LessThanLowerOrGreaterThanUpperThreshold | LessThanLowerThreshold | GreaterThanUpperThreshold`   
Required: Yes

 ** [InsufficientDataActions](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-InsufficientDataActions"></a>
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:  
 **Amazon SNS actions:**   
 `arn:aws:sns:region:account-id:sns-topic-name `   
 **Lambda actions:**   
+ Invoke the latest version of a Lambda function: `arn:aws:lambda:region:account-id:function:function-name ` 
+ Invoke a specific version of a Lambda function: `arn:aws:lambda:region:account-id:function:function-name:version-number ` 
+ Invoke a function by using an alias Lambda function: `arn:aws:lambda:region:account-id:function:function-name:alias-name ` 
Type: Array of strings  
Array Members: Maximum number of 5 items.  
Length Constraints: Minimum length of 1. Maximum length of 1024.  
Required: No

 ** [OKActions](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-OKActions"></a>
The actions to execute when this alarm transitions to the `OK` state from any other state. Each action is specified as an Amazon Resource Name (ARN).  
Valid Values:  
 **Amazon SNS actions:**   
 `arn:aws:sns:region:account-id:sns-topic-name `   
 **Lambda actions:**   
+ Invoke the latest version of a Lambda function: `arn:aws:lambda:region:account-id:function:function-name ` 
+ Invoke a specific version of a Lambda function: `arn:aws:lambda:region:account-id:function:function-name:version-number ` 
+ Invoke a function by using an alias Lambda function: `arn:aws:lambda:region:account-id:function:function-name:alias-name ` 
Type: Array of strings  
Array Members: Maximum number of 5 items.  
Length Constraints: Minimum length of 1. Maximum length of 1024.  
Required: No

 ** [QueryResultsToAlarm](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-QueryResultsToAlarm"></a>
The number of query results, out of the most recent `QueryResultsToEvaluate` results, that must breach the threshold to trigger the alarm to transition to `ALARM` (the M in M-of-N evaluation). Must be less than or equal to `QueryResultsToEvaluate`.  
Type: Integer  
Valid Range: Minimum value of 1.  
Required: Yes

 ** [QueryResultsToEvaluate](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-QueryResultsToEvaluate"></a>
The number of most recent scheduled query results to evaluate against the threshold (the N in M-of-N evaluation). Valid range is 1 through 100.  
Type: Integer  
Valid Range: Minimum value of 1.  
Required: Yes

 ** [ScheduledQueryConfiguration](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-ScheduledQueryConfiguration"></a>
The configuration of the underlying CloudWatch Logs scheduled query that this alarm evaluates, including the query string, log groups, schedule, and aggregation expression.  
Type: [ScheduledQueryConfiguration](API_ScheduledQueryConfiguration.md) object  
Required: Yes

 ** [Tags](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-Tags"></a>
A list of key-value pairs to associate with the alarm. You can use tags to categorize and manage your alarms.  
Type: Array of [Tag](API_Tag.md) objects  
Required: No

 ** [Threshold](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-Threshold"></a>
The value to compare with the aggregated query result.  
Type: Double  
Required: Yes

 ** [TreatMissingData](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-TreatMissingData"></a>
Sets how this alarm is to handle missing data points. Valid values are `breaching`, `notBreaching`, `ignore`, and `missing`. If this parameter is omitted, the default behavior of `missing` is used.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 255.  
Required: No

 ** [WarmUpConfiguration](#API_PutLogAlarm_RequestSyntax) **   <a name="ACW-PutLogAlarm-request-WarmUpConfiguration"></a>
The warm-up configuration for the alarm. A warm-up period delays alarm evaluation after you create or update the alarm. The warm-up period reduces alarm noise from missing data while a new resource or service starts publishing data.  
For more information, see [Alarm warm-up periods](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/alarm-warm-up.html) in the *Amazon CloudWatch User Guide*.  
Type: [WarmUpConfiguration](API_WarmUpConfiguration.md) object  
Required: No

## Response Elements
<a name="API_PutLogAlarm_ResponseElements"></a>

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

## Errors
<a name="API_PutLogAlarm_Errors"></a>

For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md).

 ** LimitExceeded **   
The quota for alarms for this customer has already been reached.    
 ** message **   

HTTP Status Code: 400

 ** ResourceConflict **   
The operation could not be completed because the request conflicts with the current state of the alarm or its underlying scheduled query resource.  
HTTP Status Code: 409

## Examples
<a name="API_PutLogAlarm_Examples"></a>

### Create a log alarm that monitors error count
<a name="API_PutLogAlarm_Example_1"></a>

Create a log alarm that runs a CloudWatch Logs Insights query every 5 minutes counting log entries that contain "ERROR", and triggers when the count exceeds 10 in 3 of the last 5 evaluations.

#### Sample Request
<a name="API_PutLogAlarm_Example_1_Request"></a>

```
aws cloudwatch put-log-alarm \
    --alarm-name "HighErrorRateAlarm" \
    --alarm-description "Alarm when error count exceeds threshold" \
    --scheduled-query-configuration '{
        "QueryString": "fields @timestamp, @message | filter @message like /ERROR/",
        "LogGroupIdentifiers": ["arn:aws:logs:us-east-1:111122223333:log-group:/aws/lambda/my-function"],
        "ScheduledQueryRoleARN": "arn:aws:iam::111122223333:role/ScheduledQueryRole",
        "AggregationExpression": "count(*)",
        "ScheduleConfiguration": {
            "ScheduleExpression": "rate(5 minutes)",
            "StartTimeOffset": 360
        }
    }' \
    --query-results-to-alarm 3 \
    --query-results-to-evaluate 5 \
    --threshold 10.0 \
    --comparison-operator "GreaterThanThreshold" \
    --alarm-actions "arn:aws:sns:us-east-1:111122223333:my-topic" \
    --treat-missing-data "notBreaching"
```

#### Sample Response
<a name="API_PutLogAlarm_Example_1_Response"></a>

```
{
    "AlarmArn": "arn:aws:cloudwatch:us-east-1:111122223333:alarm:HighErrorRateAlarm"
}
```

## See Also
<a name="API_PutLogAlarm_SeeAlso"></a>

For more information about using this API in one of the language-specific AWS SDKs, see the following:
+  [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for C\+\+](https://docs.aws.amazon.com/goto/SdkForCpp/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/goto/boto3/monitoring-2010-08-01/PutLogAlarm) 
+  [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/monitoring-2010-08-01/PutLogAlarm)