Added collectd-python man page.

diff --git a/src/Makefile.am b/src/Makefile.am
index f8deccf5da9f7c31a3df65f63c8aaa1fdfd20fc1..ca587a4accc43bbd171c573fa21aaf3c31b350ac 100644 (file)
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -1116,6 +1116,7 @@ dist_man_MANS = collectd.1 \
                collectdmon.1 \
                collectd-nagios.1 \
                collectd-perl.5 \
+               collectd-python.5 \
                collectd-snmp.5 \
                collectd-unixsock.5 \
                types.db.5
@@ -1131,6 +1132,7 @@ EXTRA_DIST +=   collectd.conf.pod \
                collectdmon.pod \
                collectd-nagios.pod \
                collectd-perl.pod \
+               collectd-python.pod \
                collectd.pod \
                collectd-snmp.pod \
                collectd-unixsock.pod \

diff --git a/src/collectd-python.pod b/src/collectd-python.pod
new file mode 100644 (file)
index 0000000..b6a0b0c
--- /dev/null
+++ b/src/collectd-python.pod
@@ -0,0 +1,587 @@
+=head1 NAME
+
+collectd-python - Documentation of collectd's C<python plugin>
+
+=head1 SYNOPSIS
+
+  <LoadPlugin python>
+    Globals true
+  </LoadPlugin>
+  # ...
+  <Plugin python>
+    ModulePath "/path/to/your/python/modules"
+    LogTraces true
+    Interactive true
+    Import "spam"
+
+    <Module spam>
+      spam "wonderful" "lovely"
+    </Module>
+  </Plugin>
+
+=head1 DESCRIPTION
+
+The C<python plugin> embeds a Python-interpreter into collectd and provides an
+interface to collectd's plugin system. This makes it possible to write plugins
+for collectd in Python. This is a lot more efficient than executing a
+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.
+
+=head1 CONFIGURATION
+
+=over 4
+
+=item B<LoadPlugin> I<Plugin>
+
+Loads the Python plugin I<Plugin>. Unlike most other LoadPlugin lines, this one
+should be a block containing the line "Globals true". This will cause collectd
+to export the name of all objects in the python interpreter for all plugins to
+see. If you don't do this or your platform does not support it, the embeded
+interpreter will start anywa but you won't be able to load certain python
+modules, e.g. "time".
+
+=item B<MudulePath> I<Name>
+
+Appends I<Name> to B<sys.path>. You won't be able to import any scripts you
+wrote unless they are located in one of the directuries in this list. Please
+note that it only has effect on plugins loaded after this option.
+
+=item B<LogTraces> I<bool>
+
+If a python script throws an exception it will be logged by collectd with the
+name of the exception and the message. If you set this option to true it will
+also log the full stacktrace just like the default output of an interactive
+python interpreter. This should probably be set to false most of the time but
+is very useful for development and debugging of new modules.
+
+=item B<Interactive> I<bool>
+
+This option will causethe 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.
+
+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
+used as a reference guide during coding.
+
+This interactive session will behave slightly differently from a daemonized
+collectd script as well as from a normal python interpreter:
+1. collectd will try to import the B<readline> module to give you a decent
+way of entering your commmands. The daemonized collectd won't do that.
+2. collectd will block SIGINT. Pressing Ctrl+C will usually cause collectd to
+shut down. This would be problematic in an interactive session, therefore this
+signal will be blocked. You can still use it to interrupt syscalls like sleep
+and pause but it won't generate a KeyboardInterrupt exception either.
+
+To quit collectd send EOF (press Ctrl+D at the beginning of a new line).
+
+=item E<lt>B<Module> I<Name>E<gt> block
+
+This block may be used to pass on configuration settings to a Python module.
+The configuration is converted into an instance of the B<Config> class which
+is passed to the registered configuration callback. See below for details about
+the B<Config> class and how to register callbacks.
+
+The I<name> identifies the callback.
+
+=back
+
+=head1 WRITING YOUR OWN PLUGINS
+
+Writing your own plugins is quite simple. collectd manages plugins by means of
+B<dispatch functions> which call the appropriate B<callback functions>
+registered by the plugins. Any plugin basically consists of the implementation
+of these callback functions and initializing code which registers the
+functions with collectd. See the section "EXAMPLES" below for a really basic
+example. The following types of B<callback functions> are known to collectd
+(all of them are optional):
+
+=over 4
+
+=item configuration functions
+
+This type of functions is 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.
+
+Python thread support has not been initialized at this point so do not use any
+threading functions at this point!
+
+=item init functions
+
+This type of functions is 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
+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
+throws any kind of exception the plugin will be skipped for an increasing
+amount of time until it returns normally again.
+
+=item write functions
+
+This type of function is 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
+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
+to the user.
+
+=item notification function
+
+This type of function is 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
+L<collectd.conf(5)> for more details), but any plugin may dispatch
+notifications as well.
+
+=item shutdown functions
+
+This type of function is 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
+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 stderr
+instead.
+
+See the documentation of the various B<register_> methods in the section
+"FUNCTIONS" below for the number and types of arguments passed to each
+B<callback function>. This section also explains how to register B<callback
+functions> with collectd.
+
+To enable a module, copy it to a place where Python can find it (i.E<nbsp>e. a
+directory listed in B<sys.path>) just as any other Python plugin and add
+an appropriate B<Import> option to the configuration file. After restarting
+collectd you're done.
+
+=head1 CLASSES
+
+The following complex types are used to pass values between the Python plugin
+and collectd:
+
+=over 4
+
+=item Config
+
+The Config class is an object which keeps the informations provided in the
+configuration file. The sequence of children keeps one entry for each
+configuration option. Each such entry is another Config instance, which
+may nest further if nested blocks are used.
+
+class Config(object)
+ |  This represents a piece of collectd's config file.
+ |  It is passed to scripts with config callbacks (see B<register_config>)
+ |  and is of little use if created somewhere else.
+ |
+ |  It has no methods beyond the bare minimum and only exists for its
+ |  data members
+ |
+ |  ----------------------------------------------------------------------
+ |  Data descriptors defined here:
+ |
+ |  parent
+ |      This represents the parent of this node. On the root node
+ |      of the config tree it will be None.
+ |
+ |  key
+ |      This is the keyword of this item, ie the first word of any
+ |      given line in the config file. It will always be a string.
+ |
+ |  values
+ |      This is a tuple (which might be empty) of all value, ie 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 bool,
+ |      depending on the contents of the configuration file.
+ |
+ |  children
+ |      This is a tuple of child nodes. For most nodes this will be
+ |      empty. If this node represents a block instead of a single line of the config
+ |      file it will contain all nodes in this block.
+
+
+=item PluginData
+
+This should not be used directly but it is the base class for both Values and
+Notification. It is used to identify the source of a value or notification.
+
+class PluginData(object)
+ |  This is an internal class that is the base for Values
+ |  and Notification. It is pretty useless by itself and was therefore not
+ |  exported to the collectd module.
+ |
+ |  ----------------------------------------------------------------------
+ |  Data descriptors defined here:
+ |
+ |  host
+ |      The hostname of the host this value was read from.
+ |      For dispatching this can be set to an empty string which means
+ |      the local hostname as defined in collectd.conf.
+ |
+ |  plugin
+ |      The name of the plugin that read the data. Setting this
+ |      member to an empty string will insert "python" upon dispatching.
+ |
+ |  plugin_instance
+ |
+ |  time
+ |      This is the Unix timestap of the time this value was read.
+ |      For dispatching values this can be set to 0 which means "now".
+ |      This means the time the value is actually dispatched, not the time
+ |      it was set to 0.
+ |
+ |  type
+ |      The type of this value. This type has to be defined
+ |      in your types.db. Attempting to set it to any other value will
+ |      raise a TypeError exception.
+ |      Assigning a type is mandetory, calling dispatch without doing
+ |      so will raise a RuntimeError exception.
+ |
+ |  type_instance
+
+
+=item Values
+
+A Value is an object which features a sequence of values. It is based on then
+I<PluginData> type and uses its members to identify the values.
+
+class Values(PluginData)
+ |  A Values object used for dispatching values to collectd and receiving
+ |  values from write callbacks.
+ |  
+ |  Method resolution order:
+ |      Values
+ |      PluginData
+ |      object
+ |  
+ |  Methods defined here:
+ |  
+ |  dispatch(...)
+ |      dispatch([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
+ |      
+ |      Dispatch this instance to the collectd process. The object has members
+ |      for each of the possible arguments for this method. For a detailed
+ |      explanation of these parameters see the member of the same same.
+ |      
+ |      If you do not submit a parameter the value saved in its member will be
+ |      submitted. If you do provide a parameter it will be used instead,
+ |      without altering the member.
+ |  
+ |  write(...)
+ |      write([destination][, type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
+ |
+ |      Write this instance to a single plugin or all plugins if 'destination' is obmitted.
+ |      This will bypass the main collectd process and all filtering and caching.
+ |      Other than that it works similar to 'dispatch'. In most cases 'dispatch' should be
+ |      used instead of 'write'.
+ |
+ |  ----------------------------------------------------------------------
+ |  Data descriptors defined here:
+ |  
+ |  interval
+ |      The interval is the timespan in seconds between two submits for the
+ |      same data source. This value has to be a positive integer, so you can't
+ |      submit more than one value per second. If this member is set to a
+ |      non-positive value, the default value as specified in the config file
+ |      will be used (default: 10).
+ |      
+ |      If you submit values more often than the specified interval, the average
+ |      will be used. If you submit less values, your graphs will have gaps.
+ |  
+ |  values
+ |      These are the actual values that get dispatched to collectd.
+ |      It has to be a sequence (a tuple or list) of numbers.
+ |      The size of the sequence and the type of its content depend on the type
+ |      member your types.db file. For more information on this read the
+ |      types.db man page.
+ |      
+ |      If the sequence does not have the correct size upon dispatch a
+ |      RuntimeError exception will be raised. If the content of the sequence
+ |      is not a number, a TypeError exception will be raised.
+
+
+=item Notification
+
+A notification is an object defining the severity and message of the status
+message as well as an identification of a data instance by means of the members
+of PluginData on which it is based.
+
+class Notification(PluginData)
+ |  The Notification class is a wrapper around the collectd notification.
+ |  It can be used to notify other plugins about bad stuff happening. It works
+ |  similar to Values but has a severity and a message instead of interval
+ |  and time.
+ |  Notifications can be dispatched at any time and can be received with
+ |  register_notification.
+ |  
+ |  Method resolution order:
+ |      Notification
+ |      PluginData
+ |      object
+ |  
+ |  Methods defined here:
+ |  
+ |  dispatch(...)
+ |      dispatch([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
+ |      
+ |      Dispatch this instance to the collectd process. The object has members
+ |      for each of the possible arguments for this method. For a detailed
+ |      explanation of these parameters see the member of the same same.
+ |      
+ |      If you do not submit a parameter the value saved in its member will be
+ |      submitted. If you do provide a parameter it will be used instead,
+ |      without altering the member.
+ |  
+ |  ----------------------------------------------------------------------
+ |  Data descriptors defined here:
+ |  
+ |  message
+ |      Some kind of description what's going on and why this Notification
+ |      was generated.
+ |  
+ |  severity
+ |      The severity of this notification. Assign or compare to
+ |      NOTIF_FAILURE, NOTIF_WARNING or NOTIF_OKAY.
+
+
+=back
+
+=head1 FUNCTIONS
+
+The following functions provide the C-interface to Python-modules.
+
+=over 4
+
+=item B<register_*>(I<callback>[, I<data>][, I<name>]) -> identifier
+
+There are eight different register functions to get callback for eight
+different events. With one exception all of them are called as shown above.
+
+I<callback> is a callable object that will be called every time the event is
+        triggered.
+I<data> is an optional object that will be passed back to the callback function
+        every time it is called. If you obmit this parameter no object is
+        passed back to your callback, not even None.
+I<name> is an optional identifier for this callback. The default name is
+        B<python>.I<module>.I<name>'. I<module> and I<name> are taken from the
+        B<__module__> and B<__name__> attributes of your callback function. If
+        the parameter I<name> contains a B<.>' it replaces both I<module> and
+        I<name>, otherwise it replaces only I<name>.
+        Every callback needs a unique identifier, so if you want to register
+        one function multiple time 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.
+
+These functions are called in the various stages of the daemon (see the
+section "WRITING YOUR OWN PLUGINS" above) and are passed the following
+arguments:
+
+=over 4
+
+=item register_config
+
+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>
+blocks inside the Python configuration block. Additionally you will only
+receive blocks where your callback identifier matches B<python.>I<blockname>. In
+order for this to work the way the identifier is constructed is shortened to
+not have a I<name> part.
+
+=item register_init
+
+The callback will be called without arguments.
+
+=item register_read(callback[, interval][, data][, name]) -> identifier
+
+This function takes an additional parameter: I<interval>. It specifies the
+time between calls to the callback function.
+
+The callback will be called without arguments.
+
+=item register_shutdown
+
+The callback will be called without arguments.
+
+=item register_write
+
+The callback function will be called with one arguments 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 register_flush
+
+Like B<register_config> the identifier is shortened because it determines what
+flush requests the plugin will receive.
+
+The arguments passed are I<timeout> and I<identifier>. I<timeout> indicates
+that only data older than I<timeout> seconds is to be flushed. I<identifier>
+specifies which values are to be flushed.
+
+=item register_log
+
+The arguments are I<severity> and I<message>. The severity is an integer and
+small for important messages and high for less important messages. The least
+important level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In
+between there are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>,
+and B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the
+end.
+
+If this callback throws an exception it will B<not> be logged. It will just be
+printed to sys.stderr which usually means silently ignored.
+
+=item register_notification
+
+The only argument passed is a I<Notification> object. See above for the layout of this
+data type.
+
+=back
+
+=item B<unregister_*>(I<identifier>) -> None
+
+Removes a callback or data-set from collectd's internal list of callback
+functions. Every register_* function has an unregister_* function. I<identifier>
+is either the string that was returned by the register function or a callback
+function. The identifier will be constructed in the same way as for the
+register functions.
+
+=item B<flush>(I<plugin[, I<timeout>][, I<identifier>]) -> None
+
+Flush one or all plugins. I<timeout> and the specified I<identifiers> are
+passed on to the registered flush-callbacks. If omitted, the timeout defaults
+to C<-1>. The identifier defaults to None. If the B<plugin> argument has been
+specified, only named plugin will be flushed.
+
+=item B<error>, B<warning>, B<notice>, B<info>, B<debug>(I<message>)
+
+Log a message with the specified severity.
+
+=back
+
+=head1 EXAMPLES
+
+Any Python module will start similar to:
+
+  import collectd
+
+A very simple read function might look like:
+
+  def read(data=None):
+    vl = collectd.Values(type='gauge')
+    vl.plugin='python.spam'
+    vl.dispatch(values=[random.random() * 100])
+
+A very simple write function might look like:
+
+  def write(vl, data=None):
+    for i in vl.values:
+      print "%s (%s): %f" % (vl.plugin, vl.type, i)
+
+To register those functions with collectd:
+
+  collectd.register_read(read);
+  collectd.register_write(write);
+
+See the section "CLASSES" above for a complete documentation of the data
+types used by the read, write and match functions.
+
+=head1 NOTES
+
+=over 4
+
+=item
+
+Please feel free to send in new plugins to collectd's mailinglist 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.
+
+Before submitting your plugin, please take a look at
+L<http://collectd.org/dev-info.shtml>.
+
+=back
+
+=head1 CAVEATS
+
+=over 4
+
+=item
+
+collectd is heavily multi-threaded. Each collectd thread accessing the python
+plugin will be mapped to a Python interpreter thread. Any such thread will be
+created and destroyed transparently and on-the-fly.
+
+Hence, any plugin has to be thread-safe if it provides several entry points
+from collectd (i.E<nbsp>e. if it registers more than one callback or if a
+registered callback may be called more than once in parallel).
+
+=item
+
+The Python thread module is initialized just before calling the init callbacks.
+This means you must not use Python's threading module prior to this point. This
+includes all config and possibly other callback as well.
+
+=item
+
+The python plugin exports the internal API of collectd which is considered
+unstable and subject to change at any time. We try hard to not break backwards
+compatibility in the Python API during the life cycle of one major release.
+However, this cannot be guaranteed at all times. Watch out for warnings
+dispatched by the python plugin after upgrades.
+
+=back
+
+=head1 KNOWN BUGS
+
+=over 4
+
+=item
+
+This plugin is not compatible with python3. Trying to complie it with python3
+will fail because of the ways string, unicode and bytearray bahavior was
+changed.
+
+Not all aspects of the collectd API are accessable from python. This includes
+but is not limited to meta-data, filters and data sets.
+
+=back
+
+=head1 SEE ALSO
+
+L<collectd(1)>,
+L<collectd.conf(5)>,
+L<collectd-perl(5)>,
+L<collectd-exec(5)>,
+L<types.db(5)>,
+L<python(1)>,
+
+=head1 AUTHOR
+
+The C<python plugin> has been written by Sebastian Harl
+E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
+
+This manpage has been written by Florian Forster
+E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt> and Sebastian Harl
+E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
+
+=cut
+