Merge pull request #2517 from shubsmor/shubsmor-lambda-cloudwatch-sub…

…scription-sns-notification

New serverless pattern - lambda-cloudwatch-subscription-sns-notification

cloudwatch-account-subscription-Lambda-sns-notification/README.md

@@ -0,0 +1,81 @@
+# Account level alerting using Amazon CloudWatch, AWS Lambda and Amazon SNS
+
+This pattern demonstrates an alerting system that leverages an AWS CloudWatch Logs Account-level Subscription filter to trigger a Lambda function, which in turn sends an SNS notification when a specified pattern (in this case, "Exception") is matched in log events across any log group within the account. Currently, there is no out-of-the-box offering from AWS that allows customers to be alerted on specific event patterns across their entire account.
+
+By implementing this pattern, customers can proactively monitor and receive notifications for critical events or errors, such as exceptions or any specific pattern, that may occur in any of their applications or services. This centralized approach to log monitoring and alerting eliminates the need to configure individual alerting mechanisms for each log group or application, thereby streamlining the process and ensuring consistent alerting across the entire AWS account.
+
+Important: 
+* This application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+* Additionally, There is a risk of causing an infinite recursive loop with subscription filters that can lead to a large increase in ingestion billing if not addressed. To mitigate this risk, we recommend that you use selection criteria in your account-level subscription filters to exclude log groups that ingest log data from resources that are part of the subscription delivery workflow. Please see [Account-level subscription filters risk](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters-AccountLevel.html)
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed
+
+## Deployment Instructions
+
+1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
+    ``` 
+    git clone https://github.com/aws-samples/serverless-patterns
+    ```
+2. Change directory to the pattern directory:
+    ```
+    cd cloudwatch-account-subscription-Lambda-sns-notification
+    ```
+3. From the command line, use AWS SAM to deploy the AWS resources for the pattern as specified in the template.yml file:
+    ```
+    sam build
+
+    sam deploy --guided --parameter-overrides EmailAddress='[email protected]' LambdaFunctionName='NotificationLambda'
+    ```
+4. During the prompts:
+    * Enter a stack name
+    * Enter the desired AWS Region
+    * Allow SAM CLI to create IAM roles with the required permissions.
+
+    Once you have run `sam deploy --guided` mode once and saved arguments to a configuration file (samconfig.toml), you can use `sam deploy` in future to use these defaults.
+
+5. Note the outputs from the SAM deployment process. These contain the resource names and/or ARNs which are used for testing.
+
+## How it works
+
+The key components of this pattern are:
+
+1. AWS CloudWatch Logs Account-level Subscription Filter: This filter is configured to match the desired pattern ("Exception" in this case) and send the matching log events to a designated AWS Lambda function.
+
+2. AWS Lambda Function: This function processes the log events received from the subscription filter and sends a notification to an SNS topic when the specified pattern is matched.
+
+3. AWS Simple Notification Service (SNS) Topic: This SNS topic receives the notifications from the Lambda function and delivers them to subscribed endpoints, such as email addresses or mobile devices, enabling real-time alerting for critical events.
+
+
+This pattern deploys an account-level subscription filter that monitors all existing and new log groups for a matching log pattern of "Exception". This allows you to catch any event containing the "Exception" pattern across all applications within your AWS account. Optionally, you can produce an exception in any application's logs to test this pattern.
+*This pattern creates a new SNS topic with an email subscription. Please confirm the email verification by clicking on the "Confirm subscription" link sent via Amazon SNS.*
+
+## Testing
+To test this pattern, which monitors all log groups for the "Exception" pattern and sends SNS notifications, follow these steps:
+
+    - Choose an application generating logs in your AWS account.
+    - Intentionally introduce an exception or error condition that logs an "Exception" message.
+    - Verify the log event containing "Exception" is written to CloudWatch Logs.
+    - Monitor for an SNS email notification containing details like the log group name, log stream name, and the log event with the "Exception" pattern.
+
+This pattern automatically monitors new log groups created, ensuring comprehensive coverage across your AWS account.
+
+## Cleanup
+ 
+1. Delete the stack
+    ```bash
+    aws cloudformation delete-stack --stack-name STACK_NAME
+    ```
+1. Confirm the stack has been deleted
+    ```bash
+    aws cloudformation list-stacks --query "StackSummaries[?contains(StackName,'STACK_NAME')].StackStatus"
+    ```
+----
+Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0

cloudwatch-account-subscription-Lambda-sns-notification/cloudwatch-account-subscription-Lambda-sns-notification.json

@@ -0,0 +1,93 @@
+{
+    "title": "Account level alerting using Amazon CloudWatch, AWS Lambda and Amazon SNS",
+    "description": "Creates alerting system at account level which triggers Lambda function which can parse and publish a SNS notification",
+    "language": "Python",
+    "level": "200",
+    "framework": "SAM",
+    "introBox": {
+        "headline": "How it works",
+        "text": [
+            "This sample project showcases a centralized alerting system that leverages CloudWatch Logs Subscription filters and Lambda functions to trigger SNS notifications when a specified pattern is matched across any CloudWatch log group within the account. This robust solution enables comprehensive monitoring and proactive alerting, ensuring timely identification and mitigation of critical events or errors",
+            "The core components of this pattern include a CloudWatch Logs Account-level Subscription filter, which monitors log events across the entire account, and a notification Lambda function. This function is triggered by the Subscription filter and responsibly publishes relevant details, such as log group name, log stream name, and the matched log event, to the SNS topic, ensuring that stakeholders receive comprehensive and actionable information."
+        ]
+    },
+    "gitHub": {
+        "template": {
+            "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/cloudwatch-account-subscription-Lambda-sns-notification",
+            "templateURL": "serverless-patterns/cloudwatch-account-subscription-Lambda-sns-notification",
+            "projectFolder": "cloudwatch-account-subscription-Lambda-sns-notification",
+            "templateFile": "template.yaml"
+        }
+    },
+    "resources": {
+        "bullets": [
+            {
+                "text": "Account-level subscription filters",
+                "link": "https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters-AccountLevel.html#LambdaFunctionExample-AccountLevel"
+            },
+            {
+                "text": "Lambda function",
+                "link": "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+            }
+        ]
+    },
+    "deploy": {
+        "text": [
+            "sam build",
+            "sam deploy --guided --parameter-overrides EmailAddress='[email protected]' LambdaFunctionName='NotificationLambda'"
+        ]
+    },
+    "testing": {
+        "text": [
+            "To test this pattern, which monitors all log groups for the 'Exception' pattern and sends SNS notifications, follow these steps:",
+            "1. Choose an application generating logs in your AWS account.",
+            "2. Intentionally introduce an exception or error condition that logs an 'Exception' message.",
+            "3. Verify the log event containing 'Exception' is written to CloudWatch Logs.",
+            "4. Monitor for an SNS email notification containing details like the log group name, log stream name, and the log event with the 'Exception' pattern.",
+            "This pattern automatically monitors new log groups created, ensuring comprehensive coverage across your AWS account."
+        ]
+    },
+    "cleanup": {
+        "text": [
+            "Delete the stack: <code>cdk delete</code>."
+        ]
+    },
+    "authors": [
+        {
+            "name": "Shubham",
+            "image": "https://avatars.githubusercontent.com/u/150242047?s=400&u=aaa2db07529d3e1e82ec59daacb05b6abc7c3a5f&v=4",
+            "bio": "Cloud Support Engineer - SVLS",
+            "linkedin": "shubham-more-1b6aa185"
+        }
+    ],
+    "patternArch": {
+        "icon1": {
+            "x": 20,
+            "y": 50,
+            "service": "cloudwatch",
+            "label": "Amazon CloudWatch"
+        },
+        "icon2": {
+            "x": 50,
+            "y": 50,
+            "service": "lambda",
+            "label": "AWS Lambda"
+        },
+        "line1": {
+            "from": "icon1",
+            "to": "icon2",
+            "label": "trigger"
+        },
+        "icon3": {
+            "x": 80,
+            "y": 50,
+            "service": "sns",
+            "label": "Amazon SNS"
+        },
+        "line2": {
+            "from": "icon2",
+            "to": "icon3",
+            "label": "publish"
+        }
+    }
+}

cloudwatch-account-subscription-Lambda-sns-notification/example-pattern.json

@@ -0,0 +1,63 @@
+{
+  "title": "Account level alerting using Amazon CloudWatch, AWS Lambda and Amazon SNS",
+  "description": "Creates alerting system at account level which triggers Lambda function which can parse and publish a SNS notification",
+  "language": "Python",
+  "level": "200",
+  "framework": "SAM",
+  "introBox": {
+    "headline": "How it works",
+    "text": [
+      "This sample project showcases a centralized alerting system that leverages CloudWatch Logs Subscription filters and Lambda functions to trigger SNS notifications when a specified pattern is matched across any CloudWatch log group within the account. This robust solution enables comprehensive monitoring and proactive alerting, ensuring timely identification and mitigation of critical events or errors",
+      "The core components of this pattern include a CloudWatch Logs Account-level Subscription filter, which monitors log events across the entire account, and a notification Lambda function. This function is triggered by the Subscription filter and responsibly publishes relevant details, such as log group name, log stream name, and the matched log event, to the SNS topic, ensuring that stakeholders receive comprehensive and actionable information."
+    ]
+  },
+  "gitHub": {
+    "template": {
+      "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/cloudwatch-account-subscription-Lambda-sns-notification",
+      "templateURL": "serverless-patterns/cloudwatch-account-subscription-Lambda-sns-notification",
+      "projectFolder": "cloudwatch-account-subscription-Lambda-sns-notification",
+      "templateFile": "template.yaml"
+    }
+  },
+  "resources": {
+    "bullets": [
+      {
+        "text": "Account-level subscription filters",
+        "link": "https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters-AccountLevel.html#LambdaFunctionExample-AccountLevel"
+      },
+      {
+        "text": "Lambda function",
+        "link": "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+      }
+    ]
+  },
+  "deploy": {
+    "text": [
+      "sam build",
+      "sam deploy --guided --parameter-overrides EmailAddress='[email protected]' LambdaFunctionName='NotificationLambda'"
+    ]
+  },
+  "testing": {
+    "text": [
+      "To test this pattern, which monitors all log groups for the 'Exception' pattern and sends SNS notifications, follow these steps:",
+      "1. Choose an application generating logs in your AWS account.",
+      "2. Intentionally introduce an exception or error condition that logs an 'Exception' message.",
+      "3. Verify the log event containing 'Exception' is written to CloudWatch Logs.",
+      "4. Monitor for an SNS email notification containing details like the log group name, log stream name, and the log event with the 'Exception' pattern.",
+      "This pattern automatically monitors new log groups created, ensuring comprehensive coverage across your AWS account."
+    ]
+  },
+  "cleanup": {
+    "text": [
+      "Delete the stack: <code>cdk delete</code>."
+    ]
+  },
+  "authors": [
+    {
+      "name": "Shubham",
+      "image": "https://avatars.githubusercontent.com/u/150242047?s=400&u=aaa2db07529d3e1e82ec59daacb05b6abc7c3a5f&v=4",
+      "bio": "Cloud Support Engineer - SVLS",
+      "linkedin": "shubham-more-1b6aa185"
+    }
+  ]
+}

cloudwatch-account-subscription-Lambda-sns-notification/notification-lambda/index.py

@@ -0,0 +1,35 @@
+import json
+import boto3
+import gzip
+import base64
+from io import BytesIO
+import os
+sns = boto3.client('sns')
+
+def lambda_handler(event, context):
+    topicArn = os.environ['SNS_TOPIC_ARN']
+
+    compressed_log_data = event['awslogs']['data']
+    uncompressed_log_data = gzip.decompress(base64.b64decode(compressed_log_data))
+    print("Printing uncompressed_log_data :", uncompressed_log_data)
+
+    log_events = json.loads(uncompressed_log_data)['logEvents']
+    log_group = json.loads(uncompressed_log_data)['logGroup']
+    log_stream = json.loads(uncompressed_log_data)['logStream']
+
+    notification_message = f"*** An Exception has occurred within the specified log group. Please review the logs for detailed information and troubleshoot accordingly.***. \n Logdetails : \n Log events received from log group: {log_group}, log stream: {log_stream} \n log event: {log_events}"
+
+    response = sns.publish(
+        TopicArn=topicArn,
+        Message=notification_message,
+        Subject='Account Notification'
+        )
+
+    print(f"Notification published - messageID:", response['MessageId'])
+
+    return {
+        "statusCode": 200,
+        "body": json.dumps({
+            "message": "hello world"
+        }),
+    }

cloudwatch-account-subscription-Lambda-sns-notification/template.yaml

@@ -0,0 +1,76 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: SAM template to demonstrate alerting with CloudWatch Subscription Filter
+
+Parameters:
+  EmailAddress:
+    Type: String
+    Description: Email address to receive notifications
+
+  LambdaFunctionName:
+    Type: String
+    Description: Name of the Lambda function to be invoked by CloudWatch Logs
+
+Globals:
+  Function:
+    Timeout: 3
+    MemorySize: 128
+
+Resources:
+  # SNS Topic for notifications
+  NotificationTopic:
+    Type: AWS::SNS::Topic
+    Properties:
+      TopicName: AccountLevelNotificationTopic
+  # SNS Topic Subscription for Email Notifications
+
+  EmailSubscription:
+    Type: AWS::SNS::Subscription
+    Properties:
+      Endpoint: !Ref EmailAddress
+      Protocol: email
+      TopicArn: !Ref NotificationTopic
+
+  CloudWatchLogSubscriptionLambdaPermission:
+    Type: AWS::Lambda::Permission
+    Properties:
+      FunctionName: !GetAtt NotificationLambda.Arn
+      Principal: logs.amazonaws.com
+      Action: 'lambda:InvokeFunction'
+      SourceArn: !Sub 'arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:*'
+      SourceAccount: !Ref AWS::AccountId
+
+
+  CloudWatchLogSubscriptionPolicy:
+    Type: AWS::Logs::AccountPolicy
+    Properties:
+      PolicyName: CloudWatchLogsAccountLevelSubscriptionPolicy
+      PolicyDocument: !Sub "{\"DestinationArn\":\"arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:${LambdaFunctionName}\", \"FilterPattern\": \"Exception\", \"Distribution\": \"Random\"}"
+      SelectionCriteria: !Sub "LogGroupName NOT IN [\"/aws/lambda/example\", \"/custom/lambda/print\"]" #All the loggroups [Make sure to give valid loggroups] you would like to exclude this helps with log recursion prevention - https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Subscriptions-recursion-prevention.html
+      PolicyType: "SUBSCRIPTION_FILTER_POLICY"
+      Scope: "ALL"
+    DependsOn: CloudWatchLogSubscriptionLambdaPermission
+
+  # Notification Lambda function
+  NotificationLambda:
+    Type: AWS::Serverless::Function
+    Properties:
+      FunctionName: !Ref LambdaFunctionName
+      Handler: index.lambda_handler
+      Runtime: python3.13
+      CodeUri: notification-lambda/
+      Environment:
+        Variables:
+          SNS_TOPIC_ARN: !Ref NotificationTopic
+      Policies:
+        - SNSPublishMessagePolicy:
+            TopicName: !GetAtt NotificationTopic.TopicName
+
+
+Outputs:
+  NotificationLambdaArn:
+    Description: ARN of the Notification Lambda function
+    Value: !GetAtt NotificationLambda.Arn
+  NotificationTopicArn:
+    Description: ARN of the SNS Topic for notifications
+    Value: !Ref NotificationTopic