gcp-monitoring-check

Table of Contents

• Overview

• Usage examples

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

• Configuration

  • Authentication with Google Cloud Platform
  • Asset registration
  • Check definition

• Installation from source

• Additional notes

• Contributing

Overview

The gcp-monitoring-check is a Sensu Check that collects metrics from the Google Cloud Platform's Monitoring API.
This plugin outputs metrics in Prometheus format, suitable for automatic metrics ingestion by the Sensu agent. From there you can use the Sensu Check resource metric threshold feature to alert based on metric values.

Usage Examples

Help Output

Sensu GCP Monitoring Check

Usage:
  gcp-monitoring-check [flags]
  gcp-monitoring-check [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     Print the version number of this plugin

Flags:
      --aligner string       monitoring API request aligner (https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#Aligner)
  -c, --config string        The measurement configuration JSON string to use
      --creds-file string    GCP Creds File
      --creds-json string    GCP Creds JSON
  -n, --dry-run              Dryrun only list metrics, do not get metrics data
  -F, --filter string       GCP Monitoring Filter String Ex: "metric.label.instancename=\"test\""
  -h, --help                 help for gcp-monitoring-check
  -m, --metric string        GCP Metric. (required)
  -o, --output-config        output measurement configuration json string
  -p, --period-minutes int   Previous number of minutes to consider for metrics statistic calculation (default 1)
  -P, --preset string        The service preset to use (default "None")
  -I, --project-id string    GCP Project ID. (required)
      --reducer string       monitoring API request reducer (https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#reducer)
  -v, --verbose              Enable verbose output

Environment Variables

Basic Setup

To retrieve the recent timeseries data for a single metric from a specific GCP service for a particular project you need to specific the
--creds-file, --metric, and --project-id cmdline arguments. Other arguments and environment variables can be added
to optimize the metric response. Metrics data will be returned in Prometheus format, converting GCP metric labels into Prometheus tags.

If you would like to obtain data for multiple metrics you can use the --config option and passing a measurement configuration JSON string that defines multiple metrics
requests in a single operation. Or if a service preset is available for the service you are interested in you can use the --preset argument instead of
providing a configuration string

Important Commandline Arguments

Project-ID

The --project-id cmdline argument defines the GCP project scope for which to request metrics for. This is required for normal operation.

Creds File / Creds JSON

Either --creds-file or -creds-json is required to provide the authentication token. Please see the section of configuration GCP authentication below.

Filter

The --filter cmdline argument contains a valid GCP monitering API filter expression that will be added in an AND fashion to the time series data request.
Ref: https://cloud.google.com/monitoring/custom-metrics/reading-metrics#time-series_filters

Metric

The --metric cmdline argument contains GCP monitoring API metric to request timeseries data for.

Period Minutes

The --period-minutes argument contains the previous number of minutes over which to request time-series data. This period will also define the GCP time series request alignment period.

Aligner

The Aligner specifies the operation that will be applied to the data points in each alignment period in a time series. Except for ALIGN_NONE, which specifies that no operation be applied, each alignment operation replaces the set of data values in each alignment period with a single value: the result of applying the operation to the data values. An aligned time series has a single data value at the end of each alignmentPeriod.
Default value: ALIGN_NONE

Aligners act to calculate common statistics on specific metrics, providing a single value over the alignment period. For example ALIGN_MEAN would return the mean value of the metrics, instead of all the values in the alignment period.

Ref: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#Aligner

Reducer

A Reducer operation describes how to aggregate data points from imultiple time series into a single time series, where the value of each data point in the resulting series is a function of all the already aligned values in the input time series. Default value: REDUCE_NONE

Ref: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#reducer

Preset

This argument can be used to select a pre-defined measurement configuration built-in into this check plugin. Currently gcp-compute is the only preset available.

GCP Services Metric Presets

This plugin is intended to grow a collection of service presets for commonly used GCP services. Each of the presets will include an opinioned subset of available metrics that are commonly used for alert thresholding.
If you would like to submit a preset, please open a PR with a proposed preset definition. You can follow the pattern set forth by the gcp-compute preset.

Custom Presets

You can define your own service preset by passing a json measurement config string into the check using the --config option. Using this its possible to construct your own tailored GCP metrics output, or to develop a proposed preset to include in this plugin.

Exporting Preset Configurations

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 the gcp-compute preset metrics configuration

gcp --preset "gcp-compute" --output-config --project-id "some-project" --creds-file /path/to/authentication-token.json

Configuration

Authenticating with Google Cloud Platform

In order to use this plugin you must first prepare your Google Cloud Platform account to allow applications to access the monitoring.

• Enable GCP Monitoring API

• Prepare GCP Service Account with viewer role

• Create and download service account authentication key

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/gcp-monitoring-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/gcp-monitoring-check].

Check definition

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

go build

Additional notes

Contributing

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