Using Amazon CloudWatch Logs with AWS OpsWorks Stacks

Important

The AWS OpsWorks Stacks service reached end of life on May 26, 2024 and has been disabled for both new and existing customers. We strongly recommend customers migrate their workloads to other solutions as soon as possible. If you have questions about migration, reach out to the AWS Support Team on AWS re:Post or through AWS Premium Support.

To simplify the process of monitoring logs on multiple instances, AWS OpsWorks Stacks supports Amazon CloudWatch Logs. You enable CloudWatch Logs at the layer level in AWS OpsWorks Stacks. CloudWatch Logs integration works with Chef 11.10 and Chef 12 Linux-based stacks. You incur additional charges when you enable CloudWatch Logs, so review Amazon CloudWatch Pricing before you get started.

CloudWatch Logs monitors selected logs for the occurrence of a user-specified pattern. For example, you can monitor logs for the occurrence of a literal term such as NullReferenceException, or count the number of such occurrences. After you enable CloudWatch Logs in AWS OpsWorks Stacks, the AWS OpsWorks Stacks agent sends the logs to CloudWatch Logs. For more information about CloudWatch Logs, see Getting Started with CloudWatch Logs.

Prerequisites

Before you can enable CloudWatch Logs, your instances must be running version 3444 or later of the AWS OpsWorks Stacks agent in Chef 11.10 stacks, and 4023 or later in Chef 12 stacks. You must also use a compatible instance profile for any instances that you are monitoring by using CloudWatch Logs.

If you are using a custom instance profile (one that AWS OpsWorks Stacks did not provide when you created the stack), AWS OpsWorks Stacks cannot automatically upgrade the instance profile. You must manually attach the AWSOpsWorksCloudWatchLogs policy to your profile by using IAM. For information, see Managing IAM policies in the IAM User Guide.

If you need to upgrade your agent version or instance profile, AWS OpsWorks Stacks displays a reminder similar to following screen shot when you open the CloudWatch Logs tab on the Layer page.

Updating the agent on all instances in a layer can take some time. If you try to enable CloudWatch Logs on a layer before the agent upgrade is complete, you see a message similar to the following.

Enabling CloudWatch Logs

1. After any required agent and instance profile upgrades are complete, you can enable CloudWatch Logs by setting the slider control on the CloudWatch Logs tab to On.

   

2. To stream command logs, set the Stream command logs slider to On. This sends logs of Chef activities and user-initiated commands on your layer's instances to CloudWatch Logs.

   The data included in these logs closely matches what you see in the results of a DescribeCommands operation, when you open the target of the log URL. It includes data about setup, configure, deploy, undeploy, start, stop, and recipe run commands.

3. To stream logs of activities that are stored in a custom location on your layer's instances, such as /var/log/apache/myapp/mylog*, type the custom location in the Stream custom logs string box, and then choose Add (+).

4. Choose Save. Within a few minutes, AWS OpsWorks Stacks log streams should be visible in the CloudWatch Logs console.

   

Turning Off CloudWatch Logs

To turn off CloudWatch Logs, edit your layer settings.

1. On your layer's properties page, choose Edit.

   

2. On the editing page, choose the CloudWatch Logs tab.

3. In the CloudWatch Logs area, turn off Stream command logs. Choose X on custom logs to delete them from log streams, if applicable.

4. Choose Save.

Deleting Streamed Logs from CloudWatch Logs

After you turn off CloudWatch Logs streaming from AWS OpsWorks Stacks, existing logs are still available in the CloudWatch Logs management console. You still incur charges for stored logs, unless you export the logs to Amazon S3 or delete them. For more information about exporting logs to S3, see Exporting Log Data to Amazon S3.

You can delete log streams and log groups in the CloudWatch Logs management console, or by running the delete-log-stream and delete-log-group AWS CLI commands. For more information about changing log retention periods, see Change Log Data Retention in CloudWatch Logs.

Managing Your Logs in CloudWatch Logs

The logs that you are streaming are managed in the CloudWatch Logs console.

AWS OpsWorks creates default log groups and log streams automatically. Log groups for AWS OpsWorks Stacks data have names that match the following pattern:

stack_name/layer_name/chef_log_name

Custom logs have names that match the following pattern:

/stack_name/layer_short_name/file_path_name. The path name is made more human-readable by the removal of special characters, such as asterisks (*).

When you've located your logs in CloudWatch Logs, you can organize the logs into groups, search and filter logs by creating metric filters, and create custom alarms.

Configuring Chef 12.2 Windows Layers to Use CloudWatch Logs

CloudWatch Logs automatic integration is not supported for Windows-based instances. The CloudWatch Logs tab is not available on layers in Chef 12.2 stacks. To manually enable streaming to CloudWatch Logs for Windows-based instances, do the following.

• Update the instance profile for Windows-based instances so that the CloudWatch Logs agent has appropriate permissions. The AWSOpsWorksCloudWatchLogs policy statement shows which permissions are required.

  Typically, you do this task only once. You can then use the updated instance profile for all Windows instances in a layer.

• Edit the following JSON configuration file on each instance. This file includes log stream preferences, such as which logs to monitor.

  %PROGRAMFILES%\Amazon\Ec2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json

You can automate the preceding two tasks by creating custom recipes to handle the required tasks and assigning them to the Chef 12.2 layer's Setup events. Each time you start a new instance on those layers, AWS OpsWorks Stacks automatically runs your recipes after the instance finishes booting, enabling CloudWatch Logs.

To turn off CloudWatch Logs on Windows-based instances, reverse the process. Clear the Enable CloudWatch Logs integration check box in the EC2 Service Properties dialog box, delete log stream preferences from the AWS.EC2.Windows.CloudWatch.json file; and stop running any Chef recipes that are automatically assigning CloudWatch Logs permissions to new instances in Chef 12.2 layers.