How to email your Amazon CloudWatch dashboard

Amazon CloudWatch enables customers to collect monitoring and operational data in the form of logs, metrics, alarms, and events, thereby allowing easy workload visualization and notifications. Many customers use Amazon CloudWatch  dashboards to monitor applications and infrastructure insights in order to have a unified dashboard for monitoring. Traditionally, operational health data access was only viewable for technical support staff; while there is an option to share the dashboard, users still need to log in to the AWS console to see the health of the dashboard.

In this blog, you will learn how to email your CloudWatch dashboards to your stakeholders. This solution allows your executives and on-call teams to receive emails with snapshots of CloudWatch dashboards, giving them at-glance access to the information without the need to log in to an AWS account.

Solution Overview

The solution will initiate based on an event trigger in Amazon EventBridge as an entry point for initiating the Lambda function. A Lambda function then will leverage CloudWatch API to get the requested dashboard. CloudWatch API will return the detailed information about the dashboard, including what widgets are included and their location on the dashboard. Once we have the list of widgets, we call another CloudWatch API to retrieve an image of the widget. You need to get details of each widget separately. Once you get the requested images, the solution will send a notification to the Amazon Simple Email Service (Amazon SES) queue, which sends the email to subscribers.

Email CloudWatch Metrics Dashboard Architecture

Prerequisites

To get hands-on experience with all the features described in this post, complete the following prerequisites:

1. Ensure that you have an AWS account, secure access to log in to the account via the AWS Management Console, and AWS Identity and Access Management (IAM) permissions to use Amazon CloudWatch and Amazon Simple Email Service (Amazon SES) resources.
2. Access to Create AWS Lambda Function and send emails with Amazon SES.
3. Permission to set up Amazon EventBridge to set up the schedule.
4. Permission to create IAM policy and IAM role.

Solution Walkthrough

The steps below will guide you through building the solution. The high-level steps are:

1. Configure Amazon SES to send emails on behalf of the Lambda function
   • Create a Configuration Set. Amazon SES documentation – Configuration sets.
   • Create Verified identities. Amazon SES documentation – Verifies identities.
2. Run the CloudFormation template that will
   • Create an IAM Policy with the necessary permissions for your Lambda Function.
   • Create an IAM Role, attach the IAM Policy created.
   • Create the AWS Lambda Function.
   • Create the Amazon EventBridge Schedule.

To create an Amazon SES Configuration set (console)

1. Sign in to the AWS Management Console and open the Amazon SES console at https://console.aws.amazon.com/ses/.
2. On the AWS console, choose the region where your solution will be deployed.
3. In the navigation pane, under Configuration, choose Configuration sets.
4. Choose Create set.
5. For Configuration set name box, enter a unique name for your set. For example, cw-dashboard-alerts.
6. Leave all other options as default.
7. Choose Create set.

To create an Amazon SES Verified identity (console)

1. Sign in to the AWS Management Console and open the Amazon SES console at https://console.aws.amazon.com/ses/.
2. On the AWS console, choose the region where your solution will be deployed.
3. In the navigation pane, under Configuration, choose Verified identities.
4. Choose Create identity.
5. For Identity Details, choose Email address.
   • For Email address box, enter a valid email address. We recommend utilizing a distribution list.
6. Select Assign a default configuration set.
   • For Default configuration set, choose the configuration set created earlier.
7. Choose Create identity.
8. Upon creation, you will see a status page where Identity status shows as Verification pending. To change it to verified:
   • The email address entered will receive a verification email with the subject Amazon Web Services – Email Address Verification Request in region <region>.
   • Open that email and click on the link provided. The link will start with https://email-verification and end with amazonaws.com.
   • You should see this page:
     

     Verified Identity

   • Return to the Amazon SES console and refresh the page, it should show the Identity status as Verified.

• AWS CloudFormation stack template
  • Download stack template file from this link.
  • Navigate to AWS CloudFormation.
  • Choose Create stack, then choose With new resources.
  • Choose Template is ready.
  • Choose Upload a template file.
  • Select Choose file, then select local file you just downloaded.
  • Choose Next.

• On the Specify stack details page
  • Enter a Stack name as CWDashboardEmailStack.
  • For CWDashboardList, enter All to send all CloudWatch dashboards that the Lambda function can access, or a comma-separated list of the names of the CloudWatch dashboards you want the image to be sent via email.
  • For EmailRecipient enter the email address configured as a verified identity in the SES steps. This is where the email with the dashboard images will be sent to.
  • For EmailSender enter an email address that will show as the FROM address on the email sent.
  • For LambdaExecSchedule enter number of minutes interval between
    • each execution of the Lambda Function
  • For SESConfigSet enter the name of the Amazon SES configuration set created in the prior steps.
  • Choose Next.
  • Choose Next.
  • Select I acknowledge that AWS CloudFormation might create IAM resources.
  • Choose Submit.
• Wait until the stack state changes from CREATE_IN_PROGRESS to CREATE_COMPLETE. This process will take a few minutes.
• After the stack has completed deployment, on the stack details, select Resources to see the Amazon Resource Names of the resources that were created.

Lambda Code Walkthrough

Code Flow

1. The Lambda function performs the following steps to generate images and send as emails:
   • Using CloudWatch APIs, and the CloudWatch Dashboard name provided in the Lambda function Environment variables, generate a list of Dashboard widget names.
   • Iterate in a for-loop over the Dashboard Widget Names and call CloudWatch Image API to generate images for each widget.
   • Create an email body in HTML format.
   • Attach Images along with HTML email body and send email using Amazon SES API.
2. IAM role associated with Lambda function should have permissions to perform these actions:
   • Execute Function;
   • Use the KMS key to decrypt Lambda environment variables;
   • Perform CloudWatch API calls to
     • List dashboards,
     • Read dashboard information. There is a limit of 20 transactions per second for this API.
     • Retrieve widget image. This is limited to 100 metrics in the graph and up to 100 KB uncompressed payload.
   • Send logs and post metrics to CloudWatch;
   • Send Emails via Amazon SES;
3. Lambda function is parametrized via environment variables.
   • CONFIGURATION_SET: Amazon SES config set name.
   • DASHBOARD_LIST: Which dashboards to send, or send All.
   • RECIPIENT: Recipient for the email with dashboard images.
   • SENDER: From email address.

Lambda Function Environment Variables

Deploy the Lambda Function and EventBridge Scheduler

We’ve provided an AWS CloudFormation template that you can use to deploy the solution. The template creates the following AWS resources in your account:

• IAM role and policy
• Lambda Function
• EventBridge Scheduler to execute Lambda Function

In addition, the AWS CloudFormation template creates

• CloudWatch Log Group for logging Lambda execution logs

Amazon Simple Email Service configuration set with email setup is a pre-requisite for the AWS CloudFormation stack and is provided as a parameter for the AWS CloudFormation template.

Clean up:

For cost optimization, after you complete and test this solution, clean up the resources. You can delete them by deleting cloud formation stack: CWDashboardEmailStack.

Limitations:

• This solution uses get_metric_widget_image, which is restricted to widgets of the metric type. The call is limited to 100 metrics shown in the widget graph and up to 100KB uncompressed payload.
  Amazon SES accepts messages up to 40 MB in size as per FAQ.
• Metrics in an Amazon CloudWatch Dashboard Widget need to be from same Region.
• Amazon CloudWatch Dashboard Gauge Widgets will appear as time series line graphs in emails.
• Scaling options for Lambda function
  • Increase the Lambda function memory limit and timeout values
  • Distribute Amazon CloudWatch Dashboards across multiple Lambda Functions

Conclusion:

This solution allows your executives and on-call teams to receive emails with a snapshot of configured CloudWatch dashboards, without the need for them to have or log in to an AWS account.

About the Authors