PyNagios 0.1.2-dev Documentation

Overview

PyNagios is a Python library for writing Nagios plug-ins. Writing a Nagios plug-in typically involves conforming to a large list of guidelines, and this library removes the boilerplate necessary in writing your own plug-ins.

Tutorial

Start here for a quick start guide.

API Documentation

The complete API documentation, organized by module.

Issues

If any issues are found with the library, please file an issue with the PyNagios issue tracker. Tickets are triaged quickly and you should receive a prompt response.

Contributing

PyNagios is an open source project which welcomes contributions which can be anything from simple documentation fixes to new features. To contribute, fork the project on GitHub and send a pull request.

Indices and tables

• Index
• Module Index
• Search Page

API Documentation

PyNagios contains one main top-level package, pynagios.

pynagios – Python Library for Writing Nagios Plugins

This package provides all the modules for writing a Nagios plugin with Python. The package file itself exports the constants used throughout the library.

pynagios.version = '0.1.2-dev'

Current version of PyNagios

pynagios.PerfData

Alias for pynagios.perf_data.PerfData

pynagios.Plugin

Alias for pynagios.plugin.Plugin

pynagios.Range

Alias for pynagios.range.Range

pynagios.Response

Alias for pynagios.response.Response

pynagios.Status

Alias for pynagios.status.Status

pynagios.OK

A Status object representing the OK response status.

pynagios.WARNING

A Status object representing the WARNING response status.

pynagios.CRITICAL

A Status object representing the CRITICAL response status.

pynagios.UNKNOWN

A Status object representing the UNKNOWN response status.

Sub-modules:

perf_data – Performance Data Classes

Tools for creating performance data for Nagios plugin responses. If you’re adding performance data to a Response object, then set_perf_data() can be called instead of having to create an entire PerfData object.

class pynagios.perf_data.PerfData(label, value[, uom=None[, warn=None[, crit=None[, minval=None[, maxval=None]]]]])

Creates a new object representing a single performance data item for a Nagios response.

Performance data is extra key/value data that can be returned along with a response. The performance data is not used immediately by Nagios itself, but can be extracted by 3rd party tools and can often be helpful additional information for system administrators to view. The label can be any string, but value must be a numeric value.

Raises ValueError if any of the parameters are invalid. The exact nature of the error is in the human readable message attribute of the exception.

Parameters:

• label: Label for the performance data. This must be a string.
• value: Value of the data point. This must be a number whose characters are in the class of [-0-9.]
• uom (optional): Unit of measure. This must only be %, s for seconds, c for continous data, or a unit of bit space measurement (‘b’, ‘kb’, etc.)
• warn (optional): Warning range for this metric.
• crit (optional): Critical range for this metric.
• minval (optional): Minimum value possible for this metric, if one exists.
• maxval (optional): Maximum value possible for this metric, if one exists.

value

The value of this metric.

warn

The warning range of this metric. This return value of this will always be a Range object, even if it was set with a string.

crit

The critical range of this metric. This return value of this will always be a Range object, even if it was set with a string.

minval

The minimum value possible for this metric. This doesn’t make a lot of sense if the uom is ‘%’, since that is obviously going to be 0, but this will return whatever was set.

maxval

The maximum value possible for this metric. This doesn’t make a lot of sense if the uom is ‘%’, since that is obviously going to be 100, but this will return whatever was set.

uom

The unit of measure (UOM) for this metric.

__str__()

Returns the proper string format that should be outputted in the plugin response string. This format is documented in depth in the Nagios developer guidelines, but in general looks like this:

‘label’=value[UOM];[warn];[crit];[min];[max]

plugin – Plugin Class

This module provides the Plugin class, which is the basic class which encapsulates a single plugin. This is the class which should be subclassed when creating new plugins.

class pynagios.plugin.Plugin([argv=sys.argv])

Instantiates a plugin, setting up the options and arguments state. Initialization by itself shouldn’t do much, since the plugin should run when check() is called.

This init method will parse the arguments given in args and will set the results on the options attribute. If no args are given, the command line arguments given to the whole Python application will be used.

All plugins parse standard command line arguments that are required by the Nagios developer guidelines:

• hostname - Set via -H or --hostname, this should be the host that this check targets, if applicable.
• warning - Set via -w or --warning, this should be a valid range in which the value of the plugin is considered to be a warning.
• critical - Set via -c or --critical, this should be a valid range in which the value is considered to be critical.
• timeout - Set via -t or --timeout, this is an int value for the timeout of this check.
• verbosity - Set via -v, where additional v means more verbosity. Example: -vvv will set options.verbosity to 3.

Subclasses can define additional options by creating Action instances and assigning them to class attributes. The easiest way to make an Action is to use Python’s built-in argparse methods. The following is an example plugin which adds a simple string argument::

class MyPlugin(Plugin):
    parser = ArgumentParser()
    parser.add_argument("--your-name", dest="your_name", type="string")

Instantiating the above plugin will result in the value of the new argument being available in options.your_name.

options

Dictionary of parsed command line options and their values. As an example, to get the hostname passed in via the command line::

options.hostname

args

Array of additional positional arguments passed in via the command line. For example, if you call the plugin with ./plugin 1 2 3, then options.args will return [1,2,3].

check()

This method is what should be called to run this plugin and return a proper Response object. Subclasses are expected to implement this.

response_for_value(value, message=None)

This method is meant to be used by plugin implementers to return a valid Response object for the given value. The status of this response is determined based on the warning and critical ranges given via the command line, which the plugin automatically parses.

An optional message argument may be provided to set the message for the Response object. Note that this can easily be added later as well by simply setting the message attribute on the response object returned.

Creating a response using this method from check() makes it trivial to calculate the value, grab a response, set some performance metrics, and return it.

response - Response Class

Contains the class which represents a response for Nagios. This encapsulates the response format that Nagios expects.

class pynagios.response.Response([status=None[, message=None]])

Nagios responses are expected to be in a very specific format, and this class allows these responses to easily be built up and extracted in the proper format.

This class makes it easy to set the status, message, and performance data for a response.

Parameters:

• status (optional): A Status object representing the status of the response.
• message (optional): An information message to include with the output.

set_perf_data(label, value, uom=None, warn=None, crit=None, minval=None, maxval=None)

Adds performance data to the response. Performance data is shown in the Nagios GUI and can be used by 3rd party programs to build graphs or other informational output. There are many options to this method. They are the same as the initialization parameters for a PerfData object.

See also

PerfData

exit()

This prints out the response to stdout and exits with the proper exit code.

__str__()

The string format of this object is the valid Nagios output format. The response format is expected to be the following:

status: information|performance data

An example of realistic output:

OK: 27 users logged in|users=27;0:40;0:60;0;

range - Tools for Working with Nagios Ranges

Contains a class to represent a range that adheres to the range format defined by Nagios.

class pynagios.range.Range(value)

Initializes a Nagios range with the given value. The value should be in the Nagios range format, which is the following:

[@]start:end

Notes:

• start must be less than or equal to end
• Ranges by default are exclusive. A range of 10:20 will match values that are < 10 OR >20.
• @ means the range is inclusive. So @10:20 is valid in the case that the value is >= 10 AND <= 20.
• If start or end is ~, this value is negative or positive inifinity, respectively. A range of ~:20 will match values that are > 20 only.
• If start is not given, then it is assumed to be 0.
• If end is not given, but a : exists, then end is assumed to be infinity. Example: 5: would match < 5.

in_range(value)

Tests whether value is in this range.

__str__()

Turns this range object back into a valid range string which can be passed to another plugin or used for debug output. The string returned from here should generally be equivalent to the value given to the constructor, but sometimes it can be slightly different. However, it will always be functionally equivalent.

Examples:

>> str(Range("@10:20")) == "@10:20"
>> str(Range("10")) == "10"
>> str(Range("10:")) == "10:~"

class pynagios.range.RangeValueError

This exception is raised when an invalid value is passed to Range. The message of this exception will contain a human readable explanation of the error.

status - Nagios Status Objects

This module provides the Status class, which encapsulates a status code for Nagios.

class pynagios.status.Status(name, exit_code)

Creates a new status object for Nagios with the given name and exit code.

Note: In general, this should never be called since the standard statuses are exported from pynagios.