1COLLECTD-PERL(5)                   collectd                   COLLECTD-PERL(5)
2
3
4

NAME

6       collectd-perl - Documentation of collectd's "perl plugin"
7

SYNOPSIS

9         LoadPlugin perl
10         # ...
11         <Plugin perl>
12           IncludeDir "/path/to/perl/plugins"
13           BaseName "Collectd::Plugins"
14           EnableDebugger ""
15           LoadPlugin "FooBar"
16
17           <Plugin FooBar>
18             Foo "Bar"
19           </Plugin>
20         </Plugin>
21

DESCRIPTION

23       The "perl plugin" embeds a Perl-interpreter into collectd and provides
24       an interface to collectd's plugin system. This makes it possible to
25       write plugins for collectd in Perl. This is a lot more efficient than
26       executing a Perl-script every time you want to read a value with the
27       "exec plugin" (see collectd-exec(5)) and provides a lot more
28       functionality, too.
29

CONFIGURATION

31       LoadPlugin Plugin
32           Loads the Perl plugin Plugin. This does basically the same as use
33           would do in a Perl program. As a side effect, the first occurrence
34           of this option causes the Perl-interpreter to be initialized.
35
36       BaseName Name
37           Prepends Name:: to all plugin names loaded after this option. This
38           is provided for convenience to keep plugin names short. All Perl-
39           based plugins provided with the collectd distributions reside in
40           the "Collectd::Plugins" namespace.
41
42       <Plugin Name> block
43           This block may be used to pass on configuration settings to a Perl
44           plugin. The configuration is converted into a config-item data type
45           which is passed to the registered configuration callback. See below
46           for details about the config-item data type and how to register
47           callbacks.
48
49           The name identifies the callback. It is used literally and
50           independent of the BaseName setting.
51
52       EnableDebugger Package[=option,...]
53           Run collectd under the control of the Perl source debugger. If
54           Package is not the empty string, control is passed to the
55           debugging, profiling, or tracing module installed as
56           Devel::Package. A comma-separated list of options may be specified
57           after the "=" character. Please note that you may not leave out the
58           Package option even if you specify "". This is the same as using
59           the -d:Package command line option.
60
61           See perldebug for detailed documentation about debugging Perl.
62
63           This option does not prevent collectd from daemonizing, so you
64           should start collectd with the -f command line option. Else you
65           will not be able to use the command line driven interface of the
66           debugger.
67
68       IncludeDir Dir
69           Adds Dir to the @INC array. This is the same as using the -IDir
70           command line option or use lib Dir in the source code. Please note
71           that it only has effect on plugins loaded after this option.
72
73       RegisterLegacyFlush true|false
74           The "Perl plugin" used to register one flush callback (called
75           "perl") and call all Perl-based flush handlers when this callback
76           was called. Newer versions of the plugin wrap the Perl flush
77           handlers and register them directly with the daemon in addition to
78           the legacy "perl" callback. This allows to call specific Perl flush
79           handlers, but has the downside that flushing all plugins now calls
80           the Perl flush handlers twice (once directly and once via the
81           legacy callback). Unfortunately, removing the "perl" callback would
82           break backwards compatibility.
83
84           This option allows you to disable the legacy "perl" flush callback
85           if you care about the double call and don't call the "perl"
86           callback in your setup.
87

WRITING YOUR OWN PLUGINS

89       Writing your own plugins is quite simple. collectd manages plugins by
90       means of dispatch functions which call the appropriate callback
91       functions registered by the plugins. Any plugin basically consists of
92       the implementation of these callback functions and initializing code
93       which registers the functions with collectd. See the section "EXAMPLES"
94       below for a really basic example. The following types of callback
95       functions are known to collectd (all of them are optional):
96
97       configuration functions
98           This type of functions is called during configuration if an
99           appropriate Plugin block has been encountered. It is called once
100           for each Plugin block which matches the name of the callback as
101           provided with the plugin_register method - see below.
102
103       init functions
104           This type of functions is called once after loading the module and
105           before any calls to the read and write functions. It should be used
106           to initialize the internal state of the plugin (e. g. open sockets,
107           ...). If the return value evaluates to false, the plugin will be
108           disabled.
109
110       read functions
111           This type of function is used to collect the actual data. It is
112           called once per interval (see the Interval configuration option of
113           collectd). Usually it will call plugin_dispatch_values to dispatch
114           the values to collectd which will pass them on to all registered
115           write functions. If the return value evaluates to false the plugin
116           will be skipped for an increasing amount of time until it returns
117           true again.
118
119       write functions
120           This type of function is used to write the dispatched values. It is
121           called once for each call to plugin_dispatch_values.
122
123       flush functions
124           This type of function is used to flush internal caches of plugins.
125           It is usually triggered by the user only. Any plugin which caches
126           data before writing it to disk should provide this kind of callback
127           function.
128
129       log functions
130           This type of function is used to pass messages of plugins or the
131           daemon itself to the user.
132
133       notification function
134           This type of function is used to act upon notifications. In
135           general, a notification is a status message that may be associated
136           with a data instance.  Usually, a notification is generated by the
137           daemon if a configured threshold has been exceeded (see the section
138           "THRESHOLD CONFIGURATION" in collectd.conf(5) for more details),
139           but any plugin may dispatch notifications as well.
140
141       shutdown functions
142           This type of function is called once before the daemon shuts down.
143           It should be used to clean up the plugin (e.g. close sockets, ...).
144
145       Any function (except log functions) may set the $@ variable to describe
146       errors in more detail. The message will be passed on to the user using
147       collectd's logging mechanism.
148
149       See the documentation of the plugin_register method in the section
150       "METHODS" below for the number and types of arguments passed to each
151       callback function. This section also explains how to register callback
152       functions with collectd.
153
154       To enable a plugin, copy it to a place where Perl can find it (i. e. a
155       directory listed in the @INC array) just as any other Perl plugin and
156       add an appropriate LoadPlugin option to the configuration file. After
157       restarting collectd you're done.
158

DATA TYPES

160       The following complex types are used to pass values between the Perl
161       plugin and collectd:
162
163       Config-Item
164           A config-item is one structure which keeps the information provided
165           in the configuration file. The array of children keeps one entry
166           for each configuration option. Each such entry is another config-
167           item structure, which may nest further if nested blocks are used.
168
169             {
170               key      => key,
171               values   => [ val1, val2, ... ],
172               children => [ { ... }, { ... }, ... ]
173             }
174
175       Data-Set
176           A data-set is a list of one or more data-sources. Each data-source
177           defines a name, type, min- and max-value and the data-set wraps
178           them up into one structure. The general layout looks like this:
179
180             [{
181               name => 'data_source_name',
182               type => DS_TYPE_COUNTER || DS_TYPE_GAUGE || DS_TYPE_DERIVE || DS_TYPE_ABSOLUTE,
183               min  => value || undef,
184               max  => value || undef
185             }, ...]
186
187       Value-List
188           A value-list is one structure which features an array of values and
189           fields to identify the values, i. e. time and host, plugin name and
190           plugin-instance as well as a type and type-instance. Since the
191           "type" is not included in the value-list but is passed as an extra
192           argument, the general layout looks like this:
193
194             {
195               values => [123, 0.5],
196               time   => time (),
197               interval => plugin_get_interval (),
198               host   => $hostname_g,
199               plugin => 'myplugin',
200               type   => 'myplugin',
201               plugin_instance => '',
202               type_instance   => ''
203             }
204
205       Notification
206           A notification is one structure defining the severity, time and
207           message of the status message as well as an identification of a
208           data instance. Also, it includes an optional list of user-defined
209           meta information represented as (name, value) pairs:
210
211             {
212               severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
213               time     => time (),
214               message  => 'status message',
215               host     => $hostname_g,
216               plugin   => 'myplugin',
217               type     => 'mytype',
218               plugin_instance => '',
219               type_instance   => '',
220               meta     => [ { name => <name>, value => <value> }, ... ]
221             }
222
223       Match-Proc
224           A match-proc is one structure storing the callbacks of a "match" of
225           the filter chain infrastructure. The general layout looks like
226           this:
227
228             {
229               create  => 'my_create',
230               destroy => 'my_destroy',
231               match   => 'my_match'
232             }
233
234       Target-Proc
235           A target-proc is one structure storing the callbacks of a "target"
236           of the filter chain infrastructure. The general layout looks like
237           this:
238
239             {
240               create  => 'my_create',
241               destroy => 'my_destroy',
242               invoke  => 'my_invoke'
243             }
244

METHODS

246       The following functions provide the C-interface to Perl-modules. They
247       are exported by the ":plugin" export tag (see the section "EXPORTS"
248       below).
249
250       plugin_register (type, name, data)
251           Registers a callback-function or data-set.
252
253           type can be one of:
254
255           TYPE_CONFIG
256           TYPE_INIT
257           TYPE_READ
258           TYPE_WRITE
259           TYPE_FLUSH
260           TYPE_LOG
261           TYPE_NOTIF
262           TYPE_SHUTDOWN
263           TYPE_DATASET
264
265           name is the name of the callback-function or the type of the data-
266           set, depending on the value of type. (Please note that the type of
267           the data-set is the value passed as name here and has nothing to do
268           with the type argument which simply tells plugin_register what is
269           being registered.)
270
271           The last argument, data, is either a function name or an array-
272           reference.  If type is TYPE_DATASET, then the data argument must be
273           an array-reference which points to an array of hashes. Each hash
274           describes one data-set. For the exact layout see Data-Set above.
275           Please note that there is a large number of predefined data-sets
276           available in the types.db file which are automatically registered
277           with collectd - see types.db(5) for a description of the format of
278           this file.
279
280           Note: Using plugin_register to register a data-set is deprecated.
281           Add the new type to a custom types.db(5) file instead. This
282           functionality might be removed in a future version of collectd.
283
284           If the type argument is any of the other types (TYPE_INIT,
285           TYPE_READ, ...) then data is expected to be a function name. If the
286           name is not prefixed with the plugin's package name collectd will
287           add it automatically.  The interface slightly differs from the C
288           interface (which expects a function pointer instead) because Perl
289           does not support to share references to subroutines between
290           threads.
291
292           These functions are called in the various stages of the daemon (see
293           the section "WRITING YOUR OWN PLUGINS" above) and are passed the
294           following arguments:
295
296           TYPE_CONFIG
297               The only argument passed is config-item. See above for the
298               layout of this data type.
299
300           TYPE_INIT
301           TYPE_READ
302           TYPE_SHUTDOWN
303               No arguments are passed.
304
305           TYPE_WRITE
306               The arguments passed are type, data-set, and value-list. type
307               is a string. For the layout of data-set and value-list see
308               above.
309
310           TYPE_FLUSH
311               The arguments passed are timeout and identifier. timeout
312               indicates that only data older than timeout seconds is to be
313               flushed. identifier specifies which values are to be flushed.
314
315           TYPE_LOG
316               The arguments are log-level and message. The log level is small
317               for important messages and high for less important messages.
318               The least important level is LOG_DEBUG, the most important
319               level is LOG_ERR. In between there are (from least to most
320               important): LOG_INFO, LOG_NOTICE, and LOG_WARNING. message is
321               simply a string without a newline at the end.
322
323           TYPE_NOTIF
324               The only argument passed is notification. See above for the
325               layout of this data type.
326
327       plugin_unregister (type, plugin)
328           Removes a callback or data-set from collectd's internal list of
329           functions / datasets.
330
331       plugin_dispatch_values (value-list)
332           Submits a value-list to the daemon. If the data-set identified by
333           value-list->{type} is found (and the number of values matches the
334           number of data-sources) then the type, data-set and value-list is
335           passed to all write-callbacks that are registered with the daemon.
336
337       plugin_write ([plugins => ...][, datasets => ...], valuelists => ...)
338           Calls the write function of the given plugins with the provided
339           data sets and value lists. In contrast to plugin_dispatch_values,
340           it does not update collectd's internal cache and bypasses the
341           filter mechanism (see collectd.conf(5) for details). If the plugins
342           argument has been omitted, the values will be dispatched to all
343           registered write plugins. If the datasets argument has been
344           omitted, the required data sets are looked up according to the
345           "type" member in the appropriate value list. The value of all three
346           arguments may either be a single scalar or a reference to an array.
347           If the datasets argument has been specified, the number of data
348           sets has to equal the number of specified value lists.
349
350       plugin_flush ([timeout => timeout][, plugins => ...][, identifiers =>
351       ...])
352           Flush one or more plugins. timeout and the specified identifiers
353           are passed on to the registered flush-callbacks. If omitted, the
354           timeout defaults to "-1". The identifier defaults to the undefined
355           value. If the plugins argument has been specified, only named
356           plugins will be flushed. The value of the plugins and identifiers
357           arguments may either be a string or a reference to an array of
358           strings.
359
360       plugin_dispatch_notification (notification)
361           Submits a notification to the daemon which will then pass it to all
362           notification-callbacks that are registered.
363
364       plugin_log (log-level, message)
365           Submits a message of level log-level to collectd's logging
366           mechanism.  The message is passed to all log-callbacks that are
367           registered with collectd.
368
369       ERROR, WARNING, NOTICE, INFO, DEBUG (message)
370           Wrappers around plugin_log, using LOG_ERR, LOG_WARNING, LOG_NOTICE,
371           LOG_INFO and LOG_DEBUG respectively as log-level.
372
373       plugin_get_interval ()
374           Returns the interval of the current plugin as a floating point
375           number in seconds. This value depends on the interval configured
376           within the "LoadPlugin perl" block or the global interval (see
377           collectd.conf(5) for details).
378
379       The following function provides the filter chain C-interface to Perl-
380       modules.  It is exported by the ":filter_chain" export tag (see the
381       section "EXPORTS" below).
382
383       fc_register (type, name, proc)
384           Registers filter chain callbacks with collectd.
385
386           type may be any of:
387
388           FC_MATCH
389           FC_TARGET
390
391           name is the name of the match or target. By this name, the
392           callbacks are identified in the configuration file when specifying
393           a Match or Target block (see collectd.conf(5) for details).
394
395           proc is a hash reference. The hash includes up to three callbacks:
396           an optional constructor (create) and destructor (destroy) and a
397           mandatory match or invoke callback. match is called whenever
398           processing an appropriate match, while invoke is called whenever
399           processing an appropriate target (see the section "FILTER
400           CONFIGURATION" in collectd.conf(5) for details). Just like any
401           other callbacks, filter chain callbacks are identified by the
402           function name rather than a function pointer because Perl does not
403           support to share references to subroutines between threads. The
404           following arguments are passed to the callbacks:
405
406           create
407               The arguments passed are config-item and user-data. See above
408               for the layout of the config-item data-type. user-data is a
409               reference to a scalar value that may be used to store any
410               information specific to this particular instance. The daemon
411               does not care about this information at all. It's for the
412               plugin's use only.
413
414           destroy
415               The only argument passed is user-data which is a reference to
416               the user data initialized in the create callback. This callback
417               may be used to cleanup instance-specific information and
418               settings.
419
420           match, invoke
421               The arguments passed are data-set, value-list, meta and user-
422               data.  See above for the layout of the data-set and value-list
423               data-types. meta is a pointer to an array of meta information,
424               just like the meta member of the notification data-type (see
425               above). user-data is a reference to the user data initialized
426               in the create callback.
427

GLOBAL VARIABLES

429       $hostname_g
430           As the name suggests this variable keeps the hostname of the system
431           collectd is running on. The value might be influenced by the
432           Hostname or FQDNLookup configuration options (see collectd.conf(5)
433           for details).
434
435       $interval_g
436           This variable keeps the interval in seconds in which the read
437           functions are queried (see the Interval configuration option).
438
439           Note: This variable should no longer be used in favor of
440           "plugin_get_interval()" (see above). This function takes any
441           plugin-specific interval settings into account (see the "Interval"
442           option of "LoadPlugin" in collectd.conf(5) for details).
443
444       Any changes to these variables will be globally visible in collectd.
445

EXPORTS

447       By default no symbols are exported. However, the following export tags
448       are available (:all will export all of them):
449
450       :plugin
451           plugin_register ()
452           plugin_unregister ()
453           plugin_dispatch_values ()
454           plugin_flush ()
455           plugin_flush_one ()
456           plugin_flush_all ()
457           plugin_dispatch_notification ()
458           plugin_log ()
459       :types
460           TYPE_CONFIG
461           TYPE_INIT
462           TYPE_READ
463           TYPE_WRITE
464           TYPE_FLUSH
465           TYPE_SHUTDOWN
466           TYPE_LOG
467           TYPE_DATASET
468       :ds_types
469           DS_TYPE_COUNTER
470           DS_TYPE_GAUGE
471           DS_TYPE_DERIVE
472           DS_TYPE_ABSOLUTE
473       :log
474           ERROR ()
475           WARNING ()
476           NOTICE ()
477           INFO ()
478           DEBUG ()
479           LOG_ERR
480           LOG_WARNING
481           LOG_NOTICE
482           LOG_INFO
483           LOG_DEBUG
484       :filter_chain
485           fc_register
486           FC_MATCH_NO_MATCH
487           FC_MATCH_MATCHES
488           FC_TARGET_CONTINUE
489           FC_TARGET_STOP
490           FC_TARGET_RETURN
491       :fc_types
492           FC_MATCH
493           FC_TARGET
494       :notif
495           NOTIF_FAILURE
496           NOTIF_WARNING
497           NOTIF_OKAY
498       :globals
499           $hostname_g
500           $interval_g
501

EXAMPLES

503       Any Perl plugin will start similar to:
504
505         package Collectd::Plugins::FooBar;
506
507         use strict;
508         use warnings;
509
510         use Collectd qw( :all );
511
512       A very simple read function might look like:
513
514         sub foobar_read
515         {
516           my $vl = { plugin => 'foobar', type => 'gauge' };
517           $vl->{'values'} = [ rand(42) ];
518           plugin_dispatch_values ($vl);
519           return 1;
520         }
521
522       A very simple write function might look like:
523
524         sub foobar_write
525         {
526           my ($type, $ds, $vl) = @_;
527           for (my $i = 0; $i < scalar (@$ds); ++$i) {
528             print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
529           }
530           return 1;
531         }
532
533       A very simple match callback might look like:
534
535         sub foobar_match
536         {
537           my ($ds, $vl, $meta, $user_data) = @_;
538           if (matches($ds, $vl)) {
539             return FC_MATCH_MATCHES;
540           } else {
541             return FC_MATCH_NO_MATCH;
542           }
543         }
544
545       To register those functions with collectd:
546
547         plugin_register (TYPE_READ, "foobar", "foobar_read");
548         plugin_register (TYPE_WRITE, "foobar", "foobar_write");
549
550         fc_register (FC_MATCH, "foobar", "foobar_match");
551
552       See the section "DATA TYPES" above for a complete documentation of the
553       data types used by the read, write and match functions.
554

NOTES

556       ·   Please feel free to send in new plugins to collectd's mailing list
557           at <collectd at collectd.org> for review and, possibly, inclusion
558           in the main distribution. In the latter case, we will take care of
559           keeping the plugin up to date and adapting it to new versions of
560           collectd.
561
562           Before submitting your plugin, please take a look at
563           <http://collectd.org/dev-info.shtml>.
564

CAVEATS

566       ·   collectd is heavily multi-threaded. Each collectd thread accessing
567           the perl plugin will be mapped to a Perl interpreter thread (see
568           threads(3perl)).  Any such thread will be created and destroyed
569           transparently and on-the-fly.
570
571           Hence, any plugin has to be thread-safe if it provides several
572           entry points from collectd (i. e. if it registers more than one
573           callback or if a registered callback may be called more than once
574           in parallel). Please note that no data is shared between threads by
575           default. You have to use the threads::shared module to do so.
576
577       ·   Each function name registered with collectd has to be available
578           before the first thread has been created (i. e. basically at
579           compile time). This basically means that hacks (yes, I really
580           consider this to be a hack) like "*foo = \&bar; plugin_register
581           (TYPE_READ, "plugin", "foo");" most likely will not work. This is
582           due to the fact that the symbol table is not shared across
583           different threads.
584
585       ·   Each plugin is usually only loaded once and kept in memory for
586           performance reasons. Therefore, END blocks are only executed once
587           when collectd shuts down. You should not rely on END blocks anyway
588           - use shutdown functions instead.
589
590       ·   The perl plugin exports the internal API of collectd which is
591           considered unstable and subject to change at any time. We try hard
592           to not break backwards compatibility in the Perl API during the
593           life cycle of one major release.  However, this cannot be
594           guaranteed at all times. Watch out for warnings dispatched by the
595           perl plugin after upgrades.
596

SEE ALSO

598       collectd(1), collectd.conf(5), collectd-exec(5), types.db(5), perl(1),
599       threads(3perl), threads::shared(3perl), perldebug(1)
600

AUTHOR

602       The "perl plugin" has been written by Sebastian Harl
603       <sh at tokkee.org>.
604
605       This manpage has been written by Florian Forster <octo at collectd.org>
606       and Sebastian Harl <sh at tokkee.org>.
607
608
609
6105.9.2                             2019-09-16                  COLLECTD-PERL(5)
Impressum