gcloud-monitor

A node.js module for Custom monitoring using Google Cloud Monitoring v3 API

Installation

npm i --save gcloud-monitor

Usage

Gauge

Create a Gauge Metric

const monitor = require('gcloud-monitor')({
  project: '<google-cloud-project-name>',
  resource: {
    // optional, defaults to {type: 'global'}
    // more info: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/MonitoredResource
  },
  auth: {
    // optional, if using on GCE
    // more info: https://github.com/google/google-api-nodejs-client#authorizing-and-authenticating
  },
  // optional: default report throttle time
  timeout: 1000
})
 
/**
 * create a gauge
 * more info: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricDescriptor
 * @param  {String} metricType 
 * @param  {Object} [opts] metric params
 * @param  {Object} [opts.throttle] // report throttle time
 * @param  {Object} [opts.description] 
 * @param  {Object} [opts.displayName] 
 * @param  {Object} [opts.labels] label descriptors
 * @param  {Object} [opts.metricDomain] default: 'custom.googleapis.com'
 * @param  {Object} [opts.unit] 
 * @param  {Object} [opts.valueType] default: 'INT64'
 * @return {Promise<Gauge,Error>} resolves gauge instance
 */
monitor.createGauge('connections', {
  displayName: 'Connections',
  description: 'Active socket connection count',
  labels: [{
    key: 'foo',
    description: 'foo label description',
    valueType: 'INT64'
  }],
  unit: 'connections',
  valueType: 'INT64'
}).then((gauge) => {
  // use gauge...
})

Report Gauge Metric Data

/**
 * report a metric value
 * @param  {*} value 
 * @param  {Date} [time] 
 * @param  {Object} [labels] 
 * @return {Promise} 
 */
gauge.report(1, new Date(), {
  foo: 1
}).then((data) => {
  console.log('Response data', data)
})

Delete a Gauge Metric

/**
 * delete the cumulative metric
 * @return {Promise} 
 */
gauge.delete().then(function (data) {
  console.log('Response data', data)
})

Cumulative

Create a Cumulative Metric

const monitor = require('gcloud-monitor')({
  project: '<google-cloud-project-name>',
  auth: {/*auth-json*/} // optional, if using on GCE
})
 
/**
 * create a cumulative metric
 * more info: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricDescriptor
 * @param  {String} metricType 
 * @param  {Object} [opts] metric params
 * @param  {Object} [opts.description] 
 * @param  {Object} [opts.displayName] 
 * @param  {Object} [opts.labels] label descriptors
 * @param  {Object} [opts.metricDomain] default: 'custom.googleapis.com'
 * @param  {Object} [opts.unit] 
 * @param  {Object} [opts.valueType] default: INT64
 * @return {Promise<Model,Error>} resolves Cumulative instance
 */
monitor.createCumulative('requestsPerSecond', {
  displayName: 'Requests per Second',
  description: 'Active socket connection count',
  labels: [{
    key: 'foo',
    description: 'foo label description',
    valueType: 'INT64'
  }],
  unit: 'req/s',
  valueType: 'INT64'
}).then((cumulative) => {
  // use cumulative...
})

Report Cumulative Metric Data

/**
 * report a metric value
 * @param  {*} value 
 * @param  {Object|Date} [interval|endTime]
 * @param  {Object} [interval.startTime] default: last `interval.startTime` or `createCumulative` time
 * @param  {Object} [interval.endTime] 
 * @param  {Object} [labels] 
 * @return {Promise} 
 */
cumulative.report(1, {
  startTime: startTime,
  endTime: new Date()
}, {
  foo: 1
}).then((data) => {
  console.log('Response data', data)
})

Delete a Cumulative Metric

/**
 * delete the cumulative metric
 * @return {Promise} 
 */
cumulative.delete().then(function (data) {
  console.log('Response data', data)
})

Note about throttle

Throttle can be set globally as gcloud-monitor opt or on each individual "metric" as a factory opt. This option throttles metric reports to the interval specified in ms.

Cumulative time series metrics batching can be grouped by passing opt.groupBy function. For example, if you want to batch cumulative metric data grouped by label name: groupBy: (timeSeriesItem) => (timeSeriesItem.metric.labels && timeSeriesItem.metric.labels.name)

License

MIT