# Monitoring environments in Elastic Beanstalk
With Elastic Beanstalk health monitoring, you can verify application availability and create alerts that activate when metrics exceed your thresholds. You can use Elastic Beanstalk health monitoring in both the console and command line to track your environment's status.
**Topics**
+ [Monitoring environment health in the AWS management console](environment-health-console.md)
+ [Using the EB CLI to monitor environment health](health-enhanced-ebcli.md)
+ [Basic health reporting](using-features.healthstatus.md)
+ [Enhanced health reporting and monitoring in Elastic Beanstalk](health-enhanced.md)
+ [Manage alarms](using-features.alarms.md)
+ [Viewing an Elastic Beanstalk environment's change history](using-features.changehistory.md)
+ [Viewing an Elastic Beanstalk environment's event stream](using-features.events.md)
+ [Listing and connecting to server instances](using-features.ec2connect.md)
+ [Viewing logs from Amazon EC2 instances in your Elastic Beanstalk environment](using-features.logging.md)
+ [Viewing deployment logs for an Elastic Beanstalk environment](environments-deployment-logs.md)
# Monitoring environment health in the AWS management console
You can access operational information about your application from the Elastic Beanstalk console. The console displays your environment's status and application health at a glance. In the console's **Environments** page and in each application's page, the environments on the list are color-coded to indicate status.
**To monitor an environment in the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Monitoring**.
The Monitoring page shows you overall statistics about your environment, such as CPU utilization and average latency. In addition to the overall statistics, you can view monitoring graphs that show resource usage over time. You can click any of the graphs to view more detailed information.
**Note**
By default, only basic CloudWatch metrics are enabled, which return data in five-minute periods. You can enable more granular one-minute CloudWatch metrics by editing your environment's configuration settings.
## Monitoring graphs
The **Monitoring** page shows an overview of health-related metrics for your environment. This includes the default set of metrics provided by Elastic Load Balancing and Amazon EC2, and graphs that show how the environment's health has changed over time.
The bar above the graphs provides a variety of time intervals for you to select. For example, select **1w** to display information that spans over the last week. Or select **3h** to display information that spans over the last three hours.
For a greater variety of time interval selections, choose **Custom**. From here you have two range options: *Absolute* or *Relative*. The **Absolute** option allows you to specify a specific date range, such as *January 1, 2023 to June 30, 2023*. The **Relative** option allows to select an integer with a specific time unit: *Minutes*, *Hours,* *Days*, *Weeks*, or *Months*. Examples include *10 Hours*, *10 Days*, and *10 Months*.
![\[Environment health monitoring section on the environment monitoring page of the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-monitoring-graphs.png)
## Customizing the monitoring console
To create and view custom metrics you must use Amazon CloudWatch. With CloudWatch you can create custom dashboards to monitor your resources in a single view. Select **Add to dashboard** to navigate to the Amazon CloudWatch console from the **Monitoring** page. Amazon CloudWatch provides you the option to create a new dashboard or select an existing one. For more information, see [Using Amazon CloudWatch dashboards](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) in the *Amazon CloudWatch User Guide*.
![\[Environment health monitoring section on the environment monitoring page of the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-monitoring-graphs.png)
[Elastic Load Balancing](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/elb-metricscollected.html) and [Amazon EC2](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/ec2-metricscollected.html) metrics are enabled for all environments.
With [enhanced health](health-enhanced.md), the EnvironmentHealth metric is enabled, and a graph is added to the monitoring console automatically. Enhanced health also adds the [Health page](health-enhanced-console.md#health-enhanced-console-healthpage) to the management console. For a list of available enhanced health metrics, see [Publishing Amazon CloudWatch custom metrics for an environment](health-enhanced-cloudwatch.md).
# Using the EB CLI to monitor environment health
The [Elastic Beanstalk Command Line Interface](eb-cli3.md) (EB CLI) is a command line tool for managing AWS Elastic Beanstalk environments. You also can use the EB CLI to monitor your environment's health in real time and with more granularity than is currently available in the Elastic Beanstalk console
After [installing](eb-cli3.md#eb-cli3-install) and [configuring](eb-cli3-configuration.md) the EB CLI, you can launch a new environment and deploy your code to it with the **eb create** command. If you already have an environment that you created in the Elastic Beanstalk console, you can attach the EB CLI to it by running **eb init** in a project folder and following the prompts (the project folder can be empty).
**Important**
Ensure that you are using the latest version of the EB CLI by running `pip install` with the `--upgrade` option:
```
$ sudo pip install --upgrade awsebcli
```
For complete EB CLI installation instructions, see [Install EB CLI with setup script (recommended)](eb-cli3.md#eb-cli3-install).
To use the EB CLI to monitor your environment's health, you must first configure a local project folder by running **eb init** and following the prompts. For complete instructions, see [Configure the EB CLI](eb-cli3-configuration.md).
If you already have an environment running in Elastic Beanstalk and want to use the EB CLI to monitor its health, follow these steps to attach it to the existing environment.
**To attach the EB CLI to an existing environment**
1. Open a command line terminal and navigate to your user folder.
1. Create and open a new folder for your environment.
1. Run the **eb init** command, and then choose the application and environment whose health you want to monitor. If you have only one environment running the application you choose, the EB CLI will select it automatically and you won't need to choose the environment, as shown in the following example.
```
~/project$ eb init
Select an application to use
1) elastic-beanstalk-example
2) [ Create new Application ]
(default is 2): 1
Select the default environment.
You can change this later by typing "eb use [environment_name]".
1) elasticBeanstalkEx2-env
2) elasticBeanstalkExa-env
(default is 1): 1
```
**To monitor health by using the EB CLI**
1. Open a command line and navigate to your project folder.
1. Run the **eb health** command to display the health status of the instances in your environment. In this example, there are five instances running in a Linux environment.
```
~/project $ eb health
elasticBeanstalkExa-env Ok 2015-07-08 23:13:20
WebServer Ruby 2.1 (Puma)
total ok warning degraded severe info pending unknown
5 5 0 0 0 0 0 0
instance-id status cause health
Overall Ok
i-d581497d Ok
i-d481497c Ok
i-136e00c0 Ok
i-126e00c1 Ok
i-8b2cf575 Ok
instance-id r/sec %2xx %3xx %4xx %5xx p99 p90 p75 p50 p10 requests
Overall 671.8 100.0 0.0 0.0 0.0 0.003 0.002 0.001 0.001 0.000
i-d581497d 143.0 1430 0 0 0 0.003 0.002 0.001 0.001 0.000
i-d481497c 128.8 1288 0 0 0 0.003 0.002 0.001 0.001 0.000
i-136e00c0 125.4 1254 0 0 0 0.004 0.002 0.001 0.001 0.000
i-126e00c1 133.4 1334 0 0 0 0.003 0.002 0.001 0.001 0.000
i-8b2cf575 141.2 1412 0 0 0 0.003 0.002 0.001 0.001 0.000
instance-id type az running load 1 load 5 user% nice% system% idle% iowait% cpu
i-d581497d t2.micro 1a 12 mins 0.0 0.04 6.2 0.0 1.0 92.5 0.1
i-d481497c t2.micro 1a 12 mins 0.01 0.09 5.9 0.0 1.6 92.4 0.1
i-136e00c0 t2.micro 1b 12 mins 0.15 0.07 5.5 0.0 0.9 93.2 0.0
i-126e00c1 t2.micro 1b 12 mins 0.17 0.14 5.7 0.0 1.4 92.7 0.1
i-8b2cf575 t2.micro 1c 1 hour 0.19 0.08 6.5 0.0 1.2 92.1 0.1
instance-id status id version ago deployments
i-d581497d Deployed 1 Sample Application 12 mins
i-d481497c Deployed 1 Sample Application 12 mins
i-136e00c0 Deployed 1 Sample Application 12 mins
i-126e00c1 Deployed 1 Sample Application 12 mins
i-8b2cf575 Deployed 1 Sample Application 1 hour
```
In this example, there is a single instance running in a Windows environment.
```
~/project $ eb health
WindowsSampleApp-env Ok 2018-05-22 17:33:19
WebServer IIS 10.0 running on 64bit Windows Server 2016/2.2.0
total ok warning degraded severe info pending unknown
1 1 0 0 0 0 0 0
instance-id status cause health
Overall Ok
i-065716fba0e08a351 Ok
instance-id r/sec %2xx %3xx %4xx %5xx p99 p90 p75 p50 p10 requests
Overall 13.7 100.0 0.0 0.0 0.0 1.403 0.970 0.710 0.413 0.079
i-065716fba0e08a351 2.4 100.0 0.0 0.0 0.0 1.102* 0.865 0.601 0.413 0.091
instance-id type az running % user time % privileged time % idle time cpu
i-065716fba0e08a351 t2.large 1b 4 hours 0.2 0.1 99.7
instance-id status id version ago deployments
i-065716fba0e08a351 Deployed 2 Sample Application 4 hours
```
## Reading the output
The output displays the name of the environment, the environment's overall health, and the current date at the top of the screen.
```
elasticBeanstalkExa-env Ok 2015-07-08 23:13:20
```
The next three lines display the type of environment ("WebServer" in this case), the configuration (Ruby 2.1 with Puma), and a breakdown of how many instances are in each of the seven states.
```
WebServer Ruby 2.1 (Puma)
total ok warning degraded severe info pending unknown
5 5 0 0 0 0 0 0
```
The rest of the output is split into four sections. The first displays the *status* and the *cause* of the status for the environment overall, and then for each instance. The following example shows two instances in the environment with a status of `Info` and a cause indicating that a deployment has started.
```
instance-id status cause health
Overall Ok
i-d581497d Info Performing application deployment (running for 3 seconds)
i-d481497c Info Performing application deployment (running for 3 seconds)
i-136e00c0 Ok
i-126e00c1 Ok
i-8b2cf575 Ok
```
For information about health statuses and colors, see [Health colors and statuses](health-enhanced-status.md).
The **requests** section displays information from the web server logs on each instance. In this example, each instance is taking requests normally and there are no errors.
```
instance-id r/sec %2xx %3xx %4xx %5xx p99 p90 p75 p50 p10 requests
Overall 13.7 100.0 0.0 0.0 0.0 1.403 0.970 0.710 0.413 0.079
i-d581497d 2.4 100.0 0.0 0.0 0.0 1.102* 0.865 0.601 0.413 0.091
i-d481497c 2.7 100.0 0.0 0.0 0.0 0.842* 0.788 0.480 0.305 0.062
i-136e00c0 4.1 100.0 0.0 0.0 0.0 1.520* 1.088 0.883 0.524 0.104
i-126e00c1 2.2 100.0 0.0 0.0 0.0 1.334* 0.791 0.760 0.344 0.197
i-8b2cf575 2.3 100.0 0.0 0.0 0.0 1.162* 0.867 0.698 0.477 0.076
```
The **cpu** section shows operating system metrics for each instance. The output differs by operating system. Here is the output for Linux environments.
```
instance-id type az running load 1 load 5 user% nice% system% idle% iowait% cpu
i-d581497d t2.micro 1a 12 mins 0.0 0.03 0.2 0.0 0.0 99.7 0.1
i-d481497c t2.micro 1a 12 mins 0.0 0.03 0.3 0.0 0.0 99.7 0.0
i-136e00c0 t2.micro 1b 12 mins 0.0 0.04 0.1 0.0 0.0 99.9 0.0
i-126e00c1 t2.micro 1b 12 mins 0.01 0.04 0.2 0.0 0.0 99.7 0.1
i-8b2cf575 t2.micro 1c 1 hour 0.0 0.01 0.2 0.0 0.1 99.6 0.1
```
Here is the output for Windows environments.
```
instance-id type az running % user time % privileged time % idle time
i-065716fba0e08a351 t2.large 1b 4 hours 0.2 0.0 99.8
```
For information about the server and operating system metrics shown, see [Instance metrics](health-enhanced-metrics.md).
The final section, **deployments**, shows the deployment status of each instance. If a rolling deployment fails, you can use the deployment ID, status, and version label shown to identify instances in your environment that are running the wrong version.
```
instance-id status id version ago deployments
i-d581497d Deployed 1 Sample Application 12 mins
i-d481497c Deployed 1 Sample Application 12 mins
i-136e00c0 Deployed 1 Sample Application 12 mins
i-126e00c1 Deployed 1 Sample Application 12 mins
i-8b2cf575 Deployed 1 Sample Application 1 hour
```
## Interactive health view
The **eb health** command displays a snapshot of your environment's health. To refresh the displayed information every 10 seconds, use the `--refresh` option.
```
$ eb health --refresh
elasticBeanstalkExa-env Ok 2015-07-09 22:10:04 (1 secs)
WebServer Ruby 2.1 (Puma)
total ok warning degraded severe info pending unknown
5 5 0 0 0 0 0 0
instance-id status cause health
Overall Ok
i-bb65c145 Ok Application deployment completed 35 seconds ago and took 26 seconds
i-ba65c144 Ok Application deployment completed 17 seconds ago and took 25 seconds
i-f6a2d525 Ok Application deployment completed 53 seconds ago and took 26 seconds
i-e8a2d53b Ok Application deployment completed 32 seconds ago and took 31 seconds
i-e81cca40 Ok
instance-id r/sec %2xx %3xx %4xx %5xx p99 p90 p75 p50 p10 requests
Overall 671.8 100.0 0.0 0.0 0.0 0.003 0.002 0.001 0.001 0.000
i-bb65c145 143.0 1430 0 0 0 0.003 0.002 0.001 0.001 0.000
i-ba65c144 128.8 1288 0 0 0 0.003 0.002 0.001 0.001 0.000
i-f6a2d525 125.4 1254 0 0 0 0.004 0.002 0.001 0.001 0.000
i-e8a2d53b 133.4 1334 0 0 0 0.003 0.002 0.001 0.001 0.000
i-e81cca40 141.2 1412 0 0 0 0.003 0.002 0.001 0.001 0.000
instance-id type az running load 1 load 5 user% nice% system% idle% iowait% cpu
i-bb65c145 t2.micro 1a 12 mins 0.0 0.03 0.2 0.0 0.0 99.7 0.1
i-ba65c144 t2.micro 1a 12 mins 0.0 0.03 0.3 0.0 0.0 99.7 0.0
i-f6a2d525 t2.micro 1b 12 mins 0.0 0.04 0.1 0.0 0.0 99.9 0.0
i-e8a2d53b t2.micro 1b 12 mins 0.01 0.04 0.2 0.0 0.0 99.7 0.1
i-e81cca40 t2.micro 1c 1 hour 0.0 0.01 0.2 0.0 0.1 99.6 0.1
instance-id status id version ago deployments
i-bb65c145 Deployed 1 Sample Application 12 mins
i-ba65c144 Deployed 1 Sample Application 12 mins
i-f6a2d525 Deployed 1 Sample Application 12 mins
i-e8a2d53b Deployed 1 Sample Application 12 mins
i-e81cca40 Deployed 1 Sample Application 1 hour
(Commands: Help,Quit, ▼ ▲ ◄ ►)
```
This example shows an environment that has recently been scaled up from one to five instances. The scaling operation succeeded, and all instances are now passing health checks and are ready to take requests. In interactive mode, the health status updates every 10 seconds. In the upper-right corner, a timer ticks down to the next update.
In the lower-left corner, the report displays a list of options. To exit interactive mode, press **Q**. To scroll, press the arrow keys. To see a list of additional commands, press **H**.
## Interactive health view options
When viewing environment health interactively, you can use keyboard keys to adjust the view and tell Elastic Beanstalk to replace or reboot individual instances. To see a list of available commands while viewing the health report in interactive mode, press **H** .
```
up,down,home,end Scroll vertically
left,right Scroll horizontally
F Freeze/unfreeze data
X Replace instance
B Reboot instance
<,> Move sort column left/right
-,+ Sort order descending/ascending
P Save health snapshot data file
Z Toggle color/mono mode
Q Quit this program
Views
1 All tables/split view
2 Status Table
3 Request Summary Table
4 CPU%/Load Table
H This help menu
(press Q or ESC to return)
```
# Basic health reporting
This topic explains the functionality offered by Elastic Beanstalk basic health.
AWS Elastic Beanstalk uses information from multiple sources to determine if your environment is available and processing requests from the Internet. An environment's health is represented by one of four colors, and is displayed on the [environment overview](environments-console.md) page of the Elastic Beanstalk console. It's also available from the [DescribeEnvironments](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_DescribeEnvironments.html) API and by calling **eb status** with the [EB CLI](eb-cli3.md).
The basic health reporting system provides information about the health of instances in an Elastic Beanstalk environment based on health checks performed by Elastic Load Balancing for load-balanced environments, or Amazon Elastic Compute Cloud for single-instance environments.
In addition to checking the health of your EC2 instances, Elastic Beanstalk also monitors the other resources in your environment and reports missing or incorrectly configured resources that can cause your environment to become unavailable to users.
Metrics gathered by the resources in your environment is published to Amazon CloudWatch in five minute intervals. This includes operating system metrics from EC2, request metrics from Elastic Load Balancing. You can view graphs based on these CloudWatch metrics on the [Monitoring page](environment-health-console.md) of the environment console. For basic health, these metrics are not used to determine an environment's health.
**Topics**
+ [Health colors](#using-features.healthstatus.colors)
+ [Elastic Load Balancing health checks](#using-features.healthstatus.understanding)
+ [Single instance and worker tier environment health checks](#monitoring-basic-healthcheck-singleinstance)
+ [Additional checks](#monitoring-basic-additionalchecks)
+ [Amazon CloudWatch metrics](#monitoring-basic-cloudwatch)
## Health colors
Elastic Beanstalk reports the health of a web server environment depending on how the application running in it responds to the health check. Elastic Beanstalk uses one of four colors to describe status, as shown in the following table:
****
| Color | Description |
| --- | --- |
| Grey | Your environment is being updated. |
| Green | Your environment has passed the most recent health check. At least one instance in your environment is available and taking requests. |
| Yellow | Your environment has failed one or more health checks. Some requests to your environment are failing. |
| Red | Your environment has failed three or more health checks, or an environment resource has become unavailable. Requests are consistently failing. |
These descriptions only apply to environments using basic health reporting. See [Health colors and statuses](health-enhanced-status.md) for details related to enhanced health.
## Elastic Load Balancing health checks
In a load-balanced environment, Elastic Load Balancing sends a request to each instance in an environment every 10 seconds to confirm that instances are healthy. By default, the load balancer is configured to open a TCP connection on port 80. If the instance acknowledges the connection, it is considered healthy.
You can choose to override this setting by specifying an existing resource in your application. If you specify a path, such as `/health`, the health check URL is set to `HTTP:80/health`. The health check URL should be set to a path that is always served by your application. If it is set to a static page that is served or cached by the web server in front of your application, health checks will not reveal issues with the application server or web container. For instructions on modifying your health check URL, see [Health check](environments-cfg-clb.md#using-features.managing.elb.healthchecks).
If a health check URL is configured, Elastic Load Balancing expects a GET request that it sends to return a response of `200 OK`. The application fails the health check if it fails to respond within 5 seconds or if it responds with any other HTTP status code. After 5 consecutive health check failures, Elastic Load Balancing takes the instance out of service.
For more information about Elastic Load Balancing health checks, see [Health Check](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/TerminologyandKeyConcepts.html#healthcheck) in the *Elastic Load Balancing User Guide*.
**Note**
Configuring a health check URL does not change the health check behavior of an environment's Auto Scaling group. An unhealthy instance is removed from the load balancer, but is not automatically replaced by Amazon EC2 Auto Scaling unless you configure Amazon EC2 Auto Scaling to use the Elastic Load Balancing health check as a basis for replacing instances. To configure Amazon EC2 Auto Scaling to replace instances that fail an Elastic Load Balancing health check, see [Auto Scaling health check setting for your Elastic Beanstalk environment](environmentconfig-autoscaling-healthchecktype.md).
## Single instance and worker tier environment health checks
In a single instance or worker tier environment, Elastic Beanstalk determines the instance's health by monitoring its Amazon EC2 instance status. Elastic Load Balancing health settings, including HTTP health check URLs, cannot be used in these environment types.
For more information on Amazon EC2 instance status checks, see [Monitoring Instances with Status Checks](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-system-instance-status-check.html) in the *Amazon EC2 User Guide*.
## Additional checks
In addition to Elastic Load Balancing health checks, Elastic Beanstalk monitors resources in your environment and changes health status to red if they fail to deploy, are not configured correctly, or become unavailable. These checks confirm that:
+ The environment's Auto Scaling group is available and has a minimum of at least one instance.
+ The environment's security group is available and is configured to allow incoming traffic on port 80.
+ The environment CNAME exists and is pointing to the right load balancer.
+ In a worker environment, the Amazon Simple Queue Service (Amazon SQS) queue is being polled at least once every three minutes.
## Amazon CloudWatch metrics
With basic health reporting, the Elastic Beanstalk service does not publish any metrics to Amazon CloudWatch. The CloudWatch metrics used to produce graphs on the [Monitoring page](environment-health-console.md) of the environment console are published by the resources in your environment.
For example, EC2 publishes the following metrics for the instances in your environment's Auto Scaling group:
`CPUUtilization`
Percentage of compute units currently in use.
`DiskReadBytes``DiskReadOps``DiskWriteBytes``DiskWriteOps`
Number of bytes read and written, and number of read and write operations.
`NetworkIn``NetworkOut`
Number of bytes sent and received.
Elastic Load Balancing publishes the following metrics for your environment's load balancer:
`BackendConnectionErrors`
Number of connection failures between the load balancer and environment instances.
`HTTPCode_Backend_2XX``HTTPCode_Backend_4XX`
Number of successful (2XX) and client error (4XX) response codes generated by instances in your environment.
`Latency`
Number of seconds between when the load balancer relays a request to an instance and when the response is received.
`RequestCount`
Number of completed requests.
These lists are not comprehensive. For a full list of metrics that can be reported for these resources, see the following topics in the Amazon CloudWatch Developer Guide:
**Metrics**
| Namespace | Topic |
| --- | --- |
| AWS::ElasticLoadBalancing::LoadBalancer | [Elastic Load Balancing Metrics and Resources](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/elb-metricscollected.html) |
| AWS::AutoScaling::AutoScalingGroup | [Amazon Elastic Compute Cloud Metrics and Resources](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/ec2-metricscollected.html) |
| AWS::SQS::Queue | [Amazon SQS Metrics and Resources](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/sqs-metricscollected.html) |
| AWS::RDS::DBInstance | [Amazon RDS Dimensions and Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/rds-metricscollected.html) |
### Worker environment health metric
For worker environments only, the SQS daemon publishes a custom metric for environment health to CloudWatch, where a value of 1 is Green. You can review the CloudWatch health metric data in your account using the `ElasticBeanstalk/SQSD` namespace. The metric dimension is `EnvironmentName`, and the metric name is `Health`. All instances publish their metrics to the same namespace.
To enable the daemon to publish metrics, the environment's instance profile must have permission to call `cloudwatch:PutMetricData`. This permission is included in the default instance profile. For more information, see [Managing Elastic Beanstalk instance profiles](iam-instanceprofile.md).
# Enhanced health reporting and monitoring in Elastic Beanstalk
This section explains the functionality of the Elastic Beanstalk Enhanced Health feature.
Enhanced health reporting is a feature that you can enable on your environment to allow AWS Elastic Beanstalk to gather additional information about resources in your environment. Elastic Beanstalk analyzes the information gathered to provide a better picture of overall environment health and aid in the identification of issues that can cause your application to become unavailable.
In addition to changes in how health color works, enhanced health adds a *status* descriptor that provides an indicator of the severity of issues observed when an environment is yellow or red. When more information is available about the current status, you can choose the **Causes** button to view detailed health information on the [health page](health-enhanced-console.md).
To provide detailed health information about the Amazon EC2 instances running in your environment, Elastic Beanstalk includes a [health agent](#health-enhanced-agent) in the Amazon Machine Image (AMI) for each platform version that supports enhanced health. The health agent monitors web server logs and system metrics and relays them to the Elastic Beanstalk service. Elastic Beanstalk analyzes these metrics and data from Elastic Load Balancing and Amazon EC2 Auto Scaling to provide an overall picture of an environment's health.
In addition to collecting and presenting information about your environment's resources, Elastic Beanstalk monitors the resources in your environment for several error conditions and provides notifications to help you avoid failures and resolve configuration issues. [Factors that influence your environment's health](#health-enhanced-factors) include the results of each request served by your application, metrics from your instances' operating system, and the status of the most recent deployment.
You can view health status in real time by using the [environment overview](health-enhanced-console.md) page of the Elastic Beanstalk console or the [eb health](health-enhanced-ebcli.md) command in the [Elastic Beanstalk command line interface](eb-cli3.md) (EB CLI). To record and track environment and instance health over time, you can configure your environment to publish the information gathered by Elastic Beanstalk for enhanced health reporting to Amazon CloudWatch as custom metrics. CloudWatch [charges](https://aws.amazon.com/cloudwatch/pricing/) for custom metrics apply to all metrics other than `EnvironmentHealth`, which is free of charge.
**Windows platform notes**
When you enable enhanced health reporting on a Windows Server environment, don't change [IIS logging configuration](https://docs.microsoft.com/en-us/iis/manage/provisioning-and-managing-iis/configure-logging-in-iis). For enhanced health monitoring to work correctly, IIS logging must be configured with the **W3C** format and the **ETW event only** or **Both log file and ETW event** log event destinations.
In addition, don't disable or stop the [Elastic Beanstalk health agent](#health-enhanced-agent) Windows service on any of your environment's instances. To collect and report enhanced health information on an instance, this service should be enabled and running.
The first time you create an environment Elastic Beanstalk prompts you to create the required roles and enables enhanced health reporting by default. Continue reading for details on how enhanced health reporting works, or see [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md) to get started using it right away.
**Topics**
+ [The Elastic Beanstalk health agent](#health-enhanced-agent)
+ [Factors in determining instance and environment health](#health-enhanced-factors)
+ [Health check rule customization](#health-enhanced.rules)
+ [Enhanced health roles](#health-enhanced-roles)
+ [Enhanced health authorization](#health-enhanced-authz)
+ [Enhanced health events](#health-enhanced-events)
+ [Enhanced health reporting behavior during updates, deployments, and scaling](#health-enhanced-effects)
+ [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md)
+ [Enhanced health monitoring with the environment management console](health-enhanced-console.md)
+ [Health colors and statuses](health-enhanced-status.md)
+ [Instance metrics](health-enhanced-metrics.md)
+ [Configuring enhanced health rules for an environment](health-enhanced-rules.md)
+ [Publishing Amazon CloudWatch custom metrics for an environment](health-enhanced-cloudwatch.md)
+ [Using enhanced health reporting with the Elastic Beanstalk API](health-enhanced-api.md)
+ [Enhanced health log format](health-enhanced-serverlogs.md)
+ [Notifications and troubleshooting](environments-health-enhanced-notifications.md)
+ [AI-powered environment analysis](health-ai-analysis.md)
## The Elastic Beanstalk health agent
The Elastic Beanstalk health agent is a daemon process (or service, on Windows environments) that runs on each Amazon EC2 instance in your environment, monitoring operating system and application-level health metrics and reporting issues to Elastic Beanstalk. The health agent is included in all platform versions starting with version 2.0 of each platform.
The health agent reports similar metrics to those [published to CloudWatch](using-features.healthstatus.md#monitoring-basic-cloudwatch) by Amazon EC2 Auto Scaling and Elastic Load Balancing as part of [basic health reporting](using-features.healthstatus.md), including CPU load, HTTP codes, and latency. The health agent, however, reports directly to Elastic Beanstalk, with greater granularity and frequency than basic health reporting.
For basic health, these metrics are published every five minutes and can be monitored with graphs in the environment management console. With enhanced health, the Elastic Beanstalk health agent reports metrics to Elastic Beanstalk every 10 seconds. Elastic Beanstalk uses the metrics provided by the health agent to determine the health status of each instance in the environment and, combined with other [factors](#health-enhanced-factors), to determine the overall health of the environment.
The overall health of the environment can be viewed in real time in the environment overview page of the Elastic Beanstalk console, and is published to CloudWatch by Elastic Beanstalk every 60 seconds. You can view detailed metrics reported by the health agent in real time with the [**eb health**](health-enhanced-ebcli.md) command in the [EB CLI](eb-cli3.md).
For an additional charge, you can choose to publish individual instance and environment-level metrics to CloudWatch every 60 seconds. Metrics published to CloudWatch can then be used to create [monitoring graphs](environment-health-console.md#environment-health-console-customize) in the [environment management console](environments-console.md).
Enhanced health reporting only incurs a charge if you choose to publish enhanced health metrics to CloudWatch. When you use enhanced health, you still get the basic health metrics published for free, even if you don't choose to publish enhanced health metrics.
See [Instance metrics](health-enhanced-metrics.md) for details on the metrics reported by the health agent. For details on publishing enhanced health metrics to CloudWatch, see [Publishing Amazon CloudWatch custom metrics for an environment](health-enhanced-cloudwatch.md).
## Factors in determining instance and environment health
In addition to the basic health reporting system checks, including [Elastic Load Balancing health checks](using-features.healthstatus.md#using-features.healthstatus.understanding) and [resource monitoring](using-features.healthstatus.md#monitoring-basic-additionalchecks), Elastic Beanstalk enhanced health reporting gathers additional data about the state of the instances in your environment. This includes operating system metrics, server logs, and the state of ongoing environment operations such as deployments and updates. The Elastic Beanstalk health reporting service combines information from all available sources and analyzes it to determine the overall health of the environment.
### Operations and commands
When you perform an operation on your environment, such as deploying a new version of an application, Elastic Beanstalk makes several changes that affect the environment's health status.
For example, when you deploy a new version of an application to an environment that is running multiple instances, you might see messages similar to the following as you monitor the environment's health [with the EB CLI](health-enhanced-ebcli.md).
```
id status cause
Overall Info Command is executing on 3 out of 5 instances
i-bb65c145 Pending 91 % of CPU is in use. 24 % in I/O wait
Performing application deployment (running for 31 seconds)
i-ba65c144 Pending Performing initialization (running for 12 seconds)
i-f6a2d525 Ok Application deployment completed 23 seconds ago and took 26 seconds
i-e8a2d53b Pending 94 % of CPU is in use. 52 % in I/O wait
Performing application deployment (running for 33 seconds)
i-e81cca40 Ok
```
In this example, the overall status of the environment is `Ok` and the cause of this status is that the *Command is executing on 3 out of 5 instances*. Three of the instances in the environment have the status *Pending*, indicating that an operation is in progress.
When an operation completes, Elastic Beanstalk reports additional information about the operation. For the example, Elastic Beanstalk displays the following information about an instance that has already been updated with the new version of the application:
```
i-f6a2d525 Ok Application deployment completed 23 seconds ago and took 26 seconds
```
Instance health information also includes details about the most recent deployment to each instance in your environment. Each instance reports a deployment ID and status. The deployment ID is an integer that increases by one each time you deploy a new version of your application or change settings for on-instance configuration options, such as environment variables. You can use the deployment information to identify instances that are running the wrong version of your application after a failed [rolling deployment](using-features.rolling-version-deploy.md).
In the cause column, Elastic Beanstalk includes informational messages about successful operations and other healthy states across multiple health checks, but they don't persist indefinitely. Causes for unhealthy environment statuses persist until the environment returns to a healthy status.
### Command timeout
Elastic Beanstalk applies a command timeout from the time an operation begins to allow an instance to transition into a healthy state. This command timeout is set in your environment's update and deployment configuration (in the [aws:elasticbeanstalk:command](command-options-general.md#command-options-general-elasticbeanstalkcommand) namespace) and defaults to 10 minutes.
During rolling updates, Elastic Beanstalk applies a separate timeout to each batch in the operation. This timeout is set as part of the environment's rolling update configuration (in the [aws:autoscaling:updatepolicy:rollingupdate](command-options-general.md#command-options-general-autoscalingupdatepolicyrollingupdate) namespace). If all instances in the batch are healthy within the rolling update timeout, the operation continues to the next batch. If not, the operation fails.
**Note**
If your application does not pass health checks with an **OK** status but is stable at a different level, you can set the `HealthCheckSuccessThreshold` option in the [`aws:elasticbeanstalk:command namespace`](command-options-general.md#command-options-general-elasticbeanstalkcommand) to change the level at which Elastic Beanstalk considers an instance to be healthy.
For a web server environment to be considered healthy, each instance in the environment or batch must pass 12 consecutive health checks over the course of two minutes. For a worker tier environment, each instance must pass 18 health checks. Before the command times out, Elastic Beanstalk doesn't lower an environment's health status when health checks fail. If the instances in the environment become healthy within the command timeout, the operation succeeds.
### HTTP requests
When no operation is in progress on an environment, the primary source of information about instance and environment health is the web server logs for each instance. To determine the health of an instance and the overall health of the environment, Elastic Beanstalk considers the number of requests, the result of each request, and the speed at which each request was resolved.
On Linux-based platforms, Elastic Beanstalk reads and parses web server logs to get information about HTTP requests. On the Windows Server platform, Elastic Beanstalk receives this information [directly from the IIS web server](health-enhanced-metrics-server-iis.md).
Your environment might not have an active web server. For example, the Multicontainer Docker platform doesn't include a web server. Other platforms include a web server, and your application might disable it. In these cases, your environment requires additional configuration to provide the [Elastic Beanstalk health agent](#health-enhanced-agent) with logs in the format that it needs to relay health information to the Elastic Beanstalk service. See [Enhanced health log format](health-enhanced-serverlogs.md) for details.
### Operating system metrics
Elastic Beanstalk monitors operating system metrics reported by the health agent to identify instances that are consistently low on system resources.
See [Instance metrics](health-enhanced-metrics.md) for details on the metrics reported by the health agent.
## Health check rule customization
Elastic Beanstalk enhanced health reporting relies on a set of rules to determine the health of your environment. Some of these rules might not be appropriate for your particular application. A common case is an application that returns frequent HTTP 4xx errors by design. Elastic Beanstalk, using one of its default rules, concludes that something is going wrong, and changes your environment health status from OK to Warning, Degraded, or Severe, depending on the error rate. To handle this case correctly, Elastic Beanstalk allows you to configure this rule and ignore application HTTP 4xx errors. For details, see [Configuring enhanced health rules for an environment](health-enhanced-rules.md).
## Enhanced health roles
Enhanced health reporting requires two roles—a service role for Elastic Beanstalk and an instance profile for the environment. The service role allows Elastic Beanstalk to interact with other AWS services on your behalf to gather information about the resources in your environment. The instance profile allows the instances in your environment to write logs to Amazon S3 and to communicate enhanced health information to the Elastic Beanstalk service.
When you create an Elastic Beanstalk environment using the Elastic Beanstalk console or the EB CLI, Elastic Beanstalk creates a default service role and attaches required managed policies to a default instance profile for your environment.
If you use the API, an SDK, or the AWS CLI to create environments, you must create these roles in advance, and specify them during environment creation to use enhanced health. For instructions on creating appropriate roles for your environments, see [Elastic Beanstalk Service roles, instance profiles, and user policies](concepts-roles.md).
We recommend that you use *managed policies* for your instance profile and service role. Managed policies are AWS Identity and Access Management (IAM) policies that Elastic Beanstalk maintains. Using managed policies guarantees that your environment has all permissions it needs to function properly.
For the instance profile, you can use the `AWSElasticBeanstalkWebTier` or `AWSElasticBeanstalkWorkerTier` managed policy, for a [web server tier](concepts-webserver.md) or [worker tier](concepts-worker.md) environment, respectively. For details about these two managed instance profile policies, see [Managing Elastic Beanstalk instance profiles](iam-instanceprofile.md).
## Enhanced health authorization
The Elastic Beanstalk instance profile managed policies contain permissions for the `elasticbeanstalk:PutInstanceStatistics` action. This action isn't part of the Elastic Beanstalk API. It's part of a different API that environment instances use internally to communicate enhanced health information to the Elastic Beanstalk service. You don't call this API directly.
When you create a new environment, authorization for the `elasticbeanstalk:PutInstanceStatistics` action is enabled by default. To increase security of your environment and help prevent health data spoofing on your behalf, we recommend that you keep authorization for this action enabled. If you use managed policies for your instance profile, this feature is available for your new environment without any further configuration. However, If you use a *custom instance profile* instead of a *managed policy*, your environment might display a **No Data** health status. This happens because the instances aren't authorized for the action that communicates enhanced health data to the service.
To authorize the action, include the following statement in your instance profile.
```
{
"Sid": "ElasticBeanstalkHealthAccess",
"Action": [
"elasticbeanstalk:PutInstanceStatistics"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:*:*:application/*",
"arn:aws:elasticbeanstalk:*:*:environment/*"
]
}
```
If you don’t want to use enhanced health authorization at this time, disable it by setting set the `EnhancedHealthAuthEnabled` option in the [aws:elasticbeanstalk:healthreporting:system](command-options-general.md#command-options-general-elasticbeanstalkhealthreporting) namespace to `false`. If this option is disabled, the permissions described previously aren’t required. You can remove them from the instance profile for [ least privilege access](security-best-practices.md#security-best-practices.preventive.least-priv) to your applications and environments.
**Note**
Previously the default setting for `EnhancedHealthAuthEnabled` was `false`, which resulted in authorization for the `elasticbeanstalk:PutInstanceStatistics` action also being disabled by default. To enable this action for an existing environment, set the `EnhancedHealthAuthEnabled` option in the [aws:elasticbeanstalk:healthreporting:system](command-options-general.md#command-options-general-elasticbeanstalkhealthreporting) namespace to `true`. You can configure this option by using an [option setting](ebextensions-optionsettings.md) in a [configuration file](ebextensions.md).
## Enhanced health events
The enhanced health system generates events when an environment transitions between states. The following example shows events output by an environment transitioning between **Info**, **OK**, and **Severe** states.
![\[The Elastic Beanstalk environment overview page of the Elastic Beanstalk console showing enhanced health recent events\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-events.png)
When transitioning to a worse state, the enhanced health event includes a message indicating the transition cause.
Not all changes in status at an instance level cause Elastic Beanstalk to emit an event. To prevent false alarms, Elastic Beanstalk generates a health-related event only if an issue persists across multiple checks.
Real-time environment-level health information, including status, color, and cause, is available in the [environment overview](environments-dashboard.md) page of the Elastic Beanstalk console and the [EB CLI](eb-cli3.md). By attaching the EB CLI to your environment and running the [**eb health**](health-enhanced-ebcli.md) command, you can also view real-time statuses from each of the instances in your environment.
## Enhanced health reporting behavior during updates, deployments, and scaling
Enabling enhanced health reporting can affect how your environment behaves during configuration updates and deployments. Elastic Beanstalk won't complete a batch of updates until all of the instances pass health checks consistently. Also, because enhanced health reporting applies a higher standard for health and monitors more factors, instances that pass basic health reporting's [ELB health check](using-features.healthstatus.md#using-features.healthstatus.understanding) won't necessarily pass with enhanced health reporting. See the topics on [rolling configuration updates](using-features.rollingupdates.md) and [rolling deployments](using-features.rolling-version-deploy.md) for details on how health checks affect the update process.
Enhanced health reporting can also highlight the need to set a proper [health check URL](environments-cfg-clb.md#using-features.managing.elb.healthchecks) for Elastic Load Balancing. When your environment scales up to meet demand, new instances will start taking requests as soon as they pass enough ELB health checks. If a health check URL is not configured, this can be as little as 20 seconds after a new instance is able to accept a TCP connection.
If your application hasn't finished starting up by the time the load balancer declares it healthy enough to receive traffic, you will see a flood of failed requests, and your environment will start to fail health checks. A health check URL that hits a path served by your application can prevent this issue. ELB health checks won't pass until a GET request to the health check URL returns a 200 status code.
# Enabling Elastic Beanstalk enhanced health reporting
This topic explains how enhanced health reporting is enabled. It provides procedures for you to enable the enhanced health feature for your environment with the Elastic Beanstalk console, the EB CLI, and with an .ebextensions configuration.
New environments created with the latest [platform versions](concepts.platforms.md) include the AWS Elastic Beanstalk [health agent](health-enhanced.md#health-enhanced-agent), which supports enhanced health reporting. If you create your environment in the Elastic Beanstalk console or with the EB CLI, enhanced health is enabled by default. You can also set your health reporting preference in your application's source code using [configuration files](ebextensions.md).
Enhanced health reporting requires an [instance profile](concepts-roles-instance.md) and [service role](concepts-roles-service.md) with the standard set of permissions. When you create an environment in the Elastic Beanstalk console, Elastic Beanstalk creates the required roles automatically. See [Learn how to get started with Elastic Beanstalk](GettingStarted.md) for instructions on creating your first environment.
**Topics**
+ [Enabling enhanced health reporting using the Elastic Beanstalk console](#health-enhanced-enable-console)
+ [Enabling enhanced health reporting using the EB CLI](#health-enhanced-enable-ebcli)
+ [Enabling enhanced health reporting using a configuration file](#health-enhanced-enable-config)
## Enabling enhanced health reporting using the Elastic Beanstalk console
**To enable enhanced health reporting in a running environment using the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Configuration**.
1. In the **Monitoring** configuration category, choose **Edit**.
1. Under **Health reporting**, for **System**, choose **Enhanced**.
**Note**
The options for enhanced health reporting don't appear if you are using an [unsupported platform or version](health-enhanced.md).
1. To save the changes choose **Apply** at the bottom of the page.
The Elastic Beanstalk console defaults to enhanced health reporting when you create a new environment with a version 2 (v2) platform version. You can disable enhanced health reporting by changing the health reporting option during environment creation.
**To disable enhanced health reporting when creating an environment using the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. [Create an application](applications.md) or select an existing one.
1. [Create an environment](using-features.environments.md). On the **Create a new environment** page, before choosing **Create environment**, choose **Configure more options**.
1. In the **Monitoring** configuration category, choose **Edit**.
1. Under **Health reporting**, for **System**, choose **Basic**.
1. Choose **Save**.
## Enabling enhanced health reporting using the EB CLI
When you create a new environment with the **eb create** command, the EB CLI enables enhanced health reporting by default and applies the default instance profile and service role.
You can specify a different service role by name by using the `--service-role` option.
If you have an environment running with basic health reporting on a v2 platform version and you want to switch to enhanced health, follow these steps.
**To enable enhanced health on a running environment using the [EB CLI](eb-cli3.md)**
1. Use the **eb config** command to open the configuration file in the default text editor.
```
~/project$ eb config
```
1. Locate the `aws:elasticbeanstalk:environment` namespace in the settings section. Ensure that the value of `ServiceRole` is not null and that it matches the name of your [service role](concepts-roles-service.md).
```
aws:elasticbeanstalk:environment:
EnvironmentType: LoadBalanced
ServiceRole: aws-elasticbeanstalk-service-role
```
1. Under the `aws:elasticbeanstalk:healthreporting:system:` namespace, change the value of `SystemType` to **enhanced**.
```
aws:elasticbeanstalk:healthreporting:system:
SystemType: enhanced
```
1. Save the configuration file and close the text editor.
1. The EB CLI starts an environment update to apply your configuration changes. Wait for the operation to complete or press **Ctrl\$1C** to exit safely.
```
~/project$ eb config
Printing Status:
INFO: Environment update is starting.
INFO: Health reporting type changed to ENHANCED.
INFO: Updating environment no-role-test's configuration settings.
```
## Enabling enhanced health reporting using a configuration file
You can enable enhanced health reporting by including a [configuration file](ebextensions.md) in your source bundle. The following example shows a configuration file that enables enhanced health reporting and assigns the default service and instance profile to the environment:
**Example .ebextensions/enhanced-health.config**
```
option_settings:
aws:elasticbeanstalk:healthreporting:system:
SystemType: enhanced
aws:autoscaling:launchconfiguration:
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
aws:elasticbeanstalk:environment:
ServiceRole: aws-elasticbeanstalk-service-role
```
If you created your own instance profile or service role, replace the highlighted text with the names of those roles.
# Enhanced health monitoring with the environment management console
When you enable enhanced health reporting in AWS Elastic Beanstalk, you can monitor environment health in the [environment management console](environments-console.md).
**Topics**
+ [Environment overview](#health-enhanced-console-overview)
+ [Environment health page](#health-enhanced-console-healthpage)
+ [Monitoring page](#health-enhanced-console-monitoringpage)
## Environment overview
The [environment overview](environments-dashboard.md) displays the [health status](health-enhanced-status.md) of the environment and lists events that provide information about recent changes in health status.
**To view the environment overview**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
For detailed information about the current environment's health, open the **Health** page by choosing **Causes**. Alternatively, in the navigation pane, choose **Health**.
## Environment health page
The **Health** page displays health status, metrics, and causes for the environment and for each Amazon EC2 instance in the environment.
**Note**
Elastic Beanstalk displays the **Health** page only if you have [enabled enhanced health monitoring](health-enhanced-enable.md) for the environment.
The following image shows the **Health** page for a Linux environment.
![\[Environment health page for a Linux environment\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-instances.png)
The following image shows the **Health** page for a Windows environment. Notice that CPU metrics are different from those on a Linux environment.
![\[Environment health page for a Windows environment.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-instances-win.png)
At the top of the page you can see the total number of environment instances, as well as the number of instances per status. To display only instances that have a particular status, choose**Filter By**, and then select a [status](health-enhanced-status.md).
![\[Environment health page showing the filter by menu for choosing an instance status to display\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-instances-status.png)
To reboot or terminate an unhealthy instance, choose **Instance Actions**, and then choose **Reboot** or **Terminate**.
![\[Environment health page showing the instance actions menu for rebooting or terminating unhealthy instances.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-instances-actions.png)
Elastic Beanstalk updates the **Health** page every 10 seconds. It reports information about environment and instance health.
For each Amazon EC2 instance in the environment, the page displays the instance's ID and [status](health-enhanced-status.md), the amount of time since the instance was launched, the ID of the most recent deployment executed on the instance, the responses and latency of requests that the instance served, and load and CPU utilization information. The **Overall** row displays average response and latency information for the entire environment.
The page displays many details in a very wide table. To hide some of the columns, choose ![\[the cog icon.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/cog.png) (**Preferences**). Select or clear column names, and then choose **Confirm**.
![\[Selecting columns to display on the environment health page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-console-preferences.png)
Choose the **Instance ID** of any instance to view more information about the instance, including its Availability Zone and instance type.
![\[Server metrics on the environment health page with instance information\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-console-instance.png)
Choose the **Deployment ID** of any instance to view information about the last [deployment](using-features.deploy-existing-version.md) to the instance.
![\[Server metrics on the environment health page with deployment information\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-console-deployment.png)
Deployment information includes the following:
+ **Deployment ID**—The unique identifier for the [deployment](using-features.deploy-existing-version.md). Deployment IDs starts at 1 and increase by one each time you deploy a new application version or change configuration settings that affect the software or operating system running on the instances in your environment.
+ **Version**—The version label of the application source code used in the deployment.
+ **Status**—The status of the deployment, which can be `In Progress`, `Deployed`, or `Failed`.
+ **Time**— For in-progress deployments, the time that the deployment started. For completed deployments, the time that the deployment ended.
If you [enable X-Ray integration](environment-configuration-debugging.md) on your environment and instrument your application with the AWS X-Ray SDK, the **Health** page adds links to the AWS X-Ray console in the overview row.
![\[Request metrics on the environment health page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-console-xray.png)
Choose a link to view traces related to the highlighted statistic in the AWS X-Ray console.
## Monitoring page
The **Monitoring** page displays summary statistics and graphs for the custom Amazon CloudWatch metrics generated by the enhanced health reporting system. See [Monitoring environment health in the AWS management console](environment-health-console.md) for instructions on adding graphs and statistics to this page.
# Health colors and statuses
Enhanced health reporting represents instance and overall environment health by using four colors, similar to [basic health reporting](using-features.healthstatus.md). Enhanced health reporting also provides seven health statuses, which are single-word descriptors that provide a better indication of the state of your environment.
## Instance status and environment status
Every time Elastic Beanstalk runs a health check on your environment, enhanced health reporting checks the health of each instance in your environment by analyzing all of [the data](health-enhanced.md#health-enhanced-factors) available. If any lower-level check fails, Elastic Beanstalk downgrades the health of the instance.
Elastic Beanstalk displays the health information for the overall environment (color, status, and cause) in the [environment management console](environments-console.md). This information is also available in the EB CLI. Health status and cause messages for individual instances are updated every 10 seconds and are available from the [EB CLI](eb-cli3.md) when you view health status with [**eb health**](health-enhanced-ebcli.md).
Elastic Beanstalk uses changes in instance health to evaluate environment health, but does not immediately change environment health status. When an instance fails health checks at least three times in any one-minute period, Elastic Beanstalk may downgrade the health of the environment. Depending on the number of instances in the environment and the issue identified, one unhealthy instance can cause Elastic Beanstalk to display an informational message or to change the environment's health status from green (**OK**) to yellow (**Warning**) or red (**Degraded** or **Severe**).
## OK (green)
This status is displayed when:
+ An instance is passing health checks and the health agent is not reporting any problems.
+ Most instances in the environment are passing health checks and the health agent is not reporting major issues.
+ An instance is passing health checks and is completing requests normally.
*Example:* Your environment was recently deployed and is taking requests normally. Five percent of requests are returning 400 series errors. Deployment completed normally on each instance.
*Message (instance):* Application deployment completed 23 seconds ago and took 26 seconds.
## Warning (yellow)
This status is displayed when:
+ The health agent is reporting a moderate number of request failures or other issues for an instance or environment.
+ An operation is in progress on an instance and is taking a very long time.
*Example:* One instance in the environment has a status of **Severe**.
*Message (environment):* Impaired services on 1 out of 5 instances.
## Degraded (red)
This status is displayed when the health agent is reporting a high number of request failures or other issues for an instance or environment.
*Example:* environment is in the process of scaling up to 5 instances.
*Message (environment):* 4 active instances is below Auto Scaling group minimum size 5.
## Severe (red)
This status is displayed when the health agent is reporting a very high number of request failures or other issues for an instance or environment.
*Example:* Elastic Beanstalk is unable to contact the load balancer to get instance health.
*Message (environment):* ELB health is failing or not available for all instances. None of the instances are sending data. Unable to assume role "arn:aws:iam::123456789012:role/aws-elasticbeanstalk-service-role". Verify that the role exists and is configured correctly.
*Message (Instances):* Instance ELB health has not been available for 37 minutes. No data. Last seen 37 minutes ago.
## Info (green)
This status is displayed when:
+ An operation is in progress on an instance.
+ An operation is in progress on several instances in an environment.
*Example:* A new application version is being deployed to running instances.
*Message (environment):* Command is executing on 3 out of 5 instances.
*Message (instance):* Performing application deployment (running for 3 seconds).
## Pending (grey)
This status is displayed when an operation is in progress on an instance within the [command timeout](health-enhanced.md#health-enhanced-factors-timeout).
*Example:* You have recently created the environment and instances are being bootstrapped.
*Message:* Performing initialization (running for 12 seconds).
## Unknown (grey)
This status is displayed when Elastic Beanstalk and the health agent are reporting an insufficient amount of data on an instance.
*Example:* No data is being received.
## Suspended (grey)
This status is displayed when Elastic Beanstalk stopped monitoring the environment's health. The environment might not work correctly. Some severe health conditions, if they last a long time, cause Elastic Beanstalk to transition the environment to the **Suspended** status.
*Example:* Elastic Beanstalk can't access the environment's [service role](iam-servicerole.md).
*Example:* The [Auto Scaling group](using-features.managing.as.md) that Elastic Beanstalk created for the environment has been deleted.
*Message:* Environment health has transitioned from **OK** to **Severe**. There are no instances. Auto Scaling group desired capacity is set to 1.
# Instance metrics
Instance metrics provide information about the health of instances in your environment. The [Elastic Beanstalk health agent](health-enhanced.md#health-enhanced-agent) runs on each instance. It gathers and relays metrics about instances to Elastic Beanstalk, which analyzes the metrics to determine the health of the instances in your environments.
The on-instance Elastic Beanstalk health agent gathers metrics about instances from web servers and the operating system. To get web server information on Linux-based platforms, Elastic Beanstalk reads and parses web server logs. On the Windows Server platform, Elastic Beanstalk receives this information directly from the IIS web server. Web servers provide information about incoming HTTP requests: how many requests came in, how many resulted in errors, and how long they took to resolve. The operating system provides snapshot information about the state of the instances' resources: the CPU load and distribution of time spent on each process type.
The health agent gathers web server and operating system metrics and relays them to Elastic Beanstalk every 10 seconds. Elastic Beanstalk analyzes the data and uses the results to update the health status for each instance and the environment.
**Topics**
+ [Web server metrics](#health-enhanced-metrics-server)
+ [Operating system metrics](#health-enhanced-metrics-os)
+ [Web server metrics capture in IIS on Windows server](health-enhanced-metrics-server-iis.md)
## Web server metrics
On Linux-based platforms, the Elastic Beanstalk health agent reads web server metrics from logs generated by the web container or server that processes requests on each instance in your environment. Elastic Beanstalk platforms are configured to generate two logs: one in human-readable format and one in machine-readable format. The health agent relays machine-readable logs to Elastic Beanstalk every 10 seconds.
For more information on the log format used by Elastic Beanstalk, see [Enhanced health log format](health-enhanced-serverlogs.md).
On the Windows Server platform, Elastic Beanstalk adds a module to the IIS web server's request pipeline and captures metrics about HTTP request times and response codes. The module sends these metrics to the on-instance health agent using a high-performance interprocess communication (IPC) channel. For implementation details, see [Web server metrics capture in IIS on Windows server](health-enhanced-metrics-server-iis.md).Reported Web Server Metrics
`RequestCount`
Number of requests handled by the web server per second over the last 10 seconds. Shown as an average `r/sec` (requests per second) in the EB CLI and [Environment health page](health-enhanced-console.md#health-enhanced-console-healthpage).
`Status2xx``Status3xx``Status4xx``Status5xx`
Number of requests that resulted in each type of status code over the last 10 seconds. For example, successful requests return a 200 OK, redirects are a 301, and a 404 is returned if the URL entered doesn't match any resources in the application.
The EB CLI and [Environment health page](health-enhanced-console.md#health-enhanced-console-healthpage) show these metrics both as a raw number of requests for instances, and as a percentage of overall requests for environments.
`p99.9``p99``p95``p90``p85``p75``p50``p10`
Average latency for the slowest *x* percent of requests over the last 10 seconds, where *x* is the difference between the number and 100. For example, `p99 1.403` indicates the slowest 1% of requests over the last 10 seconds had an average latency of 1.403 seconds.
## Operating system metrics
The Elastic Beanstalk health agent reports the following operating system metrics. Elastic Beanstalk uses these metrics to identify instances that are under sustained heavy load. The metrics differ by operating system.Reported operating system metrics—Linux
`Running`
The amount of time that has passed since the instance was launched.
`Load 1``Load 5`
Load average in the last one-minute and five-minute periods. Shown as a decimal value indicating the average number of processes running during that time. If the number shown is higher than the number of vCPUs (threads) available, then the remainder is the average number of processes that were waiting.
For example, if your instance type has four vCPUs, and the load is 4.5, there was an average of .5 processes in wait during that time period, equivalent to one process waiting 50 percent of the time.
`User %``Nice %``System %``Idle %``I/O Wait %`
Percentage of time that the CPU has spent in each state over the last 10 seconds.Reported operating system metrics—Windows
`Running`
The amount of time that has passed since the instance was launched.
`% User Time``% Privileged Time``% Idle Time`
Percentage of time that the CPU has spent in each state over the last 10 seconds.
# Web server metrics capture in IIS on Windows server
On the Windows Server platform, Elastic Beanstalk adds a module to the IIS web server's request pipeline and captures metrics about HTTP request times and response codes. The module sends these metrics to the on-instance health agent using a high-performance interprocess communication (IPC) channel. The health agent aggregates these metrics, combines them with operating system metrics, and sends them to the Elastic Beanstalk service.
## Implementation details
To capture metrics from IIS, Elastic Beanstalk implements a managed [https://msdn.microsoft.com/en-us/library/system.web.ihttpmodule%28v=vs.110%29.aspx](https://msdn.microsoft.com/en-us/library/system.web.ihttpmodule%28v=vs.110%29.aspx), and subscribes to the [https://msdn.microsoft.com/en-us/library/system.web.httpapplication.beginrequest(v=vs.110).aspx](https://msdn.microsoft.com/en-us/library/system.web.httpapplication.beginrequest(v=vs.110).aspx) and [https://msdn.microsoft.com/en-us/library/system.web.httpapplication.endrequest(v=vs.110).aspx](https://msdn.microsoft.com/en-us/library/system.web.httpapplication.endrequest(v=vs.110).aspx) events. This enables the module to report HTTP request latency and response codes for all web requests handled by IIS. To add the module to the IIS request pipeline, Elastic Beanstalk registers the module in the [https://docs.microsoft.com/en-us/iis/configuration/system.webserver/modules/](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/modules/) section of the IIS configuration file, `%windir%\System32\inetsrv\config\applicationHost.config`.
The Elastic Beanstalk module in IIS sends the captured web request metrics to the on-instance health agent, which is a Windows service named `HealthD`. To send this data, the module uses [https://msdn.microsoft.com/en-us/library/system.servicemodel.netnamedpipebinding(v=vs.110).aspx](https://msdn.microsoft.com/en-us/library/system.servicemodel.netnamedpipebinding(v=vs.110).aspx), which provides a secure and reliable binding that is optimized for on-machine communication.
# Configuring enhanced health rules for an environment
AWS Elastic Beanstalk enhanced health reporting relies on a set of rules to determine the health of your environment. Some of these rules might not be appropriate for your particular application. The following are some common examples:
+ You use client-side test tools. In this case, frequent HTTP client (4xx) errors are expected.
+ You use [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/) in conjunction with your environment's Application Load Balancer to block unwanted incoming traffic. In this case, Application Load Balancer returns HTTP 403 for each rejected incoming message.
By default, Elastic Beanstalk includes all application HTTP 4xx errors when determining the environment's health. It changes your environment health status from **OK** to **Warning**, **Degraded**, or **Severe**, depending on the error rate. To correctly handle cases such as the examples we mentioned, Elastic Beanstalk enables you to configure some enhanced health rules. You can choose to ignore application HTTP 4xx errors on the environment's instances, or to ignore HTTP 4xx errors returned by the environment's load balancer. This topic describes how to make these configuration changes.
**Note**
Currently, these are the only available enhanced heath rule customizations. You can't configure enhanced health to ignore other HTTP errors in addition to 4xx.
## Configuring enhanced health rules using the Elastic Beanstalk console
You can use the Elastic Beanstalk console to configure enhanced health rules in your environment.
**To configure HTTP 4xx status code checking using the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Configuration**.
1. In the **Monitoring** configuration category, choose **Edit**.
1. Under **Health monitoring rule customization**, enable or disable the desired **Ignore** options.
![\[Health monitoring rule customization section on the monitoring configuration page of the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/enhanced-health-rule-customization.png)
1. To save the changes choose **Apply** at the bottom of the page.
## Configuring enhanced health rules using the EB CLI
You can use the EB CLI to configure enhanced health rules by saving your environment's configuration locally, adding an entry that configures enhanced health rules, and then uploading the configuration to Elastic Beanstalk. You can apply the saved configuration to an environment during or after creation.
**To configure HTTP 4xx status code checking using the EB CLI and saved configurations**
1. Initialize your project folder with [**eb init**](eb-cli3-configuration.md).
1. Create an environment by running the **eb create** command.
1. Save a configuration template locally by running the **eb config save** command. The following example uses the `--cfg` option to specify the name of the configuration.
```
$ eb config save --cfg 01-base-state
Configuration saved at: ~/project/.elasticbeanstalk/saved_configs/01-base-state.cfg.yml
```
1. Open the saved configuration file in a text editor.
1. Under `OptionSettings` > `aws:elasticbeanstalk:healthreporting:system:`, add a `ConfigDocument` key to list each enhanced health rule to configure. The following `ConfigDocument` disables the checking of application HTTP 4xx status codes, while keeping the checking of load balancer HTTP 4xx code enabled.
```
OptionSettings:
...
aws:elasticbeanstalk:healthreporting:system:
ConfigDocument:
Rules:
Environment:
Application:
ApplicationRequests4xx:
Enabled: false
ELB:
ELBRequests4xx:
Enabled: true
Version: 1
SystemType: enhanced
...
```
**Note**
You can combine `Rules` and `CloudWatchMetrics` in the same `ConfigDocument` option setting. `CloudWatchMetrics` are described in [Publishing Amazon CloudWatch custom metrics for an environment](health-enhanced-cloudwatch.md).
If you previously enabled `CloudWatchMetrics`, the configuration file that you retrieve using the **eb config save** command already has a `ConfigDocument` key with a `CloudWatchMetrics` section. *Do not delete it*—add a `Rules` section into the same `ConfigDocument` option value.
1. Save the configuration file and close the text editor. In this example, the updated configuration file is saved with a name (`02-cloudwatch-enabled.cfg.yml`) that's different from the downloaded configuration file. This creates a separate saved configuration when the file is uploaded. You can use the same name as the downloaded file to overwrite the existing configuration without creating a new one.
1. Use the **eb config put** command to upload the updated configuration file to Elastic Beanstalk.
```
$ eb config put 02-cloudwatch-enabled
```
When using the **eb config** `get` and `put` commands with saved configurations, don't include the file name extension.
1. Apply the saved configuration to your running environment.
```
$ eb config --cfg 02-cloudwatch-enabled
```
The `--cfg` option specifies a named configuration file that is applied to the environment. You can save the configuration file locally or in Elastic Beanstalk. If a configuration file with the specified name exists in both locations, the EB CLI uses the local file.
## Configuring enhanced health rules using a config document
The configuration (config) document for enhanced health rules is a JSON document that lists the rules to configure.
The following example shows a config document that disables the checking of application HTTP 4xx status codes and enables the checking of load balancer HTTP 4xx status codes.
```
{
"Rules": {
"Environment": {
"Application": {
"ApplicationRequests4xx": {
"Enabled": false
}
},
"ELB": {
"ELBRequests4xx": {
"Enabled": true
}
}
}
},
"Version": 1
}
```
For the AWS CLI, you pass the document as a value for the `Value` key in an option settings argument, which itself is a JSON object. In this case, you must escape quotation marks in the embedded document. The following command checks if the configuration settings are valid.
```
$ aws elasticbeanstalk validate-configuration-settings --application-name my-app --environment-name my-env --option-settings '[
{
"Namespace": "aws:elasticbeanstalk:healthreporting:system",
"OptionName": "ConfigDocument",
"Value": "{\"Rules\": { \"Environment\": { \"Application\": { \"ApplicationRequests4xx\": { \"Enabled\": false } }, \"ELB\": { \"ELBRequests4xx\": {\"Enabled\": true } } } }, \"Version\": 1 }"
}
]'
```
For an `.ebextensions` configuration file in YAML, you can provide the JSON document as is.
```
option_settings:
- namespace: aws:elasticbeanstalk:healthreporting:system
option_name: ConfigDocument
value: {
"Rules": {
"Environment": {
"Application": {
"ApplicationRequests4xx": {
"Enabled": false
}
},
"ELB": {
"ELBRequests4xx": {
"Enabled": true
}
}
}
},
"Version": 1
}
```
# Publishing Amazon CloudWatch custom metrics for an environment
You can publish the data gathered by AWS Elastic Beanstalk enhanced health reporting to Amazon CloudWatch as custom metrics. Publishing metrics to CloudWatch lets you monitor changes in application performance over time and identify potential issues by tracking how resource usage and request latency scale with load.
By publishing metrics to CloudWatch, you also make them available for use with [monitoring graphs](environment-health-console.md#environment-health-console-graphs) and [alarms](using-features.alarms.md). One free metric, *EnvironmentHealth*, is enabled automatically when you use enhanced health reporting. Custom metrics other than *EnvironmentHealth* incur standard [CloudWatch charges](https://aws.amazon.com/cloudwatch/pricing/).
To publish CloudWatch custom metrics for an environment, you must first enable enhanced health reporting on the environment. See [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md) for instructions.
**Topics**
+ [Enhanced health reporting metrics](#health-enhanced-cloudwatch-metrics)
+ [Configuring CloudWatch metrics using the Elastic Beanstalk console](#health-enhanced-cloudwatch-console)
+ [Configuring CloudWatch custom metrics using the EB CLI](#health-enhanced-cloudwatch-ebcli)
+ [Providing custom metric config documents](#health-enhanced-cloudwatch-configdocument)
## Enhanced health reporting metrics
When you enable enhanced health reporting in your environment, the enhanced health reporting system automatically publishes one [CloudWatch custom metric](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/publishingMetrics.html), *EnvironmentHealth*. To publish additional metrics to CloudWatch, configure your environment with those metrics by using the [Elastic Beanstalk console](#health-enhanced-cloudwatch-console), [EB CLI](#health-enhanced-cloudwatch-ebcli), or [.ebextensions](command-options.md).
You can publish the following enhanced health metrics from your environment to CloudWatch.Available metrics—all platforms
`EnvironmentHealth`
*Environment only.* This is the only CloudWatch metric that the enhanced health reporting system publishes, unless you configure additional metrics. Environment health is represented by one of seven [statuses](health-enhanced-status.md). In the CloudWatch console, these statuses map to the following values:
+ 0 – OK
+ 1 – Info
+ 5 – Unknown
+ 10 – No data
+ 15 – Warning
+ 20 – Degraded
+ 25 – Severe
`InstancesSevere``InstancesDegraded``InstancesWarning``InstancesInfo``InstancesOk``InstancesPending``InstancesUnknown``InstancesNoData`
*Environment only.* These metrics indicate the number of instances in the environment with each health status. `InstancesNoData` indicates the number of instances for which no data is being received.
`ApplicationRequestsTotal``ApplicationRequests5xx``ApplicationRequests4xx``ApplicationRequests3xx``ApplicationRequests2xx`
*Instance and environment.* Indicates the total number of requests completed by the instance or environment, and the number of requests that completed with each status code category.
`ApplicationLatencyP10``ApplicationLatencyP50``ApplicationLatencyP75``ApplicationLatencyP85``ApplicationLatencyP90``ApplicationLatencyP95``ApplicationLatencyP99``ApplicationLatencyP99.9`
*Instance and environment.* Indicates the average amount of time, in seconds, it takes to complete the fastest *x* percent of requests.
`InstanceHealth`
*Instance only.* Indicates the current health status of the instance. Instance health is represented by one of seven [statuses](health-enhanced-status.md). In the CloudWatch console, these statuses map to the following values:
+ 0 – OK
+ 1 – Info
+ 5 – Unknown
+ 10 – No data
+ 15 – Warning
+ 20 – Degraded
+ 25 – SevereAvailable metrics—Linux
`CPUIrq``CPUIdle``CPUUser``CPUSystem``CPUSoftirq``CPUIowait``CPUNice`
*Instance only.* Indicates the percentage of time that the CPU has spent in each state over the last minute.
`LoadAverage1min`
*Instance only.* The average CPU load of the instance over the last minute.
`RootFilesystemUtil`
*Instance only.* Indicates the percentage of disk space that's in use.Available metrics—Windows
`CPUIdle``CPUUser``CPUPrivileged`
Instance only. Indicates the percentage of time that the CPU has spent in each state over the last minute.
## Configuring CloudWatch metrics using the Elastic Beanstalk console
You can use the Elastic Beanstalk console to configure your environment to publish enhanced health reporting metrics to CloudWatch and make them available for use with monitoring graphs and alarms.
**To configure CloudWatch custom metrics in the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Configuration**.
1. In the **Monitoring** configuration category, choose **Edit**.
1. Under **Health reporting**, select the instance and environment metrics to publish to CloudWatch. To select multiple metrics, press the **Ctrl** key while choosing.
1. To save the changes choose **Apply** at the bottom of the page.
Enabling CloudWatch custom metrics adds them to the list of metrics available on the [**Monitoring** page](environment-health-console.md).
## Configuring CloudWatch custom metrics using the EB CLI
You can use the EB CLI to configure custom metrics by saving your environment's configuration locally, adding an entry that defines the metrics to publish, and then uploading the configuration to Elastic Beanstalk. You can apply the saved configuration to an environment during or after creation.
**To configure CloudWatch custom metrics with the EB CLI and saved configurations**
1. Initialize your project folder with [**eb init**](eb-cli3-configuration.md).
1. Create an environment by running the **eb create** command.
1. Save a configuration template locally by running the **eb config save** command. The following example uses the `--cfg` option to specify the name of the configuration.
```
$ eb config save --cfg 01-base-state
Configuration saved at: ~/project/.elasticbeanstalk/saved_configs/01-base-state.cfg.yml
```
1. Open the saved configuration file in a text editor.
1. Under `OptionSettings` > `aws:elasticbeanstalk:healthreporting:system:`, add a `ConfigDocument` key to enable each of the CloudWatch metrics you want. For example, the following `ConfigDocument` publishes `ApplicationRequests5xx` and `ApplicationRequests4xx` metrics at the environment level, and `ApplicationRequestsTotal` metrics at the instance level.
```
OptionSettings:
...
aws:elasticbeanstalk:healthreporting:system:
ConfigDocument:
CloudWatchMetrics:
Environment:
ApplicationRequests5xx: 60
ApplicationRequests4xx: 60
Instance:
ApplicationRequestsTotal: 60
Version: 1
SystemType: enhanced
...
```
In the example, 60 indicates the number of seconds between measurements. Currently, this is the only supported value.
**Note**
You can combine `CloudWatchMetrics` and `Rules` in the same `ConfigDocument` option setting. `Rules` are described in [Configuring enhanced health rules for an environment](health-enhanced-rules.md).
If you previously used `Rules` to configure enhanced health rules, then the configuration file that you retrieve using the **eb config save** command already has a `ConfigDocument` key with a `Rules` section. *Do not delete it*—add a `CloudWatchMetrics` section into the same `ConfigDocument` option value.
1. Save the configuration file and close the text editor. In this example, the updated configuration file is saved with a name (`02-cloudwatch-enabled.cfg.yml`) that is different from the downloaded configuration file. This creates a separate saved configuration when the file is uploaded. You can use the same name as the downloaded file to overwrite the existing configuration without creating a new one.
1. Use the **eb config put** command to upload the updated configuration file to Elastic Beanstalk.
```
$ eb config put 02-cloudwatch-enabled
```
When using the **eb config** `get` and `put` commands with saved configurations, don't include the file extension.
1. Apply the saved configuration to your running environment.
```
$ eb config --cfg 02-cloudwatch-enabled
```
The `--cfg` option specifies a named configuration file that is applied to the environment. You can save the configuration file locally or in Elastic Beanstalk. If a configuration file with the specified name exists in both locations, the EB CLI uses the local file.
## Providing custom metric config documents
The configuration (config) document for Amazon CloudWatch custom metrics is a JSON document that lists the metrics to publish at the environment and instance levels. The following example shows a config document that enables all custom metrics available on Linux.
```
{
"CloudWatchMetrics": {
"Environment": {
"ApplicationLatencyP99.9": 60,
"InstancesSevere": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"InstancesUnknown": 60,
"ApplicationLatencyP85": 60,
"InstancesInfo": 60,
"ApplicationRequests2xx": 60,
"InstancesDegraded": 60,
"InstancesWarning": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"InstancesNoData": 60,
"InstancesPending": 60,
"ApplicationLatencyP10": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"InstancesOk": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60
},
"Instance": {
"ApplicationLatencyP99.9": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"ApplicationLatencyP85": 60,
"CPUUser": 60,
"ApplicationRequests2xx": 60,
"CPUIdle": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"RootFilesystemUtil": 60,
"LoadAverage1min": 60,
"CPUIrq": 60,
"CPUNice": 60,
"CPUIowait": 60,
"ApplicationLatencyP10": 60,
"LoadAverage5min": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"CPUSystem": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60,
"InstanceHealth": 60,
"CPUSoftirq": 60
}
},
"Version": 1
}
```
For the AWS CLI, you pass the document as a value for the `Value` key in an option settings argument, which itself is a JSON object. In this case, you must escape quotation marks in the embedded document.
```
$ aws elasticbeanstalk validate-configuration-settings --application-name my-app --environment-name my-env --option-settings '[
{
"Namespace": "aws:elasticbeanstalk:healthreporting:system",
"OptionName": "ConfigDocument",
"Value": "{\"CloudWatchMetrics\": {\"Environment\": {\"ApplicationLatencyP99.9\": 60,\"InstancesSevere\": 60,\"ApplicationLatencyP90\": 60,\"ApplicationLatencyP99\": 60,\"ApplicationLatencyP95\": 60,\"InstancesUnknown\": 60,\"ApplicationLatencyP85\": 60,\"InstancesInfo\": 60,\"ApplicationRequests2xx\": 60,\"InstancesDegraded\": 60,\"InstancesWarning\": 60,\"ApplicationLatencyP50\": 60,\"ApplicationRequestsTotal\": 60,\"InstancesNoData\": 60,\"InstancesPending\": 60,\"ApplicationLatencyP10\": 60,\"ApplicationRequests5xx\": 60,\"ApplicationLatencyP75\": 60,\"InstancesOk\": 60,\"ApplicationRequests3xx\": 60,\"ApplicationRequests4xx\": 60},\"Instance\": {\"ApplicationLatencyP99.9\": 60,\"ApplicationLatencyP90\": 60,\"ApplicationLatencyP99\": 60,\"ApplicationLatencyP95\": 60,\"ApplicationLatencyP85\": 60,\"CPUUser\": 60,\"ApplicationRequests2xx\": 60,\"CPUIdle\": 60,\"ApplicationLatencyP50\": 60,\"ApplicationRequestsTotal\": 60,\"RootFilesystemUtil\": 60,\"LoadAverage1min\": 60,\"CPUIrq\": 60,\"CPUNice\": 60,\"CPUIowait\": 60,\"ApplicationLatencyP10\": 60,\"LoadAverage5min\": 60,\"ApplicationRequests5xx\": 60,\"ApplicationLatencyP75\": 60,\"CPUSystem\": 60,\"ApplicationRequests3xx\": 60,\"ApplicationRequests4xx\": 60,\"InstanceHealth\": 60,\"CPUSoftirq\": 60}},\"Version\": 1}"
}
]'
```
For an `.ebextensions` configuration file in YAML, you can provide the JSON document as is.
```
option_settings:
- namespace: aws:elasticbeanstalk:healthreporting:system
option_name: ConfigDocument
value: {
"CloudWatchMetrics": {
"Environment": {
"ApplicationLatencyP99.9": 60,
"InstancesSevere": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"InstancesUnknown": 60,
"ApplicationLatencyP85": 60,
"InstancesInfo": 60,
"ApplicationRequests2xx": 60,
"InstancesDegraded": 60,
"InstancesWarning": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"InstancesNoData": 60,
"InstancesPending": 60,
"ApplicationLatencyP10": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"InstancesOk": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60
},
"Instance": {
"ApplicationLatencyP99.9": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"ApplicationLatencyP85": 60,
"CPUUser": 60,
"ApplicationRequests2xx": 60,
"CPUIdle": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"RootFilesystemUtil": 60,
"LoadAverage1min": 60,
"CPUIrq": 60,
"CPUNice": 60,
"CPUIowait": 60,
"ApplicationLatencyP10": 60,
"LoadAverage5min": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"CPUSystem": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60,
"InstanceHealth": 60,
"CPUSoftirq": 60
}
},
"Version": 1
}
```
# Using enhanced health reporting with the Elastic Beanstalk API
Because AWS Elastic Beanstalk enhanced health reporting has role and solution stack requirements, you must update scripts and code that you used prior to the release of enhanced health reporting before you can use it. To maintain backward compatibility, enhanced health reporting is not enabled by default when you create an environment using the Elastic Beanstalk API.
You configure enhanced health reporting by setting the service role, the instance profile, and Amazon CloudWatch configuration options for your environment. You can do this in three ways: by setting the configuration options in the `.ebextensions` folder, with saved configurations, or by configuring them directly in the `create-environment` call's `option-settings` parameter.
To use the API, SDKs, or AWS command line interface (CLI) to create an environment that supports enhanced health, you must:
+ Create a service role and instance profile with the appropriate [permissions](concepts-roles.md)
+ Create a new environment with a new [platform version](concepts.platforms.md)
+ Set the health system type, instance profile, and service role [configuration options](command-options.md)
Use the following configuration options in the `aws:elasticbeanstalk:healthreporting:system`, `aws:autoscaling:launchconfiguration`, and `aws:elasticbeanstalk:environment` namespaces to configure your environment for enhanced health reporting.
## Enhanced health configuration options
**SystemType**
Namespace: `aws:elasticbeanstalk:healthreporting:system`
To enable enhanced health reporting, set to **enhanced**.
**IamInstanceProfile**
Namespace: `aws:autoscaling:launchconfiguration`
Set to the name of an instance profile configured for use with Elastic Beanstalk.
**ServiceRole**
Namespace: `aws:elasticbeanstalk:environment`
Set to the name of a service role configured for use with Elastic Beanstalk.
**ConfigDocument** (optional)
Namespace: `aws:elasticbeanstalk:healthreporting:system`
A JSON document that defines the and instance and environment metrics to publish to CloudWatch. For example:
```
{
"CloudWatchMetrics":
{
"Environment":
{
"ApplicationLatencyP99.9":60,
"InstancesSevere":60
}
"Instance":
{
"ApplicationLatencyP85":60,
"CPUUser": 60
}
}
"Version":1
}
```
**Note**
Config documents may require special formatting, such as escaping quotes, depending on how you provide them to Elastic Beanstalk. See [Providing custom metric config documents](health-enhanced-cloudwatch.md#health-enhanced-cloudwatch-configdocument) for examples.
# Enhanced health log format
AWS Elastic Beanstalk platforms use a custom web server log format to efficiently relay information about HTTP requests to the enhanced health reporting system. The system analyzes the logs, identifies issues, and sets the instance and environment health accordingly. If you disable the web server proxy on your environment and serve requests directly from the web container, you can still make full use of enhanced health reporting by configuring your server to output logs in the location and format that the [Elastic Beanstalk health agent](health-enhanced.md#health-enhanced-agent) uses.
**Note**
The information on this page is relevant only to Linux-based platforms. On the Windows Server platform, Elastic Beanstalk receives information about HTTP requests directly from the IIS web server. For details, see [Web server metrics capture in IIS on Windows server](health-enhanced-metrics-server-iis.md).
## Web server log configuration
Elastic Beanstalk platforms are configured to output two logs with information about HTTP requests. The first is in verbose format and provides detailed information about the request, including the requester's user agent information and a human-readable timestamp.
**/var/log/nginx/access.log**
The following example is from an nginx proxy running on a Ruby web server environment, but the format is similar for Apache.
```
172.31.24.3 - - [23/Jul/2015:00:21:20 +0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3" "177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:21 +0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3" "177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:22 +0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3" "177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:22 +0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3" "177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:22 +0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3" "177.72.242.17"
```
The second log is in terse format. It includes information relevant only to enhanced health reporting. This log is output to a subfolder named `healthd` and rotates hourly. Old logs are deleted immediately after rotating out.
**/var/log/nginx/healthd/application.log.2015-07-23-00**
The following example shows a log in the machine-readable format.
```
1437609879.311"/"200"0.083"0.083"177.72.242.17
1437609879.874"/"200"0.347"0.347"177.72.242.17
1437609880.006"/bad/path"404"0.001"0.001"177.72.242.17
1437609880.058"/"200"0.530"0.530"177.72.242.17
1437609880.928"/bad/path"404"0.001"0.001"177.72.242.17
```
The enhanced health log format includes the following information:
+ The time of the request, in Unix time
+ The path of the request
+ The HTTP status code for the result
+ The request time
+ The upstream time
+ The `X-Forwarded-For` HTTP header
For nginx proxies, times are printed in floating-point seconds, with three decimal places. For Apache, whole microseconds are used.
**Note**
If you see a warning similar to the following in a log file, where `DATE-TIME` is a date and time, and you are using a custom proxy, such as in a multi-container Docker environment, you must use an .ebextension to configure your environment so that `healthd` can read your log files:
```
W, [DATE-TIME #1922] WARN -- : log file "/var/log/nginx/healthd/application.log.DATE-TIME" does not exist
```
You can start with the .ebextension in the [Multicontainer Docker sample](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/samples/docker-multicontainer-v2.zip).
**/etc/nginx/conf.d/webapp\$1healthd.conf**
The following example shows the log configuration for nginx with the `healthd` log format highlighted.
```
upstream my_app {
server unix:///var/run/puma/my_app.sock;
}
log_format healthd '$msec"$uri"'
'$status"$request_time"$upstream_response_time"'
'$http_x_forwarded_for';
server {
listen 80;
server_name _ localhost; # need to listen to localhost for worker tier
if ($time_iso8601 ~ "^(\d{4})-(\d{2})-(\d{2})T(\d{2})") {
set $year $1;
set $month $2;
set $day $3;
set $hour $4;
}
access_log /var/log/nginx/access.log main;
access_log /var/log/nginx/healthd/application.log.$year-$month-$day-$hour healthd;
location / {
proxy_pass http://my_app; # match the name of upstream directive which is defined above
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location /assets {
alias /var/app/current/public/assets;
gzip_static on;
gzip on;
expires max;
add_header Cache-Control public;
}
location /public {
alias /var/app/current/public;
gzip_static on;
gzip on;
expires max;
add_header Cache-Control public;
}
}
```
**/etc/httpd/conf.d/healthd.conf**
The following example shows the log configuration for Apache.
```
LogFormat "%{%s}t\"%U\"%s\"%D\"%D\"%{X-Forwarded-For}i" healthd
CustomLog "|/usr/sbin/rotatelogs /var/log/httpd/healthd/application.log.%Y-%m-%d-%H 3600" healthd
```
## Generating logs for enhanced health reporting
To provide logs to the health agent, you must do the following:
+ Output logs in the correct format, as shown in the previous section
+ Output logs to `/var/log/nginx/healthd/`
+ Name logs using the following format: `application.log.$year-$month-$day-$hour`
+ Rotate logs once per hour
+ Do not truncate logs
# Notifications and troubleshooting
**Try Amazon Q Developer CLI for AI-assisted troubleshooting**
Amazon Q Developer CLI can help you troubleshoot environment issues quickly. The Q CLI provides solutions by checking environment status, reviewing events, analyzing logs, and asking clarifying questions. For more information and detailed walkthroughs, see [Troubleshooting Elastic Beanstalk Environments with Amazon Q Developer CLI ](https://aws.amazon.com/blogs/devops/troubleshooting-elastic-beanstalk-environments-with-amazon-q-developer-cli/) in the AWS blogs.
This page lists messages for common issues and links to more information. Messages appear in the [Environment overview pane](environments-dashboard-envoverview.md) of the Elastic Beanstalk console and are recorded in [events](using-features.events.md) when health issues persist across several checks.
## Deployments
Elastic Beanstalk monitors your environment for consistency following deployments. If a rolling deployment fails, the version of your application running on the instances in your environment may vary. This can occur if a deployment succeeds on one or more batches but fails prior to all batches completing.
*Incorrect application version found on 2 out of 5 instances. Expected version "v1" (deployment 1).*
*Incorrect application version on environment instances. Expected version "v1" (deployment 1).*
The expected application version is not running on some or all instances in an environment.
*Incorrect application version "v2" (deployment 2). Expected version "v1" (deployment 1).*
The application deployed to an instance differs from the expected version. If a deployment fails, the expected version is reset to the version from the most recent successful deployment. In the above example, the first deployment (version "v1") succeeded, but the second deployment (version "v2") failed. Any instances running "v2" are considered unhealthy.
To solve this issue, start another deployment. You can [redeploy a previous version](using-features.deploy-existing-version.md) that you know works, or configure your environment to [ignore health checks](using-features.rolling-version-deploy.md#environments-cfg-rollingdeployments-console) during deployment and redeploy the new version to force the deployment to complete.
You can also identify and terminate the instances that are running the wrong application version. Elastic Beanstalk will launch instances with the correct version to replace any instances that you terminate. Use the [EB CLI health command](health-enhanced-ebcli.md) to identify instances that are running the wrong application version.
## Application server
*15% of requests are erroring with HTTP 4xx*
*20% of the requests to the ELB are erroring with HTTP 4xx.*
A high percentage of HTTP requests to an instance or environment are failing with 4xx errors.
A 400 series status code indicates that the user made a bad request, such as requesting a page that doesn't exist (404 File Not Found) or that the user doesn't have access to (403 Forbidden). A low number of 404s is not unusual but a large number could mean that there are internal or external links to unavailable pages. These issues can be resolved by fixing bad internal links and adding redirects for bad external links.
*5% of the requests are failing with HTTP 5xx*
*3% of the requests to the ELB are failing with HTTP 5xx.*
A high percentage of HTTP requests to an instance or environment are failing with 500 series status codes.
A 500 series status code indicates that the application server encountered an internal error. These issues indicate that there is an error in your application code and should be identified and fixed quickly.
*95% of CPU is in use*
On an instance, the health agent is reporting an extremely high percentage of CPU usage and sets the instance health to **Warning** or **Degraded**.
Scale your environment to take load off of instances.
## Worker instance
*20 messages waiting in the queue (25 seconds ago)*
Requests are being added to your worker environment's queue faster than they can be processed. Scale your environment to increase capacity.
*5 messages in Dead Letter Queue (15 seconds ago)*
Worker requests are failing repeatedly and being added to the [Dead-letter queues](using-features-managing-env-tiers.md#worker-deadletter). Check the requests in the dead-letter queue to see why they are failing.
## Other resources
*4 active instances is below Auto Scaling group minimum size 5*
The number of instances running in your environment is fewer than the minimum configured for the Auto Scaling group.
*Auto Scaling group (groupname) notifications have been deleted or modified*
The notifications configured for your Auto Scaling group have been modified outside of Elastic Beanstalk.
# AI-powered environment analysis
AWS Elastic Beanstalk's AI-powered analysis identifies root causes and recommends solutions for environment health issues. When your environment experiences problems, you can request an AI analysis using the `RequestEnvironmentInfo` and `RetrieveEnvironmentInfo` API operations with the `analyze` info type to get AI-generated insights and recommended solutions.
**Note**
AI analysis is available only on supported Amazon Linux 2 and AL2023 platform versions released on or after February 16, 2026.
## How it works
When you request an AI analysis, Elastic Beanstalk runs a script on an instance in your environment that collects recent events, instance health, and logs (up to 170,000 [tokens](https://docs.aws.amazon.com/bedrock/latest/userguide/key-definitions.html) of data). It then sends this data to Amazon Bedrock in your account and returns insights and recommended next steps.
## Prerequisites
Before you use AI analysis, verify that your environment meets the following requirements:
+ Environment running a [supported platform version](#health-ai-analysis-supported-platforms)
+ [Instance profile](iam-instanceprofile.md) with required permissions (see [Required permissions](#health-ai-analysis-permissions) below)
+ **Anthropic use case details** – AI analysis uses Anthropic Claude models through Amazon Bedrock. Anthropic requires you to submit a one-time use case details form before you can invoke their models. To submit this form, select any Anthropic model from the model catalog in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), or call the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_PutUseCaseForModelAccess.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_PutUseCaseForModelAccess.html) API. You only need to do this once per AWS account. If you submit the form from the AWS Organizations management account, it automatically covers all member accounts in the organization. For more information, see [Access Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html).
+ **GovCloud regions** – If you are using AWS GovCloud (US) regions, you must enable access to the latest Anthropic Claude Sonnet and/or Opus model in Amazon Bedrock before using AI analysis. For instructions on enabling model access in GovCloud regions, see [Manage access to Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html#model-access-govcloud). For information about the latest available Anthropic Claude Sonnet and/or Opus model, see [Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html).
## Required permissions
To use AI analysis, the Amazon EC2 instance profile for your environment must have permissions to invoke Amazon Bedrock. Add the following permissions to your instance profile:
+ `bedrock:InvokeModel`
+ `bedrock:ListFoundationModels`
+ `elasticbeanstalk:DescribeEvents`
+ `elasticbeanstalk:DescribeEnvironmentHealth`
For more information about configuring instance profiles, see [Managing Elastic Beanstalk instance profiles](iam-instanceprofile.md).
## Using AI analysis in the console
**From the environment overview**
When your environment's health status is **Warning**, **Degraded**, or **Severe**, an **AI Analysis** button appears in the environment overview section. Click on this button to initiate an AI analysis of your environment.
**From the Logs page**
You can also access AI analysis from the **Logs** page in the navigation pane. Click on the **AI Analysis** button to request an AI-powered analysis of your environment's current state.
## Using AI analysis with the AWS CLI
You can use the Elastic Beanstalk API through the AWS CLI to request and retrieve AI analysis programmatically.
**Request AI analysis**
Use the [http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RequestEnvironmentInfo.html](http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RequestEnvironmentInfo.html) operation with the `InfoType` parameter set to `analyze`.
**Example AWS CLI - Request AI analysis**
```
aws elasticbeanstalk request-environment-info \
--environment-name my-env \
--info-type analyze \
--region us-east-1
```
**Retrieve AI analysis**
Use the [http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RetrieveEnvironmentInfo.html](http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RetrieveEnvironmentInfo.html) operation with the `InfoType` parameter set to `analyze` to retrieve the analysis results.
**Example AWS CLI - Retrieve AI analysis**
```
aws elasticbeanstalk retrieve-environment-info \
--environment-name my-env \
--info-type analyze \
--region us-east-1
```
The response includes an AI-generated analysis of the current state of the environment, along with recommended solutions for any identified issues.
## Using AI analysis with the EB CLI
If you use the EB CLI, you can request AI analysis with the `--analyze` (`-ai`) option of the **eb logs** command. The command requests the analysis, waits for it to complete, and displays the results.
**Example EB CLI - Request AI analysis**
```
$ eb logs --analyze
```
The `--analyze` option is not compatible with `--instance`, `--all`, `--zip`, or `--log-group`. For the full command reference, see [**eb logs**](eb3-logs.md).
**Note**
The `--analyze` option requires EB CLI version 3.27 or later.
## Important considerations
+ **Pricing** – AI analysis uses Amazon Bedrock to process your environment data, and standard Amazon Bedrock pricing applies for model invocations. For pricing details, see [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/).
+ **Platform requirement** – AI analysis is available only on Amazon Linux 2 and AL2023 based platform versions released on or after February 16, 2026. To use this feature, update your environment to a supported platform version. For more information, see [Updating your Elastic Beanstalk environment's platform version](using-features.platform.upgrade.md).
+ **Permissions** – Before using AI analysis, ensure that your instance profile has the required Amazon Bedrock permissions (`bedrock:InvokeModel` and `bedrock:ListFoundationModels`) and Elastic Beanstalk permissions (`elasticbeanstalk:DescribeEvents` and `elasticbeanstalk:DescribeEnvironmentHealth`).
+ **Data privacy** – The analysis sends environment events and logs to Amazon Bedrock in your account for processing. For information about how Amazon Bedrock handles your data, see [Amazon Bedrock Security and Compliance](https://aws.amazon.com/bedrock/security-compliance/).
+ **Service quotas** – AI analysis uses an Anthropic Claude model in Amazon Bedrock, which has default quotas for requests per minute and tokens per minute. If you encounter throttling errors, you can request a quota increase. For more information, see [Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html).
## Supported platform versions
AI analysis is supported on Amazon Linux 2 and AL2023 based platform versions released on or after [February 16, 2026](RELEASE_NOTES_URL). To verify your platform version, see [Elastic Beanstalk release notes](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/welcome.html).
# Manage alarms
This topic walks you through the steps to create alarms for metrics that you're monitoring. It also provides instructions to view your existing alarms and to check their state.
You can create alarms for metrics that you are monitoring by using the Elastic Beanstalk console. Alarms help you monitor changes to your AWS Elastic Beanstalk environment so that you can easily identify and mitigate problems before they occur. For example, you can set an alarm that notifies you when CPU utilization in an environment exceeds a certain threshold, ensuring that you are notified before a potential problem occurs. For more information, see [Using Elastic Beanstalk with Amazon CloudWatch](AWSHowTo.cloudwatch.md).
**Note**
Elastic Beanstalk uses CloudWatch for monitoring and alarms, meaning CloudWatch costs are applied to your AWS account for any alarms that you use.
For more information about monitoring specific metrics, see [Basic health reporting](using-features.healthstatus.md).
**To check the state of your alarms**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Alarms**.
The page displays a list of existing alarms. If any alarms are in the alarm state, they are flagged with the warning icon (![\[Image of the warning icon.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/warning.png)).
1. To filter alarms, choose the drop-down menu, and then select a filter.
1. To edit or delete an alarm, choose the edit icon (![\[Image of a cog, which serves as the edit icon.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/cog.png)) or the delete icon (![\[Image of an x, which servers as the delete icon.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/x.png)), respectively.
**To create an alarm**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Monitoring**.
1. Locate the metric for which you want to create an alarm, and then choose the alarm icon (![\[Image of a bell, which serves as the alarm icon.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/bell.png)). The **Add alarm** page is displayed.
1. Enter details about the alarm:
+ **Name**: A name for this alarm.
+ **Description** (optional): A short description of what this alarm is.
+ **Period**: The time interval between readings.
+ **Threshold**: Describes the behavior and value that the metric must exceed in order to trigger an alarm.
+ **Change state after**: The amount a time after a threshold has been exceed that triggers a change in state of the alarm.
+ **Notify**: The Amazon SNS topic that is notified when an alarm changes state.
+ **Notify when state changes to**:
+ **OK**: The metric is within the defined threshold.
+ **Alarm**: The metric exceeded the defined threshold.
+ **Insufficient data**: The alarm has just started, the metric is not available, or not enough data is available for the metric to determine the alarm state.
1. Choose **Add**. The environment status changes to gray while the environment updates. You can view the alarm that you created by choosing **Alarms** in the navigation pane.
# Viewing an Elastic Beanstalk environment's change history
This topic explains how you can use the Elastic Beanstalk Console to view a history of configuration changes that have been made to your Elastic Beanstalk environments.
Elastic Beanstalk fetches your change history from events recorded in [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) and displays them in a list that you can easily navigate and filter.
The Change History panel displays the following information for changes made to your environments:
+ The date and time when a change was made
+ The IAM user that was responsible for a change made
+ The source tool (either Elastic Beanstalk command line interface (EB CLI) or console) that was used to make the change
+ The configuration parameter and new values that were set
Any sensitive data that is part of the change, such as the names of database users affected by the change, aren't displayed in the panel.
**To view change history**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Change history**.
The Change History page shows a list of configuration changes that were made to your Elastic Beanstalk environments.
Note the following points about navigating the information on this page:
+ You can page through the list by choosing **<** (previous) or **>** (next), or by choosing a specific page number.
+ Under the **Configuration changes** column, select the arrow icon to toggle between expanding and collapsing the list of changes under the **Changes made** heading.
+ Use the search bar to filter your results from the change history list. You can enter any string to narrow down the list of changes that are displayed.
Note the following about filtering the displayed results:
+ The search filter is not case sensitive.
+ You can filter displayed changes based on information under the **Configuration changes** column, even when it is not visible due to being collapsed inside **Changes made**.
+ You can only filter the results displayed. However, the filter remains in place even if you select to go to another page to display more results. Your filtered results also append to the result set of the next page.
The following examples demonstrate how the data shown on the earlier screen can be filtered:
+ Enter **GettingStartedApp-env** in the search box to narrow down the results to only include the changes that were made to the environment named *GettingStartedApp-env*.
+ Enter **example3** in the search box to narrow down the results to only include changes that were made by IAM users whose username contains the string *example3*.
+ Enter **2020-10** in the search box to narrow down the results to only include changes that were made during the month of October 2020. Change the search value to **2020-10-16** to filter further the displayed results to only include changes that were made on the day of October 16, 2020.
+ Enter **proxy:staticfiles** in the search box to narrow down the results to only include the changes that were made to the namespace named *aws:elasticbeanstalk:environment:proxy:staticfiles*. The rows that are displayed are the result of the filter. This is true even for results that are collapsed under **Changes made**.
# Viewing an Elastic Beanstalk environment's event stream
This topic explains how to access events and notifications associated with your application.
## Viewing events with the Elastic Beanstalk console
**To view events with the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Events**.
The Events page shows a list of all events that have been recorded for the environment. You can page through the list choosing **<** (previous), **>** (next), or page numbers. You can filter the type of events shown by using the **Severity** drop-down list.
## Viewing events with command line tools
The [EB CLI](eb-cli3.md) and [AWS CLI](https://aws.amazon.com/cli/) both provide commands for retrieving events. If you are managing your environment using the EB CLI, use [**eb events**](eb3-events.md) to print a list of events. This command also has a `--follow` option that continues to show new events until you press **Ctrl\$1C** to stop output.
To pull events using the AWS CLI, use the `describe-events` command and specify the environment by name or ID:
```
$ aws elasticbeanstalk describe-events --environment-id e-gbjzqccra3
{
"Events": [
{
"ApplicationName": "elastic-beanstalk-example",
"EnvironmentName": "elasticBeanstalkExa-env",
"Severity": "INFO",
"RequestId": "a4c7bfd6-2043-11e5-91e2-9114455c358a",
"Message": "Environment update completed successfully.",
"EventDate": "2015-07-01T22:52:12.639Z"
},
...
```
For more information about the command line tools, see [Setting up the EB command line interface (EB CLI) to manage Elastic Beanstalk](eb-cli3.md).
# Listing and connecting to server instances
This topic explains how to view a list of the Amazon EC2 instances running your Elastic Beanstalk application environment and how to connect to them.
You can view a list of Amazon EC2 instances running your AWS Elastic Beanstalk application environment through the Elastic Beanstalk console. You can connect to the instances using any SSH client. You can connect to the instances running Windows using Remote Desktop.
**Important**
Before you can access your Elastic Beanstalk–provisioned Amazon EC2 instances, you must create an Amazon EC2 key pair and configure your Elastic Beanstalk–provisioned Amazon EC2instances to use the Amazon EC2 key pair. You can set up your Amazon EC2 key pairs using the [AWS Management Console](https://console.aws.amazon.com/). For instructions on creating a key pair for Amazon EC2, see the *Amazon EC2 Getting Started Guide*. For more information on how to configure your Amazon EC2 instances to use an Amazon EC2 key pair, see [EC2 key pair](using-features.managing.security.md#using-features.managing.security.keypair).
By default, Elastic Beanstalk does not enable remote connections to EC2 instances in a Windows container except for those in legacy Windows containers. (Elastic Beanstalk configures EC2 instances in legacy Windows containers to use port 3389 for RDP connections.) You can enable remote connections to your EC2 instances running Windows by adding a rule to a security group that authorizes inbound traffic to the instances. We strongly recommend that you remove the rule when you end your remote connection. You can add the rule again the next time you need to log in remotely. For more information, see [Adding a Rule for Inbound RDP Traffic to a Windows Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/authorizing-access-to-an-instance.html#authorizing-access-to-an-instance-rdp) and [Connect to Your Windows Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2Win_GetStarted.html#connecting_to_windows_instance) in the *Amazon Elastic Compute Cloud User Guide for Microsoft Windows*.
**To view and connect to Amazon EC2 instances for an environment**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane of the console, choose **Load Balancers**.
1. Load balancers created by Elastic Beanstalk have **awseb** in the name. Find the load balancer for your environment and click it.
1. Choose the **Instances** tab in the bottom pane of the console.
A list of the instances that the load balancer for your Elastic Beanstalk environment uses is displayed. Make a note of an instance ID that you want to connect to.
1. In the navigation pane of the Amazon EC2 console, choose **Instances**, and find your instance ID in the list.
1. Right-click the instance ID for the Amazon EC2 instance running in your environment's load balancer, and then select **Connect** from the context menu.
1. Make a note of the instance's public DNS address on the **Description** tab.
1. Connect to an instance running Linux by using the SSH client of your choice, and then type **ssh -i .ec2/mykeypair.pem ec2-user@ **.
For more information on connecting to an Amazon EC2 Linux instance, see [Getting Started with Amazon EC2 Linux Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) in the *Amazon EC2 User Guide*.
If your Elastic Beanstalk environment uses the [.NET on Windows Server platform](create_deploy_NET.container.console.md), see [Getting Started with Amazon EC2 Windows Instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html) in the *Amazon EC2 User Guide*.
# Viewing logs from Amazon EC2 instances in your Elastic Beanstalk environment
This topic explains the types of instance logs that Elastic Beanstalk provides. It also provides detailed instructions for retreiveing and managing them.
The Amazon EC2 instances in your Elastic Beanstalk environment generate logs that you can view to troubleshoot issues with your application or configuration files. Logs created by the web server, application server, Elastic Beanstalk platform scripts, and CloudFormation are stored locally on individual instances. You can easily retrieve them by using the [environment management console](environments-console.md) or the EB CLI. You can also configure your environment to stream logs to Amazon CloudWatch Logs in real time.
Tail logs are the last 100 lines of the most commonly used log files—Elastic Beanstalk operational logs and logs from the web server or application server. When you request tail logs in the environment management console or with **eb logs**, an instance in your environment concatenates the most recent log entries into a single text file and uploads it to Amazon S3.
Bundle logs are full logs for a wider range of log files, including logs from yum and cron and several logs from CloudFormation. When you request bundle logs, an instance in your environment packages the full log files into a ZIP archive and uploads it to Amazon S3.
To upload rotated logs to Amazon S3, the instances in your environment must have an [instance profile](concepts-roles-instance.md) with permission to write to your Elastic Beanstalk Amazon S3 bucket. These permissions are included in the default instance profile that Elastic Beanstalk prompts you to create when you launch an environment in the Elastic Beanstalk console for the first time.
**To retrieve instance logs**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Logs**.
1. Choose **Request Logs**, and then choose the type of logs to retrieve. To get tail logs, choose **Last 100 Lines**. To get bundle logs, choose **Full Logs**.
1. When Elastic Beanstalk finishes retrieving your logs, choose **Download**.
Elastic Beanstalk stores tail and bundle logs in an Amazon S3 bucket, and generates a presigned Amazon S3 URL that you can use to access your logs. Elastic Beanstalk deletes the files from Amazon S3 after a duration of 15 minutes.
**Warning**
Anyone in possession of the presigned Amazon S3 URL can access the files before they are deleted. Make the URL available only to trusted parties.
**Note**
Your user policy must have the `s3:DeleteObject` permission. Elastic Beanstalk uses your user permissions to delete the logs from Amazon S3.
To persist logs, you can configure your environment to publish logs to Amazon S3 automatically after they are rotated. To enable log rotation to Amazon S3, follow the procedure in [Configuring instance log viewing](environments-cfg-logging.md#environments-cfg-logging-console). Instances in your environment will attempt to upload logs that have been rotated once per hour.
If your application generates logs in a location that isn't part of the default configuration for your environment's platform, you can extend the default configuration by using configuration files (`[.ebextensions](ebextensions.md)`). You can add your application's log files to tail logs, bundle logs, or log rotation.
For real-time log streaming and long-term storage, configure your environment to [stream logs to Amazon CloudWatch Logs](#health-logs-cloudwatchlogs).
To get AI-powered analysis of your environment logs, events, and instance health to identify root causes and solutions for health issues, see [AI-powered environment analysis](health-ai-analysis.md).
**Topics**
+ [Log location on Amazon EC2 instances](#health-logs-instancelocation)
+ [Log location in Amazon S3](#health-logs-s3location)
+ [Log rotation settings on Linux](#health-logs-logrotate)
+ [Extending the default log task configuration](#health-logs-extend)
+ [Streaming log files to Amazon CloudWatch Logs](#health-logs-cloudwatchlogs)
## Log location on Amazon EC2 instances
Logs are stored in standard locations on the Amazon EC2 instances in your environment. Elastic Beanstalk generates the following logs.
**Amazon Linux 2**
+ `/var/log/eb-engine.log`
**Amazon Linux AMI (AL1)**
**Note**
On [July 18, 2022](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2022-07-18-linux-al1-retire.html), Elastic Beanstalk set the status of all platform branches based on Amazon Linux AMI (AL1) to **retired**. For more information about migrating to a current and fully supported Amazon Linux 2023 platform branch, see [Migrating your Elastic Beanstalk Linux application to Amazon Linux 2023 or Amazon Linux 2](using-features.migration-al.md).
+ `/var/log/eb-activity.log`
+ `/var/log/eb-commandprocessor.log`
**Windows Server**
+ `C:\Program Files\Amazon\ElasticBeanstalk\logs\`
+ `C:\cfn\log\cfn-init.log`
These logs contain messages about deployment activities, including messages related to configuration files ([`.ebextensions`](ebextensions.md)).
Each application and web server stores logs in its own folder:
+ **Apache** – `/var/log/httpd/`
+ **IIS** – `C:\inetpub\wwwroot\`
+ **Node.js** – `/var/log/nodejs/`
+ **nginx** – `/var/log/nginx/`
+ **Passenger** – `/var/app/support/logs/`
+ **Puma** – `/var/log/puma/`
+ **Python** – `/opt/python/log/`
+ **Tomcat** – `/var/log/tomcat/`
## Log location in Amazon S3
When you request tail or bundle logs from your environment, or when instances upload rotated logs, they're stored in your Elastic Beanstalk bucket in Amazon S3. Elastic Beanstalk creates a bucket named `elasticbeanstalk-region-account-id` for each AWS Region in which you create environments. Within this bucket, logs are stored under the path `resources/environments/logs/logtype/environment-id/instance-id`.
For example, logs from instance `i-0a1fd158`, in Elastic Beanstalk environment `e-mpcwnwheky` in AWS Region `us-west-2` in account `123456789012`, are stored in the following locations:
+ **Tail Logs** –
`s3://elasticbeanstalk-us-west-2-123456789012/resources/environments/logs/tail/e-mpcwnwheky/i-0a1fd158`
+ **Bundle Logs** –
`s3://elasticbeanstalk-us-west-2-123456789012/resources/environments/logs/bundle/e-mpcwnwheky/i-0a1fd158`
+ **Rotated Logs** –
`s3://elasticbeanstalk-us-west-2-123456789012/resources/environments/logs/publish/e-mpcwnwheky/i-0a1fd158`
**Note**
You can find your environment ID in the environment management console.
Elastic Beanstalk deletes tail and bundle logs from Amazon S3 automatically 15 minutes after they are created. Rotated logs persist until you delete them or move them to Amazon Glacier.
## Log rotation settings on Linux
On Linux platforms, Elastic Beanstalk uses `logrotate` to rotate logs periodically. If configured, after a log is rotated locally, the log rotation task picks it up and uploads it to Amazon S3. Logs that are rotated locally don't appear in tail or bundle logs by default.
You can find Elastic Beanstalk configuration files for `logrotate` in `/etc/logrotate.elasticbeanstalk.hourly/`. These rotation settings are specific to the platform, and might change in future versions of the platform. For more information about the available settings and example configurations, run `man logrotate`.
The configuration files are invoked by cron jobs in `/etc/cron.hourly/`. For more information about `cron`, run `man cron`.
## Extending the default log task configuration
Elastic Beanstalk uses files in subfolders of `/opt/elasticbeanstalk/tasks` (Linux) or `C:\Program Files\Amazon\ElasticBeanstalk\config` (Windows Server) on the Amazon EC2 instance to configure tasks for tail logs, bundle logs, and log rotation.
**On Amazon Linux:**
+ **Tail Logs** –
`/opt/elasticbeanstalk/tasks/taillogs.d/`
+ **Bundle Logs** –
`/opt/elasticbeanstalk/tasks/bundlelogs.d/`
+ **Rotated Logs** –
`/opt/elasticbeanstalk/tasks/publishlogs.d/`
**On Windows Server:**
+ **Tail Logs** –
`c:\Program Files\Amazon\ElasticBeanstalk\config\taillogs.d\`
+ **Bundle Logs** –
`c:\Program Files\Amazon\ElasticBeanstalk\config\bundlelogs.d\`
+ **Rotated Logs** –
`c:\Program Files\Amazon\ElasticBeanstalk\config\publogs.d\`
For example, the `eb-activity.conf` file on Linux adds two log files to the tail logs task.
**`/opt/elasticbeanstalk/tasks/taillogs.d/eb-activity.conf `**
```
/var/log/eb-commandprocessor.log
/var/log/eb-activity.log
```
You can use environment configuration files (`[.ebextensions](ebextensions.md)`) to add your own `.conf` files to these folders. A `.conf` file lists log files specific to your application, which Elastic Beanstalk adds to the log file tasks.
Use the `files` section to add configuration files to the tasks that you want to modify. For example, the following configuration text adds a log configuration file to each instance in your environment. This log configuration file, `cloud-init.conf`, adds `/var/log/cloud-init.log` to tail logs.
```
files:
"/opt/elasticbeanstalk/tasks/taillogs.d/cloud-init.conf" :
mode: "000755"
owner: root
group: root
content: |
/var/log/cloud-init.log
```
Add this text to a file with the `.config` file name extension to your source bundle under a folder named `.ebextensions`.
```
~/workspace/my-app
|-- .ebextensions
| `-- tail-logs.config
|-- index.php
`-- styles.css
```
On Linux platforms, you can also use wildcard characters in log task configurations. This configuration file adds all files with the `.log` file name extension from the `log` folder in the application root to bundle logs.
```
files:
"/opt/elasticbeanstalk/tasks/bundlelogs.d/applogs.conf" :
mode: "000755"
owner: root
group: root
content: |
/var/app/current/log/*.log
```
Log task configurations don't support wildcard characters on Windows platforms.
**Note**
To help familiarize yourself with log customization procedures, you can deploy a sample application using the [EB CLI](eb-cli3.md). For this, the EB CLI creates a local application directory that contains an `.ebextentions` subdirectory with a sample configuration. You can also use the sample application's log files to explore the log retrieval feature described in this topic.
For more information about using configuration files, see [Advanced environment customization with configuration files (`.ebextensions`)](ebextensions.md).
Much like extending tail logs and bundle logs, you can extend log rotation using a configuration file. Whenever Elastic Beanstalk rotates its own logs and uploads them to Amazon S3, it also rotates and uploads your additional logs. Log rotation extension behaves differently depending on the platform's operating system. The following sections describe the two cases.
### Extending log rotation on Linux
As explained in [Log rotation settings on Linux](#health-logs-logrotate), Elastic Beanstalk uses `logrotate` to rotate logs on Linux platforms. When you configure your application's log files for log rotation, the application doesn't need to create copies of log files. Elastic Beanstalk configures `logrotate` to create a copy of your application's log files for each rotation. Therefore, the application must keep log files unlocked when it isn't actively writing to them.
### Extending log rotation on Windows server
On Windows Server, when you configure your application's log files for log rotation, the application must rotate the log files periodically. Elastic Beanstalk looks for files with names starting with the pattern you configured, and picks them up for uploading to Amazon S3. In addition, periods in the file name are ignored, and Elastic Beanstalk considers the name up to the period to be the base log file name.
Elastic Beanstalk uploads all versions of a base log file except for the newest one, because it considers that one to be the active application log file, which can potentially be locked. Your application can, therefore, keep the active log file locked between rotations.
For example, your application writes to a log file named `my_log.log`, and you specify this name in your `.conf` file. The application periodically rotates the file. During the Elastic Beanstalk rotation cycle, it finds the following files in the log file's folder: `my_log.log`, `my_log.0800.log`, `my_log.0830.log`. Elastic Beanstalk considers all of them to be versions of the base name `my_log`. The file `my_log.log` has the latest modification time, so Elastic Beanstalk uploads only the other two files, `my_log.0800.log` and `my_log.0830.log`.
## Streaming log files to Amazon CloudWatch Logs
You can configure your environment to stream logs to Amazon CloudWatch Logs in the Elastic Beanstalk console or by using [configuration options](command-options.md). With CloudWatch Logs, each instance in your environment streams logs to log groups that you can configure to be retained for weeks or years, even after your environment is terminated.
The set of logs streamed varies per environment, but always includes `eb-engine.log` and access logs from the nginx or Apache proxy server that runs in front of your application.
You can configure log streaming in the Elastic Beanstalk console either [during environment creation](environments-create-wizard.md#environments-create-wizard-software) or [for an existing environment](environments-cfg-logging.md#environments-cfg-logging-console). You can set the following options from the console: enable /disable log streaming to CloudWatch Logs, set the number of retention days, and select from Lifecyle options. In the following example, logs are saved for up to seven days, even when the environment is terminated.
![\[Screen image of CloudWatch Logs settings in the Elastic Beanstalk console.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/log-streaming-screen.png)
The following [configuration file](ebextensions.md) enables log streaming with 180 days retention, even if the environment is terminated.
**Example .ebextensions/log-streaming.config**
```
option_settings:
aws:elasticbeanstalk:cloudwatch:logs:
StreamLogs: true
DeleteOnTerminate: false
RetentionInDays: 180
```
# Viewing deployment logs for an Elastic Beanstalk environment
Elastic Beanstalk generates a deployment log for each deployment to your environment. The deployment log provides a consolidated, chronological view of what happened during a deployment, including dependency installation, build output, application startup, and any errors encountered. You can use deployment logs to quickly diagnose failed deployments without needing to SSH into instances or correlate multiple log files.
Deployment logs are written to each instance locally. For deployments triggered through the console, CLI, API, or managed updates, one instance continuously uploads its log to Amazon S3 during the deployment. The Elastic Beanstalk console reads the log from Amazon S3, so you can monitor progress without connecting to the instance.
Deployment logs are designed to be concise. On success, the log shows only summary messages (for example, which commands ran and completed). On failure, the log includes up to 50 lines of output from the failed step, so you can see the error without sifting through verbose output.
**Note**
Deployment logs are available on [Amazon Linux 2](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2026-03-11-al2.html) and [Amazon Linux 2023](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2026-03-11-al2023.html) platform versions released on or after March 11, 2026. Windows platforms are not currently supported.
## Supported operations
Deployment logs are generated for the following operations:
+ **Application deployments** – Deploying a new application version to your environment.
+ **Configuration updates** – Changing environment configuration settings that are applied to existing instances, and updates that add new instances to the environment.
+ **Environment creation** – The initial deployment when you create a new environment.
+ **Restart app server** – Restarting the application server on your instances.
+ **Managed platform updates** – Platform updates that Elastic Beanstalk applies automatically during a scheduled maintenance window.
Operations that don't modify application or configuration state on instances, such as requesting logs, swapping CNAMEs, or updating tags, do not generate deployment logs.
## Deployment log contents
A deployment log captures the following information during a deployment:
+ **Deployment lifecycle** – Start and completion messages for each deployment phase, such as `Starting Application deployment` and `Completed Application deployment`.
+ **.ebextensions output** – On success, the names of commands that ran. On failure, the last 50 lines of `cfn-init` output to help diagnose the issue.
+ **Platform hooks output** – On success, the names of hook scripts that ran. On failure, the last 50 lines of hook output.
+ **Dependency installation** – Output from package managers such as **npm install**, **pip install**, **composer install**, and **bundle install**. On success, only a completion message is logged. On failure, the last 50 lines of output are included.
+ **Build output** – Output from build commands such as **docker build**, **go build**, and Java builds. On failure, the last 50 lines of output are included.
+ **Application startup output** – Initial output from your application after it starts. The source depends on your platform:
+ *Docker* – Container logs from **docker logs** or **docker compose logs**
+ *Java SE, Go, Node.js, Python, Ruby, .NET* – Process stdout logs
+ *Tomcat* – Catalina log output
+ *PHP* – PHP-FPM master and pool error logs
+ *ECS* – Container logs from each task container
**Note**
Application output is captured starting 2 seconds after the application starts. Only the initial startup messages are included – if your application takes longer to produce output, it won't appear in the deployment log. To see full application logs, request bundle logs or connect to the instance directly. For more information, see [View instance logs](using-features.logging.md).
When a deployment step fails, the log marks it with `[ERROR]` and includes up to 50 lines of output from the failed step. If the deployment log does not contain enough detail, you can retrieve the full instance logs (including `eb-engine.log`, `eb-hooks.log`, and application logs) from the **Logs** tab. For more information, see [Viewing logs from Amazon EC2 instances in your Elastic Beanstalk environment](using-features.logging.md).
## Viewing deployment logs in the console
The Elastic Beanstalk console provides a **Deployments** tab on the environment dashboard where you can view your deployment history and logs.
### Viewing deployment history
**To view deployment history**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the environment dashboard, choose the **Deployments** tab.
The Deployments tab shows a table of deployments for the environment. Each row includes the following information:
+ **Request ID** – The unique identifier for the deployment.
+ **Status** – *Succeeded*, *Failed*, or *In progress*.
+ **Type** – The deployment type, such as *Environment Creation*, *Application Deployment*, *Configuration Update*, *Managed Platform Update*, *Restart App Server*, *Rebuild Environment*, *Restore Environment*, *Swap Environment Domain*, or *Terminate Environment*.
+ **Policy** – The deployment policy, such as *All at once*, *Rolling*, *Rolling with additional batch*, *Immutable*, or *Traffic splitting*.
+ **Start Time** – When the deployment began.
+ **Duration** – How long the deployment took to complete.
When a deployment is in progress, the tab automatically polls for updates. You can also choose the refresh button to manually reload the list.
### Viewing deployment details and logs
**To view deployment details**
1. On the **Deployments** tab, choose the **Request ID** link for the deployment you want to inspect.
1. The deployment detail page shows a summary section with the request ID, status, deployment type, start time, duration, and deployment policy. The deployment policy (for example, *All at once*, *Rolling*, *Rolling with additional batch*, *Immutable*, or *Traffic splitting*) is shown when it can be determined from the deployment events.
1. Below the summary, choose one of the following tabs:
+ **Events** – A timeline of events related to this deployment, filtered to show only events for the selected deployment.
+ **Deployment Logs** – The consolidated deployment log from the instance. You can search, filter by log level, and download the log file.
For in-progress deployments, the logs tab automatically refreshes to show new log entries as they are written. After a deployment completes, the console fetches the final log state to ensure you see the complete output.
**Important**
Viewing deployment logs in the console requires `s3:GetObject` permission on the environment's Amazon S3 storage bucket (`elasticbeanstalk-region-account-id`). If your IAM policy does not include this permission, the deployment history and events will still be available, but the logs tab will show an error.
## Deployment log files on instances
Deployment logs are written to the `/var/log/deployments/` directory on each instance. The log filename depends on how the deployment was triggered:
+ **Workflow-controlled deployments** (triggered through the console, CLI, or API) – `eb-deployment-request-id.log`, where *request-id* is the unique deployment request ID.
+ **Self-startup deployments** (instance launch) – `eb-deployment-timestamp-instance-id.log`, where *timestamp* is in UTC format (for example, `20260317T151315Z`) and *instance-id* is the Amazon EC2 instance ID.
Elastic Beanstalk automatically rotates these files, keeping the 50 most recent deployment logs on each instance.
For workflow-controlled deployments, the log is uploaded to Amazon S3 at the following path:
```
s3://elasticbeanstalk-region-account-id/resources/environments/logs/deployments/environment-id/log-filename
```
For self-startup deployments, the log is uploaded to Amazon S3 under a `selfstartup/` subdirectory:
```
s3://elasticbeanstalk-region-account-id/resources/environments/logs/deployments/environment-id/selfstartup/log-filename
```
For workflow-controlled deployments, the first instance to begin uploading claims the role for the entire deployment. That instance uploads its log to Amazon S3 for the duration of the deployment. For self-startup deployments, each instance uploads its own log independently. All instances still write deployment logs locally.
**Important**
Uploading deployment logs to Amazon S3 requires `s3:PutObject` permission on the environment's Amazon S3 storage bucket in the instance profile, and the VPC configuration must allow connectivity to Amazon S3.
Deployment log uploads are capped at 1 MB per file. If a deployment log exceeds this size, the uploaded version is truncated with a message indicating that the full log is available on the instance.
### Disabling S3 log uploads
To prevent deployment logs from being uploaded to Amazon S3, set the following environment property on your environment:
```
option_settings:
- namespace: aws:elasticbeanstalk:application:environment
option_name: EB_DEPLOYMENT_LOG_S3_DISABLED
value: true
```
When this environment property is set, deployment logs are still written locally to `/var/log/deployments/` on each instance, but they are not uploaded to Amazon S3 and will not be available in the console **Deployments** tab. You can also set this property in the **Configuration** page under **Software**, or by using the EB CLI or AWS CLI.