The nagiosplugin library
nagiosplugin is a Python class library which helps writing Nagios (or Icinga)
compatible plugins easily in Python. It cares for much of the boilerplate code
and default logic commonly found in Nagios checks, including:
- Nagios 3 Plugin API compliant parameters and output formatting
- Full Nagios range syntax support
- Automatic threshold checking
- Multiple independend measures
- Custom status line to communicate the main point quickly
- Long output and performance data
- Timeout handling
- Persistent “cookies” to retain state information between check runs
- Resume log file processing at the point where the last run left
- No dependencies beyond the Python standard library (except for Python 2.6).
nagiosplugin runs on POSIX and Windows systems. It is compatible with Python
3.4, Python 3.3, Python 3.2, and Python 2.7.
The nagiosplugin package is released under the Zope Public License 2.1 (ZPL), a
BSD-style Open Source license.
Comprehensive documentation is available online. The examples mentioned in
the tutorials can also be found in the nagiosplugin/examples directory of
the source distribution.
Creating a build with zc.buildout
First, create a virtualenv if not already present:
virtualenv -p python3.4 --no-setuptools .
zc.buildout will take care of all required dependencies:
bin/pip3.2 install -U zc.buildout
If you want to use another Python version like 2.7, just the same steps with the
Python version substituted:
virtualenv -p python2.7 --no-setuptools .
bin/pip2.7 install -U zc.buildout
When the buildout succeeds, run the unit test by invoking:
Our build server runs test against the trunk on a regular basis.
nagiosplugin also includes support for coverage reports. It aims at 100% test
coverage where possible. The preferred way to get a coverate report is to use
to determine test coverage and open the report in a web browser. Alternatively,
bin/coverage run bin/test
to get a purely text-based coverage report.
You may run the supplied examples with the local interpreter:
The documentation uses Sphinx. Build the documentation (buildout should have
been running before to install Sphinx etc.):
make -C doc html
How to release
To make a release, we prefer zest.releaser. To make a release, follow
the standard procedure, which usually boils down to:
nagiosplugin tried to obey the semantic version numbering specification
published on SemVer but adapts it a little bit to be PEP 386 compliant.
- Add optional keyword parameter verbose to Runtime.guarded(). This parameter
allows to set verbose level in the early execution phase (#13).
- Allow Context.evaluate() return either a Result or ServiceState object. In
case the latter is returned, it gets automatically wrapped in a Result object
- Fix bug that caused a UnicodeDecodeError when using non-ASCII characters in
- Print perfdata always on a single line (even in multi-line mode) to improve
compatibility with various monitoring systems (#11).
- Mention that nagiosplugin also runs with Python 3.4 (no code changes
- Make name prefix in status output optional by allowing to assign None to
- Accept bare metric as return value from Resource.probe().
- Fix bug where Context.describe() was not used to obtain metric description
- Fix build failures with LANG=C (#13140).
- Remove length limitation of perfdata labels (#13214).
- Fix formatting of large integers as Metric values (#13287).
- Range: allow simple numerals as argument to Range() (#12658).
- Cookie: allow for empty state file specification (#12788).
- New Summary.empty method is called if there are no results present (#11593).
- Improve range violation wording (#11597).
- Ensure that nagiosplugin install correctly with current setuptools (#12660).
- Behave and do not attach anything to the root logger.
- Add debugging topic guide. Explain how to disable the timeout when using pdb
- Made compatible with Python 2.6 (#12297).
- Tutorial #3: check_users (#11539).
- Minor documentation improvements.
- LogTail returns lines as byte strings in Python 3 to avoid codec issues
- LogTail gives a line-based iterator instead of a file object (#11564).
- Basic API docs for the most important classes (#11612).
- Made compatible with Python 2.7 (#11533).
- Made compatible with Python 3.3.
- Improve error reporting for missing contexts.
- Exit with code 3 if no metrics have been generated.
- Improve default Summary.verbose() to list all threshold violations.
- Move main source repository to https://bitbucket.org/gocept/nagiosplugin/
- API docs for the most important classes (#7939).
- Added two tutorials (#9425).
- Fix packaging issues.
- Completely reworked API. The new API is not compatible with the old 0.4 API so
you must update your plugins.
- Python 3 support.
- The Cookie class is now basically a persistent dict and accepts key/value
pairs. Cookie are stored as JSON files by default so they can be inspected by
the system administrator (#9400).
- New LogTail class which provides convenient access to constantly growing log
files which are eventually rotated.
- Windows port. nagiosplugin code now runs under pywin32 (#10899).
- Include examples in egg release (#9901).
Bugfix release to fix issues reported by users.
- Improve Mac OS X compatibility (#8755).
- Include examples in distribution (#8555).
- Change __str__ representation of large numbers to avoid scientific notation.
- Fix distribution to install correctly.
- Documentation: tutorial and topic guides.