Perl-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.
-Please note that this is still considered to be experimental and subject to
-change between minor releases.
-
=head1 CONFIGURATION
=over 4
See L<perldebug> 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<IncludeDir> I<Dir>
Adds I<Dir> to the B<@INC> array. This is the same as using the B<-IDir>
=back
+Any function 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<plugin_register> method in the section
"METHODS" below for the number and types of arguments passed to each
B<callback function>. This section also explains how to register B<callback
is the value passed as I<name> here and has nothing to do with the I<type>
argument which simply tells B<plugin_register> what is being registered.)
-The last argument, I<data>, is either a function- or an array-reference. If
-I<type> is B<TYPE_DATASET>, then the I<data> argument must be an
+The last argument, I<data>, is either a function name or an array-reference.
+If I<type> is B<TYPE_DATASET>, then the I<data> 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<Data-Set> above. Please note that
there is a large number of predefined data-sets available in the B<types.db>
file which are automatically registered with collectd.
If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>,
-...) then I<data> 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<data> 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
=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<Hostname> or
+B<FQDNLookup> configuration options (see L<collectd.conf(5)> for details).
+
+=item B<$interval_g>
+
+This variable keeps the interval in seconds in which the read functions are
+queried (see the B<Interval> 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
=back
+=item B<:globals>
+
+=over 4
+
+=item B<$hostname_g>
+
+=item B<$interval_g>
+
+=back
+
=back
=head1 EXAMPLES
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 CAVEATS
+
+=over 4
+
+=item
-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<ReadThread> configuration option).
+collectd is heavily multi-threaded. Each collectd thread accessing the perl
+plugin will be mapped to a Perl interpreter thread (see L<threads(3perl)>).
+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). Please
+note that no data is shared between threads by default. You have to use the
+B<threads::shared> module to do so.
+
+=item
+
+Each function name registered with collectd has to be available before the
+first thread has been created (i.E<nbsp>e. 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<shutdown functions>
+instead.
+
+=back
=head1 SEE ALSO
L<collectd.conf(5)>,
L<collectd-exec(5)>,
L<perl(1)>,
+L<threads(3perl)>,
+L<threads::shared(3perl)>,
L<perldebug(1)>
=head1 AUTHOR
projects / collectd.git / blobdiff