1COLLECTD-PERL(5) collectd COLLECTD-PERL(5)
2
6 collectd-perl - Documentation of collectd's "perl plugin"
7
9 <LoadPlugin perl>
10 Globals true
11 </LoadPlugin>
12 # ...
13 <Plugin perl>
14 IncludeDir "/path/to/perl/plugins"
15 BaseName "Collectd::Plugins"
16 EnableDebugger ""
17 LoadPlugin "FooBar"
18 <Plugin FooBar>
20 Foo "Bar"
21 </Plugin>
22 </Plugin>
23
25 The "perl plugin" embeds a Perl-interpreter into collectd and provides
26 an interface to collectd's plugin system. This makes it possible to
27 write plugins for collectd in Perl. This is a lot more efficient than
28 executing a Perl-script every time you want to read a value with the
29 "exec plugin" (see collectd-exec(5)) and provides a lot more
30 functionality, too.
31 When loading the "perl plugin", the Globals option should be enabled.
33 Else, the perl plugin will fail to load any Perl modules implemented in
34 C, which includes, amongst many others, the threads module used by the
35 plugin itself. See the documentation of the Globals option in
36 collectd.conf(5) for details.
37
39 LoadPlugin Plugin
40 Loads the Perl plugin Plugin. This does basically the same as use
41 would do in a Perl program. As a side effect, the first occurrence
42 of this option causes the Perl-interpreter to be initialized.
43 BaseName Name
45 Prepends Name:: to all plugin names loaded after this option. This
46 is provided for convenience to keep plugin names short. All Perl-
47 based plugins provided with the collectd distributions reside in
48 the "Collectd::Plugins" namespace.
49 <Plugin Name> block
51 This block may be used to pass on configuration settings to a Perl
52 plugin. The configuration is converted into a config-item data type
53 which is passed to the registered configuration callback. See below
54 for details about the config-item data type and how to register
55 callbacks.
56 The name identifies the callback. It is used literally and
58 independent of the BaseName setting.
59 EnableDebugger Package[=option,...]
61 Run collectd under the control of the Perl source debugger. If
62 Package is not the empty string, control is passed to the
63 debugging, profiling, or tracing module installed as
64 Devel::Package. A comma-separated list of options may be specified
65 after the "=" character. Please note that you may not leave out the
66 Package option even if you specify "". This is the same as using
67 the -d:Package command line option.
68 See perldebug for detailed documentation about debugging Perl.
70 This option does not prevent collectd from daemonizing, so you
72 should start collectd with the -f command line option. Else you
73 will not be able to use the command line driven interface of the
74 debugger.
75 IncludeDir Dir
77 Adds Dir to the @INC array. This is the same as using the -IDir
78 command line option or use lib Dir in the source code. Please note
79 that it only has effect on plugins loaded after this option.
80
82 Writing your own plugins is quite simple. collectd manages plugins by
83 means of dispatch functions which call the appropriate callback
84 functions registered by the plugins. Any plugin basically consists of
85 the implementation of these callback functions and initializing code
86 which registers the functions with collectd. See the section "EXAMPLES"
87 below for a really basic example. The following types of callback
88 functions are known to collectd (all of them are optional):
89 configuration functions
91 This type of functions is called during configuration if an
92 appropriate Plugin block has been encountered. It is called once
93 for each Plugin block which matches the name of the callback as
94 provided with the plugin_register method - see below.
95 init functions
97 This type of functions is called once after loading the module and
98 before any calls to the read and write functions. It should be used
99 to initialize the internal state of the plugin (e. g. open sockets,
100 ...). If the return value evaluates to false, the plugin will be
101 disabled.
102 read functions
104 This type of function is used to collect the actual data. It is
105 called once per interval (see the Interval configuration option of
106 collectd). Usually it will call plugin_dispatch_values to dispatch
107 the values to collectd which will pass them on to all registered
108 write functions. If the return value evaluates to false the plugin
109 will be skipped for an increasing amount of time until it returns
110 true again.
111 write functions
113 This type of function is used to write the dispatched values. It is
114 called once for each call to plugin_dispatch_values.
115 flush functions
117 This type of function is used to flush internal caches of plugins.
118 It is usually triggered by the user only. Any plugin which caches
119 data before writing it to disk should provide this kind of callback
120 function.
121 log functions
123 This type of function is used to pass messages of plugins or the
124 daemon itself to the user.
125 notification function
127 This type of function is used to act upon notifications. In
128 general, a notification is a status message that may be associated
129 with a data instance. Usually, a notification is generated by the
130 daemon if a configured threshold has been exceeded (see the section
131 "THRESHOLD CONFIGURATION" in collectd.conf(5) for more details),
132 but any plugin may dispatch notifications as well.
133 shutdown functions
135 This type of function is called once before the daemon shuts down.
136 It should be used to clean up the plugin (e.g. close sockets, ...).
137 Any function (except log functions) may set the $@ variable to describe
139 errors in more detail. The message will be passed on to the user using
140 collectd's logging mechanism.
141 See the documentation of the plugin_register method in the section
143 "METHODS" below for the number and types of arguments passed to each
144 callback function. This section also explains how to register callback
145 functions with collectd.
146 To enable a plugin, copy it to a place where Perl can find it (i. e. a
148 directory listed in the @INC array) just as any other Perl plugin and
149 add an appropriate LoadPlugin option to the configuration file. After
150 restarting collectd you're done.
151
153 The following complex types are used to pass values between the Perl
154 plugin and collectd:
155 Config-Item
157 A config-item is one structure which keeps the information provided
158 in the configuration file. The array of children keeps one entry
159 for each configuration option. Each such entry is another config-
160 item structure, which may nest further if nested blocks are used.
161 {
163 key => key,
164 values => [ val1, val2, ... ],
165 children => [ { ... }, { ... }, ... ]
166 }
167 Data-Set
169 A data-set is a list of one or more data-sources. Each data-source
170 defines a name, type, min- and max-value and the data-set wraps
171 them up into one structure. The general layout looks like this:
172 [{
174 name => 'data_source_name',
175 type => DS_TYPE_COUNTER || DS_TYPE_GAUGE || DS_TYPE_DERIVE || DS_TYPE_ABSOLUTE,
176 min => value || undef,
177 max => value || undef
178 }, ...]
179 Value-List
181 A value-list is one structure which features an array of values and
182 fields to identify the values, i. e. time and host, plugin name and
183 plugin-instance as well as a type and type-instance. Since the
184 "type" is not included in the value-list but is passed as an extra
185 argument, the general layout looks like this:
186 {
188 values => [123, 0.5],
189 time => time (),
190 interval => $interval_g,
191 host => $hostname_g,
192 plugin => 'myplugin',
193 type => 'myplugin',
194 plugin_instance => '',
195 type_instance => ''
196 }
197 Notification
199 A notification is one structure defining the severity, time and
200 message of the status message as well as an identification of a
201 data instance. Also, it includes an optional list of user-defined
202 meta information represented as (name, value) pairs:
203 {
205 severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
206 time => time (),
207 message => 'status message',
208 host => $hostname_g,
209 plugin => 'myplugin',
210 type => 'mytype',
211 plugin_instance => '',
212 type_instance => '',
213 meta => [ { name => <name>, value => <value> }, ... ]
214 }
215 Match-Proc
217 A match-proc is one structure storing the callbacks of a "match" of
218 the filter chain infrastructure. The general layout looks like
219 this:
220 {
222 create => 'my_create',
223 destroy => 'my_destroy',
224 match => 'my_match'
225 }
226 Target-Proc
228 A target-proc is one structure storing the callbacks of a "target"
229 of the filter chain infrastructure. The general layout looks like
230 this:
231 {
233 create => 'my_create',
234 destroy => 'my_destroy',
235 invoke => 'my_invoke'
236 }
237
239 The following functions provide the C-interface to Perl-modules. They
240 are exported by the ":plugin" export tag (see the section "EXPORTS"
241 below).
242 plugin_register (type, name, data)
244 Registers a callback-function or data-set.
245 type can be one of:
247 TYPE_CONFIG
249 TYPE_INIT
250 TYPE_READ
251 TYPE_WRITE
252 TYPE_FLUSH
253 TYPE_LOG
254 TYPE_NOTIF
255 TYPE_SHUTDOWN
256 TYPE_DATASET
257 name is the name of the callback-function or the type of the data-
259 set, depending on the value of type. (Please note that the type of
260 the data-set is the value passed as name here and has nothing to do
261 with the type argument which simply tells plugin_register what is
262 being registered.)
263 The last argument, data, is either a function name or an array-
265 reference. If type is TYPE_DATASET, then the data argument must be
266 an array-reference which points to an array of hashes. Each hash
267 describes one data-set. For the exact layout see Data-Set above.
268 Please note that there is a large number of predefined data-sets
269 available in the types.db file which are automatically registered
270 with collectd - see types.db(5) for a description of the format of
271 this file.
272 Note: Using plugin_register to register a data-set is deprecated.
274 Add the new type to a custom types.db(5) file instead. This
275 functionality might be removed in a future version of collectd.
276 If the type argument is any of the other types (TYPE_INIT,
278 TYPE_READ, ...) then data is expected to be a function name. If the
279 name is not prefixed with the plugin's package name collectd will
280 add it automatically. The interface slightly differs from the C
281 interface (which expects a function pointer instead) because Perl
282 does not support to share references to subroutines between
283 threads.
284 These functions are called in the various stages of the daemon (see
286 the section "WRITING YOUR OWN PLUGINS" above) and are passed the
287 following arguments:
288 TYPE_CONFIG
290 The only argument passed is config-item. See above for the
291 layout of this data type.
292 TYPE_INIT
294 TYPE_READ
295 TYPE_SHUTDOWN
296 No arguments are passed.
297 TYPE_WRITE
299 The arguments passed are type, data-set, and value-list. type
300 is a string. For the layout of data-set and value-list see
301 above.
302 TYPE_FLUSH
304 The arguments passed are timeout and identifier. timeout
305 indicates that only data older than timeout seconds is to be
306 flushed. identifier specifies which values are to be flushed.
307 TYPE_LOG
309 The arguments are log-level and message. The log level is small
310 for important messages and high for less important messages.
311 The least important level is LOG_DEBUG, the most important
312 level is LOG_ERR. In between there are (from least to most
313 important): LOG_INFO, LOG_NOTICE, and LOG_WARNING. message is
314 simply a string without a newline at the end.
315 TYPE_NOTIF
317 The only argument passed is notification. See above for the
318 layout of this data type.
319 plugin_unregister (type, plugin)
321 Removes a callback or data-set from collectd's internal list of
322 functions / datasets.
323 plugin_dispatch_values (value-list)
325 Submits a value-list to the daemon. If the data-set identified by
326 value-list->{type} is found (and the number of values matches the
327 number of data-sources) then the type, data-set and value-list is
328 passed to all write-callbacks that are registered with the daemon.
329 Note: Prior to version 4.4 of collectd, the data-set type used to
331 be passed as the first argument to plugin_register. This syntax is
332 still supported for backwards compatibility but has been deprecated
333 and will be removed in some future version of collectd.
334 plugin_write ([plugins => ...][, datasets => ...], valuelists => ...)
336 Calls the write function of the given plugins with the provided
337 data sets and value lists. In contrast to plugin_dispatch_values,
338 it does not update collectd's internal cache and bypasses the
339 filter mechanism (see collectd.conf(5) for details). If the plugins
340 argument has been omitted, the values will be dispatched to all
341 registered write plugins. If the datasets argument has been
342 omitted, the required data sets are looked up according to the
343 "type" member in the appropriate value list. The value of all three
344 arguments may either be a single scalar or a reference to an array.
345 If the datasets argument has been specified, the number of data
346 sets has to equal the number of specified value lists.
347 plugin_flush ([timeout => timeout][, plugins => ...][, identifiers =>
349 ...])
350 Flush one or more plugins. timeout and the specified identifiers
351 are passed on to the registered flush-callbacks. If omitted, the
352 timeout defaults to "-1". The identifier defaults to the undefined
353 value. If the plugins argument has been specified, only named
354 plugins will be flushed. The value of the plugins and identifiers
355 arguments may either be a string or a reference to an array of
356 strings.
357 plugin_flush_one (timeout, plugin)
359 This is identical to using "plugin_flush (timeout => timeout,
360 plugins => plugin".
361 Note: Starting with version 4.5 of collectd, plugin_flush_one has
363 been deprecated and will be removed in some future version of
364 collectd. Use plugin_flush instead.
365 plugin_flush_all (timeout)
367 This is identical to using "plugin_flush (timeout => timeout)".
368 Note: Starting with version 4.5 of collectd, plugin_flush_all has
370 been deprecated and will be removed in some future version of
371 collectd. Use plugin_flush instead.
372 plugin_dispatch_notification (notification)
374 Submits a notification to the daemon which will then pass it to all
375 notification-callbacks that are registered.
376 plugin_log (log-level, message)
378 Submits a message of level log-level to collectd's logging
379 mechanism. The message is passed to all log-callbacks that are
380 registered with collectd.
381 ERROR, WARNING, NOTICE, INFO, DEBUG (message)
383 Wrappers around plugin_log, using LOG_ERR, LOG_WARNING, LOG_NOTICE,
384 LOG_INFO and LOG_DEBUG respectively as log-level.
385 The following function provides the filter chain C-interface to Perl-
387 modules. It is exported by the ":filter_chain" export tag (see the
388 section "EXPORTS" below).
389 fc_register (type, name, proc)
391 Registers filter chain callbacks with collectd.
392 type may be any of:
394 FC_MATCH
396 FC_TARGET
397 name is the name of the match or target. By this name, the
399 callbacks are identified in the configuration file when specifying
400 a Match or Target block (see collectd.conf(5) for details).
401 proc is a hash reference. The hash includes up to three callbacks:
403 an optional constructor (create) and destructor (destroy) and a
404 mandatory match or invoke callback. match is called whenever
405 processing an appropriate match, while invoke is called whenever
406 processing an appropriate target (see the section "FILTER
407 CONFIGURATION" in collectd.conf(5) for details). Just like any
408 other callbacks, filter chain callbacks are identified by the
409 function name rather than a function pointer because Perl does not
410 support to share references to subroutines between threads. The
411 following arguments are passed to the callbacks:
412 create
414 The arguments passed are config-item and user-data. See above
415 for the layout of the config-item data-type. user-data is a
416 reference to a scalar value that may be used to store any
417 information specific to this particular instance. The daemon
418 does not care about this information at all. It's for the
419 plugin's use only.
420 destroy
422 The only argument passed is user-data which is a reference to
423 the user data initialized in the create callback. This callback
424 may be used to cleanup instance-specific information and
425 settings.
426 match, invoke
428 The arguments passed are data-set, value-list, meta and user-
429 data. See above for the layout of the data-set and value-list
430 data-types. meta is a pointer to an array of meta information,
431 just like the meta member of the notification data-type (see
432 above). user-data is a reference to the user data initialized
433 in the create callback.
434
436 $hostname_g
437 As the name suggests this variable keeps the hostname of the system
438 collectd is running on. The value might be influenced by the
439 Hostname or FQDNLookup configuration options (see collectd.conf(5)
440 for details).
441 $interval_g
443 This variable keeps the interval in seconds in which the read
444 functions are queried (see the Interval configuration option).
445 Any changes to these variables will be globally visible in collectd.
447
449 By default no symbols are exported. However, the following export tags
450 are available (:all will export all of them):
451 :plugin
453 plugin_register ()
454 plugin_unregister ()
455 plugin_dispatch_values ()
456 plugin_flush ()
457 plugin_flush_one ()
458 plugin_flush_all ()
459 plugin_dispatch_notification ()
460 plugin_log ()
461 :types
462 TYPE_CONFIG
463 TYPE_INIT
464 TYPE_READ
465 TYPE_WRITE
466 TYPE_FLUSH
467 TYPE_SHUTDOWN
468 TYPE_LOG
469 TYPE_DATASET
470 :ds_types
471 DS_TYPE_COUNTER
472 DS_TYPE_GAUGE
473 DS_TYPE_DERIVE
474 DS_TYPE_ABSOLUTE
475 :log
476 ERROR ()
477 WARNING ()
478 NOTICE ()
479 INFO ()
480 DEBUG ()
481 LOG_ERR
482 LOG_WARNING
483 LOG_NOTICE
484 LOG_INFO
485 LOG_DEBUG
486 :filter_chain
487 fc_register
488 FC_MATCH_NO_MATCH
489 FC_MATCH_MATCHES
490 FC_TARGET_CONTINUE
491 FC_TARGET_STOP
492 FC_TARGET_RETURN
493 :fc_types
494 FC_MATCH
495 FC_TARGET
496 :notif
497 NOTIF_FAILURE
498 NOTIF_WARNING
499 NOTIF_OKAY
500 :globals
501 $hostname_g
502 $interval_g
503
505 Any Perl plugin will start similar to:
506 package Collectd::Plugins::FooBar;
508 use strict;
510 use warnings;
511 use Collectd qw( :all );
513 A very simple read function might look like:
515 sub foobar_read
517 {
518 my $vl = { plugin => 'foobar' };
519 $vl->{'values'} = [ rand(42) ];
520 plugin_dispatch_values ('gauge', $vl);
521 return 1;
522 }
523 A very simple write function might look like:
525 sub foobar_write
527 {
528 my ($type, $ds, $vl) = @_;
529 for (my $i = 0; $i < scalar (@$ds); ++$i) {
530 print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n";
531 }
532 return 1;
533 }
534 A very simple match callback might look like:
536 sub foobar_match
538 {
539 my ($ds, $vl, $meta, $user_data) = @_;
540 if (matches($ds, $vl)) {
541 return FC_MATCH_MATCHES;
542 } else {
543 return FC_MATCH_NO_MATCH;
544 }
545 }
546 To register those functions with collectd:
548 plugin_register (TYPE_READ, "foobar", "foobar_read");
550 plugin_register (TYPE_WRITE, "foobar", "foobar_write");
551 fc_register (FC_MATCH, "foobar", "foobar_match");
553 See the section "DATA TYPES" above for a complete documentation of the
555 data types used by the read, write and match functions.
556
558 · Please feel free to send in new plugins to collectd's mailing list
559 at <collectd at verplant.org> for review and, possibly, inclusion
560 in the main distribution. In the latter case, we will take care of
561 keeping the plugin up to date and adapting it to new versions of
562 collectd.
563 Before submitting your plugin, please take a look at
565 <http://collectd.org/dev-info.shtml>.
566
568 · collectd is heavily multi-threaded. Each collectd thread accessing
569 the perl plugin will be mapped to a Perl interpreter thread (see
570 threads(3perl)). Any such thread will be created and destroyed
571 transparently and on-the-fly.
572 Hence, any plugin has to be thread-safe if it provides several
574 entry points from collectd (i. e. if it registers more than one
575 callback or if a registered callback may be called more than once
576 in parallel). Please note that no data is shared between threads by
577 default. You have to use the threads::shared module to do so.
578 · Each function name registered with collectd has to be available
580 before the first thread has been created (i. e. basically at
581 compile time). This basically means that hacks (yes, I really
582 consider this to be a hack) like "*foo = \&bar; plugin_register
583 (TYPE_READ, "plugin", "foo");" most likely will not work. This is
584 due to the fact that the symbol table is not shared across
585 different threads.
586 · Each plugin is usually only loaded once and kept in memory for
588 performance reasons. Therefore, END blocks are only executed once
589 when collectd shuts down. You should not rely on END blocks anyway
590 - use shutdown functions instead.
591 · The perl plugin exports the internal API of collectd which is
593 considered unstable and subject to change at any time. We try hard
594 to not break backwards compatibility in the Perl API during the
595 life cycle of one major release. However, this cannot be
596 guaranteed at all times. Watch out for warnings dispatched by the
597 perl plugin after upgrades.
598
600 · Currently, it is not possible to flush a single Perl plugin only.
601 You can either flush all Perl plugins or none at all and you have
602 to use "perl" as plugin name when doing so.
603
605 collectd(1), collectd.conf(5), collectd-exec(5), types.db(5), perl(1),
606 threads(3perl), threads::shared(3perl), perldebug(1)
607
609 The "perl plugin" has been written by Sebastian Harl
610 <sh at tokkee.org>.
611 This manpage has been written by Florian Forster <octo at verplant.org>
613 and Sebastian Harl <sh at tokkee.org>.
6144.9.5 2011-03-26 COLLECTD-PERL(5)