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.
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
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:
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.
New versions of the code are be published for download at PyPI - the Python Package Index periodically.
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
In the supported distributions, once the software repositories are configured correctly, PyMunin can be installed using yum:
yum install PyMunin
The code can be downloaded and installed automatically using pip:
pip install PyMunin
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:
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.
- 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’.
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 ).
/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.
[apachestats_web1] env.host 192.168.0.1 env.port 80 env.instance_name web1 env.instance_label WebSrv1
[apachestats_web2] env.host 192.168.0.2 env.port 80 env.instance_name web2 env.instance_label WebSrv2
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.
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.
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.
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.
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.
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.