OP5 Monitor ["OP5 Monitor"]
["Technical Reference"]

check_aws plugin


The check_aws plugin can be used to monitor AWS Services That Publish CloudWatch Metrics. It uses Boto3 for interacting with AWS CloudWatch, and the nagiosplugin library for working with the Nagios plugin format.

This plugin is available on GitHub: ITRS-Group/check_aws.

CLI usage

usage: check-aws.py [-h] -r
                    [-u UNIT] -m METRIC -n NAMESPACE [-d [DIMENSIONS]]
                    [-p PROFILE]
                    [-s {Average,Sum,SampleCount,Maximum,Minimum}]
                    [-w WARNING] [-c CRITICAL] [-v] [-P [PERIOD]] [-D DELTA]
                    [-l LAG] [-C [CREDENTIALS_FILE]] [-f [CREDENTIALS_FILE]]

Plugin for monitoring AWS via CloudWatch

optional arguments:
  -h, --help            show this help message and exit
  -r {af-south-1,ap-east-1,ap-northeast-1,ap-northeast-2,ap-northeast-3,ap-south-1,ap-southeast-1,ap-southeast-2,ca-central-1,eu-central-1,eu-north-1,eu-south-1,eu-west-1,eu-west-2,eu-west-3,me-south-1,sa-east-1,us-east-1,us-east-2,us-west-1,us-west-2}, --region {af-south-1,ap-east-1,ap-northeast-1,ap-northeast-2,ap-northeast-3,ap-south-1,ap-southeast-1,ap-southeast-2,ca-central-1,eu-central-1,eu-north-1,eu-south-1,eu-west-1,eu-west-2,eu-west-3,me-south-1,sa-east-1,us-east-1,us-east-2,us-west-1,us-west-2}
                        AWS Region
  -u UNIT, --unit UNIT  Expected unit in the response
  -m METRIC, --metric METRIC
                        Metric name
  -n NAMESPACE, --namespace NAMESPACE
                        Service Namespace
  -d [DIMENSIONS], --dimensions [DIMENSIONS]
                        One or more Dimensions for selecting datapoints:
  -p PROFILE, --profile PROFILE
                        Profile name from ~/.aws/credentials (default:
  -s {Average,Sum,SampleCount,Maximum,Minimum}, --statistic {Average,Sum,SampleCount,Maximum,Minimum}
                        Statistic for evaluating metrics (default: Average)
  -w WARNING, --warning WARNING
                        Warning if threshold is outside range (default: 0)
  -c CRITICAL, --critical CRITICAL
                        Critical if threshold is outside range (default: 0)
  -v, --verbosity       Verbosity (use up to 3 times)
  -P [PERIOD], --period [PERIOD]
                        Period in seconds over which the statistic is applied
                        (default: 60)
  -D DELTA, --delta DELTA
                        Delta measurement in seconds
  -l LAG, --lag LAG     Delay in seconds to add to starting time (default: 0)
  -f [CREDENTIALS_FILE], --credentials_file [CREDENTIALS_FILE]
                        File containing AWS credentials

Credentials and authentication

By default, the check_aws plugin looks for credentials in ~/.aws/credentials. If you want to change this, use the --credentials_file command-line option.


Dimensions are name/value pairs that are part of the identity of a metric. You can specify one or more dimensions to the check_aws plugin CLI to select which metrics to monitor.

Usage examples

VPN availability

Example command to check the AWS/VPN tunnel availability:

$ ./check-aws.py --metric TunnelState --namespace AWS/VPN -r eu-west-1 -w @0 -c @0 -d TunnelIpAddress=

Free storage space

Example command to check the free storage space in AWS RDS:

$ ./check-aws.py --metric FreeStorageSpace --namespace AWS/RDS -r eu-west-1 -w @5000000000 -c @3000000000

Credit usage

Example command to check the EC2 instance credit usage:

$ ./check-aws.py --metric CPUCreditUsage --namespace AWS/EC2 -r eu-west-1 -w 2 -c 3 -d InstanceId=i-0d7c12ec7asdf229

CPU utilisation

Example command to check the EC2 instance CPU utilisation:

$ ./check-aws.py --metric CPUUtilization --namespace AWS/EC2 -r eu-west-1 -w 50 -c 70 -d InstanceId=i-0d7c44ec7eaad229

ECS running tasks

Example command to check the ECS running task count:

$ ./check_aws.py -d ClusterName=my-ecs-cluster,ServiceName=my-ecs-service --metric RunningTaskCount --namespace ECS/ContainerInsights -w 1 -c 2


To have the check_aws plugin print out stack traces and other useful information when troubleshooting, include the -v option to your command. This argument can be stacked up to three times for extra information.