AWS CloudWatch Logs for Chef

Last year I released an unofficial Chef Cookbook on Chef Supermarket that install and configure AWS CloudWatch Logs Agent.

AWS CloudWatch Logs is great service, it allows you to monitor your log files in centralized way in a nearly real-time through AWS Console, and also allows you to search in logs for specific phrases, values, or patterns.

In order to help the deploy of CloudWatch Logs configurations, I started developing this cookbook when we at fluig Identity, chose AWS CloudWatch Logs as the solution for centralize all the logs that our applications generate (today is about 250GB per month).

Below I’m going to show you how the cookbook works and how you can use it in your Chef.

Usage

First add this cookbook to your base recipe to install the agent in all of your servers (you can use berks to download directly from Chef Supermarket):

cookbook 'aws-cloudwatchlogs', '~> 1.1.6'

You need to configure the following node attributes by an environment or role, so the recipe can configure the agent by your specific configuration. All attributes are described at CloudWatch Logs official documentation, so please take a visit to understand and adapt it to your need.

default_attributes(
   'aws_cwlogs' => {
      'region' => 'your_aws_region',
      'aws_access_key_id' => 'your_aws_access_key',
      'aws_secret_access_key' => 'your_aws_secret_key',
      'log' => {
         'syslog' => {
            'datetime_format' => '%b %d %H:%M:%S',
            'file' => '/var/log/syslog',
            'buffer_duration' => '5000',
            'log_stream_name' => '{instance_id}',
            'initial_position' => 'start_of_file',
            'log_group_name' => '/var/log/syslog'
         }
      }
   }
)

Note: If you don’t specify AWS credentials, the CloudWatch Logs Agent will attempt to use the AWS IAM Role assigned to the instance.

You can also opt to configure by declaring it in another cookbook at a higher precedence level.

default['aws_cwlogs']['region'] = 'your_aws_region'
default['aws_cwlogs']['aws_access_key_id'] = 'your_aws_access_key'
default['aws_cwlogs']['aws_secret_access_key'] = 'your_aws_secret_key'
default['aws_cwlogs']['log']['syslog'] = {
   'datetime_format' => '%b %d %H:%M:%S',
   'file' => '/var/log/syslog',
   'buffer_duration' => '5000',
   'log_stream_name' => '{instance_id}',
   'initial_position' => 'start_of_file',
   'log_group_name' => '/var/log/syslog'
}

Once you defined those attributes, you will need to reference aws_cwlogs resource in one of your recipes, by doing:

include_recipe 'aws-cloudwatchlogs'

aws_cwlogs 'syslog' do
  log node['aws_cwlogs']['log']['syslog']
end

This will create a unique log configuration file that will be stored in etc/config directory of your CloudWatch Logs Agent.

If you have more that one log attribute, each log referred will be created in its own configuration file. This avoid us to create invalid configurations in servers that don’t have the log specified.

For a complete documentation of the cookbook, please take a look at the project on GitHub.

Example

Those attributes used before will generate the CloudWatch Logs configuration below.

[syslog]
datetime_format = %b %d %H:%M:%S
file = /var/log/syslog
buffer_duration = 5000
log_stream_name = {instance_id}
initial_position = start_of_file
log_group_name = /var/log/syslog

Remember: You can configure as many logs as you need with the log attribute.

What’s next?

Currently, this cookbook was develop and tested only in Ubuntu, but, of course, pull requests are always welcome. If you have any questions, please feel free to create a New Issue on the project.