1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with cloudwatch_agent
   • Setup requirements
   • Beginning with cloudwatch_agent
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.

The cloudwatch_agent module installs configures and manages the AWS Cloudwatch Logs Agent.

Cloudwatch is an AWS service for collecting metrics and log data from AWS Instances. This module is only usable inside of AWS, and not on instances that run outside of AWS.

EC2 instances need to have an IAM role to be able to send logs to AWS. Setting up IAM oles is outside the scope of this document, but there's a nice tutorial that starts in step 2 in the (Cloudwatch Logs Agent docs)[http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/EC2NewInstanceCWL.html] (step 19 is different if you're using puppet).

If you want to install the logs agent, and are in the us-east-1 region, you can run include ::cloudwatch_agent. By default, the agent is installed using the python installer but it can be overridden (to use a package), though the default install doesn't monitor any logs.

Non us-east-1 regions can be used via the region parameter:

class { 'cloudwatch_agent':
  region => 'us-west-1',
}

Cloudwatch needs a little bit of information about each log file (like date format) so that it can be parsed out and grouped in a meaningful way by AWS.

After setting up the logs agent, logs can be specified using the cloudwatch_agent::log defined type. Sending /var/log/syslog would look like (all parameters are defaults):

cloudwatch_agent::log { '/var/log/syslog':
  datetime_format  => '%b %d %H:%M:%S',
  log_stream_name  => '{instance_id}',
  buffer_duration  => '5000',
  initial_position => 'start_of_file',
}

• cloudwatch_agent: Installs the cloudwatch log agent

• cloudwatch_agent::config: Sets the awslogs service configuration
• cloudwatch_agent::package: Install the agent package
• cloudwatch_agent::service: Manage the awslogs service

Specify whether the awslogs package should be used or not, Valid values are 'true', 'false'. Defaults to 'false'.

The ensure parameter that is passed to the awslogs package resource. Defaults to present.

The URL where the installer should be fetched from. Defaults to https://s3.amazonaws.com/aws-cloudwatch/downloads/latest/awslogs-agent-setup.py.

The ensure parameter that is passed to the awslogs service resource. Defaults to running.

The enable parameter that is passed to the awslogs service resource. Defaults to true.

The AWS region that the you're running in. Defaults to 'us-east-1'.

Where the agent should store its state. Defaults to /var/awslogs/state/agent-state

A hash of ::cloudwatch_agent::log resources that should be created.

Full details on what the cloudwatch agent does with these parameters is available in the agent reference (not all parameters are supported by this module yet).

Ensure whether or not the log file should be managed or not. Valid values are present and absent. Defaults to present.

The file that should be managed. This defaults to the resource name.

The format of the datetime stamp in the file. Defaults to '%b %d %H:%M:%S'.

The log group that this file should be grouped with. Defaults to the resource name.

The name of the log stream. Defaults to '{instance_id}'.

How long log files should be buffered before sending, in milliseconds. Defaults to '5000'.

Where the file should be read to start with, when there's no state file to reference. Defaults to 'start_of_file'.

This module is only useful in AWS, on Linux instances.