Creating a custom plugin

The nixstats monitoring agent comes with a set of plugins to monitor your servers CPU, Memory, Disk, Network, Processes and a set of plugins for your services such as MongoDB, PHP-FPM, NGiNX, Apache2/httpd.

Besides these plugins it's possible to monitor other metrics on your server by building your own plugin. Plugins are written in Python 2. The base of a plugin is as follows.

#!/usr/bin/env python
# -*- coding: utf-8 -*- 
import plugins


class Plugin(plugins.BasePlugin):
    __name__ = 'fridge'

    def run(self, *unused):
        results = {'milk': 10, 'eggs': 4}
        return results


if __name__ == '__main__':
    Plugin().execute()

This is a simple example plugin. You have to save the plugin to the plugins directory. You can find out your plugin directory by running the following command.

root@ns:~# nixstatsagent info
Version: 1.1.18
Plugins enabled: memory, diskusage, process, loadavg, network, cpu, ping, iostat, swap, system
Plugins directory: /usr/local/lib/python2.7/dist-packages/nixstatsagent/plugins
Server: 53bad1a222c9eea0378a4567

Save the plugin title under the same value as the __name__ for example in this examples case we would save the plugin to /usr/local/lib/python2.7/dist-packages/nixstatsagent/plugins/fridge.py

Now we can test the plugin by running:

root@ns:~# nixstatsagent test fridge
fridge:
{
    "eggs": 4,
    "milk": 10
}

If the test is successful you can enable the plugin by editing the configuration file usually located at /etc/nixstats.ini. Add a new section to this file called [fridge] again the same as the __name__ value in your plugin file.

[fridge]
enabled = yes
Using configuration values

You might need to use configuration values in your plugin, for example an address to connect to.

This values can be stored in the configuration file at /etc/nixstats.ini. In the last example we could add an address.

[fridge]
enabled = yes
location = http://192.168.0.100/fridge.json

We can now retrieve the configuration values in the plugin.

#!/usr/bin/env python
# -*- coding: utf-8 -*- 
import plugins
import json
import urllib2

class Plugin(plugins.BasePlugin):
    __name__ = 'fridge'

    def run(self, config):
        request = urllib2.Request(config.get(__name__, 'location'))
        raw_response = urllib2.urlopen(request)
        fridge_data = json.loads(raw_response.read(), object_hook=ascii_encode_dict)
        results = {'milk': fridge_data['milk'], 'eggs': fridge_data['eggs']}
        return results


if __name__ == '__main__':
    Plugin().execute()

The run() function now has a second parameter with the config object. We're also importing urllib2 and json to retrieve data.

After setting up your custom plugin you can find the data at the plugin tab for your server.

If you need any help creating your custom plugin feel free to contact us through the live chat or by e-mail at vincent@nixstats.com