nagios-plugin v0.1.2

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](https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT) 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](https://nagios-plugins.org/doc/guidelines.html#AEN200) for valid UOMs.

• nagiosExit

  	```
  	o.nagiosExit(state, message);
  	```
  	Generates one line output conforming to [Nagios expected format](https://nagios-plugins.org/doc/guidelines.html#PLUGOUTPUT) 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