| 1 |
How To Write And Use A Python Metric |
| 2 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3 |
|
| 4 |
One of the new features in Gmond is the ability to develop |
| 5 |
and install new metrics as dynamically loadable modules. This |
| 6 |
has enabled Gmond to be extended in new ways. One of these |
| 7 |
ways is embeded python. By loading and using the new |
| 8 |
mod_python DSO, gmond now has the ability to load and call new |
| 9 |
metric modules that have been developed using the python |
| 10 |
scripting language. The following sections will describe |
| 11 |
how to develop and deploy new metric modules using python. |
| 12 |
|
| 13 |
|
| 14 |
Writing a python metric module |
| 15 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 16 |
|
| 17 |
There are two functions that must be included in every python |
| 18 |
based metric module as well as at least one callback handler. |
| 19 |
These functions are: |
| 20 |
|
| 21 |
def metric_init(params): |
| 22 |
This function will be called once at initialization time. It |
| 23 |
can be used to do any kind of initialization that the module |
| 24 |
requires in order to properly gather the intended metric. This |
| 25 |
function also takes a single dictionary type parameter which |
| 26 |
contains configuration directives that were designated for |
| 27 |
this module in the gmond.conf file. In addition to any other |
| 28 |
initialization that is done, the function must also create, |
| 29 |
populate and return the metric description dictionary or a |
| 30 |
dictionary list. Each dictionary in the list, must supply at |
| 31 |
least the following elements: |
| 32 |
|
| 33 |
d = {'name': '<your_metric_name>', |
| 34 |
'call_back': <metric_handler_function>, |
| 35 |
'time_max': int(<your_time_max>), |
| 36 |
'value_type': '<string | uint | float | double>', |
| 37 |
'units': '<your_units>', |
| 38 |
'slope': '<zero | positive | negative | both>', |
| 39 |
'format': '<your_format>', |
| 40 |
'description': '<your_description>'} |
| 41 |
|
| 42 |
These elements are basically the same type of data that must be |
| 43 |
supplied to the gmetric commandline utility with the exception |
| 44 |
of the call_back function. See the gmetric help document for |
| 45 |
more information. The call_back entry designates a function |
| 46 |
that will be called whenever the data for this metric needs to |
| 47 |
be gathered. The format of this function is very simple. It |
| 48 |
is just a function name with a 'name' parameter |
| 49 |
|
| 50 |
def My_Metric_Handler(name): |
| 51 |
|
| 52 |
The value of the name parameter will be the name of the metric |
| 53 |
that is being gathered. This allows a call_back function to |
| 54 |
handle more than one metric and to be able to determine which |
| 55 |
metric is being handled when called. This function implements the |
| 56 |
code that handles the gathering of the metric data. The return |
| 57 |
value from this function must match the data value type that was |
| 58 |
specified in the corresponding metric description that was defined |
| 59 |
during the metric_init() function. |
| 60 |
|
| 61 |
def metric_cleanup(): |
| 62 |
This function will be called once when gmond is shutting down. |
| 63 |
Any module clean up code can be executed here and the function |
| 64 |
must not return a value. |
| 65 |
|
| 66 |
Other than the mandatory functions and metric description list as |
| 67 |
specified above, the metric module is free to do whatever it needs |
| 68 |
in order to appropriately gather the intended metric data. Each |
| 69 |
metric description dictionary can also contain additional user |
| 70 |
defined elements outside of the mandatory elements listed above. Any |
| 71 |
additional elements in the dictionary will be ignored by mod_python |
| 72 |
but can to used by the python module itself to hold additional |
| 73 |
data that should correspond to the metric. |
| 74 |
|
| 75 |
Deploying a python metric module |
| 76 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 77 |
|
| 78 |
Once a python metric module has been developed, deploying the module |
| 79 |
is as easy as copying a file to a specific directory. In the configuration |
| 80 |
of the mod_python module that is part of gmond.conf, a python metric module |
| 81 |
directory must have been specified (see next section). To deploy a |
| 82 |
python module, simply copy the .py file to the specified python module |
| 83 |
directory. Once the python module has been copied, start gmond using the |
| 84 |
-m parameter. This will show a list of all of the available metrics that |
| 85 |
gmond is capable of gathering. The list should include the name of the |
| 86 |
python module that was just deployed. Add this metric to a collection |
| 87 |
group, just like any other gmond metric. |
| 88 |
|
| 89 |
Configuring Gmond for python support |
| 90 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 91 |
|
| 92 |
Configuring Gmond to support python based modules is as easy as loading |
| 93 |
any other type of gmond dynamically loadable metric module. The name of |
| 94 |
the python support module is modpython.so. A base configuration file |
| 95 |
is included in the Ganglia source code and should have been installed |
| 96 |
automatically if done through an RPM. The basic configuration that |
| 97 |
should be added to or included by gmond.conf in your system is as |
| 98 |
follows: |
| 99 |
|
| 100 |
modules { |
| 101 |
module { |
| 102 |
name = "python_module" |
| 103 |
path = "modpython.so" |
| 104 |
params = "/usr/local/lib64/ganglia/python_modules" |
| 105 |
} |
| 106 |
} |
| 107 |
|
| 108 |
include ('/usr/local/etc/conf.d/*.pyconf') |
| 109 |
|
| 110 |
The most significant part of this configuration is the 'params' |
| 111 |
directive. The path that has been assigned to this directive will |
| 112 |
be passed down to the mod_python module and used to search for .py |
| 113 |
python modules. Any python module that is found in this location |
| 114 |
will be loaded and assumed to be a metric gathering module. If the |
| 115 |
collection groups that include metrics that are implemented in |
| 116 |
python, are put into separate configuration files and the file |
| 117 |
extension of the configuration files are .pyconf, they will |
| 118 |
automatically be loaded and read whenever the mod_python module |
| 119 |
is included. |
| 120 |
|
| 121 |
Configuring a Gmond python module |
| 122 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 123 |
|
| 124 |
The configuration of a Gmond python module is really no different |
| 125 |
than any other module. Most python modules will not require any |
| 126 |
specialized configuration at all. However, support has been |
| 127 |
provided to allow for parameters to be passed from the gmond.conf |
| 128 |
file to a python module. The syntax for passing parameters to |
| 129 |
a specific python module is at follows: |
| 130 |
|
| 131 |
modules { |
| 132 |
module { |
| 133 |
name = "example" |
| 134 |
language = "python" |
| 135 |
param YouNameIt { |
| 136 |
value = Whatever |
| 137 |
} |
| 138 |
param Another { |
| 139 |
value = NewValue |
| 140 |
} |
| 141 |
} |
| 142 |
} |
| 143 |
|
| 144 |
The "module" section must contain a "name" directive and a |
| 145 |
"language" directive. The value of the "name" directive must |
| 146 |
match the file name of the python module's .py file and the |
| 147 |
value of the "language" directive must be "python". The section |
| 148 |
can take multiple "param" sections. Each "param" section must |
| 149 |
include a name which will be the name of the value when it is |
| 150 |
passed to the python module, and a "value" directive. The |
| 151 |
"value" directive will always be passed as a string to the |
| 152 |
python module. It is up to the module itself to determine the |
| 153 |
actual value type. |
| 154 |
|