1COLLECTD-PYTHON(5) collectd COLLECTD-PYTHON(5)
2
6 collectd-python - Documentation of collectd's "python plugin"
7
9 <LoadPlugin python>
10 Globals true
11 </LoadPlugin>
12 # ...
13 <Plugin python>
14 ModulePath "/path/to/your/python/modules"
15 LogTraces true
16 Interactive true
17 Import "spam"
18 <Module spam>
20 spam "wonderful" "lovely"
21 </Module>
22 </Plugin>
23
25 The "python plugin" embeds a Python-interpreter into collectd and
26 provides an interface to collectd's plugin system. This makes it
27 possible to write plugins for collectd in Python. This is a lot more
28 efficient than executing a Python-script every time you want to read a
29 value with the "exec plugin" (see collectd-exec(5)) and provides a lot
30 more functionality, too.
31 Currently only Python 2 is supported and at least version 2.3 is
33 required.
34
36 LoadPlugin Plugin
37 Loads the Python plugin Plugin. Unlike most other LoadPlugin lines,
38 this one should be a block containing the line "Globals true". This
39 will cause collectd to export the name of all objects in the python
40 interpreter for all plugins to see. If you don't do this or your
41 platform does not support it, the embedded interpreter will start
42 anyway but you won't be able to load certain python modules, e.g.
43 "time".
44 Encoding Name
46 The default encoding for Unicode objects you pass to collectd. If
47 you omit this option it will default to ascii on Python 2 and utf-8
48 on Python 3. This is hardcoded in Python and will ignore
49 everything else, including your locale.
50 ModulePath Name
52 Appends Name to sys.path. You won't be able to import any scripts
53 you wrote unless they are located in one of the directories in this
54 list. Please note that it only has effect on plugins loaded after
55 this option. You can use multiple ModulePath lines to add more than
56 one directory.
57 LogTraces bool
59 If a python script throws an exception it will be logged by
60 collectd with the name of the exception and the message. If you set
61 this option to true it will also log the full stacktrace just like
62 the default output of an interactive python interpreter. This
63 should probably be set to false most of the time but is very useful
64 for development and debugging of new modules.
65 Interactive bool
67 This option will cause the module to launch an interactive python
68 interpreter that reads from and writes to the terminal. Note that
69 collectd will terminate right after starting up if you try to run
70 it as a daemon while this option is enabled to make sure to start
71 collectd with the -f option.
72 The collectd module is not imported into the interpreter's globals.
74 You have to do it manually. Be sure to read the help text of the
75 module, it can be used as a reference guide during coding.
76 This interactive session will behave slightly differently from a
78 daemonized collectd script as well as from a normal python
79 interpreter:
80 · 1. collectd will try to import the readline module to give you
82 a decent way of entering your commands. The daemonized collectd
83 won't do that.
84 · 2. collectd will block SIGINT. Pressing Ctrl+C will usually
86 cause collectd to shut down. This would be problematic in an
87 interactive session, therefore this signal will be blocked. You
88 can still use it to interrupt syscalls like sleep and pause but
89 it won't generate a KeyboardInterrupt exception either.
90 To quit collectd send EOF (press Ctrl+D at the beginning of a
92 new line).
93 · 3. collectd handles SIGCHLD. This means that python won't be
95 able to determine the return code of spawned processes with
96 system(), popen() and subprocess. This will result in python
97 not using external programs like less to display help texts.
98 You can override this behavior with the PAGER environment
99 variable, e.g. export PAGER=less before starting collectd.
100 Depending on your version of python this might or might not
101 result in an OSError exception which can be ignored.
102 <Module Name> block
104 This block may be used to pass on configuration settings to a
105 Python module. The configuration is converted into an instance of
106 the Config class which is passed to the registered configuration
107 callback. See below for details about the Config class and how to
108 register callbacks.
109 The name identifies the callback.
111
113 Writing your own plugins is quite simple. collectd manages plugins by
114 means of dispatch functions which call the appropriate callback
115 functions registered by the plugins. Any plugin basically consists of
116 the implementation of these callback functions and initializing code
117 which registers the functions with collectd. See the section "EXAMPLES"
118 below for a really basic example. The following types of callback
119 functions are known to collectd (all of them are optional):
120 configuration functions
122 This type of functions is called during configuration if an
123 appropriate Module block has been encountered. It is called once
124 for each Module block which matches the name of the callback as
125 provided with the register_config method - see below.
126 Python thread support has not been initialized at this point so do
128 not use any threading functions here!
129 init functions
131 This type of functions is called once after loading the module and
132 before any calls to the read and write functions. It should be used
133 to initialize the internal state of the plugin (e. g. open sockets,
134 ...). This is the earliest point where you may use threads.
135 read functions
137 This type of function is used to collect the actual data. It is
138 called once per interval (see the Interval configuration option of
139 collectd). Usually it will call plugin_dispatch_values to dispatch
140 the values to collectd which will pass them on to all registered
141 write functions. If this function throws any kind of exception the
142 plugin will be skipped for an increasing amount of time until it
143 returns normally again.
144 write functions
146 This type of function is used to write the dispatched values. It is
147 called once for every value that was dispatched by any plugin.
148 flush functions
150 This type of function is used to flush internal caches of plugins.
151 It is usually triggered by the user only. Any plugin which caches
152 data before writing it to disk should provide this kind of callback
153 function.
154 log functions
156 This type of function is used to pass messages of plugins or the
157 daemon itself to the user.
158 notification function
160 This type of function is used to act upon notifications. In
161 general, a notification is a status message that may be associated
162 with a data instance. Usually, a notification is generated by the
163 daemon if a configured threshold has been exceeded (see the section
164 "THRESHOLD CONFIGURATION" in collectd.conf(5) for more details),
165 but any plugin may dispatch notifications as well.
166 shutdown functions
168 This type of function is called once before the daemon shuts down.
169 It should be used to clean up the plugin (e.g. close sockets, ...).
170 Any function (except log functions) may set throw an exception in case
172 of any errors. The exception will be passed on to the user using
173 collectd's logging mechanism. If a log callback throws an exception it
174 will be printed to standard error instead.
175 See the documentation of the various register_ methods in the section
177 "FUNCTIONS" below for the number and types of arguments passed to each
178 callback function. This section also explains how to register callback
179 functions with collectd.
180 To enable a module, copy it to a place where Python can find it (i. e.
182 a directory listed in sys.path) just as any other Python plugin and add
183 an appropriate Import option to the configuration file. After
184 restarting collectd you're done.
185
187 The following complex types are used to pass values between the Python
188 plugin and collectd:
189 Config
191 The Config class is an object which keeps the information provided in
192 the configuration file. The sequence of children keeps one entry for
193 each configuration option. Each such entry is another Config instance,
194 which may nest further if nested blocks are used.
195 class Config(object)
197 This represents a piece of collectd's config file. It is passed to
199 scripts with config callbacks (see register_config) and is of little
200 use if created somewhere else.
201 It has no methods beyond the bare minimum and only exists for its data
203 members.
204 Data descriptors defined here:
206 parent
208 This represents the parent of this node. On the root node of the
209 config tree it will be None.
210 key This is the keyword of this item, i.e. the first word of any given
212 line in the config file. It will always be a string.
213 values
215 This is a tuple (which might be empty) of all value, i.e. words
216 following the keyword in any given line in the config file.
217 Every item in this tuple will be either a string or a float or a
219 boolean, depending on the contents of the configuration file.
220 children
222 This is a tuple of child nodes. For most nodes this will be empty.
223 If this node represents a block instead of a single line of the
224 config file it will contain all nodes in this block.
225 PluginData
227 This should not be used directly but it is the base class for both
228 Values and Notification. It is used to identify the source of a value
229 or notification.
230 class PluginData(object)
232 This is an internal class that is the base for Values and Notification.
234 It is pretty useless by itself and was therefore not exported to the
235 collectd module.
236 Data descriptors defined here:
238 host
240 The hostname of the host this value was read from. For dispatching
241 this can be set to an empty string which means the local hostname
242 as defined in collectd.conf.
243 plugin
245 The name of the plugin that read the data. Setting this member to
246 an empty string will insert "python" upon dispatching.
247 plugin_instance
249 Plugin instance string. May be empty.
250 time
252 This is the Unix timestamp of the time this value was read. For
253 dispatching values this can be set to zero which means "now". This
254 means the time the value is actually dispatched, not the time it
255 was set to 0.
256 type
258 The type of this value. This type has to be defined in your
259 types.db. Attempting to set it to any other value will raise a
260 TypeError exception. Assigning a type is mandatory, calling
261 dispatch without doing so will raise a RuntimeError exception.
262 type_instance
264 Type instance string. May be empty.
265 Values
267 A Value is an object which features a sequence of values. It is based
268 on then PluginData type and uses its members to identify the values.
269 class Values(PluginData)
271 A Values object used for dispatching values to collectd and receiving
273 values from write callbacks.
274 Method resolution order:
276 Values
278 PluginData
279 object
280 Methods defined here:
282 dispatch([type][, values][, plugin_instance][, type_instance][,
284 plugin][, host][, time][, interval]) -> None.
285 Dispatch this instance to the collectd process. The object has
286 members for each of the possible arguments for this method. For a
287 detailed explanation of these parameters see the member of the same
288 same.
289 If you do not submit a parameter the value saved in its member will
291 be submitted. If you do provide a parameter it will be used
292 instead, without altering the member.
293 write([destination][, type][, values][, plugin_instance][,
295 type_instance][, plugin][, host][, time][, interval]) -> None.
296 Write this instance to a single plugin or all plugins if
297 "destination" is omitted. This will bypass the main collectd
298 process and all filtering and caching. Other than that it works
299 similar to "dispatch". In most cases "dispatch" should be used
300 instead of "write".
301 Data descriptors defined here:
303 interval
305 The interval is the timespan in seconds between two submits for the
306 same data source. This value has to be a positive integer, so you
307 can't submit more than one value per second. If this member is set
308 to a non-positive value, the default value as specified in the
309 config file will be used (default: 10).
310 If you submit values more often than the specified interval, the
312 average will be used. If you submit less values, your graphs will
313 have gaps.
314 values
316 These are the actual values that get dispatched to collectd. It has
317 to be a sequence (a tuple or list) of numbers. The size of the
318 sequence and the type of its content depend on the type member your
319 types.db file. For more information on this read the types.db(5)
320 manual page.
321 If the sequence does not have the correct size upon dispatch a
323 RuntimeError exception will be raised. If the content of the
324 sequence is not a number, a TypeError exception will be raised.
325 Notification
327 A notification is an object defining the severity and message of the
328 status message as well as an identification of a data instance by means
329 of the members of PluginData on which it is based.
330 class Notification(PluginData) The Notification class is a wrapper
332 around the collectd notification. It can be used to notify other
333 plugins about bad stuff happening. It works similar to Values but has a
334 severity and a message instead of interval and time. Notifications can
335 be dispatched at any time and can be received with
336 register_notification.
337 Method resolution order:
339 Notification
341 PluginData
342 object
343 Methods defined here:
345 dispatch([type][, values][, plugin_instance][, type_instance][,
347 plugin][, host][, time][, interval]) -> None. Dispatch a value list.
348 Dispatch this instance to the collectd process. The object has
349 members for each of the possible arguments for this method. For a
350 detailed explanation of these parameters see the member of the same
351 same.
352 If you do not submit a parameter the value saved in its member will
354 be submitted. If you do provide a parameter it will be used
355 instead, without altering the member.
356 Data descriptors defined here:
358 message
360 Some kind of description what's going on and why this Notification
361 was generated.
362 severity
364 The severity of this notification. Assign or compare to
365 NOTIF_FAILURE, NOTIF_WARNING or NOTIF_OKAY.
366
368 The following functions provide the C-interface to Python-modules.
369 register_*(callback[, data][, name]) -> identifier
371 There are eight different register functions to get callback for
372 eight different events. With one exception all of them are called
373 as shown above.
374 · callback is a callable object that will be called every time
376 the event is triggered.
377 · data is an optional object that will be passed back to the
379 callback function every time it is called. If you omit this
380 parameter no object is passed back to your callback, not even
381 None.
382 · name is an optional identifier for this callback. The default
384 name is python.module. module is taken from the __module__
385 attribute of your callback function. Every callback needs a
386 unique identifier, so if you want to register the same callback
387 multiple time in the same module you need to specify a name
388 here. Otherwise it's save to ignore this parameter identifier
389 is the full identifier assigned to this callback.
390 These functions are called in the various stages of the daemon (see
392 the section "WRITING YOUR OWN PLUGINS" above) and are passed the
393 following arguments:
394 register_config
396 The only argument passed is a Config object. See above for the
397 layout of this data type. Note that you can not receive the
398 whole config files this way, only Module blocks inside the
399 Python configuration block. Additionally you will only receive
400 blocks where your callback identifier matches python.blockname.
401 register_init
403 The callback will be called without arguments.
404 register_read(callback[, interval][, data][, name]) -> identifier
406 This function takes an additional parameter: interval. It
407 specifies the time between calls to the callback function.
408 The callback will be called without arguments.
410 register_shutdown
412 The callback will be called without arguments.
413 register_write
415 The callback function will be called with one arguments passed,
416 which will be a Values object. For the layout of Values see
417 above. If this callback function throws an exception the next
418 call will be delayed by an increasing interval.
419 register_flush
421 Like register_config is important for this callback because it
422 determines what flush requests the plugin will receive.
423 The arguments passed are timeout and identifier. timeout
425 indicates that only data older than timeout seconds is to be
426 flushed. identifier specifies which values are to be flushed.
427 register_log
429 The arguments are severity and message. The severity is an
430 integer and small for important messages and high for less
431 important messages. The least important level is LOG_DEBUG, the
432 most important level is LOG_ERR. In between there are (from
433 least to most important): LOG_INFO, LOG_NOTICE, and
434 LOG_WARNING. message is simply a string without a newline at
435 the end.
436 If this callback throws an exception it will not be logged. It
438 will just be printed to sys.stderr which usually means silently
439 ignored.
440 register_notification
442 The only argument passed is a Notification object. See above
443 for the layout of this data type.
444 unregister_*(identifier) -> None
446 Removes a callback or data-set from collectd's internal list of
447 callback functions. Every register_* function has an unregister_*
448 function. identifier is either the string that was returned by the
449 register function or a callback function. The identifier will be
450 constructed in the same way as for the register functions.
451 flush(plugin[, timeout][, identifier]) - None
453 Flush one or all plugins. timeout and the specified identifiers are
454 passed on to the registered flush-callbacks. If omitted, the
455 timeout defaults to "-1". The identifier defaults to None. If the
456 plugin argument has been specified, only named plugin will be
457 flushed.
458 error, warning, notice, info, debug(message)
460 Log a message with the specified severity.
461
463 Any Python module will start similar to:
464 import collectd
466 A very simple read function might look like:
468 def read(data=None):
470 vl = collectd.Values(type='gauge')
471 vl.plugin='python.spam'
472 vl.dispatch(values=[random.random() * 100])
473 A very simple write function might look like:
475 def write(vl, data=None):
477 for i in vl.values:
478 print "%s (%s): %f" % (vl.plugin, vl.type, i)
479 To register those functions with collectd:
481 collectd.register_read(read);
483 collectd.register_write(write);
484 See the section "CLASSES" above for a complete documentation of the
486 data types used by the read, write and match functions.
487
489 · Please feel free to send in new plugins to collectd's mailinglist
490 at <collectd at verplant.org> for review and, possibly, inclusion
491 in the main distribution. In the latter case, we will take care of
492 keeping the plugin up to date and adapting it to new versions of
493 collectd.
494 Before submitting your plugin, please take a look at
496 <http://collectd.org/dev-info.shtml>.
497
499 · collectd is heavily multi-threaded. Each collectd thread accessing
500 the python plugin will be mapped to a Python interpreter thread.
501 Any such thread will be created and destroyed transparently and on-
502 the-fly.
503 Hence, any plugin has to be thread-safe if it provides several
505 entry points from collectd (i. e. if it registers more than one
506 callback or if a registered callback may be called more than once
507 in parallel).
508 · The Python thread module is initialized just before calling the
510 init callbacks. This means you must not use Python's threading
511 module prior to this point. This includes all config and possibly
512 other callback as well.
513 · The python plugin exports the internal API of collectd which is
515 considered unstable and subject to change at any time. We try hard
516 to not break backwards compatibility in the Python API during the
517 life cycle of one major release. However, this cannot be
518 guaranteed at all times. Watch out for warnings dispatched by the
519 python plugin after upgrades.
520
522 · This plugin is not compatible with python3. Trying to compile it
523 with python3 will fail because of the ways string, unicode and
524 bytearray behavior was changed.
525 · Not all aspects of the collectd API are accessible from python.
527 This includes but is not limited to meta-data, filters and data
528 sets.
529
531 collectd(1), collectd.conf(5), collectd-perl(5), collectd-exec(5),
532 types.db(5), python(1),
533
535 The "python plugin" has been written by Sven Trenkel
536 <collectd at semidefinite.de>.
537 This manpage has been written by Sven Trenkel
539 <collectd at semidefinite.de>. It is based on the collectd-perl(5)
540 manual page by Florian Forster <octo at verplant.org> and Sebastian
541 Harl <sh at tokkee.org>.
5424.9.5 2011-03-26 COLLECTD-PYTHON(5)