Updates

About

Regular Munin Plugins employ one-plugin one-graph logic and require the execution of a script for data retrieval for each graph. Multigraph plugins permit the retrieval of data for multiple graphs in one execution run (one-plugin many-graphs), reducing the processing time and delay for the fetch cycle significantly. More information on Multigraph Plugins can be found in the Munin Wiki at the Munin Project Website:

  • [Multigraph Plugins] (http://munin-monitoring.org/wiki/MultigraphSampleOutput)
  • [Multigraph Plugin Protocol] (http://munin-monitoring.org/wiki/protocol-multigraph)

PyMunin has been developed for implementing Multigraph Plugins using Python, but simple single graph plugins are also supported.

The code for retrieval of data is totally separated from Munin specific code. The modules for data retrieval in pysysinfo can be used independently of Munin in other monitoring solutions.

The authoritative source for information on Munin and Munin Plugins is the Munin Wiki at the Munin Project Website. You can also check Instant Munin Plugin Starter book from Packt Publishing for a step-by-step introduction to Munin.

For information on other projects you can check my GitHub Personal Page and GitHub Profile.

Plugins

PyMunin has been used in developing many Multigraph Munin Plugins. The following is a list of plugins that are included the base distribution of PyMunin: * Apache Tomcat Server * Apache Web Server * Asterisk Telephony Server * Disk Space Usage * Disk I/O * FreeSWITCH Soft Switch * Lighttpd Web Server * Memcached Cache Server * MySQL Database Server * Network Interfaces * Network Connections * Nginx Web Server * NTP - Time Synchronization Server * NTP Synchronization State * NTP Remote Host Offset * NTP Remote Host Offsets * PHP APC (PHP Cache) * PHP FPM (FastCGI Process Manager) * PostgreSQL Database Server * Processes and Threads * Rackspace Cloud * Redis Server * System Resources * Sangoma Wanpipe Telephony Interfaces * Varnish Cache Web Application Accelerator

Download

Binary Packages

PyMunin has been packaged for Fedora and is also included in the EPEL Repository for Red Hat Enterprise Linux, CentOS, Scientific Linux, etc. You can check the latest updates to the packages distributed by Fedora Project here:

https://admin.fedoraproject.org/updates/PyMunin

Please take not that the binary packages might take a long time to get updated between distribution releases, so check the source packages to get the latest and greatest.

Anyone that is interested in packaging PyMunin for other distributions can contact me directly for assistance.

Source Packages

New versions of the code are be published for download at PyPI - the Python Package Index periodically.

You can download the latest development version of this code that is hosted at GitHub either in ZIP or TAR format.

You can also get the latest development version of the code by cloning the Git repository for the project by running:

git clone git://github.com/aouyar/PyMunin

Installation

Binary Packages

PyMunin is included in the latest versions of Fedora Linux, aand starting with EL6,PyMunin can be installed in Red Hat Enterprise Linux, CentOS, Scientific Linux, etc. using the EPEL Repository.

In the supported distributions, once the software repositories are configured correctly, PyMunin can be installed using yum:

yum install PyMunin

Source Packages

Automated Installation

The code can be downloaded and installed automatically using pip:

To install the latest version published in PyPI using pip execute:

pip install PyMunin

To install the latest development version directly from GitHub using pip execute:

pip install git+https://github.com/aouyar/PyMunin.git#egg=PyMunin

The other option is to download and uncompress the code manually and execute the included setup.py script to start installation:

./setup.py install

This will install pymunin and pysysinfo in Python site packages. The plugins will be unpacked as console scripts into the install bin directory. Each of the scripts will be prefixed with pymunin- (ex. pymunin-apachestats ) to avoid name collisions with other binaries. The location will be /usr/local/bin/ if installed globally or $VIRTUAL_ENV/bin if installed with virtualenv.

The plugins will automatically be installed in Munin Plugins directory (ex. /usr/share/munin/plugins ), if the installation process is executed with a privileged user and the pymunin- prefix will be dropped in the process.

If the installation process fails while copying the plugin scripts to Munin Plugin Directory because of permissions problems pymunin-install script will be created for copying the plugins from the bin directory to /usr/share/munin/plugins.

In certain cases the install script might fail to determine the path for installing the Munin Plugins (ex. /usr/share/munin/plugins ). The MUNIN_PLUGIN_DIR environment variable could be set before executing the setup script to force the installation of plugins in a specific directory.

Manual Installation

  • The pymunin and pysysinfo directories should be placed in Python search path or in the Munin Plugins directory (ex. /usr/share/munin/plugins_ ).
  • Copy the plugin scripts in the directory pymunin/plugins to the Munin Plugins directory (ex. /usr/share/munin/plugins ) after removing the file extension ‘py’.

Configuration

Activation the Plugins

Enable the plugins just like the standard plugins by creating symbolic links in the Munin Plugins Configuration Directory ( /etc/munin/plugins ) pointing to actual plugins scripts in /usr/share/munin/plugins.

Configuration of the Plugins

Configuration files for plugins can be created in the Munin Plugins Configuration Directory ( /etc/munin/plugin-conf.d ).

The environment variables used by the plugin scripts are documented in the individual web pages for the plugins and in the header part of the plugin modules in pymunin/plugins.

Configuration of Multiple Instances of Plugins

The configuration of multiple instances of plugins will be illustrated with a simple example for monitoring two instances of Apache Web Servers from the same node.

Multiple symbolic links with different names pointing to the same plugin script in are created in /usr/share/munin/plugins is created in the Munin Plugins Configuration Directory ( /etc/munin/plugins ).

Example:

/etc/munin/plugins/apachestats_web1 -> /usr/share/munin/plugins/apachestats
/etc/munin/plugins/apachestats_web2 -> /usr/share/munin/plugins/apachestats

Independent configuration files ( /etc/munin/plugin-conf.d/apachestats_web1 and /etc/munin/plugin-conf.d/apachestats_web2 ) are created for the two instances.

/etc/munin/plugin-conf.d/apachestats_web1 :

[apachestats_web1]
  env.host 192.168.0.1
  env.port 80
  env.instance_name web1
  env.instance_label WebSrv1

/etc/munin/plugin-conf.d/apachestats_web2 :

[apachestats_web2]
  env.host 192.168.0.2
  env.port 80
  env.instance_name web2
  env.instance_label WebSrv2

Troubleshooting

On error plugins return short error messages by default. Plugin debugging must be enabled to return full trace for exceptions. Use munin-run with the –pidebug option to enable plugin debugging.

Collaboration

I would be happy to receive suggestions on improving the code for developing Munin Plugins. You can use the Issues functionality of GitHub to document problems and to propose improvements. Alternatively you can use the internal messaging system of GitHub or my e-mail address to contact me directly, but the Issues system is the preferred medium for reporting errors or proposing improvements.

I hope that by sharing the code, the existing plugins will get more testing and receive improvements, and many more Multigraph Munin Plugins will be developed collaboratively.

I would be glad to receive some sample graphs from anyone using the plugins.

Development

Design

The plugins consist of the following components:

  • The pymunin module ( plugins/pymunin ) implements the base classes for developing Munin plugins.
    • Munin Plugins can be created by subclassing the MuninPlugin class.
    • Each plugin contains one or more graphs implemented by MuninGraph class instances.
    • The muninMain function implements the entry point for Munin Plugins.
  • The plugin logic is implemented in the plugin scripts in pymunin/plugins.
  • The actual data retrieval logic is separated from the plugins to facilitate code reuse. Individual modules in the directory pysysinfo implement classes for getting the monitoring data and returning them as dictionary objects. The separation of the data retrieval logic should facilitate the use of the code in other monitoring solutions.
  • Common utility classes and methods used by various data retrieval modules are placed in the util module in pysysinfo.

Plugin Development

The first step for implementing a new Multigraph Munin Plugin is developing a new module in pysysinfo for retrieving the monitoring data.

The steps for developing the actual plugin script are as follows:

  • Plugin scripts are placed in pymunin/plugins by default.
  • New plugins are implemented by extending the MuninPlugin class in pymunin. You can check the plugin scripts in pymunin/plugins for working examples.
  • The plugin_name property of MuninPlugin class must be set to the name of the plugin.
  • Graph Objects are registered to the plugin in the constructor of the plugin class.
  • Code for creating graph objects which are instances of the MuninGraph class are placed in the constructor of the plugin class.
  • Code for adding fields to the graph using the addField method of the MuninGraph class is placed in the constructor of the plugin class.
  • Code for registering the graphs to plugin using the appendGraph method of the MuninPlugin class is placed in the constructor of the plugin class.
  • The retrieveVals method of the plugin class is overwritten to retrieve data points and to associate values with the graph fields using the setGraphVal method of the MuninPlugin class.
  • The muninMain function in /plugins/pymunin is called with the plugin class as argument for initializing the main method of plugin.

Credits

PyMunin has been developed by Ali Onur Uyar ([aouyar @ GitHub] (https://github.com/aouyar)).

Some of the people that have knowingly or unknowingly contributed to the development are:

  • Initial packaging of the code was done by Mark Lavin. PyMunin is installable using pip or easy_install thanks to Mark. :-)
  • PyMunin has been packaged for Fedora and Red Hat Enterprise Linux by Matthias Runge.
  • The initial design of the solution was inspired by python-munin by Samuel Stauffer.
  • The Rackspace Cloud plugin was initially developed by Brian Welsh. and it is the first plugin that has been contributed to the project.
  • Sebastian Rojo has contributed many improvements to the Asterisk Plugin.
  • Preston Mason has made significant contributions to the Varnish Cache and PHP APC Cache Plugins.
  • Many plugins were inspired by existing _Munin Plugins_developed by other people. (Before developing any plugins, I always try to check existing solutions.)
  • Many people have contributed by testing the plugins and identifying issues.

I hope that more people will be using PyMunin for developing plugins in the future.

License

PyMunin is copyrighted free software made available under the terms of the GPL License Version 3 or later.

See the file COPYING that acompanies the code for full licensing information.