Plugins Package

Plugins Package

Python Nagios extensions

exception pynag.Plugins.PluginError(message, errorcode=None, errorstring=None, *args, **kwargs)

Bases: pynag.errors.PynagError

Base class for errors in this module.

class pynag.Plugins.PluginHelper

Bases: object

PluginHelper takes away some of the tedious work of writing Nagios plugins. Primary features include:

  • Keep a collection of your plugin messages (queue for both summary and longoutput)
  • Keep record of exit status
  • Keep a collection of your metrics (for both perfdata and thresholds)
  • Automatic Command-line arguments
  • Make sure output of your plugin is within Plugin Developer Guidelines

Usage: p = PluginHelper() p.status(warning) p.add_summary(‘Example Plugin with warning status’) p.add_metric(‘cpu load’, ‘90’) p.exit()


Appends message to the end of Plugin long_output. Message does not need a suffix

>>> p = PluginHelper()
>>> p.add_long_output('Status of sensor 1')
>>> p.add_long_output('* Temperature: OK')
>>> p.add_long_output('* Humidity: OK')
>>> p.get_long_output()
u'Status of sensor 1\n* Temperature: OK\n* Humidity: OK'
add_metric(label=u'', value=u'', warn=u'', crit=u'', min=u'', max=u'', uom=u'', perfdatastring=None)

Add numerical metric (will be outputted as nagios performanca data)

>>> p = PluginHelper()
>>> p.add_metric(label="load1", value="7")
>>> p.add_metric(label="load5", value="5")
>>> p.add_metric(label="load15",value="2")
>>> p.get_perfdata()
"'load1'=7;;;; 'load5'=5;;;; 'load15'=2;;;;"
>>> p = PluginHelper()
>>> p.add_metric(perfdatastring="load1=6;;;;")
>>> p.add_metric(perfdatastring="load5=4;;;;")
>>> p.add_metric(perfdatastring="load15=1;;;;")
>>> p.get_perfdata()
"'load1'=6;;;; 'load5'=4;;;; 'load15'=1;;;;"
add_option(*args, **kwargs)

Same as self.parser.add_option()


Update exit status of the nagios plugin. This function will keep history of the worst status added

Examples: >>> p = PluginHelper() >>> p.add_status(0) # ok >>> p.add_status(2) # critical >>> p.add_status(1) # warning >>> p.get_status() # 2

>>> p = PluginHelper()
>>> p.add_status('warning')
>>> p.add_status('ok')
>>> p.get_status()
>>> p.add_status('okay')
Traceback (most recent call last):
Exception: Invalid status supplied "okay"

Adds message to Plugin Summary

arguments = None

Checks all metrics (add_metric() against any thresholds set in self.options.thresholds or with –threshold from commandline)

check_metric(metric_name, thresholds)

Check one specific metric against a list of thresholds. Updates self.status() and writes to summary or longout as appropriate.

metric_name – A string representing the name of the metric (the label part of the performance data) thresholds – a list in the form of [ (level,range) ] where range is a string in the format of “start..end”

Examples: >>> p = PluginHelper() >>> thresholds = [(warning,‘2..5’), (critical,‘5..inf’)] >>> p.get_plugin_output() u’Unknown -‘ >>> p.add_metric(‘load15’, ‘3’) >>> p.check_metric(‘load15’,thresholds) >>> p.get_plugin_output() u”Warning - Warning on load15 | ‘load15’=3;@2:5;~:5;;”

>>> p = PluginHelper()
>>> thresholds = [(warning,'2..5'), (critical,'5..inf')]
>>> p.add_metric('load15', '3')
>>> p.verbose = True
>>> p.check_metric('load15',thresholds)
>>> p.get_plugin_output()
u"Warning - Warning on load15 | 'load15'=3;@2:5;~:5;;\nWarning on load15"

Invalid metric: >>> p = PluginHelper() >>> p.add_status(ok) >>> p.add_summary(‘Everythings fine!’) >>> p.get_plugin_output() u’OK - Everythings fine!’ >>> thresholds = [(warning,‘2..5’), (critical,‘5..inf’)] >>> p.check_metric(‘never_added_metric’, thresholds) >>> p.get_plugin_output() u’Unknown - Everythings fine!. Metric never_added_metric not found’

Invalid threshold: >>> p = PluginHelper() >>> thresholds = [(warning, ‘invalid’), (critical,‘5..inf’)] >>> p.add_metric(‘load1’, ‘10’) >>> p.check_metric(‘load1’, thresholds) Traceback (most recent call last): ... SystemExit: 3


Converts new threshold range format to old one. Returns None.

x..y -> x:y inf..y -> :y -inf..y -> :y x..inf -> x: -inf..inf -> :
exit(exit_code=None, summary=None, long_output=None, perfdata=None)
Print all collected output to screen and exit nagios style, no arguments are needed
except if you want to override default behavior.
summary – Is this text as the plugin summary instead of self.get_summary() long_output – Use this text as long_output instead of self.get_long_output() perfdata – Use this text instead of self.get_perfdata() exit_code – Use this exit code instead of self.status()
get_default_values(section_name=None, config_file=None)

Returns an optionParser.Values instance of all defaults after parsing extra opts config file

The Nagios extra-opts spec we use is the same as described here:



Returns all long_output that has been added via add_long_output


Return one specific metric (PerfdataMetric object) with the specified label. Returns None if not found.

Example: >>> p = PluginHelper() >>> p.add_metric(label=”load1”, value=”7”) >>> p.add_metric(label=”load15”,value=”2”) >>> p.get_metric(“load1”) ‘load1’=7;;;; >>> p.get_metric(“unknown”) # Returns None


Get perfdatastring for all valid perfdatametrics collected via add_perfdata

Examples: >>> p = PluginHelper() >>> p.add_metric(label=”load1”, value=”7”, warn=”-inf..10”, crit=”10..inf”) >>> p.add_metric(label=”load5”, value=”5”, warn=”-inf..7”, crit=”7..inf”) >>> p.add_metric(label=”load15”,value=”2”, warn=”-inf..5”, crit=”5..inf”) >>> p.get_perfdata() “‘load1’=7;10:;~:10;; ‘load5’=5;7:;~:7;; ‘load15’=2;5:;~:5;;”

Example with legacy output (show_legacy should be set with a cmdline option): >>> p.show_legacy = True >>> p.get_perfdata() “‘load1’=7;10:;~:10;; ‘load5’=5;7:;~:7;; ‘load15’=2;5:;~:5;;”

get_plugin_output(exit_code=None, summary=None, long_output=None, perfdata=None)

Get all plugin output as it would be printed to screen with self.exit()

Examples of functionality: >>> p = PluginHelper() >>> p.get_plugin_output() u’Unknown -‘

>>> p = PluginHelper()
>>> p.add_summary('Testing')
>>> p.add_long_output('Long testing output')
>>> p.add_long_output('More output')
>>> p.get_plugin_output(exit_code=0)
u'OK - Testing\nLong testing output\nMore output'
>>> p = PluginHelper()
>>> p.add_summary('Testing')
>>> p.add_status(0)
>>> p.get_plugin_output()
u'OK - Testing'
>>> p = PluginHelper()
>>> p.show_status_in_summary = False
>>> p.add_summary('Testing')
>>> p.add_metric(label="load1", value="7")
>>> p.add_metric(label="load5", value="5")
>>> p.add_metric(label="load15",value="2")
>>> p.get_plugin_output(exit_code=0)
u"Testing | 'load1'=7;;;; 'load5'=5;;;; 'load15'=2;;;;"
>>> p = PluginHelper()
>>> p.show_status_in_summary = False
>>> p.add_summary('Testing')
>>> p.add_long_output('Long testing output')
>>> p.add_long_output('More output')
>>> p.add_metric(label="load1", value="7")
>>> p.add_metric(label="load5", value="5")
>>> p.add_metric(label="load15",value="2")
>>> p.get_plugin_output(exit_code=0)
u"Testing | 'load1'=7;;;; 'load5'=5;;;; 'load15'=2;;;;\nLong testing output\nMore output"

Returns the worst nagios status (integer 0,1,2,3) that has been put with add_status()

If status has never been added, returns 3 for UNKNOWN

options = None

Parsers commandline arguments, prints error if there is a syntax error.

self.options – As created by OptionParser.parse() self.arguments – As created by OptionParser.parse()
argument_list – By default use sys.argv[1:], override only if you know what you are doing.
run_function(function, *args, **kwargs)

Executes “function” and exits Nagios style with status “unkown” if there are any exceptions. The stacktrace will be in long_output.

Example: >>> p = PluginHelper() >>> p.add_status(‘ok’) >>> p.get_status() 0 >>> p.add_status(‘okay’) Traceback (most recent call last): ... Exception: Invalid status supplied “okay” >>> p.run_function( p.add_status, ‘warning’ ) >>> p.get_status() 1 >>> p.run_function( p.add_status, ‘okay’ ) Traceback (most recent call last): ... SystemExit: 3


Overwrite current long_output with message

Example: >>> s = PluginHelper() >>> s.add_long_output(‘first long output’) >>> s.set_long_output(‘Fatal error’) >>> s.get_long_output() u’Fatal error’


Overwrite current summary with message

Example: >>> s = PluginHelper() >>> s.add_summary(‘first summary’) >>> s.set_summary(‘Fatal error’) >>> s.get_summary() u’Fatal error’


Configures plugin to timeout after seconds number of seconds

show_debug = False
show_legacy = False
show_longoutput = True
show_perfdata = True
show_status_in_summary = True
show_summary = True

Same as get_status() if new_status=None, otherwise call add_status(new_status)

thresholds = None
timeout = 58
verbose = False
class pynag.Plugins.simple(shortname=None, version=None, blurb=None, extra=None, url=None, license=None, plugin=None, timeout=15, must_threshold=True)

Bases: object

Nagios plugin helper library based on Nagios::Plugin

Sample usage

from pynag.Plugins import WARNING, CRITICAL, OK, UNKNOWN, simple as Plugin

# Create plugin object np = Plugin() # Add arguments np.add_arg(“d”, “disk”) # Do activate plugin np.activate() ... check stuff, np[‘disk’] to address variable assigned above... # Add a status message and severity np.add_message( WARNING, “Disk nearing capacity” ) # Get parsed code and messages (code, message) = np.check_messages() # Return information and exit nagios_exit(code, message)


Parse out all command line options and get ready to process the plugin. This should be run after argument preps

add_arg(spec_abbr, spec, help_text, required=1, action=u'store')

Add an argument to be handled by the option parser. By default, the arg is not required.

required = optional parameter action = [store, append, store_true]

add_message(code, message)

Add a message with code to the object. May be called multiple times. The messages added are checked by check_messages, following.

Only CRITICAL, WARNING, OK and UNKNOWN are accepted as valid codes.

add_perfdata(label, value, uom=None, warn=None, crit=None, minimum=None, maximum=None)

Append perfdata string to the end of the message

check_messages(joinstr=u' ', joinallstr=None)

Check the current set of messages and return an appropriate nagios return code and/or a result message. In scalar context, returns only a return code; in list context returns both a return code and an output message, suitable for passing directly to nagios_exit()

joinstr = string

A string used to join the relevant array to generate the message string returned in list context i.e. if the ‘critical’ array is non-empty, check_messages would return:

joinallstr = string

By default, only one set of messages are joined and returned in the result message i.e. if the result is CRITICAL, only the ‘critical’ messages are included in the result; if WARNING, only the ‘warning’ messages are included; if OK, the ‘ok’ messages are included (if supplied) i.e. the default is to return an ‘errors-only’ type message.

If joinallstr is supplied, however, it will be used as a string to join the resultant critical, warning, and ok messages together i.e. all messages are joined and returned.


Check if a value is within a given range. This should replace change_threshold eventually. Exits with appropriate exit code given the range.

Taken from: Range definition

Generate an alert if x... 10 < 0 or > 10, (outside the range of {0 .. 10}) 10: < 10, (outside {10 .. #}) ~:10 > 10, (outside the range of {-# .. 10}) 10:20 < 10 or > 20, (outside the range of {10 .. 20}) @10:20 # 10 and # 20, (inside the range of {10 .. 20})


Changes CRITICAL, WARNING, OK and UNKNOWN code_text to integer representation for use within add_message() and nagios_exit()

nagios_exit(code_text, message)

Exit with exit_code, message, and optionally perfdata

send_nsca(*args, **kwargs)

Wrapper around pynag.Utils.send_nsca - here for backwards compatibility

new_threshold_syntax Module

These are helper functions and implementation of proposed new threshold format for nagios plugins according to:

In short, plugins should implement a –threshold option which takes argument in form of:
# metric={metric},ok={range},warn={range},crit={range},unit={unit}prefix={SI prefix}
–treshold metric=load1,ok=0..5,warning=5..10,critical=10..inf
exception pynag.Plugins.new_threshold_syntax.Error(message, errorcode=None, errorstring=None, *args, **kwargs)

Bases: pynag.errors.PynagError

Base class for errors in this module.

exception pynag.Plugins.new_threshold_syntax.InvalidThreshold(message, errorcode=None, errorstring=None, *args, **kwargs)

Bases: pynag.Plugins.new_threshold_syntax.Error

Raised when an invalid threshold was provided.

pynag.Plugins.new_threshold_syntax.check_range(value, range)

Returns True if value is within range, else False

value – Numerical value to check, can be any number range – string in the format of “start..end”

Examples: >>> check_range(5, “0..10”) True >>> check_range(11, “0..10”) False

pynag.Plugins.new_threshold_syntax.check_threshold(value, ok=None, warning=None, critical=None)

Checks value against warning/critical and returns Nagios exit code.

Format of range_threshold is according to:

This function returns (in order of appearance):
int(0) - If no levels are specified, return OK int(3) - If any invalid input provided, return UNKNOWN int(0) - If an ok level is specified and value is within range, return OK int(2) - If a critical level is specified and value is within range, return CRITICAL int(1) - If a warning level is specified and value is within range, return WARNING int(2) - If an ok level is specified, return CRITICAL int(0) - Otherwise return OK
value – value to check ok – ok range warning – warning range critical – critical range

# Example Usage: >>> check_threshold(88, warning=”90..95”, critical=”95..100”) 0 >>> check_threshold(92, warning=”90..95”, critical=”95..100”) 1 >>> check_threshold(96, warning=”90..95”, critical=”95..100”) 2


Take threshold string as and normalize it to the format supported by plugin development team

The input (usually a string in the form of ‘the new threshold syntax’) is a string in the form of x..y

The output will be a compatible string in the older nagios plugin format @x:y


>>> convert_to_classic_format("0..5")
>>> convert_to_classic_format("inf..5")
>>> convert_to_classic_format("5..inf")
>>> convert_to_classic_format("inf..inf")
>>> convert_to_classic_format("^0..5")
>>> convert_to_classic_format("10..20")
>>> convert_to_classic_format("10..inf")

takes a threshold string as an input and returns a hash map of options and values

>>> parse_threshold('metric=disk_usage,ok=0..90,warning=90..95,critical=95..100')
{u'thresholds': [(0, u'0..90'), (1, u'90..95'), (2, u'95..100')], u'metric': u'disk_usage'}