README
1How To Write And Use A Python Metric
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4One of the new features in Gmond is the ability to develop
5and install new metrics as dynamically loadable modules. This
6has enabled Gmond to be extended in new ways. One of these
7ways is embeded python. By loading and using the new
8mod_python DSO, gmond now has the ability to load and call new
9metric modules that have been developed using the python
10scripting language. The following sections will describe
11how to develop and deploy new metric modules using python.
12
13
14Writing a python metric module
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17There are two functions that must be included in every python
18based metric module as well as at least one callback handler.
19These functions are:
20
21def 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
61def 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
66Other than the mandatory functions and metric description list as
67specified above, the metric module is free to do whatever it needs
68in order to appropriately gather the intended metric data. Each
69metric description dictionary can also contain additional user
70defined elements outside of the mandatory elements listed above. Any
71additional elements in the dictionary will be ignored by mod_python
72but can to used by the python module itself to hold additional
73data that should correspond to the metric.
74
75Deploying a python metric module
76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78Once a python metric module has been developed, deploying the module
79is as easy as copying a file to a specific directory. In the configuration
80of the mod_python module that is part of gmond.conf, a python metric module
81directory must have been specified (see next section). To deploy a
82python module, simply copy the .py file to the specified python module
83directory. 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
85gmond is capable of gathering. The list should include the name of the
86python module that was just deployed. Add this metric to a collection
87group, just like any other gmond metric.
88
89Configuring Gmond for python support
90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92Configuring Gmond to support python based modules is as easy as loading
93any other type of gmond dynamically loadable metric module. The name of
94the python support module is modpython.so. A base configuration file
95is included in the Ganglia source code and should have been installed
96automatically if done through an RPM. The basic configuration that
97should be added to or included by gmond.conf in your system is as
98follows:
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
110The most significant part of this configuration is the 'params'
111directive. The path that has been assigned to this directive will
112be passed down to the mod_python module and used to search for .py
113python modules. Any python module that is found in this location
114will be loaded and assumed to be a metric gathering module. If the
115collection groups that include metrics that are implemented in
116python, are put into separate configuration files and the file
117extension of the configuration files are .pyconf, they will
118automatically be loaded and read whenever the mod_python module
119is included.
120
121Configuring a Gmond python module
122~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123
124The configuration of a Gmond python module is really no different
125than any other module. Most python modules will not require any
126specialized configuration at all. However, support has been
127provided to allow for parameters to be passed from the gmond.conf
128file to a python module. The syntax for passing parameters to
129a specific python module is at follows:
130
131modules {
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
144The "module" section must contain a "name" directive and a
145"language" directive. The value of the "name" directive must
146match the file name of the python module's .py file and the
147value of the "language" directive must be "python". The section
148can take multiple "param" sections. Each "param" section must
149include a name which will be the name of the value when it is
150passed to the python module, and a "value" directive. The
151"value" directive will always be passed as a string to the
152python module. It is up to the module itself to determine the
153actual value type.
154
155
README.in
1How To Write And Use A Python Metric
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4One of the new features in Gmond is the ability to develop
5and install new metrics as dynamically loadable modules. This
6has enabled Gmond to be extended in new ways. One of these
7ways is embeded python. By loading and using the new
8mod_python DSO, gmond now has the ability to load and call new
9metric modules that have been developed using the python
10scripting language. The following sections will describe
11how to develop and deploy new metric modules using python.
12
13
14Writing a python metric module
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17There are two functions that must be included in every python
18based metric module as well as at least one callback handler.
19These functions are:
20
21def 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
61def 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
66Other than the mandatory functions and metric description list as
67specified above, the metric module is free to do whatever it needs
68in order to appropriately gather the intended metric data. Each
69metric description dictionary can also contain additional user
70defined elements outside of the mandatory elements listed above. Any
71additional elements in the dictionary will be ignored by mod_python
72but can to used by the python module itself to hold additional
73data that should correspond to the metric.
74
75Deploying a python metric module
76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78Once a python metric module has been developed, deploying the module
79is as easy as copying a file to a specific directory. In the configuration
80of the mod_python module that is part of gmond.conf, a python metric module
81directory must have been specified (see next section). To deploy a
82python module, simply copy the .py file to the specified python module
83directory. 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
85gmond is capable of gathering. The list should include the name of the
86python module that was just deployed. Add this metric to a collection
87group, just like any other gmond metric.
88
89Configuring Gmond for python support
90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92Configuring Gmond to support python based modules is as easy as loading
93any other type of gmond dynamically loadable metric module. The name of
94the python support module is modpython.so. A base configuration file
95is included in the Ganglia source code and should have been installed
96automatically if done through an RPM. The basic configuration that
97should be added to or included by gmond.conf in your system is as
98follows:
99
100 modules {
101 module {
102 name = "python_module"
103 path = "modpython.so"
104 params = "@moduledir@/python_modules"
105 }
106 }
107
108 include ('@sysconfdir@/conf.d/*.pyconf')
109
110The most significant part of this configuration is the 'params'
111directive. The path that has been assigned to this directive will
112be passed down to the mod_python module and used to search for .py
113python modules. Any python module that is found in this location
114will be loaded and assumed to be a metric gathering module. If the
115collection groups that include metrics that are implemented in
116python, are put into separate configuration files and the file
117extension of the configuration files are .pyconf, they will
118automatically be loaded and read whenever the mod_python module
119is included.
120
121Configuring a Gmond python module
122~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123
124The configuration of a Gmond python module is really no different
125than any other module. Most python modules will not require any
126specialized configuration at all. However, support has been
127provided to allow for parameters to be passed from the gmond.conf
128file to a python module. The syntax for passing parameters to
129a specific python module is at follows:
130
131modules {
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
144The "module" section must contain a "name" directive and a
145"language" directive. The value of the "name" directive must
146match the file name of the python module's .py file and the
147value of the "language" directive must be "python". The section
148can take multiple "param" sections. Each "param" section must
149include a name which will be the name of the value when it is
150passed to the python module, and a "value" directive. The
151"value" directive will always be passed as a string to the
152python module. It is up to the module itself to determine the
153actual value type.
154
155