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 aboutcontainer_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
Open the IAM console at https://console.aws.amazon.com/iam/
. -
In the navigation pane, choose Roles.
-
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
. -
Choose the Permissions tab.
-
Under Permissions Policies, in the Permissions section, choose Attach policies.
-
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
For more information, see Viewing available metrics in the Amazon CloudWatch User Guide.