1COLLECTD-PYTHON(5) collectd COLLECTD-PYTHON(5)
2
6 collectd-python - Documentation of collectd's "python plugin"
7
9 LoadPlugin python
10 # ...
11 <Plugin python>
12 ModulePath "/path/to/your/python/modules"
13 LogTraces true
14 Interactive false
15 Import "spam"
16 <Module spam>
18 spam "wonderful" "lovely"
19 </Module>
20 </Plugin>
21
23 The "python plugin" embeds a Python-interpreter into collectd and
24 provides an interface to collectd's plugin system. This makes it
25 possible to write plugins for collectd in Python. This is a lot more
26 efficient than executing a Python-script every time you want to read a
27 value with the "exec plugin" (see collectd-exec(5)) and provides a lot
28 more functionality, too.
29 The minimum required Python version is 2.6.
31
33 LoadPlugin Plugin
34 Loads the Python plugin Plugin.
35 Encoding Name
37 The default encoding for Unicode objects you pass to collectd. If
38 you omit this option it will default to ascii on Python 2. On
39 Python 3 it will always be utf-8, as this function was removed, so
40 this will be silently ignored. These defaults are hardcoded in
41 Python and will ignore everything else, including your locale.
42 ModulePath Name
44 Prepends Name to sys.path. You won't be able to import any scripts
45 you wrote unless they are located in one of the directories in this
46 list. Please note that it only has effect on plugins loaded after
47 this option. You can use multiple ModulePath lines to add more than
48 one directory.
49 LogTraces bool
51 If a Python script throws an exception it will be logged by
52 collectd with the name of the exception and the message. If you set
53 this option to true it will also log the full stacktrace just like
54 the default output of an interactive Python interpreter. This does
55 not apply to the CollectError exception, which will never log a
56 stacktrace. This should probably be set to false most of the time
57 but is very useful for development and debugging of new modules.
58 Interactive bool
60 This option will cause the module to launch an interactive Python
61 interpreter that reads from and writes to the terminal. Note that
62 collectd will terminate right after starting up if you try to run
63 it as a daemon while this option is enabled so make sure to start
64 collectd with the -f option.
65 The collectd module is not imported into the interpreter's globals.
67 You have to do it manually. Be sure to read the help text of the
68 module, it can be used as a reference guide during coding.
69 This interactive session will behave slightly differently from a
71 daemonized collectd script as well as from a normal Python
72 interpreter:
73 · 1. collectd will try to import the readline module to give you
75 a decent way of entering your commands. The daemonized collectd
76 won't do that.
77 · 2. Python will be handling SIGINT. Pressing Ctrl+C will usually
79 cause collectd to shut down. This would be problematic in an
80 interactive session, therefore Python will be handling it in
81 interactive sessions. This allows you to use Ctrl+C to
82 interrupt Python code without killing collectd. This also means
83 you can catch KeyboardInterrupt exceptions which does not work
84 during normal operation.
85 To quit collectd send EOF (press Ctrl+D at the beginning of a
87 new line).
88 · 3. collectd handles SIGCHLD. This means that Python won't be
90 able to determine the return code of spawned processes with
91 system(), popen() and subprocess. This will result in Python
92 not using external programs like less to display help texts.
93 You can override this behavior with the PAGER environment
94 variable, e.g. export PAGER=less before starting collectd.
95 Depending on your version of Python this might or might not
96 result in an OSError exception which can be ignored.
97 If you really need to spawn new processes from Python you can
99 register an init callback and reset the action for SIGCHLD to
100 the default behavior. Please note that this will break the exec
101 plugin. Do not even load the exec plugin if you intend to do
102 this!
103 There is an example script located in
105 contrib/python/getsigchld.py to do this. If you import this
106 from collectd.conf SIGCHLD will be handled normally and
107 spawning processes from Python will work as intended.
108 <Module Name> block
110 This block may be used to pass on configuration settings to a
111 Python module. The configuration is converted into an instance of
112 the Config class which is passed to the registered configuration
113 callback. See below for details about the Config class and how to
114 register callbacks.
115 The name identifies the callback.
117
119 There are a lot of places where strings are sent from collectd to
120 Python and from Python to collectd. How exactly this works depends on
121 whether byte or unicode strings or Python2 or Python3 are used.
122 Python2 has str, which is just bytes, and unicode. Python3 has str,
124 which is a unicode object, and bytes.
125 When passing strings from Python to collectd all of these object are
127 supported in all places, however str should be used if possible. These
128 strings must not contain a NUL byte. Ignoring this will result in a
129 TypeError exception. If a byte string was used it will be used as is
130 by collectd. If a unicode object was used it will be encoded using the
131 default encoding (see above). If this is not possible Python will raise
132 a UnicodeEncodeError exception.
133 When passing strings from collectd to Python the behavior depends on
135 the Python version used. Python2 will always receive a str object.
136 Python3 will usually receive a str object as well, however the original
137 string will be decoded to unicode using the default encoding. If this
138 fails because the string is not a valid sequence for this encoding a
139 bytes object will be returned instead.
140
142 Writing your own plugins is quite simple. collectd manages plugins by
143 means of dispatch functions which call the appropriate callback
144 functions registered by the plugins. Any plugin basically consists of
145 the implementation of these callback functions and initializing code
146 which registers the functions with collectd. See the section "EXAMPLES"
147 below for a really basic example. The following types of callback
148 functions are known to collectd (all of them are optional):
149 configuration functions
151 These are called during configuration if an appropriate Module
152 block has been encountered. It is called once for each Module block
153 which matches the name of the callback as provided with the
154 register_config method - see below.
155 Python thread support has not been initialized at this point so do
157 not use any threading functions here!
158 init functions
160 These are called once after loading the module and before any calls
161 to the read and write functions. It should be used to initialize
162 the internal state of the plugin (e. g. open sockets, ...). This is
163 the earliest point where you may use threads.
164 read functions
166 These are used to collect the actual data. It is called once per
167 interval (see the Interval configuration option of collectd).
168 Usually it will call plugin_dispatch_values to dispatch the values
169 to collectd which will pass them on to all registered write
170 functions. If this function throws any kind of exception the plugin
171 will be skipped for an increasing amount of time until it returns
172 normally again.
173 write functions
175 These are used to write the dispatched values. It is called once
176 for every value that was dispatched by any plugin.
177 flush functions
179 These are used to flush internal caches of plugins. It is usually
180 triggered by the user only. Any plugin which caches data before
181 writing it to disk should provide this kind of callback function.
182 log functions
184 These are used to pass messages of plugins or the daemon itself to
185 the user.
186 notification function
188 These are used to act upon notifications. In general, a
189 notification is a status message that may be associated with a data
190 instance. Usually, a notification is generated by the daemon if a
191 configured threshold has been exceeded (see the section "THRESHOLD
192 CONFIGURATION" in collectd.conf(5) for more details), but any
193 plugin may dispatch notifications as well.
194 shutdown functions
196 These are called once before the daemon shuts down. It should be
197 used to clean up the plugin (e.g. close sockets, ...).
198 Any function (except log functions) may throw an exception in case of
200 errors. The exception will be passed on to the user using collectd's
201 logging mechanism. If a log callback throws an exception it will be
202 printed to standard error instead.
203 See the documentation of the various register_ methods in the section
205 "FUNCTIONS" below for the number and types of arguments passed to each
206 callback function. This section also explains how to register callback
207 functions with collectd.
208 To enable a module, copy it to a place where Python can find it (i. e.
210 a directory listed in sys.path) just as any other Python plugin and add
211 an appropriate Import option to the configuration file. After
212 restarting collectd you're done.
213
215 The following complex types are used to pass values between the Python
216 plugin and collectd:
217 CollectdError
219 This is an exception. If any Python script raises this exception it
220 will still be treated like an error by collectd but it will be logged
221 as a warning instead of an error and it will never generate a
222 stacktrace.
223 class CollectdError(Exception)
225 Basic exception for collectd Python scripts. Throwing this exception
227 will not cause a stacktrace to be logged, even if LogTraces is enabled
228 in the config.
229 Signed
231 The Signed class is just a long. It has all its methods and behaves
232 exactly like any other long object. It is used to indicate if an
233 integer was or should be stored as a signed or unsigned integer object.
234 class Signed(long)
236 This is a long by another name. Use it in meta data dicts to choose the
238 way it is stored in the meta data.
239 Unsigned
241 The Unsigned class is just a long. It has all its methods and behaves
242 exactly like any other long object. It is used to indicate if an
243 integer was or should be stored as a signed or unsigned integer object.
244 class Unsigned(long)
246 This is a long by another name. Use it in meta data dicts to choose the
248 way it is stored in the meta data.
249 Config
251 The Config class is an object which keeps the information provided in
252 the configuration file. The sequence of children keeps one entry for
253 each configuration option. Each such entry is another Config instance,
254 which may nest further if nested blocks are used.
255 class Config(object)
257 This represents a piece of collectd's config file. It is passed to
259 scripts with config callbacks (see register_config) and is of little
260 use if created somewhere else.
261 It has no methods beyond the bare minimum and only exists for its data
263 members.
264 Data descriptors defined here:
266 parent
268 This represents the parent of this node. On the root node of the
269 config tree it will be None.
270 key This is the keyword of this item, i.e. the first word of any given
272 line in the config file. It will always be a string.
273 values
275 This is a tuple (which might be empty) of all value, i.e. words
276 following the keyword in any given line in the config file.
277 Every item in this tuple will be either a string, a float or a
279 boolean, depending on the contents of the configuration file.
280 children
282 This is a tuple of child nodes. For most nodes this will be empty.
283 If this node represents a block instead of a single line of the
284 config file it will contain all nodes in this block.
285 PluginData
287 This should not be used directly but it is the base class for both
288 Values and Notification. It is used to identify the source of a value
289 or notification.
290 class PluginData(object)
292 This is an internal class that is the base for Values and Notification.
294 It is pretty useless by itself and was therefore not exported to the
295 collectd module.
296 Data descriptors defined here:
298 host
300 The hostname of the host this value was read from. For dispatching
301 this can be set to an empty string which means the local hostname
302 as defined in collectd.conf.
303 plugin
305 The name of the plugin that read the data. Setting this member to
306 an empty string will insert "python" upon dispatching.
307 plugin_instance
309 Plugin instance string. May be empty.
310 time
312 This is the Unix timestamp of the time this value was read. For
313 dispatching values this can be set to zero which means "now". This
314 means the time the value is actually dispatched, not the time it
315 was set to 0.
316 type
318 The type of this value. This type has to be defined in your
319 types.db. Attempting to set it to any other value will raise a
320 TypeError exception. Assigning a type is mandatory, calling
321 dispatch without doing so will raise a RuntimeError exception.
322 type_instance
324 Type instance string. May be empty.
325 Values
327 A Value is an object which features a sequence of values. It is based
328 on the PluginData type and uses its members to identify the values.
329 class Values(PluginData)
331 A Values object used for dispatching values to collectd and receiving
333 values from write callbacks.
334 Method resolution order:
336 Values
338 PluginData
339 object
340 Methods defined here:
342 dispatch([type][, values][, plugin_instance][, type_instance][,
344 plugin][, host][, time][, interval]) -> None.
345 Dispatch this instance to the collectd process. The object has
346 members for each of the possible arguments for this method. For a
347 detailed explanation of these parameters see the member of the same
348 same.
349 If you do not submit a parameter the value saved in its member will
351 be submitted. If you do provide a parameter it will be used
352 instead, without altering the member.
353 write([destination][, type][, values][, plugin_instance][,
355 type_instance][, plugin][, host][, time][, interval]) -> None.
356 Write this instance to a single plugin or all plugins if
357 "destination" is omitted. This will bypass the main collectd
358 process and all filtering and caching. Other than that it works
359 similar to "dispatch". In most cases "dispatch" should be used
360 instead of "write".
361 Data descriptors defined here:
363 interval
365 The interval is the timespan in seconds between two submits for the
366 same data source. This value has to be a positive integer, so you
367 can't submit more than one value per second. If this member is set
368 to a non-positive value, the default value as specified in the
369 config file will be used (default: 10).
370 If you submit values more often than the specified interval, the
372 average will be used. If you submit less values, your graphs will
373 have gaps.
374 values
376 These are the actual values that get dispatched to collectd. It has
377 to be a sequence (a tuple or list) of numbers. The size of the
378 sequence and the type of its content depend on the type member your
379 types.db file. For more information on this read the types.db(5)
380 manual page.
381 If the sequence does not have the correct size upon dispatch a
383 RuntimeError exception will be raised. If the content of the
384 sequence is not a number, a TypeError exception will be raised.
385 meta
387 These are the meta data for this Value object. It has to be a
388 dictionary of numbers, strings or bools. All keys must be strings.
389 int and <long> objects will be dispatched as signed integers unless
390 they are between 2**63 and 2**64-1, which will result in a unsigned
391 integer. You can force one of these storage classes by using the
392 classes collectd.Signed and collectd.Unsigned. A meta object
393 received by a write callback will always contain Signed or Unsigned
394 objects.
395 Notification
397 A notification is an object defining the severity and message of the
398 status message as well as an identification of a data instance by means
399 of the members of PluginData on which it is based.
400 class Notification(PluginData) The Notification class is a wrapper
402 around the collectd notification. It can be used to notify other
403 plugins about bad stuff happening. It works similar to Values but has a
404 severity and a message instead of interval and time. Notifications can
405 be dispatched at any time and can be received with
406 register_notification.
407 Method resolution order:
409 Notification
411 PluginData
412 object
413 Methods defined here:
415 dispatch([type][, message][, plugin_instance][, type_instance][,
417 plugin][, host][, time][, severity][, meta]) -> None. Dispatch a
418 notification.
419 Dispatch this instance to the collectd process. The object has
420 members for each of the possible arguments for this method. For a
421 detailed explanation of these parameters see the member of the same
422 same.
423 If you do not submit a parameter the value saved in its member will
425 be submitted. If you do provide a parameter it will be used
426 instead, without altering the member.
427 Data descriptors defined here:
429 message
431 Some kind of description of what's going on and why this
432 Notification was generated.
433 severity
435 The severity of this notification. Assign or compare to
436 NOTIF_FAILURE, NOTIF_WARNING or NOTIF_OKAY.
437 meta
439 These are the meta data for the Notification object. It has to be
440 a dictionary of numbers, strings or bools. All keys must be
441 strings. int and long objects will be dispatched as signed integers
442 unless they are between 2**63 and 2**64-1, which will result in a
443 unsigned integer. One of these storage classes can be forced by
444 using the classes collectd.Signed and collectd.Unsigned. A meta
445 object received by a notification callback will always contain
446 Signed or Unsigned objects.
447
449 The following functions provide the C-interface to Python-modules.
450 register_*(callback[, data][, name]) -> identifier
452 There are eight different register functions to get callback for
453 eight different events. With one exception all of them are called
454 as shown above.
455 · callback is a callable object that will be called every time
457 the event is triggered.
458 · data is an optional object that will be passed back to the
460 callback function every time it is called. If you omit this
461 parameter no object is passed back to your callback, not even
462 None.
463 · name is an optional identifier for this callback. The default
465 name is python.module. module is taken from the __module__
466 attribute of your callback function. Every callback needs a
467 unique identifier, so if you want to register the same callback
468 multiple times in the same module you need to specify a name
469 here. Otherwise it's safe to ignore this parameter.
470 · identifier is the full identifier assigned to this callback.
472 These functions are called in the various stages of the daemon (see
474 the section "WRITING YOUR OWN PLUGINS" above) and are passed the
475 following arguments:
476 register_config
478 The only argument passed is a Config object. See above for the
479 layout of this data type. Note that you cannot receive the
480 whole config files this way, only Module blocks inside the
481 Python configuration block. Additionally you will only receive
482 blocks where your callback identifier matches python.blockname.
483 register_init
485 The callback will be called without arguments.
486 register_read(callback[, interval][, data][, name]) -> identifier
488 This function takes an additional parameter: interval. It
489 specifies the time between calls to the callback function.
490 The callback will be called without arguments.
492 register_shutdown
494 The callback will be called without arguments.
495 register_write
497 The callback function will be called with one argument passed,
498 which will be a Values object. For the layout of Values see
499 above. If this callback function throws an exception the next
500 call will be delayed by an increasing interval.
501 register_flush
503 Like register_config is important for this callback because it
504 determines what flush requests the plugin will receive.
505 The arguments passed are timeout and identifier. timeout
507 indicates that only data older than timeout seconds is to be
508 flushed. identifier specifies which values are to be flushed.
509 register_log
511 The arguments are severity and message. The severity is an
512 integer and small for important messages and high for less
513 important messages. The least important level is LOG_DEBUG, the
514 most important level is LOG_ERR. In between there are (from
515 least to most important): LOG_INFO, LOG_NOTICE, and
516 LOG_WARNING. message is simply a string without a newline at
517 the end.
518 If this callback throws an exception it will not be logged. It
520 will just be printed to sys.stderr which usually means silently
521 ignored.
522 register_notification
524 The only argument passed is a Notification object. See above
525 for the layout of this data type.
526 unregister_*(identifier) -> None
528 Removes a callback or data-set from collectd's internal list of
529 callback functions. Every register_* function has an unregister_*
530 function. identifier is either the string that was returned by the
531 register function or a callback function. The identifier will be
532 constructed in the same way as for the register functions.
533 get_dataset(name) -> definition
535 Returns the definition of a dataset specified by name. definition
536 is a list of tuples, each representing one data source. Each tuple
537 has 4 values:
538 name
540 A string, the name of the data source.
541 type
543 A string that is equal to either of the variables
544 DS_TYPE_COUNTER, DS_TYPE_GAUGE, DS_TYPE_DERIVE or
545 DS_TYPE_ABSOLUTE.
546 min A float or None, the minimum value.
548 max A float or None, the maximum value.
550 flush(plugin[, timeout][, identifier]) - None
552 Flush one or all plugins. timeout and the specified identifiers are
553 passed on to the registered flush-callbacks. If omitted, the
554 timeout defaults to "-1". The identifier defaults to None. If the
555 plugin argument has been specified, only named plugin will be
556 flushed.
557 error, warning, notice, info, debug(message)
559 Log a message with the specified severity.
560
562 Any Python module will start similar to:
563 import collectd
565 A very simple read function might look like:
567 import random
569 def read(data=None):
571 vl = collectd.Values(type='gauge')
572 vl.plugin='python.spam'
573 vl.dispatch(values=[random.random() * 100])
574 A very simple write function might look like:
576 def write(vl, data=None):
578 for i in vl.values:
579 print "%s (%s): %f" % (vl.plugin, vl.type, i)
580 To register those functions with collectd:
582 collectd.register_read(read)
584 collectd.register_write(write)
585 See the section "CLASSES" above for a complete documentation of the
587 data types used by the read, write and match functions.
588
590 · collectd is heavily multi-threaded. Each collectd thread accessing
591 the Python plugin will be mapped to a Python interpreter thread.
592 Any such thread will be created and destroyed transparently and on-
593 the-fly.
594 Hence, any plugin has to be thread-safe if it provides several
596 entry points from collectd (i. e. if it registers more than one
597 callback or if a registered callback may be called more than once
598 in parallel).
599 · The Python thread module is initialized just before calling the
601 init callbacks. This means you must not use Python's threading
602 module prior to this point. This includes all config and possibly
603 other callback as well.
604 · The python plugin exports the internal API of collectd which is
606 considered unstable and subject to change at any time. We try hard
607 to not break backwards compatibility in the Python API during the
608 life cycle of one major release. However, this cannot be
609 guaranteed at all times. Watch out for warnings dispatched by the
610 python plugin after upgrades.
611
613 · Not all aspects of the collectd API are accessible from Python.
614 This includes but is not limited to filters.
615
617 collectd(1), collectd.conf(5), collectd-perl(5), collectd-exec(5),
618 types.db(5), python(1),
619
621 The "python plugin" has been written by Sven Trenkel
622 <collectd at semidefinite.de>.
623 This manpage has been written by Sven Trenkel
625 <collectd at semidefinite.de>. It is based on the collectd-perl(5)
626 manual page by Florian Forster <octo at collectd.org> and Sebastian
627 Harl <sh at tokkee.org>.
6285.8.0.145.gca1cb27 2018-10-23 COLLECTD-PYTHON(5)