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>
=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<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
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
=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<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
[{
name => 'data_source_name',
- type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+ type => DS_TYPE_COUNTER || DS_TYPE_GAUGE,
min => value || undef,
max => value || undef
}, ...]
{
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
=item TYPE_LOG
+=item TYPE_NOTIF
+
=item TYPE_SHUTDOWN
=item TYPE_DATASET
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
+data-set. 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.
+file which are automatically registered with collectd - see L<types.db(5)> for
+a description of the format of this file.
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
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.
+=item TYPE_NOTIF
+
+The only argument passed is I<notification>. See above for the layout of this
+data type.
+
=back
=item B<plugin_unregister> (I<type>, I<plugin>)
type, data-set and value-list is passed to all write-callbacks that are
registered with the daemon.
+=item B<plugin_dispatch_notification> (I<notification>)
+
+Submits a I<notification> to the daemon which will then pass it to all
+notification-callbacks that are registered.
+
=item B<plugin_log> (I<log-level>, I<message>)
Submits a I<message> of level I<log-level> to collectd's logging mechanism.
=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
=item B<plugin_dispatch_values> ()
+=item B<plugin_dispatch_notification> ()
+
=item B<plugin_log> ()
=back
=back
+=item B<:notif>
+
+=over 4
+
+=item B<NOTIF_FAILURE>
+
+=item B<NOTIF_WARNING>
+
+=item B<NOTIF_OKAY>
+
+=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 NOTES
+
+=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).
+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 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 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<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(1)>,
L<collectd.conf(5)>,
L<collectd-exec(5)>,
+L<types.db(5)>,
L<perl(1)>,
+L<threads(3perl)>,
+L<threads::shared(3perl)>,
L<perldebug(1)>
=head1 AUTHOR
projects / collectd.git / blobdiff