X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=src%2Fcollectd-python.pod;fp=src%2Fcollectd-python.pod;h=0da891f1e47b5aa3dc14eabb7f97fc6b0d7dfc45;hb=1cf67d3e29da8ce7bdb29bc2fb8b1f0c1ca96e39;hp=0000000000000000000000000000000000000000;hpb=9caf56be59e558bc2fc4eaee3178580910fed869;p=pkg-collectd.git diff --git a/src/collectd-python.pod b/src/collectd-python.pod new file mode 100644 index 0000000..0da891f --- /dev/null +++ b/src/collectd-python.pod @@ -0,0 +1,757 @@ +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# 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 + +=head1 SYNOPSIS + + LoadPlugin python + # ... + + ModulePath "/path/to/your/python/modules" + LogTraces true + Interactive false + Import "spam" + + + spam "wonderful" "lovely" + + + +=head1 DESCRIPTION + +The C 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 (see +L) and provides a lot more functionality, too. + +The minimum required Python version is I<2.3>. + +=head1 CONFIGURATION + +=over 4 + +=item B I + +Loads the Python plugin I. + +=item B I + +The default encoding for Unicode objects you pass to collectd. If you omit this +option it will default to B on I. On I it will +always be B, as this function was removed, so this will be silently +ignored. +These defaults are hardcoded in Python and will ignore everything else, +including your locale. + +=item B I + +Prepends I to B. You won't be able to import any scripts you +wrote unless they are located in one of the directories in this list. Please +note that it only has effect on plugins loaded after this option. You can +use multiple B lines to add more than one directory. + +=item B I + +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 I + +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 so make sure to start collectd with the B<-f> option. + +The B module is I 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: + +=over 4 + +=item + +B<1.> collectd will try to import the B module to give you a decent +way of entering your commands. The daemonized collectd won't do that. + +=item + +B<2.> collectd will block I. Pressing I 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 I +exception either. + +To quit collectd send I (press I at the beginning of a new line). + +=item + +B<3.> collectd handles I. This means that Python won't be able to +determine the return code of spawned processes with system(), popen() and +subprocess. This will result in Python not using external programs like less +to display help texts. You can override this behavior with the B +environment variable, e.g. I before starting collectd. +Depending on your version of Python this might or might not result in an +B exception which can be ignored. + +If you really need to spawn new processes from Python you can register an init +callback and reset the action for SIGCHLD to the default behavior. Please note +that this I break the exec plugin. Do not even load the exec plugin if +you intend to do this! + +There is an example script located in B to do +this. If you import this from I SIGCHLD will be handled +normally and spawning processes from Python will work as intended. + +=back + +=item EB IE 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 class which is +passed to the registered configuration callback. See below for details about +the B class and how to register callbacks. + +The I identifies the callback. + +=back + +=head1 STRINGS + +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, which is just bytes, and I. Python3 has I, +which is a unicode object, and I. + +When passing strings from Python to collectd all of these object are supported +in all places, however I should be used if possible. These strings must +not contain a NUL byte. Ignoring this will result in a I exception. +If a byte string was used it will be used as is by collectd. If a unicode +object was used it will be encoded using the default encoding (see above). If +this is not possible Python will raise a I exception. + +When passing strings from collectd to Python the behavior depends on the +Python version used. Python2 will always receive a I object. Python3 will +usually receive a I object as well, however the original string will be +decoded to unicode using the default encoding. If this fails because the +string is not a valid sequence for this encoding a I object will be +returned instead. + +=head1 WRITING YOUR OWN PLUGINS + +Writing your own plugins is quite simple. collectd manages plugins by means of +B which call the appropriate B +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 are known to collectd +(all of them are optional): + +=over 4 + +=item configuration functions + +These are called during configuration if an appropriate +B block has been encountered. It is called once for each B +block which matches the name of the callback as provided with the +B method - see below. + +Python thread support has not been initialized at this point so do not use any +threading functions here! + +=item init functions + +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.Eg. open sockets, ...). This is the +earliest point where you may use threads. + +=item read functions + +These are used to collect the actual data. It is called once +per interval (see the B configuration option of collectd). Usually +it will call B to dispatch the values to collectd +which will pass them on to all registered B. 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 + +These are used to write the dispatched values. It is called +once for every value that was dispatched by any plugin. + +=item flush functions + +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 + +These are used to pass messages of plugins or the daemon itself +to the user. + +=item notification function + +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 +L for more details), but any plugin may dispatch +notifications as well. + +=item shutdown functions + +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 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. + +See the documentation of the various B methods in the section +"FUNCTIONS" below for the number and types of arguments passed to each +B. This section also explains how to register B with collectd. + +To enable a module, copy it to a place where Python can find it (i.Ee. a +directory listed in B) just as any other Python plugin and add +an appropriate B 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: + +=head2 Signed + +The Signed class is just a long. It has all its methods and behaves exactly +like any other long object. It is used to indicate if an integer was or should +be stored as a signed or unsigned integer object. + + class Signed(long) + +This is a long by another name. Use it in meta data dicts +to choose the way it is stored in the meta data. + +=head2 Unsigned + +The Unsigned class is just a long. It has all its methods and behaves exactly +like any other long object. It is used to indicate if an integer was or should +be stored as a signed or unsigned integer object. + + class Unsigned(long) + +This is a long by another name. Use it in meta data dicts +to choose the way it is stored in the meta data. + +=head2 Config + +The Config class is an object which keeps the information 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) 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: + +=over 4 + +=item parent + +This represents the parent of this node. On the root node +of the config tree it will be None. + +=item key + +This is the keyword of this item, i.e. the first word of any given line in the +config file. It will always be a string. + +=item values + +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, a float or a boolean, +depending on the contents of the configuration file. + +=item 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. + +=back + +=head2 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: + +=over 4 + +=item 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. + +=item plugin + +The name of the plugin that read the data. Setting this member to an empty +string will insert "python" upon dispatching. + +=item plugin_instance + +Plugin instance string. May be empty. + +=item time + +This is the Unix timestamp of the time this value was read. For dispatching +values this can be set to zero which means "now". This means the time the value +is actually dispatched, not the time it was set to 0. + +=item type + +The type of this value. This type has to be defined in your I. +Attempting to set it to any other value will raise a I exception. +Assigning a type is mandatory, calling dispatch without doing so will raise a +I exception. + +=item type_instance + +Type instance string. May be empty. + +=back + +=head2 Values + +A Value is an object which features a sequence of values. It is based on the +I 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: + +=over 4 + +=item Values + +=item PluginData + +=item object + +=back + +Methods defined here: + +=over 4 + +=item B([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None. + +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. + +=item B([destination][, type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None. + +Write this instance to a single plugin or all plugins if "destination" is +omitted. 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". + +=back + +Data descriptors defined here: + +=over 4 + +=item 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. + +=item 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 I file. For more +information on this read the L manual page. + +If the sequence does not have the correct size upon dispatch a I +exception will be raised. If the content of the sequence is not a number, a +I exception will be raised. + +=item meta + +These are the meta data for this Value object. +It has to be a dictionary of numbers, strings or bools. All keys must be +strings. I and objects will be dispatched as signed integers unless +they are between 2**63 and 2**64-1, which will result in a unsigned integer. +You can force one of these storage classes by using the classes +B and B. A meta object received by a write +callback will always contain B or B objects. + +=back + +=head2 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 I 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: + +=over 4 + +=item Notification + +=item PluginData + +=item object + +=back + +Methods defined here: + +=over 4 + +=item B([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. + +=back + +Data descriptors defined here: + +=over 4 + +=item message + +Some kind of description of what's going on and why this Notification was +generated. + +=item severity + +The severity of this notification. Assign or compare to I, +I or I. + +=back + +=head1 FUNCTIONS + +The following functions provide the C-interface to Python-modules. + +=over 4 + +=item B(I[, I][, I]) -> 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. + +=over 4 + +=item + +I is a callable object that will be called every time the event is +triggered. + +=item + +I is an optional object that will be passed back to the callback function +every time it is called. If you omit this parameter no object is passed back to +your callback, not even None. + +=item + +I is an optional identifier for this callback. The default name is +B.I. I 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 times in the same module you need to +specify a name here. Otherwise it's safe to ignore this parameter. + +=item + +I is the full identifier assigned to this callback. + +=back + +These functions are called in the various stages of the daemon (see the section +L<"WRITING YOUR OWN PLUGINS"> above) and are passed the following arguments: + +=over 4 + +=item register_config + +The only argument passed is a I object. See above for the layout of this +data type. +Note that you cannot receive the whole config files this way, only B +blocks inside the Python configuration block. Additionally you will only +receive blocks where your callback identifier matches BI. + +=item register_init + +The callback will be called without arguments. + +=item register_read(callback[, interval][, data][, name]) -> I + +This function takes an additional parameter: I. 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 argument passed, which will be a +I object. For the layout of I see above. +If this callback function throws an exception the next call will be delayed by +an increasing interval. + +=item register_flush + +Like B is important for this callback because it determines +what flush requests the plugin will receive. + +The arguments passed are I and I. I indicates +that only data older than I seconds is to be flushed. I +specifies which values are to be flushed. + +=item register_log + +The arguments are I and I. The severity is an integer and +small for important messages and high for less important messages. The least +important level is B, the most important level is B. In +between there are (from least to most important): B, B, +and B. I is simply a string B a newline at the +end. + +If this callback throws an exception it will B be logged. It will just be +printed to B which usually means silently ignored. + +=item register_notification + +The only argument passed is a I object. See above for the layout of this +data type. + +=back + +=item B(I) -> None + +Removes a callback or data-set from collectd's internal list of callback +functions. Every I function has an I function. +I 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(I) -> I + +Returns the definition of a dataset specified by I. I is a list +of tuples, each representing one data source. Each tuple has 4 values: + +=over 4 + +=item name + +A string, the name of the data source. + +=item type + +A string that is equal to either of the variables B, +B, B or B. + +=item min + +A float or None, the minimum value. + +=item max + +A float or None, the maximum value. + +=back + +=item B(I[, I][, I]) -> None + +Flush one or all plugins. I and the specified I are +passed on to the registered flush-callbacks. If omitted, the timeout defaults +to C<-1>. The identifier defaults to None. If the B argument has been +specified, only named plugin will be flushed. + +=item B, B, B, B, B(I) + +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 L<"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 mailing list at +EcollectdEatEcollectd.orgE 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. + +=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.Ee. 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 + +Not all aspects of the collectd API are accessible from Python. This includes +but is not limited to filters and data sets. + +=back + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, + +=head1 AUTHOR + +The C has been written by +Sven Trenkel EcollectdEatEsemidefinite.deE. + +This manpage has been written by Sven Trenkel +EcollectdEatEsemidefinite.deE. +It is based on the L manual page by +Florian Forster EoctoEatEcollectd.orgE and +Sebastian Harl EshEatEtokkee.orgE. + +=cut