NagAconda – Python Nagios Integration

Nagios has been around for quite some time, but producing output it can consume is something of a black art. Only the plugin documentation actually explains what all the extra semicolons or extended formatting even means.

This is especially onerous when performance consuming add-ons expect a specific structure before operating properly. This package strives to greatly simplify the process of actually generating Nagios output.

Plugin – Nagios Plugin Wrapper

The Plugin module provides all the parts necessary to create a simple Nagios report for a service or host check by removing all that pesky inside knowledge necessary. All the classes and methods provided here reduce plugin creation to a few lines of python unless the plugin is especially complex.

All specifications for this module are obtained from the Nagios developer documentation.

Usage

from NagAconda import Plugin
from Person import Dude

feet = Plugin("Plugin to quantify current foot odor.", "1.0")
feet.add_option('t', 'target', 'Person to check for odor.',
    required=True)

feet.enable_status('warning')
feet.enable_status('critical')
feet.start()

roommate = Dude(feet.options.target)
feet.set_value('stench', rommmate.gym_socks())
feet.set_status_message('Current stench level (%s)' % rommmate.gym_socks())

feet.finish()

API Specification

class NagAconda.Plugin(description, version)

This is the primary control class for NagAconda.

The attributes available here are direct-access to parsed options and arguments, not class-level variables.

options

This contains all of the options obtained from the command line for this plugin. This includes any options registered by the master class.

arguments

After start is called, all command-line options are read, and anything left over is placed into this object for further use. Most Nagios parsers use explicit option setting, so you might never use this.

add_option(flag, name, helptext, **kwargs)

Adds a Nagios-style help option to this plugin.

Parameters:

• flag – A one-letter shortcut for this option.
• name – The full name for this option.
• helptext – Instructions for usage of this option.
• required (True or False) – Force option for plugin execution. Default False.
• action (Setting string. Default ‘store’) – What type of storage action should take place for this parameter? This is the same as the OptionParser ‘action’ setting. Default is ‘store’.
• callback (function reference or None) – When action is callback, use specified function.
• default – What value to default if unset.

enable_status(status_type, required=False)

Enable warning or critical exit statuses.

Nagios requires error levels to be returned by the running application to evaluate exit status since the text is indeterminate. For Nagios:

• 0 - Status OK
• 1 - Plugin is notifying a warning state.
• 2 - Plugin is notifying of a critical error or state.
• 3 - Some unknown or unhandled error occurred.
• other - Nagios will report this as a plugin failure.

By default, warnings and critical errors are not enabled, in case the plugin is just tracking values. This method will turn them on and add the proper command-line elements so the user can set them.

Note

If warning or critical is enabled and set as required, failing to provide them to the plugin will result in an automatic exit and presentation of the usage documentation.

When plugins make use of multiple performance metrics, they may also have different scales, and hence warning/critical ranges involved. In this case, ranges must be passed by the command-line in comma-delimited format.

Parameters:

• status_type (String.) – Should be either warning or critical.
• required (True or False. Default False.) – Should this threshold be a required option?

finish()

Prints out all results in a form Nagios understands.

The process of setting a value through ‘set_value’ actually applies warning and critical threshold checks, so by now, all is over but the shouting. This method prints out the status and performance data in a manner Nagios will understand.

set_range(range_type, range_end, range_start=0, range_num=1, invert=False)

Manually set certain warning or critical exit statuses.

This function allows the plugin author to set warning or critical thresholds without getting them from the command line. In fact, if called after the ‘start’ method, it can override user parameters.

The ‘end’ parameter is the only required element, as per the Nagios plugin API. However, if set, these rules apply:

1. value < start || value > end, trigger error
2. If inverted, start <= value <= end, trigger error

As the python language gives direct access to various numeric values, use -infinity instead of ‘~’ described by the Nagios API.

Parameters:

• range_type (String.) – Should be either warning or critical.
• range_end (Number) – Values > this should trigger a range error.
• range_start (Number, default 0.) – Values < this should trigger a range error.
• range_num (Boolean, default False.) – Set to use multiple ranges, one per range.
• invert – Set to True to throw errors inside the range.

set_value(name, val, **kwargs)

Set a performance measurement for output to Nagios.

There is theoretically no limit on the number of metrics being tracked in Nagios performance output. That said, we strongly recommend reading the Nagios developer docs to understand how warning and critical test ranges are handled.

Should a minimum or maximum value be provided here, they will only be used to build percentage ranges, and will not otherwise affect operation of Nagios.

This should always be called after the start method.

Note

Any value parameter that is not submitted as an numeric type will be converted to one so tests work properly.

Parameters:

• name – Name of the performance setting.
• val (float) – Value observed for this iteration.
• lowest (float or None) – Minimum possible value for this setting. Optional.
• highest (float or None) – Maximum possible value for this setting. Optional.
• scale (string or None) – The unit of measurement to apply to this value. should be a byte measurement (B, KB, MB, GB, TB) or a unit of time (s, ms, us, ns), or a percentage (%).
• threshold (integer, default 1) – Which warning/critical range to target for this value? Default 1, since most never use more.

Raises ValueError:  

When an invalid scale is passed.

Return string:

One of ‘ok’, ‘warning’ or ‘critical’, as to how this value compared to the enabled and supplied thresholds.

set_status_message(message)

Set a more informational exit string for plugin status.

By default, NagAconda exits merely with OK, WARNING, or CRITICAL, a raw interpretation as applied to provided warning and critical thresholds. Clearly this isn’t sufficent in many cases where plugins know more than merely the metrics being measured. This method is provided as a means to manually add textual information to the plugin’s output that won’t interfere with Nagios’s parsing of that status.

Since status may change through the process of the plugin’s execution several times, or in accordance to the status of several metrics, this is provided separately from the ‘finish’ method.

Note

This is not the same as verbose Nagios output that can span multiple lines. This is just appended to the usual OK / WARNING / CRITICAL status reported back to Nagios.

Parameters:message (string) – Exit status to include in Nagios output. String will be filtered to remove characters that may cause Nagios to ignore or misinterpret plugin output.

start()

Invokes all preparation steps to retrieve host/service status.

Starts the actual plugin’s work. The Plugin class will start by parsing any options so the whole process can short-circuit before we do anything important.

Note

This method may exit directly to the console.

unknown_error(message)

The Plugin encountered an unexpected error, and must immediately exit.

The plugin system itself handles all the necessary details when processing thresholds, which will take care of OK, WARNING, and CRITICAL exit status, but what about UNKNOWN? If some kind of unexpected behavior or parameter, or otherwise misbehaving resource confuses our plugin, we should immediately stop and reconsider. Call this to generate Nagios output with an optional message as to why the plugin quit processing.

This allows ‘finish’ to continue to function as an expected exit point full of processed performance metrics without unnecessary error handling/formatting logic.

Parameters:message (string) – Exit status to include in Nagios output.