NAME

App::AWS::CloudWatch::Monitor - collect and send metrics to AWS CloudWatch

SYNOPSIS

use App::AWS::CloudWatch::Monitor;

my $monitor = App::AWS::CloudWatch::Monitor->new();
$monitor->run(\%opt, \@ARGV);

aws-cloudwatch-monitor [--check <module>]
                       [--from-cron] [--verify] [--verbose]
                       [--version] [--help]

DESCRIPTION

App::AWS::CloudWatch::Monitor is an extensible framework for collecting and sending custom metrics to AWS CloudWatch from an AWS EC2 instance.

For the commandline interface to App::AWS::CloudWatch::Monitor, see the documentation for aws-cloudwatch-monitor.

For adding check modules, see the documentation for App::AWS::CloudWatch::Monitor::Check.

CONSTRUCTOR

• new

  Returns a new App::AWS::CloudWatch::Monitor object.

METHODS

• config

  Returns the loaded config.

• run

  Loads and runs the specified check modules to gather metric data.

  For options and arguments to run, see the documentation for aws-cloudwatch-monitor.

INSTALLATION

perl Makefile.PL
make
make test && sudo make install

App::AWS::CloudWatch::Monitor can also be installed using cpanm.

cpanm App::AWS::CloudWatch::Monitor

CONFIGURATION

To send metrics to AWS, you need to provide the access key id and secret access key for your configured AWS CloudWatch service. You can set these in the file config.ini.

An example is provided as part of this distribution. The user running the metric script, like the user configured in cron for example, will need access to the configuration file.

To set up the configuration file, copy config.ini.example into one of the following locations:

• $ENV{HOME}/.config/aws-cloudwatch-monitor/config.ini
• /etc/aws-cloudwatch-monitor/config.ini

After creating the file, edit and update the values accordingly.

[aws]
aws_access_key_id = example
aws_secret_access_key = example

NOTE: If the $ENV{HOME}/.config/aws-cloudwatch-monitor/ directory exists, config.ini will be loaded from there regardless of a config file in /etc/aws-cloudwatch-monitor/.

KNOWN LIMITATIONS

AWS CloudWatch limits each upload to no more than 20 different metrics

AWS CloudWatch will return a 400 response if attempting to upload more than 20 different metrics at once.

https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html

A metrics collection can quickly exceed 20 metrics since each check module gathers multiple metrics.

aws-cloudwatch-monitor --check Process --process apache --process postgres --process master --process emacs --check Memory --check DiskSpace --check Inode --disk-path /
Failed to call CloudWatch: HTTP 400. Message: The collection MetricData must not have a size greater than 20.

Until this limitation is worked around in a future release of App::AWS::CloudWatch::Monitor, splitting the checks into separate aws-cloudwatch-monitor commands allows the uploads to succeed.

aws-cloudwatch-monitor --check Process --process apache --process postgres --process master --process emacs
Successfully reported metrics to CloudWatch. Reference Id: <snip>

aws-cloudwatch-monitor --check Memory --check DiskSpace --check Inode --disk-path /
Successfully reported metrics to CloudWatch. Reference Id: <snip>

BUGS AND ENHANCEMENTS

Please report any bugs or feature requests at rt.cpan.org.

Please include in the bug report:

• the operating system aws-cloudwatch-monitor is running on
• the output of the command aws-cloudwatch-monitor --version
• the command being run, error, and any additional steps to reproduce the issue