Debian Codegraph @

gmond/modules/python/README

raw
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