![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 071ef4549f17461d3fedd08ba048ff0258fed8d7..426a7118c99b8346d38e1d659ff2f4142090c594 100644 (file)
--- a/src/collectd-python.pod
+++ b/src/collectd-python.pod
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
+=encoding UTF-8
+
=head1 NAME
collectd-python - Documentation of collectd's C<python plugin>
Python-script every time you want to read a value with the C<exec plugin> (see
L<collectd-exec(5)>) and provides a lot more functionality, too.
-At least Python I<version 2.3> is required.
+The minimum required Python version is I<2.3>.
=head1 CONFIGURATION
This option will cause the module to launch an interactive Python interpreter
that reads from and writes to the terminal. Note that collectd will terminate
right after starting up if you try to run it as a daemon while this option is
-enabled to make sure to start collectd with the B<-f> option.
+enabled so make sure to start collectd with the B<-f> option.
The B<collectd> module is I<not> imported into the interpreter's globals. You
have to do it manually. Be sure to read the help text of the module, it can be
=head1 STRINGS
-There are a lot of places where strings are send from collectd to Python and
-from Python to collectd. How exactly this works depends on wheather byte or
+There are a lot of places where strings are sent from collectd to Python and
+from Python to collectd. How exactly this works depends on whether byte or
unicode strings or Python2 or Python3 are used.
Python2 has I<str>, which is just bytes, and I<unicode>. Python3 has I<str>,
object was used it will be encoded using the default encoding (see above). If
this is not possible Python will raise a I<UnicodeEncodeError> exception.
-Wenn passing strings from collectd to Python the behavior depends on the
+When passing strings from collectd to Python the behavior depends on the
Python version used. Python2 will always receive a I<str> object. Python3 will
usually receive a I<str> object as well, however the original string will be
decoded to unicode using the default encoding. If this fails because the
=item configuration functions
-This type of functions is called during configuration if an appropriate
+These are called during configuration if an appropriate
B<Module> block has been encountered. It is called once for each B<Module>
block which matches the name of the callback as provided with the
B<register_config> method - see below.
=item init functions
-This type of functions is called once after loading the module and before any
+These are called once after loading the module and before any
calls to the read and write functions. It should be used to initialize the
internal state of the plugin (e.E<nbsp>g. open sockets, ...). This is the
earliest point where you may use threads.
=item read functions
-This type of function is used to collect the actual data. It is called once
+These are used to collect the actual data. It is called once
per interval (see the B<Interval> configuration option of collectd). Usually
it will call B<plugin_dispatch_values> to dispatch the values to collectd
which will pass them on to all registered B<write functions>. If this function
=item write functions
-This type of function is used to write the dispatched values. It is called
+These are used to write the dispatched values. It is called
once for every value that was dispatched by any plugin.
=item flush functions
-This type of function is used to flush internal caches of plugins. It is
+These are used to flush internal caches of plugins. It is
usually triggered by the user only. Any plugin which caches data before
writing it to disk should provide this kind of callback function.
=item log functions
-This type of function is used to pass messages of plugins or the daemon itself
+These are used to pass messages of plugins or the daemon itself
to the user.
=item notification function
-This type of function is used to act upon notifications. In general, a
+These are used to act upon notifications. In general, a
notification is a status message that may be associated with a data instance.
Usually, a notification is generated by the daemon if a configured threshold
has been exceeded (see the section "THRESHOLD CONFIGURATION" in
=item shutdown functions
-This type of function is called once before the daemon shuts down. It should
+These are called once before the daemon shuts down. It should
be used to clean up the plugin (e.g. close sockets, ...).
=back
-Any function (except log functions) may set throw an exception in case of any
+Any function (except log functions) may throw an exception in case of
errors. The exception will be passed on to the user using collectd's logging
mechanism. If a log callback throws an exception it will be printed to standard
error instead.
This is a tuple (which might be empty) of all value, i.e. words following the
keyword in any given line in the config file.
-Every item in this tuple will be either a string or a float or a boolean,
+Every item in this tuple will be either a string, a float or a boolean,
depending on the contents of the configuration file.
=item children
=head2 Values
-A Value is an object which features a sequence of values. It is based on then
+A Value is an object which features a sequence of values. It is based on the
I<PluginData> type and uses its members to identify the values.
class Values(PluginData)
=item message
-Some kind of description what's going on and why this Notification was
+Some kind of description of what's going on and why this Notification was
generated.
=item severity
I<name> is an optional identifier for this callback. The default name is
B<python>.I<module>. I<module> is taken from the B<__module__> attribute of
your callback function. Every callback needs a unique identifier, so if you
-want to register the same callback multiple time in the same module you need to
-specify a name here. Otherwise it's save to ignore this parameter I<identifier>
-is the full identifier assigned to this callback.
+want to register the same callback multiple times in the same module you need to
+specify a name here. Otherwise it's safe to ignore this parameter.
+
+=item
+
+I<identifier> is the full identifier assigned to this callback.
=back
The only argument passed is a I<Config> object. See above for the layout of this
data type.
-Note that you can not receive the whole config files this way, only B<Module>
+Note that you cannot receive the whole config files this way, only B<Module>
blocks inside the Python configuration block. Additionally you will only
receive blocks where your callback identifier matches B<python.>I<blockname>.
=item register_write
-The callback function will be called with one arguments passed, which will be a
+The callback function will be called with one argument passed, which will be a
I<Values> object. For the layout of I<Values> see above.
If this callback function throws an exception the next call will be delayed by
an increasing interval.
=item
-Please feel free to send in new plugins to collectd's mailinglist at
+Please feel free to send in new plugins to collectd's mailing list at
E<lt>collectdE<nbsp>atE<nbsp>verplant.orgE<gt> for review and, possibly,
inclusion in the main distribution. In the latter case, we will take care of
keeping the plugin up to date and adapting it to new versions of collectd.