Cloudwatch Agent

CloudWatch Agent is a long running process that collects your application information and sent them to CloudWatch every minute. The goal of this monitor is to reduce the time overhead introduced by CloudWatch SDK and also all write operation to the service.

Thanks to the agent you can collect a wide range of metrics like: exceptions, timing about your application using a single monitor tool in your AWS space: CloudWatch.

Getting Started

The agent works using UDP/IP packages on 127.0.0.1, we just have to send simple JSON package to the monitor on port 1234

{"namespace": "wdm", "metric": "indexer-timing", "value": 81.21}

Before use the service remember to configure the AWS ApiKey and SecretKey in the daemon configuration file at /etc/default/cloudwatch-agent you can also tweak monitor option tuning the configuration file at: /etc/cloudwatch-agent/cloudwatch-agent.conf

You can try the daemon using nc tool:

echo '{"namespace": "wdm", "metric": "indexer-timing", "value": 81.21}' | nc -u localhost 1234

Advanced usage

The complete data packet structure is quite bit more complex:

{
    "namespace": ...
    "metric": ...
    "unit": ...
    "value": ...
    "op": ...
}

Where you can tune also the operation type and the metric unit. Valid operations are:

• avg - Compute the average of all packages
• sum - Sum all incoming samples
• max - Send only the max point
• min - Send only the min point

Valid units are:

• Seconds
• Microseconds
• Milliseconds
• Bytes
• Kilobytes
• Megabytes
• Gigabytes
• Terabytes
• Bits
• Kilobits
• Megabits
• Gigabits
• Terabits
• Percent
• Count
• Bytes/Second
• Kilobytes/Second
• Megabytes/Second
• Gigabytes/Second
• Terabytes/Second
• Bits/Second
• Kilobits/Second
• Megabits/Second
• Gigabits/Second
• Terabits/Second
• Count/Second

Install the agent

Debian Family

If you use a Debian like distribution you can use the precompiled package

echo "deb http://dl.bintray.com/wdalmut/deb /" | sudo tee /etc/apt/sources.list.d/wdalmut.list
echo "#deb-src http://dl.bintray.com/wdalmut/deb /" | sudo tee -a /etc/apt/sources.list.d/wdalmut.list

Now just update your repository

sudo apt-get update

And install the monitor

sudo apt-get install cloudwatch-agent

RHEL family

If you use a RedHat based distribution add the RPM repository

wget https://bintray.com/wdalmut/rpm/rpm -O bintray-wdalmut-rpm.repo
sudo mv bintray-wdalmut-rpm.repo /etc/yum.repos.d/

now just install it

sudo yum install cloudwatch-agent.x86_64

Start the agent

After the installation process and the configuration you can start the agent using the common service interface.

sudo service cw-agent start

Allowed operations are:

• start
• stop
• status
• restart

Examples of usage

Just as example you can count the number of exception in your application just sending a simple packet for each exception catched

{
    "namespace": "app"
    "metric": "errors"
    "value": 1
    "op": "sum"
}

For each exception we can collect the total number in a minute and send the total amount to CloudWatch every minute.

SDKs

You can use pre-packaged agent sdk for your application

PHP SDK

In order to get the PHP SDK you have to add the agent dependency to your composer.json

php composer.phar require corley/cloudwatch-agent-client:*

Now you can use directly in your application:

Corley\CloudWatch\Agent::point($namespace, $metric, $value);

Also with unit and the operation type:

Agent::point($namespace, $metric, $value, ["unit" => Agent::UNIT_MILLISECONDS]);
Agent::point($namespace, $metric, 1, ["op" => Agent::OP_SUM]);

Integrate with ElasticBeanStalk

If you are running your application into and ElasticBeanStalk container you can host the rpm package by yourself on S3 and just add a configuration step in your .ebextensions folder

# .ebextensions/05_monitor.config
packages:
    rpm:
        monitor: https://s3-eu-west-1.amazonaws.com/your-bucket-name/cloudwatch-agent-0.0.11-1.x86_64.rpm
container_commands:
    05_put_aws_key:
        command: echo "export AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID" > /etc/default/cloudwatch-agent && echo "export AWS_SECRET_ACCESS_KEY=$AWS_SECRET_KEY" >> /etc/default/cloudwatch-agent
    06_stop_monitor:
        command: service cw-agent stop
        ignoreErrors: true
    07_start_monitor:
        command: service cw-agent start
        ignoreErrors: true
services:
    sysvinit:
        cw-agent:
            enabled: true
            ensureRunning: true

Just remember to configure your AWS_ACCESS_KEY_ID and AWS_SECRET_KEY via the ElasticBeanStalk application environment configuration.