AWS AmazonCloudWatch documentation change
Summary
Added comprehensive documentation for creating Log Alarms using CloudWatch Logs Insights queries, including prerequisites (IAM roles), console steps, AWS CLI commands, and CloudFormation templates. Restructured document to introduce two alarm approaches: Log Alarm and metric filter.
Security assessment
The change adds detailed IAM role configurations and policies required for Log Alarms, which are security features. However, there's no evidence of addressing a specific security vulnerability or incident. The documentation focuses on operational setup of a new monitoring feature.
Diff
diff --git a/AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.md b/AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.md index 7694e95df..404d600e0 100644 --- a//AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.md +++ b//AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.md @@ -7 +7 @@ -Create an alarm based on a log group-metric filter +Create a Log Alarm @@ -11 +11 @@ Create an alarm based on a log group-metric filter -The steps in the following sections explain how to create CloudWatch alarms on logs. +You can create CloudWatch alarms that monitor your log data in two ways: @@ -13 +13,248 @@ The steps in the following sections explain how to create CloudWatch alarms on l -## Create a CloudWatch alarm based on a log group-metric filter + * **Log Alarm approach** — Create a Log Alarm that runs a CloudWatch Logs Insights query on a schedule and evaluates the aggregated results directly against a threshold. + + * **Metric filter approach** — Create a metric filter on a log group, then create a standard metric alarm on the resulting metric. + + + + +## Create a Log Alarm + +### Create a Log Alarm + +You can create a CloudWatch alarm that uses a CloudWatch Logs Insights query to monitor log data directly. The query runs on a schedule using a Scheduled Query, and the alarm evaluates the aggregated results against a threshold. For more information about how Log Alarms work, see [Log alarms](./alarm-log.html). + +### Prerequisites + +Before you create a Log Alarm, you must create an IAM role that grants CloudWatch Logs permission to execute the scheduled query. If you also want log lines included in Amazon SNS notifications, you must create a second role. + +###### Note + +If you create a Log Alarm from the CloudWatch console, the console helps you create these roles. + +#### Scheduled query execution role + +The scheduled query execution role allows CloudWatch Logs to run the query on your behalf. This role is required for all Log Alarms to execute the scheduled query. The role must trust the `logs.amazonaws.com` service principal. + +The following example shows the trust policy for the scheduled query execution role. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Service": "logs.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + } + +The following example shows the permissions policy. Scope the `Resource` to the log group ARNs that the query targets. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "logs:StartQuery", + "logs:StopQuery", + "logs:GetQueryResults", + "logs:DescribeLogGroups" + ], + "Resource": "arn:aws:logs:region:account-id:log-group:your-log-group:*" + } + ] + } + +#### Log lines role (optional) + +The log lines role allows CloudWatch to fetch log lines for Amazon SNS email notifications. This role is required only if you set `ActionLogLineCount` to a value greater than 0. The role must trust the `cloudwatch.amazonaws.com` service principal. + +The following example shows the trust policy for the log lines role. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Service": "cloudwatch.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + } + +The following example shows the permissions policy for the log lines role. The `logs:GetQueryResults` permission is required to fetch log lines. Scope the `Resource` to the log group ARNs that the query targets. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "logs:GetQueryResults" + ], + "Resource": "arn:aws:logs:region:account-id:log-group:your-log-group:*" + } + ] + } + +###### Note + +To view Log Alarm query results in the CloudWatch console, the IAM user or role accessing the console must have the `logs:GetScheduledQueryData` permission. This is a console-only API and is not available through the AWS CLI or SDK. CloudTrail logs this API as a data event, so you must configure a trail with data event logging to capture it. + +### Creating a Log Alarm using the console + +The steps in this section explain how to use the CloudWatch console to create a Log Alarm. You can also use the AWS CLI to create a Log Alarm. For more information, see Creating a Log Alarm using the AWS CLI. + +###### To create a Log Alarm + + 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). + + 2. In the navigation pane, choose **Alarms** , and then choose **All alarms**. + + 3. Choose **Create alarm**. + + 4. For **Data source** , choose **Logs**. + + 5. Under **Logs Query** : + + 1. For **Log groups** , choose one or more log groups to query. + + 2. In the query editor, enter your Logs Insights query. Choose **Preview results** to verify correct lines are getting considered. + + 3. For **Aggregation expression** , specify how to aggregate the query results to return a numerical value for alarm evaluation (for example, `count(*)` or `avg(latency) by endpoint`). + + 4. For **Schedule** , choose how often the query runs (for example, every 5 minutes). + + 6. Under **Alarm Conditions** : + + 1. For **Whenever the aggregated result is...** , choose a comparison operator. + + 2. For **than...** , enter the threshold value. + + 3. (Optional) Under **Additional Configuration** : + + 1. Modify **Datapoints to alarm** to specify the number of breaching results required to trigger `ALARM` out of last N queries. + + 2. Modify **Missing data treatment** to specify how to treat missing data. + + 7. Under **Schedule** : + + 1. For **Evaluation Frequency** , choose how often the query runs (for example, every 5 minutes). + + 2. For **Start time offset** , the lookback window for each query execution. + + 3. For **End time offset** (optional), the end of the query time range as an offset in seconds from the current time. + + 8. Under **IAM permission** : + + 1. Specify the role that is required to execute the scheduled query. You can either choose to create a new role or use an existing role. + + 9. Choose **Next**. + + 10. Under **Configure actions** , configure actions and notifications as needed. + + 1. To include log lines triggering the alarm transition in Amazon SNS email notifications, under **Include query results in the actions** : + + 1. Add **Number of query results** to specify the number of log lines to include. + + 2. Create or choose an existing role that is used to get the required query results. + + 11. Choose **Next**. + + 12. Enter a **Name** and optional **Description** (supports Markdown). + + 13. (Optional) Add tags. + + 14. Choose **Next**. + + 15. Under **Preview and create** , review your configuration, and then choose **Create alarm**. + + + + +### Creating a Log Alarm using the AWS CLI + +You can use the AWS CLI `put-log-alarm` command to create a Log Alarm. + +The following example creates a Log Alarm that monitors error counts in a log group and transitions to `ALARM` state when the count exceeds 100 in 3 out of 5 query executions. + + + aws cloudwatch put-log-alarm \ + --alarm-name "HighErrorCount" \ + --alarm-description "Alarm when error count exceeds 100" \ + --comparison-operator GreaterThanThreshold \ + --threshold 100 \ + --query-results-to-evaluate 5 \ + --query-results-to-alarm 3 \ + --treat-missing-data missing \ + --alarm-actions "arn:aws:sns:region:account-id:topic-name" \ + --scheduled-query-configuration '{