ganglia python插件标准

Context Navigation

Gmond Python metric modules ¶

One of the new features of Ganglia 3.1.x is the ability to create C/Python metric gathering modules. These modules can be plugged directly into gmond to monitor user-specified metrics.

In previous versions (2.5.x, 3.0.x), the only way to add user-specified metrics is via a command line tool called gmetric and the way to inject metrics into gmond is simply to run gmetric via a cronjob or some other process. While this works for most people, it makes user-specified metrics difficult to manage.

This document will dive into the specifics for writing a Python metric monitoring module.

The following are prerequisites for building/using Python module support:

Ganglia 3.1.x
Python 2.3.4+ (this is the oldest tested version which comes with Red Hat Enterprise Linux 4, older 2.3 versions should work as well)
Python development headers (usually in the form of python-devel binary packages)

Installation ¶

If you are trying to install Python metric modules support on a RPM-based system, install the ganglia-gmond-modules-python RPM. This includes everything needed for Python metric modules support to work.

If you are building from source, please make sure that you include the --with-python option during configure. If the Python interpreter is detected, this option will be added automatically.

Checklist ¶

To confirm that your Ganglia installation has Python support correctly setup, double check the following:

gmond.conf has a line which reads something along the lines of include ("/etc/ganglia/conf.d/*.conf"). This is the directory where you should place configuration files for your Python modules as .pyconf files
You have modpython.so in /usr/lib{64}/ganglia
The directory /usr/lib{64}/ganglia/python_modules exists. This is the directory where Python modules should be placed as .py files.

These things should be automatically done for you if you installed Python modules support via binary packages. If that is not the case please file a bug at the distribution's corresponding bug tracker.

Writing Python modules ¶

Writing a Python module is very simple. You just need to write it following a template and put the resulting Python module (.py) in /usr/lib(64)/ganglia/python_modules. A corresponding Python Configuration (.pyconf) file needs to reside in /etc/ganglia/conf.d/.

If your Python module needs to access certain files on the server, keep in mind that the module will be executed as the user which runs gmond. In other words, if gmond runs as user nobody then your module will also run as nobody. So make sure that the user which runs gmond has the correct permissions to access the files in question.

The Ganglia distribution comes with an example Python module in /usr/lib(64)/ganglia/python_modules/example.py. Alternatively, this file is also viewable from our SVN repository: http://ganglia.svn.sourceforge.net/viewvc/ganglia/branches/monitor-core-3.1/gmond/python_modules/example/example.py?view=markup

Let's look at a real-life example of a Python module which monitors the temperature of the host, by reading a file in the /proc file system, let's call this temp.py:

def temp_handler(name):
    acpi_file = "/proc/acpi/thermal_zone/THRM/temperature"

    try:
        f = open(acpi_file, 'r')

    except IOError:
        return 0

    for l in f:
        line = l.split()

    return int(line[1])

def metric_init(params):
    global descriptors

    d1 = {'name': 'temp',
        'call_back': temp_handler,
        'time_max': 90,
        'value_type': 'uint',
        'units': 'C',
        'slope': 'both',
        'format': '%u',
        'description': 'Temperature of host',
        'groups': 'health'}

    descriptors = [d1]

    return descriptors

def metric_cleanup():
    '''Clean up the metric module.'''
    pass

#This code is for debugging and unit testing
if __name__ == '__main__':
    metric_init(None)
    for d in descriptors:
        v = d['call_back'](d['name'])
        print 'value for %s is %u' % (d['name'],  v)

There are three functions that must exist in every python metric module. These functions are:

def metric_init(params):
def metric_cleanup():
def metric_handler():

While the first two functions above must exist explicitly (ie. they must be named as specified above), the metric_handler() function can actually be named anything. The only requirement is that the call_back function that is specified in the metric descriptor (described below) must match the name of the metric_handler function. In addition if your metric module supports multiple metrics, each being defined through their own metric descriptor, your module may actually implement more than one metric_handler function.

Let's go through each function one by one. The temp_handler() function simply parses the file with the temperature readings and returns it. This is the metric_handler function that was described above. The name of this function must match the function name that is specified for the call_back attribute of the corresponding metric descriptor (see below). It must also return the appropriately typed value. For example, if the value_type attribute of the metric descriptor specifies a UINT, then the metric_handler function must return a UINT data type.

The metric_init() function creates and initializes metric descriptors for each metric that the module supports. If the module supports a single metric, then the return value from the metric_init() function can be just a single descriptor. If however the module supports multiple metrics, the return value must be a list of descriptors. Each metric that is supported by the module must create and initialize a metric descriptor in the following manner:

name: name of the metric
call_back: function to call when collecting metric data
time_max: maximum time in seconds between metric collection calls
value_type: string | uint | float | double
units: unit of your metric
slope: zero | positive | negative | both
- If 'positive', RRD file generated will be of COUNTER type, otherwise will be of GAUGE type
- If 'zero', the metric will appear in the "Time and String Metrics" or the "Constant Metrics" depending on the value_type of the metric
format: format string of your metric
- Must correspond to value_type otherwise value of your metric will be unpredictable (reference: http://docs.python.org/library/stdtypes.html#string-formatting)
description: description of your metric
- Which is visible in web frontend if you hover over host metric graph
group: group of your metric
- Metrics in the web frontend hostview is grouped by this

The metric descriptor can include additional attributes and values which will be attached to the metric metadata as extra data. The extra data will be ignored by Ganglia itself but can be used by the web front as additional display or metric handling data. (The use of SPOOF_HOST and SPOOF_NAME extra attributes are examples that will be described in a later version.)

In addition, the metric_init() function takes one parameter. This parameter is a list of name/value pairs that correspond to configuration parameters that were included in the gmond.conf file for a specific metric module. These name/value pairs are read from the configuration file, passed directly to the module and are only meaningful to the metric module itself. The metric module must know what the params values mean and how to apply them to the metric module functionality. How these configuration parameters are defined is explained below.

The corresponding temp.pyconf looks like this:

modules {
  module {
    name = "temp"
    language = "python"
    # The following params are examples only
    #  They are not actually used by the temp module
    param RandomMax {
      value = 600
    }
    param ConstantValue {
      value = 112
    }
  }
}

collection_group {
  collect_every = 10
  time_threshold = 50
  metric {
    name = "temp"
    title = "Temperature"
    value_threshold = 70
  }
}

The above configuration file contains two major sections with various sub-sections. The modules section contains configuration data that is specific to each module being loaded. It may contain either a single module sub-section or multiple sub-sections. Within each module sub-section is the name of the metric module, the language in which the module was written and zero or more module specific param(s). Each param sub-section has a name and a value. The name and value make up the name/value pair that is passed into the metric_init() function as a params list as described above. The rest of the configuration file follows the same format as for any other collection_group or metric.

ganglia python插件标准

ganglia

Context Navigation

Gmond Python metric modules ¶

Installation ¶

Checklist ¶

Writing Python modules ¶

Further reading ¶

Download in other formats:

公告