Alarming on logs

You can create CloudWatch alarms that monitor your log data in two ways:

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.

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.

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:*"
        }
    ]
}

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.

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 '{
        "QueryString": "fields @timestamp, @message | filter @message like /ERROR/",
        "LogGroupIdentifiers": ["/aws/lambda/my-function"],
        "ScheduledQueryRoleARN": "arn:aws:iam::account-id:role/ScheduledQueryRole",
        "AggregationExpression": "count(*)",
        "ScheduleConfiguration": {
            "ScheduleExpression": "rate(10 minutes)",
            "StartTimeOffset": 600
        }
    }' \
    --action-log-line-count 5 \
    --action-log-line-role-arn "arn:aws:iam::account-id:role/LogLineRole"

The following table describes the key parameters for the put-log-alarm command.

Creating a Log Alarm using AWS CloudFormation

You can use the AWS::CloudWatch::LogAlarm resource type to create a Log Alarm in a AWS CloudFormation template.

The following example template creates a Log Alarm that monitors error counts.

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  HighErrorCountAlarm:
    Type: AWS::CloudWatch::LogAlarm
    Properties:
      AlarmName: HighErrorCount
      AlarmDescription: Alarm when error count exceeds 100
      ComparisonOperator: GreaterThanThreshold
      Threshold: 100
      QueryResultsToEvaluate: 5
      QueryResultsToAlarm: 3
      TreatMissingData: missing
      ActionLogLineCount: 5
      ActionLogLineRoleArn: !GetAtt LogLineRole.Arn
      ScheduledQueryConfiguration:
        QueryString: "fields @timestamp, @message | filter @message like /ERROR/"
        LogGroupIdentifiers:
          - /aws/lambda/my-function
        ScheduledQueryRoleARN: !GetAtt ScheduledQueryRole.Arn
        AggregationExpression: "count(*)"
        ScheduleConfiguration:
          ScheduleExpression: "rate(10 minutes)"
          StartTimeOffset: 600
      AlarmActions:
        - !Ref AlarmSNSTopic

Create a CloudWatch alarm based on a log group-metric filter

The procedure in this section describes how to create an alarm based on a log group-metric filter. With metric filters, you can look for terms and patterns in log data as the data is sent to CloudWatch. For more information, see Create metrics from log events using filters in the Amazon CloudWatch Logs User Guide. Before you create an alarm based on a log group-metric filter, you must complete the following actions: