nagios-plugin

Toolkit facilitates writing Nagios plugins in Node.js. It is a mimic of Perl Nagios::Plugin module, barring command line parsing functions in favor of many existing npm modules such as node-getopt or commander.js.

Annotated Working Example

Following script implements a plugin to check web sites using external program wget. This plugin addresses some defects in Nagios built-in plugin check_http, for instance unable to failover to next IP when a web site is mapped to multiple IPs and attempts to connect to currently chosen IP failed at TCP socket layer.

wget-http.js:

'use strict';
// add a command line parser;
// you can substitute with your own favorite npm module
var getOpt = require('node-getopt')
.create([ [ 'm', 'match=<STRING>', 'String response body must match' ]
        , [ 'w', 'warning=<STRING>', 'Warning threshold' ]
        , [ 'c', 'critical=<STRING>', 'Critical threshold' ]
        , [ 'h', 'help', 'display this help' ] ])
.bindHelp();
getOpt.setHelp('Usage: node wget-http.js [Options] -- '
        + '<arguments passed to wget>\nOptions:\n[[OPTIONS]]');
var args = getOpt.parseSystem();
// validate mandatory arguments
if (args.argv.length == 0) {
    console.log('missing arguments passed to wget');
    getOpt.showHelp();
    process.exit(3);
}

var Plugin = require('nagios-plugin');
// create a new plugin object with optional initialization parameters
var o = new Plugin({
    // shortName is used in output
    shortName : 'wget_http'
});
// set monitor thresholds
o.setThresholds({
    'critical' : args.options.critical || 2,
    'warning' : args.options.warning || 0.2
});

// run the check - replace with your own business logic
var exec = require('child_process').exec;
var before = new Date().getTime();
exec('wget -qO- ' + args.argv.join(' '), function(error, stdout, stderr) {
    var after = new Date().getTime();
    var diff = (after - before) / 1000;

    // check actual data against predefined threshold
    // and returns state: OK, WARNING or CRITICAL
    var state = o.checkThreshold(diff);
    // Add message for later output. Multiple messages
    // in the same state are concatenated at output
    o.addMessage(state, stdout.length + ' bytes in ' + diff
            + ' seconds response time.');
    if (args.options.match && stdout.indexOf(args.options.match) === -1) {
        o.addMessage(o.states.CRITICAL, args.options.match + ' not found');
    }
    // Add performance data
    o.addPerfData({
        label : "time",
        value : diff,
        uom : "s",
        threshold : o.threshold,
        min : 0
    });
    o.addPerfData({
        label : "size",
        value : stdout.length,
        uom : "B",
        min : 0
    });
    // check messages added earlier and return the most severe set:
    // CRITICAL; otherwise WARNING; otherwise OK
    var messageObj = o.checkMessages();
    // output the short name, state, message and perf data
    // exit the program with state as return code
    o.nagiosExit(messageObj.state, messageObj.message);
});

Outputs

$ node wget-http.js -- http://www.google.com
WGET_HTTP WARNING - 11815 bytes in 0.571 seconds response time.|time=0.571s;0.2;2;0; size=11815B;;;0;
$ node wget-http.js --match=unicorn -- http://www.google.com
WGET_HTTP CRITICAL - unicorn not found|time=0.467s;0.2;2;0; size=11763B;;;0;
$ node wget-http.js --help 
Usage: node wget-http.js [Options] -- <arguments passed to wget>
Options:
  -m, --match=<STRING>     String response body must match
  -w, --warning=<STRING>   Warning threshold
  -c, --critical=<STRING>  Critical threshold
  -h, --help               display this help
$ node wget-http.js
missing arguments passed to wget
Usage: ... <same as --help>

API

constructor

var o = new Plugin({
	shortName : 'wget_http'
});

• shortName is used in output, if omitted by default it is set to JavaScript file name launched by program

properties

• states

  enum

  o.states = {
      OK : 0,
      WARNING : 1,
      CRITICAL : 2,
      UNKNOWN : 3
  }
  

methods

• setThresholds

  o.setThresholds({
      'critical' : ...,
      'warning' : ...
  });
  

  See Nagios Plugin Development Guidelines for valid threshold formats

  • There is only one critical and warning threshold set. If setThresholds is called multiple times, the result is concatenated and latter settings overwrites previous ones.

• checkThreshold

  var state = o.checkThreshold(actualData);
  

  check actualData against predefined threshold. Returns the matching state.

• addMessage

  o.addMessage(state, 'msg');
  

  Add message to the corresponding state.

• checkMessages

  var messageObj = o.checkMessages();
  

  checkMessages concatenates messages added with addMessage by state and returns the {state, message} pair of the most severe state with message populated in this precedence: critical, warning or OK.

• addPerfData

  o.addPerfData({
      label : "time",
      value : diff,
      uom : "s",
      threshold : o.threshold,
      min : 0,
      max : 100
  })	
  

  See Nagios Plugin Development Guidelines for valid UOMs.

• nagiosExit

  o.nagiosExit(state, message);
  

  Generates one line output conforming to Nagios expected format and exit the program with state as return code. State and message should come from checkMessages output.

• getReturnMessage

  var msg = o.getReturnMessage(state, message);
  

  If you want the output string but don't want to quit the program by calling nagiosExit, you can call getReturnMessage with same parameters as nagiosExit. Internally nagiosExit calls getReturnMessage.

Install

npm install nagios-plugin