Prerequisites to environment health streaming to CloudWatch Logs Streaming environment health logs to CloudWatch Logs

Streaming Elastic Beanstalk environment health information to Amazon CloudWatch Logs

If you enable enhanced health reporting for your environment, you can configure the environment to stream health information to CloudWatch Logs. This streaming is independent from Amazon EC2 instance log streaming. This topic describes environment health information streaming. For information about instance log streaming, see Using Elastic Beanstalk with Amazon CloudWatch Logs.

When you configure environment health streaming, Elastic Beanstalk creates a CloudWatch Logs log group for environment health. The log group's name is /aws/elasticbeanstalk/environment-name/environment-health.log. Within this log group, Elastic Beanstalk creates log streams named YYYY-MM-DD#<hash-suffix> (there might be more than one log stream per date).

When the environment's health status changes, Elastic Beanstalk adds a record to the health log stream. The record represents the health status transition—the new status and a description of the cause of change. For example, an environment's status might change to Severe because the load balancer is failing. For a description of enhanced health statuses, see Health colors and statuses.

Prerequisites to environment health streaming to CloudWatch Logs

To enable environment health streaming to CloudWatch Logs, you must meet the following conditions:

Platform – You must be using a platform version that supports enhanced health reporting.
Permissions – You must grant certain logging-related permissions to Elastic Beanstalk so that it can act on your behalf to stream health information for your environment. If your environment isn't using a service role that Elastic Beanstalk created for it, aws-elasticbeanstalk-service-role, or your account's service-linked role, AWSServiceRoleForElasticBeanstalk, be sure to add the following permissions to your custom service role.
```
{
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogStreams",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:/aws/elasticbeanstalk/*:log-stream:*"
}
```

Streaming environment health logs to CloudWatch Logs

You can enable environment health streaming to CloudWatch Logs using the Elastic Beanstalk console, the EB CLI, or configuration options.

Environment health log streaming using the Elastic Beanstalk console

To stream environment health logs to CloudWatch Logs

Open the Elastic Beanstalk console, and in the Regions list, select your AWS Region.
In the navigation pane, choose Environments, and then choose the name of your environment from the list.

Note
If you have many environments, use the search bar to filter the environment list.
In the navigation pane, choose Configuration.
In the Monitoring configuration category, choose Edit.
Under Health reporting, make sure that the reporting System is set to Enhanced.
Under Health event streaming to CloudWatch Logs
- Enable Log streaming.
- Set Retention to the number of days to save the logs.
- Select the Lifecycle setting that determines whether the logs are saved after the environment is terminated.
To save the changes choose Apply at the bottom of the page.

After you enable log streaming, you can return to the Monitoring configuration category or page and find the Log Group link. Click this link to see your environment health logs in the CloudWatch console.

Environment health log streaming using the EB CLI

To enable environment health log streaming to CloudWatch Logs using the EB CLI, use the eb logs command.


$ eb logs --cloudwatch-logs enable --cloudwatch-log-source environment-health

You can also use eb logs to retrieve logs from CloudWatch Logs. For example, the following command retrieves all the health logs for your environment, and saves them to a directory under .elasticbeanstalk/logs.


$ eb logs --all --cloudwatch-log-source environment-health

Environment health log streaming using configuration files

When you create or update an environment, you can use a configuration file to set up and configure environment health log streaming to CloudWatch Logs. To use the example below, copy the text into a file with the .config extension in the .ebextensions directory at the top level of your application source bundle. The example configures Elastic Beanstalk to enable environment health log streaming, keep the logs after terminating the environment, and save them for 30 days.

Example Health streaming configuration file


############################################################################
##  Sets up Elastic Beanstalk to stream environment health information
##  to Amazon CloudWatch Logs.
##  Works only for environments that have enhanced health reporting enabled.
############################################################################

option_settings:
  aws:elasticbeanstalk:cloudwatch:logs:health:
    HealthStreamingEnabled: true
    ### Settings below this line are optional.
    # DeleteOnTerminate: Delete the log group when the environment is
    # terminated. Default is false. If false, the health data is kept
    # RetentionInDays days.
    DeleteOnTerminate: false
    # RetentionInDays: The number of days to keep the archived health data
    # before it expires, if DeleteOnTerminate isn't set. Default is 7 days.
    RetentionInDays: 30

For option defaults and valid values, see aws:elasticbeanstalk:cloudwatch:logs:health.