X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-perl.pod;h=8cdf08bb3b6807229bb4a985a5b01f74771f8378;hb=d767db104769bed7fefea61538bdacb364434e9a;hp=b6537470de793847fcbc6424c94f3ea31591b78e;hpb=613c72c29b5405d7e170ae7fe12611492ecb5fef;p=collectd.git diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod index b6537470..8cdf08bb 100644 --- a/src/collectd-perl.pod +++ b/src/collectd-perl.pod @@ -21,9 +21,6 @@ for collectd in Perl. This is a lot more efficient than executing a Perl-script every time you want to read a value with the C (see L) and provides a lot more functionality, too. -Please note that this is still considered to be experimental and subject to -change between minor releases. - =head1 CONFIGURATION =over 4 @@ -50,6 +47,10 @@ using the B<-d:Package> command line option. See L for detailed documentation about debugging Perl. +This option does not prevent collectd from daemonizing, so you should start +collectd with the B<-f> command line option. Else you will not be able to use +the command line driven interface of the debugger. + =item B I Adds I to the B<@INC> array. This is the same as using the B<-IDir> @@ -60,13 +61,13 @@ only has effect on plugins loaded after this option. =head1 WRITING YOUR OWN PLUGINS -Writing your own plugins is quite simply. collectd manages plugins by means of +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 these are optional): +(all of them are optional): =over 4 @@ -91,11 +92,26 @@ amount of time until it returns B again. This type of function is used to write the dispatched values. It is called once for each call to B. +=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 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 @@ -103,6 +119,10 @@ be used to clean up the plugin (e.g. close sockets, ...). =back +Any function (except log functions) may set the B<$@> variable to describe +errors in more detail. The message will be passed on to the user using +collectd's logging mechanism. + See the documentation of the B method in the section "METHODS" below for the number and types of arguments passed to each B. This section also explains how to register B 'data_source_name', - type => DS_TYPE_COUNTER || DS_TYPE_GAUGE + type => DS_TYPE_COUNTER || DS_TYPE_GAUGE, min => value || undef, max => value || undef }, ...] @@ -144,12 +164,28 @@ layout looks like this: { values => [123, 0.5], time => time (), - host => 'localhost', + host => $hostname_g, plugin => 'myplugin', plugin_instance => '', type_instance => '' } +=item Notification + +A notification is one structure defining the severity, time and message of the +status message as well as an identification of a data instance: + + { + severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY, + time => time (), + message => 'status message', + host => $hostname_g, + plugin => 'myplugin', + type => 'mytype', + plugin_instance => '', + type_instance => '' + } + =back =head1 METHODS @@ -173,8 +209,12 @@ I can be one of: =item TYPE_WRITE +=item TYPE_FLUSH + =item TYPE_LOG +=item TYPE_NOTIF + =item TYPE_SHUTDOWN =item TYPE_DATASET @@ -186,16 +226,23 @@ depending on the value of I. (Please note that the type of the data-set is the value passed as I here and has nothing to do with the I argument which simply tells B what is being registered.) -The last argument, I, is either a function- or an array-reference. If -I is B, then the I argument must be an +The last argument, I, is either a function name or an array-reference. +If I is B, then the I argument must be an array-reference which points to an array of hashes. Each hash describes one -data-source. For the exact layout see B above. Please note that +data-set. For the exact layout see B above. Please note that there is a large number of predefined data-sets available in the B -file which are automatically registered with collectd. +file which are automatically registered with collectd - see L for +a description of the format of this file. If the I argument is any of the other types (B, B, -...) then I is expected to be a function reference. These functions are -called in the various stages of the daemon and are passed the following +...) then I is expected to be a function name. If the name is not +prefixed with the plugin's package name collectd will add it automatically. +The interface slightly differs from the C interface (which expects a function +pointer instead) because Perl does not support to share references to +subroutines between threads. + +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 @@ -206,13 +253,18 @@ arguments: =item TYPE_SHUTDOWN -No arguments are passed +No arguments are passed. =item TYPE_WRITE The arguments passed are I, I, and I. I is a string. For the layout of I and I see above. +=item TYPE_FLUSH + +The only argument passed is I which indicates that only data older +than I seconds is to be flushed. + =item TYPE_LOG The arguments are I and I. The log level is small for @@ -221,6 +273,11 @@ 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. +=item TYPE_NOTIF + +The only argument passed is I. See above for the layout of this +data type. + =back =item B (I, I) @@ -235,6 +292,27 @@ is found (and the number of values matches the number of data-sources) then the type, data-set and value-list is passed to all write-callbacks that are registered with the daemon. +=item B ([B => I,] [B => I<...>]) + +Flush one or more plugins. I is passed on to the registered +flush-callbacks. If omitted, C<-1> is used. If the I argument has +been specified, only named plugins will be flushed. The argument's value may +either be a string or a reference to an array of strings. + +=item B (I, I) + +This is identical to using "plugin_flush (timeout =E I, plugins +=E I". + +=item B (I) + +This is identical to using "plugin_flush (timeout =E I)". + +=item B (I) + +Submits a I to the daemon which will then pass it to all +notification-callbacks that are registered. + =item B (I, I) Submits a I of level I to collectd's logging mechanism. @@ -247,6 +325,25 @@ B, B and B respectively as I. =back +=head1 GLOBAL VARIABLES + +=over 4 + +=item B<$hostname_g> + +As the name suggests this variable keeps the hostname of the system collectd +is running on. The value might be influenced by the B or +B configuration options (see L for details). + +=item B<$interval_g> + +This variable keeps the interval in seconds in which the read functions are +queried (see the B configuration option). + +=back + +Any changes to these variables will be globally visible in collectd. + =head1 EXPORTS By default no symbols are exported. However, the following export tags are @@ -264,6 +361,14 @@ available (B<:all> will export all of them): =item B () +=item B () + +=item B () + +=item B () + +=item B () + =item B () =back @@ -278,6 +383,8 @@ available (B<:all> will export all of them): =item B +=item B + =item B =item B @@ -320,6 +427,28 @@ available (B<:all> will export all of them): =back +=item B<:notif> + +=over 4 + +=item B + +=item B + +=item B + +=back + +=item B<:globals> + +=over 4 + +=item B<$hostname_g> + +=item B<$interval_g> + +=back + =back =head1 EXAMPLES @@ -356,25 +485,83 @@ A very simple write function will look like: To register those functions with collectd: - plugin_register (TYPE_READ, "foobar", \&foobar_read); - plugin_register (TYPE_WRITE, "foobar", \&foobar_write); + plugin_register (TYPE_READ, "foobar", "foobar_read"); + plugin_register (TYPE_WRITE, "foobar", "foobar_write"); See the section "DATA TYPES" above for a complete documentation of the data types used by the read and write functions. -=head1 BUGS +=head1 NOTES + +=over 4 + +=item + +Please feel free to send in new plugins to collectd's mailinglist at +EcollectdEatEverplant.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. -This plugin does not yet work correctly if collectd uses multiple threads. -Perl does not allow multiple threads to access a single interpreter at the -same time. As a temporary workaround you should use a single read thread only -(see collectd's B configuration option). +=back + +=head1 CAVEATS + +=over 4 + +=item + +collectd is heavily multi-threaded. Each collectd thread accessing the perl +plugin will be mapped to a Perl interpreter thread (see L). +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). Please note +that no data is shared between threads by default. You have to use the +B module to do so. + +=item + +Each function name registered with collectd has to be available before the +first thread has been created (i.Ee. basically at compile time). This +basically means that hacks (yes, I really consider this to be a hack) like +C<*foo = \&bar; plugin_register (TYPE_READ, "plugin", "foo");> most likely +will not work. This is due to the fact that the symbol table is not shared +across different threads. + +=item + +Each plugin is usually only loaded once and kept in memory for performance +reasons. Therefore, END blocks are only executed once when collectd shuts +down. You should not rely on END blocks anyway - use B +instead. + +=back + +=head1 KNOWN BUGS + +=over 4 + +=item + +Currently, it is not possible to flush a single Perl plugin only. You can +either flush all Perl plugins or none at all and you have to use C as +plugin name when doing so. + +=back =head1 SEE ALSO L, L, L, +L, L, +L, +L, L =head1 AUTHOR