Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name

v0.3.0 · public · Published about 2 years ago

Asset Definition
Release Notes
Release Assets

Sensu Bonsai Asset
Go Test


Table of Contents


The sensu-cloudwatch-check is a Sensu Check that generates AWS service metrics from the AWS Cloudwatch API.

Usage examples

Help output

Sensu Cloudwatch Check

  sensu-cloudwatch-check [flags]
  sensu-cloudwatch-check [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

      --config-files strings        comma separated list of AWS config files
      --credentials-files strings   comma separated list of AWS Credential files
      --profile string              AWS Credential Profile (for security use envvar AWS_PROFILE)
  -c, --config string               Use measurement configuration JSON string
  -N, --namespace string            Cloudwatch Metric Namespace
  -D, --dimension-filters strings   Comma separated list of AWS Cloudwatch Dimension Filters Ex: "Name, SecondName=SecondValue"
  -M, --metric string               Cloudwatch Metric Name
  -S, --stats strings               Comma separated list of AWS Cloudwatch Status Ex: "Average, Sum" (default [Average,Sum,SampleCount,Maximum,Minimum])
  -m, --max-pages int               Maximum number of result pages. A zero value will disable the limit (default 1)
  -o, --output-config               Output measurement configuration JSON string
  -p, --period-minutes int          Period in minutes for metrics statistic calculation (default 1)
  -P, --preset string               Preset Name (default "None")
      --recently-active             Only include metrics recently active in aprox last 3 hours
      --region string               AWS Region to use, (or set envvar AWS_REGION)
  -v, --verbose                     Enable verbose output
      --error-on-missing            Error if requested metrics configuration is missing a known metric from the AWS service metric list
  -n, --dry-run                     Dryrun only list metrics, do not get metrics data
  -h, --help                        help for sensu-cloudwatch-check

Environment Variables

Argument Environment Variable
--region AWS_REGION
--profile AWS_PROFILE

Basic Usage

To retrieve all available metrics from a specific AWS service from a particular region is to specific the
--namespace and --region cmdline arguments. Normally --region will be automatically detected as part of your
AWS credentials profiles, but you may specify a different region if required. Other arguments can be added
to optimize the metric response.

Note: The CloudWatch API uses a pagation strategy to limit the number of metrics returned in a single query. This check defaults to a limit of 1 page of results but this can be adjusted to meet your need. If the max number of result pages is too small, the check will return a warning status (return status 1) and will included a warning comment in the check output.

Note: This check enforces a restriction the cloudwatch API query to limit the size of the cloudwatch query. You must either include the --namespace or --metric-filter option. See the Cloudwatch ListMetrics API documentation for details.

Important Commandline Arguments


The --namespace argument limits the Cloudwatch query to the given namespace (ex: AWS/EC2).
Note: Either --namespace or --metric is required

Metric Filter

The --metric-filter argument limits the cloudwatch query to a given metric name (ex: CPUUtilization)
Note: Either --namespace or --metric is required

Dimension Filters

The --dimension-filters is a comma deimited list of strings representing Cloudwatch dimension filters of the form key or key=value that must match.
Allowed dimension filters are specific to AWS Namespace and metric.
You should refer to the AWS service documentation for a specific service when choosing the dimension filters to use.


The --period-minutes instructs the Cloudwatch service the length of time to accumulate metric statistics. The default is 1 minute, meaning Cloudwatch will be asked to return metric statistics for the previous 1 minute period. Difference AWS services populate Cloudwatch metrics on a different cadence, and if the period is too short, you may not have any metrics output. For example S3 bucket metrics are uploaded on a 1 day (1440 minute) cadence.

Example for AWS EC2 in region us-east-1 using stats and metric filter

sensu-cloudwatch-check --namespace "AWS/EC2" --region "us-east-1" --metric "StatusCheckFailed" --stats "Sum"

In this example the metric queries are limited to provide only the "Sum" statistica of "StatusCheckFailed" metric for the namespace "AWS/EC2"

Example for all metrics for specific AWS EC2 instance in region us-east-1 using dimension filter

sensu-cloudwatch-check --namespace "AWS/EC2" --region "us-east-1" --dimension-filters "InstanceId=i-0e302ffdcedaf34b1"

AWS CloudWatch Metrics Presets

This check comes with several presets for specific AWS Services. These presets provide a curated subset of possible Cloudwatch statistics following an opinionated naming scheme. These preset configs can be exported as a starting for for your own custom preset configuration (see below.)

The list of existing service presets includes:

Preset Name Description
ALB Preset Metrics for AWS Application Load Balancer
CLB Preset Metrics for AWS Classic Load Balancer
EC2 Preset Metrics for AWS EC2
CloudFront Preset Metrics for AWS CloudFront. Note: requires --region us-east-1

Note: The --dimension-filters and --metric-filter arguments can be used to further narrow the results
from the service presets.

Custom Presets

You can define your own service preset by passing a json preset config string into the check using the --config option

Exporting Preset Configuration

The --output-config option can be used to generate the json representation of a metric query.
This json can be edited as needed to customize the metric query.

Export examples

Output a simple AWS/EC2 namespace metrics configuration

sensu-cloudwatch-check --namespace "AWS/EC2" --region "us-east-1" --output-config

Output a basic AWS/EC2 namespace metrics configuration with an active dimension-filter

sensu-cloudwatch-check --namespace "AWS/EC2" --region "us-east-1" --dimension-filters "InstanceId=i-0e302ffdcedaf34b1" --output-config

Output the EC2 preset configuration

sensu-cloudwatch-check -P "EC2" --region "us-east-1" --output-config


Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not using an asset, please
consider doing so! If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the
following command to add the asset:

sensuctl asset add sensu/sensu-cloudwatch-check

If you're using an earlier version of sensuctl, you can find the asset on the [Bonsai Asset Index][].

Check definition

type: CheckConfig
api_version: core/v2
  name: sensu-cloudwatch-check 
  namespace: default
  command: sensu-cloudwatch-check --example example_arg
  - system
  - sensu/sensu-cloudwatch-check

Installation from source

The preferred way of installing and deploying this plugin is to use it as an Asset. If you would
like to compile and install the plugin from source or contribute to it, download the latest version
or create an executable script from this source.

From the local path of the sensu-cloudwatch-check repository:

go build

Additional notes


For more information about contributing to this plugin, see Contributing.

Are you sure you want to report this asset?

Please describe the reason for reporting this asset. Our moderators will be notified and will disable the asset if it is found to be inappropriate.


You must be signed in to report this asset.

Sign In with Github



Either download the source code:

Download Source

Or download the asset definition: