Example: Using custom Amazon CloudWatch metrics

This topic provides a configuration example that integrates Elastic Beanstalk metrics with Amazon CloudWatch agent for platforms based on Amazon Linux 2 and later. The configuration example uses files and commands in an .ebextensions configuration file.

Amazon CloudWatch is a web service that enables you to monitor, manage, and publish various metrics, as well as configure alarm actions based on data from metrics. You can define custom metrics for your own use, and Elastic Beanstalk will push those metrics to Amazon CloudWatch. Once Amazon CloudWatch contains your custom metrics, you can view those in the Amazon CloudWatch console.

Important

The Amazon CloudWatch monitoring scripts are deprecated. The CloudWatch agent has now replaced the CloudWatch monitoring scripts to collect metrics and logs.

If you're still migrating from the deprecated monitoring scripts to the agent, and require information about the monitoring scripts, see Deprecated: Collect metrics using the CloudWatch monitoring scripts in the Amazon EC2 User Guide.

The Amazon CloudWatch agent

The Amazon CloudWatch agent enables CloudWatch metric and log collection from both Amazon EC2 instances and on-premises servers across operating systems. The agent supports metrics collected at the system level. It also supports custom log and metric collection from your applications or services. For more information about the Amazon CloudWatch agent, see Collecting metrics and logs with the CloudWatch agent in the Amazon CloudWatch User Guide.

Note

Elastic Beanstalk Enhanced Health Reporting has native support for publishing a wide range of instance and environment metrics to CloudWatch. See Publishing Amazon CloudWatch custom metrics for an environment for details.

.Ebextensions configuration file

This example uses files and commands in an .ebextensions configuration file to configure and run the Amazon CloudWatch agent on the Amazon Linux 2 platform. The agent is prepackaged with Amazon Linux 2. If you're using a different operating system, additional steps for installing the agent may be necessary. For more information, see Installing the CloudWatch agent in the Amazon CloudWatch User Guide.

To use this sample, save it to a file named cloudwatch.config in a directory named .ebextensions at the top level of your project directory, then deploy your application using the Elastic Beanstalk console (include the .ebextensions directory in your source bundle) or the EB CLI.

For more information about configuration files, see Advanced environment customization with configuration files (.ebextensions).

.ebextensions/cloudwatch.config

files:  
  "/opt/aws/amazon-cloudwatch-agent/bin/config.json": 
    mode: "000600"
    owner: root
    group: root
    content: |
      {
        "agent": {
          "metrics_collection_interval": 60,
          "run_as_user": "root"
        },
        "metrics": {
          "namespace": "System/Linux",
          "append_dimensions": {
            "AutoScalingGroupName": "${aws:AutoScalingGroupName}"
          },
          "metrics_collected": {
            "mem": {
              "measurement": [
                "mem_used_percent"
              ]
            }
          }
        }
      }  
container_commands:
  start_cloudwatch_agent: 
    command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -m ec2 -s -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json

This file has two sections:

• files — This section adds the agent configuration file. It indicates which metrics and logs the agent should send to Amazon CloudWatch. In this example, we're only sending the mem_used_percent metric. For a complete listing of system level metrics supported by the Amazon CloudWatch agent, see Metrics collected by the CloudWatch agent in the Amazon CloudWatch User Guide.

• container_commands — This section contains the command that starts the agent, passing in the configuration file as a parameter. For more details about container_commands, see Container commands.

Permissions

The instances in your environment need the proper IAM permissions in order to publish custom Amazon CloudWatch metrics using the Amazon CloudWatch agent. You grant permissions to your environment's instances by adding them to the environment's instance profile. You can add permissions to the instance profile before or after deploying your application.

To grant permissions to publish CloudWatch metrics

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles.

3. Choose your environment's instance profile role. By default, when you create an environment with the Elastic Beanstalk console or EB CLI, this is aws-elasticbeanstalk-ec2-role.

4. Choose the Permissions tab.

5. Under Permissions Policies, in the Permissions section, choose Attach policies.

6. Under Attach Permissions, choose the AWS managed policy CloudWatchAgentServerPolicy. Then click Attach policy.

For more information about managing policies, see Working with Policies in the IAM User Guide.

Viewing metrics in the CloudWatch console

After deploying the CloudWatch configuration file to your environment, check the Amazon CloudWatch console to view your metrics. Custom metrics will be located in the CWAgent namespace.

For more information, see Viewing available metrics in the Amazon CloudWatch User Guide.