Tutorial: Log the State of an Amazon EC2 Instance Using CloudWatch Events

Note Amazon EventBridge is the preferred way to manage your events. CloudWatch Events and EventBridge are the same underlying service and API, but EventBridge provides more features. Changes you make in either CloudWatch or EventBridge will appear in each console. For more information, see Amazon EventBridge.

You can create an AWS Lambda function that logs the changes in state for an Amazon EC2 instance. You can choose to create a rule that runs the function whenever there is a state transition or a transition to one or more states that are of interest. In this tutorial, you log the launch of any new instance.

Step 1: Create an AWS Lambda Function

Create a Lambda function to log the state change events. You specify this function when you create your rule.

To create a Lambda function

1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

2. If you are new to Lambda, you see a welcome page. Choose Get Started Now. Otherwise, choose Create a Lambda function.

3. On the Select blueprint page, type hello for the filter and choose the hello-world blueprint.

4. On the Configure triggers page, choose Next.

5. On the Configure function page, do the following:

   1. Type a name and description for the Lambda function. For example, name the function "LogEC2InstanceStateChange".

   2. Edit the sample code for the Lambda function. For example:

      'use strict';
      
      exports.handler = (event, context, callback) => {
          console.log('LogEC2InstanceStateChange');
          console.log('Received event:', JSON.stringify(event, null, 2));
          callback(null, 'Finished');
      };

   3. For Role, choose Choose an existing role. For Existing role, select your basic execution role. Otherwise, create a new basic execution role.

   4. Choose Next.

6. On the Review page, choose Create function.

Step 2: Create a Rule

Create a rule to run your Lambda function whenever you launch an Amazon EC2 instance.

To create a CloudWatch Events rule

1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

2. In the navigation pane, choose Events, Create rule.

3. For Event source, do the following:

   1. Choose Event Pattern.

   2. Choose Build event pattern to match events by service.

   3. Choose EC2, EC2 Instance State-change Notification.

   4. Choose Specific state(s), Running.

   5. By default, the rule matches any instance in the region. To make the rule match a specific instance, choose Specific instance(s) and then select one or more instances.

4. For Targets, choose Add target, Lambda function.

5. For Function, select the Lambda function that you created.

6. Choose Configure details.

7. For Rule definition, type a name and description for the rule.

8. Choose Create rule.

Step 3: Test the Rule

To test your rule, launch an Amazon EC2 instance. After waiting a few minutes for the instance to launch and initialize, you can verify that your Lambda function was invoked.

To test your rule by launching an instance

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. Launch an instance. For more information, see Launch Your Instance in the Amazon EC2 User Guide for Linux Instances.

3. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

4. In the navigation pane, choose Events, Rules, select the name of the rule that you created, and chooseShow metrics for the rule.

5. To view the output from your Lambda function, do the following:

   1. In the navigation pane, choose Logs.

   2. Choose the name of the log group for your Lambda function (/aws/lambda/function-name).

   3. Choose the name of log stream to view the data provided by the function for the instance that you launched.

6. (Optional) When you are finished, you can open the Amazon EC2 console and stop or terminate the instance that you launched. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances.