sensu-cloudwatch-check

Table of Contents

• Overview

• Usage examples

  • Help output
  • Environment Variables
  • Basic Usage
  • Important Commandline Arguments
  • AWS CloudWatch Metrics Presets
  • Custom Presets
  • Exporting Preset Configuration

• Configuration

  • Asset registration
  • Check definition

• Installation from source

• Additional notes

• Contributing

Overview

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

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

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

Flags:
      --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

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

Namespace

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.

Period

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:

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
or CLOUDWATCH_CHECK_CONFIG envvar.

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

Configuration

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][https://bonsai.sensu.io/assets/sensu/sensu-cloudwatch-check].

Check definition

---
type: CheckConfig
api_version: core/v2
metadata:
  name: sensu-cloudwatch-check 
  namespace: default
spec:
  command: sensu-cloudwatch-check --example example_arg
  subscriptions:
  - system
  runtime_assets:
  - 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

Contributing

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