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
=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
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 these are optional):
+(all of them are optional):
=over 4
This type of function is used to write the dispatched values. It is called
once for each call to B<plugin_dispatch_values>.
+=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
=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.
+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
[{
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_WRITE
+=item TYPE_FLUSH
+
=item TYPE_LOG
+=item TYPE_NOTIF
+
=item TYPE_SHUTDOWN
=item TYPE_DATASET
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 name. If the name is not
=item TYPE_SHUTDOWN
-No arguments are passed
+No arguments are passed.
=item TYPE_WRITE
The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
string. For the layout of I<data-set> and I<value-list> see above.
+=item TYPE_FLUSH
+
+The only argument passed is I<timeout> which indicates that only data older
+than I<timeout> seconds is to be flushed.
+
=item TYPE_LOG
The arguments are I<log-level> and I<message>. The log level is small for
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_flush> ([B<timeout> => I<timeout>,] [B<plugins> => I<...>])
+
+Flush one or more plugins. I<timeout> is passed on to the registered
+flush-callbacks. If omitted, C<-1> is used. If the I<plugins> 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<plugin_flush_one> (I<timeout>, I<plugin>)
+
+This is identical to using "plugin_flush (timeout =E<gt> I<timeout>, plugins
+=E<gt> I<plugin>".
+
+=item B<plugin_flush_all> (I<timeout>)
+
+This is identical to using "plugin_flush (timeout =E<gt> I<timeout>)".
+
+=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_flush> ()
+
+=item B<plugin_flush_one> ()
+
+=item B<plugin_flush_all> ()
+
+=item B<plugin_dispatch_notification> ()
+
=item B<plugin_log> ()
=back
=item B<TYPE_WRITE>
+=item B<TYPE_FLUSH>
+
=item B<TYPE_SHUTDOWN>
=item B<TYPE_LOG>
=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
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
+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>.
-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).
+=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 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<perl> as
+plugin name when doing so.
+
+=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