How To Write And Use A Python Metric ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ One of the new features in Gmond is the ability to develop and install new metrics as dynamically loadable modules. This has enabled Gmond to be extended in new ways. One of these ways is embeded python. By loading and using the new mod_python DSO, gmond now has the ability to load and call new metric modules that have been developed using the python scripting language. The following sections will describe how to develop and deploy new metric modules using python. Writing a python metric module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are two functions that must be included in every python based metric module as well as at least one callback handler. These functions are: def metric_init(params): This function will be called once at initialization time. It can be used to do any kind of initialization that the module requires in order to properly gather the intended metric. This function also takes a single dictionary type parameter which contains configuration directives that were designated for this module in the gmond.conf file. In addition to any other initialization that is done, the function must also create, populate and return the metric description dictionary or a dictionary list. Each dictionary in the list, must supply at least the following elements: d = {'name': '', 'call_back': , 'time_max': int(), 'value_type': '', 'units': '', 'slope': '', 'format': '', 'description': ''} These elements are basically the same type of data that must be supplied to the gmetric commandline utility with the exception of the call_back function. See the gmetric help document for more information. The call_back entry designates a function that will be called whenever the data for this metric needs to be gathered. The format of this function is very simple. It is just a function name with a 'name' parameter def My_Metric_Handler(name): The value of the name parameter will be the name of the metric that is being gathered. This allows a call_back function to handle more than one metric and to be able to determine which metric is being handled when called. This function implements the code that handles the gathering of the metric data. The return value from this function must match the data value type that was specified in the corresponding metric description that was defined during the metric_init() function. def metric_cleanup(): This function will be called once when gmond is shutting down. Any module clean up code can be executed here and the function must not return a value. Other than the mandatory functions and metric description list as specified above, the metric module is free to do whatever it needs in order to appropriately gather the intended metric data. Each metric description dictionary can also contain additional user defined elements outside of the mandatory elements listed above. Any additional elements in the dictionary will be ignored by mod_python but can to used by the python module itself to hold additional data that should correspond to the metric. Deploying a python metric module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once a python metric module has been developed, deploying the module is as easy as copying a file to a specific directory. In the configuration of the mod_python module that is part of gmond.conf, a python metric module directory must have been specified (see next section). To deploy a python module, simply copy the .py file to the specified python module directory. Once the python module has been copied, start gmond using the -m parameter. This will show a list of all of the available metrics that gmond is capable of gathering. The list should include the name of the python module that was just deployed. Add this metric to a collection group, just like any other gmond metric. Configuring Gmond for python support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Configuring Gmond to support python based modules is as easy as loading any other type of gmond dynamically loadable metric module. The name of the python support module is modpython.so. A base configuration file is included in the Ganglia source code and should have been installed automatically if done through an RPM. The basic configuration that should be added to or included by gmond.conf in your system is as follows: modules { module { name = "python_module" path = "modpython.so" params = "/usr/local/lib64/ganglia/python_modules" } } include ('/usr/local/etc/conf.d/*.pyconf') The most significant part of this configuration is the 'params' directive. The path that has been assigned to this directive will be passed down to the mod_python module and used to search for .py python modules. Any python module that is found in this location will be loaded and assumed to be a metric gathering module. If the collection groups that include metrics that are implemented in python, are put into separate configuration files and the file extension of the configuration files are .pyconf, they will automatically be loaded and read whenever the mod_python module is included. Configuring a Gmond python module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The configuration of a Gmond python module is really no different than any other module. Most python modules will not require any specialized configuration at all. However, support has been provided to allow for parameters to be passed from the gmond.conf file to a python module. The syntax for passing parameters to a specific python module is at follows: modules { module { name = "example" language = "python" param YouNameIt { value = Whatever } param Another { value = NewValue } } } The "module" section must contain a "name" directive and a "language" directive. The value of the "name" directive must match the file name of the python module's .py file and the value of the "language" directive must be "python". The section can take multiple "param" sections. Each "param" section must include a name which will be the name of the value when it is passed to the python module, and a "value" directive. The "value" directive will always be passed as a string to the python module. It is up to the module itself to determine the actual value type.