| 1 |
=encoding UTF-8 |
| 2 |
|
| 3 |
=head1 NAME |
| 4 |
|
| 5 |
collectd-perl - Documentation of collectd's C<perl plugin> |
| 6 |
|
| 7 |
=head1 SYNOPSIS |
| 8 |
|
| 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 |
|
| 22 |
=head1 DESCRIPTION |
| 23 |
|
| 24 |
The C<perl plugin> embeds a Perl-interpreter into collectd and provides an |
| 25 |
interface to collectd's plugin system. This makes it possible to write plugins |
| 26 |
for collectd in Perl. This is a lot more efficient than executing a |
| 27 |
Perl-script every time you want to read a value with the C<exec plugin> (see |
| 28 |
L<collectd-exec(5)>) and provides a lot more functionality, too. |
| 29 |
|
| 30 |
=head1 CONFIGURATION |
| 31 |
|
| 32 |
=over 4 |
| 33 |
|
| 34 |
=item B<LoadPlugin> I<Plugin> |
| 35 |
|
| 36 |
Loads the Perl plugin I<Plugin>. This does basically the same as B<use> would |
| 37 |
do in a Perl program. As a side effect, the first occurrence of this option |
| 38 |
causes the Perl-interpreter to be initialized. |
| 39 |
|
| 40 |
=item B<BaseName> I<Name> |
| 41 |
|
| 42 |
Prepends I<Name>B<::> to all plugin names loaded after this option. This is |
| 43 |
provided for convenience to keep plugin names short. All Perl-based plugins |
| 44 |
provided with the I<collectd> distributions reside in the C<Collectd::Plugins> |
| 45 |
namespace. |
| 46 |
|
| 47 |
=item E<lt>B<Plugin> I<Name>E<gt> block |
| 48 |
|
| 49 |
This block may be used to pass on configuration settings to a Perl plugin. The |
| 50 |
configuration is converted into a config-item data type which is passed to the |
| 51 |
registered configuration callback. See below for details about the config-item |
| 52 |
data type and how to register callbacks. |
| 53 |
|
| 54 |
The I<name> identifies the callback. It is used literally and independent of |
| 55 |
the B<BaseName> setting. |
| 56 |
|
| 57 |
=item B<EnableDebugger> I<Package>[=I<option>,...] |
| 58 |
|
| 59 |
Run collectd under the control of the Perl source debugger. If I<Package> is |
| 60 |
not the empty string, control is passed to the debugging, profiling, or |
| 61 |
tracing module installed as Devel::I<Package>. A comma-separated list of |
| 62 |
options may be specified after the "=" character. Please note that you may not |
| 63 |
leave out the I<Package> option even if you specify B<"">. This is the same as |
| 64 |
using the B<-d:Package> command line option. |
| 65 |
|
| 66 |
See L<perldebug> for detailed documentation about debugging Perl. |
| 67 |
|
| 68 |
This option does not prevent collectd from daemonizing, so you should start |
| 69 |
collectd with the B<-f> command line option. Else you will not be able to use |
| 70 |
the command line driven interface of the debugger. |
| 71 |
|
| 72 |
=item B<IncludeDir> I<Dir> |
| 73 |
|
| 74 |
Adds I<Dir> to the B<@INC> array. This is the same as using the B<-IDir> |
| 75 |
command line option or B<use lib Dir> in the source code. Please note that it |
| 76 |
only has effect on plugins loaded after this option. |
| 77 |
|
| 78 |
=item B<RegisterLegacyFlush> I<true|false> |
| 79 |
|
| 80 |
The C<Perl plugin> used to register one flush callback (called B<"perl">) and |
| 81 |
call all Perl-based flush handlers when this callback was called. Newer versions |
| 82 |
of the plugin wrap the Perl flush handlers and register them directly with the |
| 83 |
daemon I<in addition> to the legacy B<"perl"> callback. This allows to call |
| 84 |
specific Perl flush handlers, but has the downside that flushing I<all> plugins |
| 85 |
now calls the Perl flush handlers twice (once directly and once via the legacy |
| 86 |
callback). Unfortunately, removing the B<"perl"> callback would break backwards |
| 87 |
compatibility. |
| 88 |
|
| 89 |
This option allows you to disable the legacy B<"perl"> flush callback if you care |
| 90 |
about the double call and don't call the B<"perl"> callback in your setup. |
| 91 |
|
| 92 |
=back |
| 93 |
|
| 94 |
=head1 WRITING YOUR OWN PLUGINS |
| 95 |
|
| 96 |
Writing your own plugins is quite simple. collectd manages plugins by means of |
| 97 |
B<dispatch functions> which call the appropriate B<callback functions> |
| 98 |
registered by the plugins. Any plugin basically consists of the implementation |
| 99 |
of these callback functions and initializing code which registers the |
| 100 |
functions with collectd. See the section "EXAMPLES" below for a really basic |
| 101 |
example. The following types of B<callback functions> are known to collectd |
| 102 |
(all of them are optional): |
| 103 |
|
| 104 |
=over 4 |
| 105 |
|
| 106 |
=item configuration functions |
| 107 |
|
| 108 |
This type of functions is called during configuration if an appropriate |
| 109 |
B<Plugin> block has been encountered. It is called once for each B<Plugin> |
| 110 |
block which matches the name of the callback as provided with the |
| 111 |
B<plugin_register> method - see below. |
| 112 |
|
| 113 |
=item init functions |
| 114 |
|
| 115 |
This type of functions is called once after loading the module and before any |
| 116 |
calls to the read and write functions. It should be used to initialize the |
| 117 |
internal state of the plugin (e.E<nbsp>g. open sockets, ...). If the return |
| 118 |
value evaluates to B<false>, the plugin will be disabled. |
| 119 |
|
| 120 |
=item read functions |
| 121 |
|
| 122 |
This type of function is used to collect the actual data. It is called once |
| 123 |
per interval (see the B<Interval> configuration option of collectd). Usually |
| 124 |
it will call B<plugin_dispatch_values> to dispatch the values to collectd |
| 125 |
which will pass them on to all registered B<write functions>. If the return |
| 126 |
value evaluates to B<false> the plugin will be skipped for an increasing |
| 127 |
amount of time until it returns B<true> again. |
| 128 |
|
| 129 |
=item write functions |
| 130 |
|
| 131 |
This type of function is used to write the dispatched values. It is called |
| 132 |
once for each call to B<plugin_dispatch_values>. |
| 133 |
|
| 134 |
=item flush functions |
| 135 |
|
| 136 |
This type of function is used to flush internal caches of plugins. It is |
| 137 |
usually triggered by the user only. Any plugin which caches data before |
| 138 |
writing it to disk should provide this kind of callback function. |
| 139 |
|
| 140 |
=item log functions |
| 141 |
|
| 142 |
This type of function is used to pass messages of plugins or the daemon itself |
| 143 |
to the user. |
| 144 |
|
| 145 |
=item notification function |
| 146 |
|
| 147 |
This type of function is used to act upon notifications. In general, a |
| 148 |
notification is a status message that may be associated with a data instance. |
| 149 |
Usually, a notification is generated by the daemon if a configured threshold |
| 150 |
has been exceeded (see the section "THRESHOLD CONFIGURATION" in |
| 151 |
L<collectd.conf(5)> for more details), but any plugin may dispatch |
| 152 |
notifications as well. |
| 153 |
|
| 154 |
=item shutdown functions |
| 155 |
|
| 156 |
This type of function is called once before the daemon shuts down. It should |
| 157 |
be used to clean up the plugin (e.g. close sockets, ...). |
| 158 |
|
| 159 |
=back |
| 160 |
|
| 161 |
Any function (except log functions) may set the B<$@> variable to describe |
| 162 |
errors in more detail. The message will be passed on to the user using |
| 163 |
collectd's logging mechanism. |
| 164 |
|
| 165 |
See the documentation of the B<plugin_register> method in the section |
| 166 |
"METHODS" below for the number and types of arguments passed to each |
| 167 |
B<callback function>. This section also explains how to register B<callback |
| 168 |
functions> with collectd. |
| 169 |
|
| 170 |
To enable a plugin, copy it to a place where Perl can find it (i.E<nbsp>e. a |
| 171 |
directory listed in the B<@INC> array) just as any other Perl plugin and add |
| 172 |
an appropriate B<LoadPlugin> option to the configuration file. After |
| 173 |
restarting collectd you're done. |
| 174 |
|
| 175 |
=head1 DATA TYPES |
| 176 |
|
| 177 |
The following complex types are used to pass values between the Perl plugin |
| 178 |
and collectd: |
| 179 |
|
| 180 |
=over 4 |
| 181 |
|
| 182 |
=item Config-Item |
| 183 |
|
| 184 |
A config-item is one structure which keeps the information provided in the |
| 185 |
configuration file. The array of children keeps one entry for each |
| 186 |
configuration option. Each such entry is another config-item structure, which |
| 187 |
may nest further if nested blocks are used. |
| 188 |
|
| 189 |
{ |
| 190 |
key => key, |
| 191 |
values => [ val1, val2, ... ], |
| 192 |
children => [ { ... }, { ... }, ... ] |
| 193 |
} |
| 194 |
|
| 195 |
=item Data-Set |
| 196 |
|
| 197 |
A data-set is a list of one or more data-sources. Each data-source defines a |
| 198 |
name, type, min- and max-value and the data-set wraps them up into one |
| 199 |
structure. The general layout looks like this: |
| 200 |
|
| 201 |
[{ |
| 202 |
name => 'data_source_name', |
| 203 |
type => DS_TYPE_COUNTER || DS_TYPE_GAUGE || DS_TYPE_DERIVE || DS_TYPE_ABSOLUTE, |
| 204 |
min => value || undef, |
| 205 |
max => value || undef |
| 206 |
}, ...] |
| 207 |
|
| 208 |
=item Value-List |
| 209 |
|
| 210 |
A value-list is one structure which features an array of values and fields to |
| 211 |
identify the values, i.E<nbsp>e. time and host, plugin name and |
| 212 |
plugin-instance as well as a type and type-instance. Since the "type" is not |
| 213 |
included in the value-list but is passed as an extra argument, the general |
| 214 |
layout looks like this: |
| 215 |
|
| 216 |
{ |
| 217 |
values => [123, 0.5], |
| 218 |
time => time (), |
| 219 |
interval => plugin_get_interval (), |
| 220 |
host => $hostname_g, |
| 221 |
plugin => 'myplugin', |
| 222 |
type => 'myplugin', |
| 223 |
plugin_instance => '', |
| 224 |
type_instance => '' |
| 225 |
} |
| 226 |
|
| 227 |
=item Notification |
| 228 |
|
| 229 |
A notification is one structure defining the severity, time and message of the |
| 230 |
status message as well as an identification of a data instance. Also, it |
| 231 |
includes an optional list of user-defined meta information represented as |
| 232 |
(name, value) pairs: |
| 233 |
|
| 234 |
{ |
| 235 |
severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY, |
| 236 |
time => time (), |
| 237 |
message => 'status message', |
| 238 |
host => $hostname_g, |
| 239 |
plugin => 'myplugin', |
| 240 |
type => 'mytype', |
| 241 |
plugin_instance => '', |
| 242 |
type_instance => '', |
| 243 |
meta => [ { name => <name>, value => <value> }, ... ] |
| 244 |
} |
| 245 |
|
| 246 |
=item Match-Proc |
| 247 |
|
| 248 |
A match-proc is one structure storing the callbacks of a "match" of the filter |
| 249 |
chain infrastructure. The general layout looks like this: |
| 250 |
|
| 251 |
{ |
| 252 |
create => 'my_create', |
| 253 |
destroy => 'my_destroy', |
| 254 |
match => 'my_match' |
| 255 |
} |
| 256 |
|
| 257 |
=item Target-Proc |
| 258 |
|
| 259 |
A target-proc is one structure storing the callbacks of a "target" of the |
| 260 |
filter chain infrastructure. The general layout looks like this: |
| 261 |
|
| 262 |
{ |
| 263 |
create => 'my_create', |
| 264 |
destroy => 'my_destroy', |
| 265 |
invoke => 'my_invoke' |
| 266 |
} |
| 267 |
|
| 268 |
=back |
| 269 |
|
| 270 |
=head1 METHODS |
| 271 |
|
| 272 |
The following functions provide the C-interface to Perl-modules. They are |
| 273 |
exported by the ":plugin" export tag (see the section "EXPORTS" below). |
| 274 |
|
| 275 |
=over 4 |
| 276 |
|
| 277 |
=item B<plugin_register> (I<type>, I<name>, I<data>) |
| 278 |
|
| 279 |
Registers a callback-function or data-set. |
| 280 |
|
| 281 |
I<type> can be one of: |
| 282 |
|
| 283 |
=over 4 |
| 284 |
|
| 285 |
=item TYPE_CONFIG |
| 286 |
|
| 287 |
=item TYPE_INIT |
| 288 |
|
| 289 |
=item TYPE_READ |
| 290 |
|
| 291 |
=item TYPE_WRITE |
| 292 |
|
| 293 |
=item TYPE_FLUSH |
| 294 |
|
| 295 |
=item TYPE_LOG |
| 296 |
|
| 297 |
=item TYPE_NOTIF |
| 298 |
|
| 299 |
=item TYPE_SHUTDOWN |
| 300 |
|
| 301 |
=item TYPE_DATASET |
| 302 |
|
| 303 |
=back |
| 304 |
|
| 305 |
I<name> is the name of the callback-function or the type of the data-set, |
| 306 |
depending on the value of I<type>. (Please note that the type of the data-set |
| 307 |
is the value passed as I<name> here and has nothing to do with the I<type> |
| 308 |
argument which simply tells B<plugin_register> what is being registered.) |
| 309 |
|
| 310 |
The last argument, I<data>, is either a function name or an array-reference. |
| 311 |
If I<type> is B<TYPE_DATASET>, then the I<data> argument must be an |
| 312 |
array-reference which points to an array of hashes. Each hash describes one |
| 313 |
data-set. For the exact layout see B<Data-Set> above. Please note that |
| 314 |
there is a large number of predefined data-sets available in the B<types.db> |
| 315 |
file which are automatically registered with collectd - see L<types.db(5)> for |
| 316 |
a description of the format of this file. |
| 317 |
|
| 318 |
B<Note>: Using B<plugin_register> to register a data-set is deprecated. Add |
| 319 |
the new type to a custom L<types.db(5)> file instead. This functionality might |
| 320 |
be removed in a future version of collectd. |
| 321 |
|
| 322 |
If the I<type> argument is any of the other types (B<TYPE_INIT>, B<TYPE_READ>, |
| 323 |
...) then I<data> is expected to be a function name. If the name is not |
| 324 |
prefixed with the plugin's package name collectd will add it automatically. |
| 325 |
The interface slightly differs from the C interface (which expects a function |
| 326 |
pointer instead) because Perl does not support to share references to |
| 327 |
subroutines between threads. |
| 328 |
|
| 329 |
These functions are called in the various stages of the daemon (see the |
| 330 |
section "WRITING YOUR OWN PLUGINS" above) and are passed the following |
| 331 |
arguments: |
| 332 |
|
| 333 |
=over 4 |
| 334 |
|
| 335 |
=item TYPE_CONFIG |
| 336 |
|
| 337 |
The only argument passed is I<config-item>. See above for the layout of this |
| 338 |
data type. |
| 339 |
|
| 340 |
=item TYPE_INIT |
| 341 |
|
| 342 |
=item TYPE_READ |
| 343 |
|
| 344 |
=item TYPE_SHUTDOWN |
| 345 |
|
| 346 |
No arguments are passed. |
| 347 |
|
| 348 |
=item TYPE_WRITE |
| 349 |
|
| 350 |
The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a |
| 351 |
string. For the layout of I<data-set> and I<value-list> see above. |
| 352 |
|
| 353 |
=item TYPE_FLUSH |
| 354 |
|
| 355 |
The arguments passed are I<timeout> and I<identifier>. I<timeout> indicates |
| 356 |
that only data older than I<timeout> seconds is to be flushed. I<identifier> |
| 357 |
specifies which values are to be flushed. |
| 358 |
|
| 359 |
=item TYPE_LOG |
| 360 |
|
| 361 |
The arguments are I<log-level> and I<message>. The log level is small for |
| 362 |
important messages and high for less important messages. The least important |
| 363 |
level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there |
| 364 |
are (from least to most important): B<LOG_INFO>, B<LOG_NOTICE>, and |
| 365 |
B<LOG_WARNING>. I<message> is simply a string B<without> a newline at the end. |
| 366 |
|
| 367 |
=item TYPE_NOTIF |
| 368 |
|
| 369 |
The only argument passed is I<notification>. See above for the layout of this |
| 370 |
data type. |
| 371 |
|
| 372 |
=back |
| 373 |
|
| 374 |
=item B<plugin_unregister> (I<type>, I<plugin>) |
| 375 |
|
| 376 |
Removes a callback or data-set from collectd's internal list of |
| 377 |
functionsE<nbsp>/ datasets. |
| 378 |
|
| 379 |
=item B<plugin_dispatch_values> (I<value-list>) |
| 380 |
|
| 381 |
Submits a I<value-list> to the daemon. If the data-set identified by |
| 382 |
I<value-list>->{I<type>} |
| 383 |
is found (and the number of values matches the number of data-sources) then the |
| 384 |
type, data-set and value-list is passed to all write-callbacks that are |
| 385 |
registered with the daemon. |
| 386 |
|
| 387 |
=item B<plugin_write> ([B<plugins> => I<...>][, B<datasets> => I<...>], |
| 388 |
B<valuelists> => I<...>) |
| 389 |
|
| 390 |
Calls the write function of the given I<plugins> with the provided I<data |
| 391 |
sets> and I<value lists>. In contrast to B<plugin_dispatch_values>, it does |
| 392 |
not update collectd's internal cache and bypasses the filter mechanism (see |
| 393 |
L<collectd.conf(5)> for details). If the B<plugins> argument has been omitted, |
| 394 |
the values will be dispatched to all registered write plugins. If the |
| 395 |
B<datasets> argument has been omitted, the required data sets are looked up |
| 396 |
according to the C<type> member in the appropriate value list. The value of |
| 397 |
all three arguments may either be a single scalar or a reference to an array. |
| 398 |
If the B<datasets> argument has been specified, the number of data sets has to |
| 399 |
equal the number of specified value lists. |
| 400 |
|
| 401 |
=item B<plugin_flush> ([B<timeout> => I<timeout>][, B<plugins> => I<...>][, |
| 402 |
B<identifiers> => I<...>]) |
| 403 |
|
| 404 |
Flush one or more plugins. I<timeout> and the specified I<identifiers> are |
| 405 |
passed on to the registered flush-callbacks. If omitted, the timeout defaults |
| 406 |
to C<-1>. The identifier defaults to the undefined value. If the B<plugins> |
| 407 |
argument has been specified, only named plugins will be flushed. The value of |
| 408 |
the B<plugins> and B<identifiers> arguments may either be a string or a |
| 409 |
reference to an array of strings. |
| 410 |
|
| 411 |
=item B<plugin_dispatch_notification> (I<notification>) |
| 412 |
|
| 413 |
Submits a I<notification> to the daemon which will then pass it to all |
| 414 |
notification-callbacks that are registered. |
| 415 |
|
| 416 |
=item B<plugin_log> (I<log-level>, I<message>) |
| 417 |
|
| 418 |
Submits a I<message> of level I<log-level> to collectd's logging mechanism. |
| 419 |
The message is passed to all log-callbacks that are registered with collectd. |
| 420 |
|
| 421 |
=item B<ERROR>, B<WARNING>, B<NOTICE>, B<INFO>, B<DEBUG> (I<message>) |
| 422 |
|
| 423 |
Wrappers around B<plugin_log>, using B<LOG_ERR>, B<LOG_WARNING>, |
| 424 |
B<LOG_NOTICE>, B<LOG_INFO> and B<LOG_DEBUG> respectively as I<log-level>. |
| 425 |
|
| 426 |
=item B<plugin_get_interval> () |
| 427 |
|
| 428 |
Returns the interval of the current plugin as a floating point number in |
| 429 |
seconds. This value depends on the interval configured within the |
| 430 |
C<LoadPlugin perl> block or the global interval (see L<collectd.conf(5)> for |
| 431 |
details). |
| 432 |
|
| 433 |
=back |
| 434 |
|
| 435 |
The following function provides the filter chain C-interface to Perl-modules. |
| 436 |
It is exported by the ":filter_chain" export tag (see the section "EXPORTS" |
| 437 |
below). |
| 438 |
|
| 439 |
=over 4 |
| 440 |
|
| 441 |
=item B<fc_register> (I<type>, I<name>, I<proc>) |
| 442 |
|
| 443 |
Registers filter chain callbacks with collectd. |
| 444 |
|
| 445 |
I<type> may be any of: |
| 446 |
|
| 447 |
=over 4 |
| 448 |
|
| 449 |
=item FC_MATCH |
| 450 |
|
| 451 |
=item FC_TARGET |
| 452 |
|
| 453 |
=back |
| 454 |
|
| 455 |
I<name> is the name of the match or target. By this name, the callbacks are |
| 456 |
identified in the configuration file when specifying a B<Match> or B<Target> |
| 457 |
block (see L<collectd.conf(5)> for details). |
| 458 |
|
| 459 |
I<proc> is a hash reference. The hash includes up to three callbacks: an |
| 460 |
optional constructor (B<create>) and destructor (B<destroy>) and a mandatory |
| 461 |
B<match> or B<invoke> callback. B<match> is called whenever processing an |
| 462 |
appropriate match, while B<invoke> is called whenever processing an |
| 463 |
appropriate target (see the section "FILTER CONFIGURATION" in |
| 464 |
L<collectd.conf(5)> for details). Just like any other callbacks, filter chain |
| 465 |
callbacks are identified by the function name rather than a function pointer |
| 466 |
because Perl does not support to share references to subroutines between |
| 467 |
threads. The following arguments are passed to the callbacks: |
| 468 |
|
| 469 |
=over 4 |
| 470 |
|
| 471 |
=item create |
| 472 |
|
| 473 |
The arguments passed are I<config-item> and I<user-data>. See above for the |
| 474 |
layout of the config-item data-type. I<user-data> is a reference to a scalar |
| 475 |
value that may be used to store any information specific to this particular |
| 476 |
instance. The daemon does not care about this information at all. It's for the |
| 477 |
plugin's use only. |
| 478 |
|
| 479 |
=item destroy |
| 480 |
|
| 481 |
The only argument passed is I<user-data> which is a reference to the user data |
| 482 |
initialized in the B<create> callback. This callback may be used to cleanup |
| 483 |
instance-specific information and settings. |
| 484 |
|
| 485 |
=item match, invoke |
| 486 |
|
| 487 |
The arguments passed are I<data-set>, I<value-list>, I<meta> and I<user-data>. |
| 488 |
See above for the layout of the data-set and value-list data-types. I<meta> is |
| 489 |
a pointer to an array of meta information, just like the B<meta> member of the |
| 490 |
notification data-type (see above). I<user-data> is a reference to the user |
| 491 |
data initialized in the B<create> callback. |
| 492 |
|
| 493 |
=back |
| 494 |
|
| 495 |
=back |
| 496 |
|
| 497 |
=head1 GLOBAL VARIABLES |
| 498 |
|
| 499 |
=over 4 |
| 500 |
|
| 501 |
=item B<$hostname_g> |
| 502 |
|
| 503 |
As the name suggests this variable keeps the hostname of the system collectd |
| 504 |
is running on. The value might be influenced by the B<Hostname> or |
| 505 |
B<FQDNLookup> configuration options (see L<collectd.conf(5)> for details). |
| 506 |
|
| 507 |
=item B<$interval_g> |
| 508 |
|
| 509 |
This variable keeps the interval in seconds in which the read functions are |
| 510 |
queried (see the B<Interval> configuration option). |
| 511 |
|
| 512 |
B<Note:> This variable should no longer be used in favor of |
| 513 |
C<plugin_get_interval()> (see above). This function takes any plugin-specific |
| 514 |
interval settings into account (see the C<Interval> option of C<LoadPlugin> in |
| 515 |
L<collectd.conf(5)> for details). |
| 516 |
|
| 517 |
=back |
| 518 |
|
| 519 |
Any changes to these variables will be globally visible in collectd. |
| 520 |
|
| 521 |
=head1 EXPORTS |
| 522 |
|
| 523 |
By default no symbols are exported. However, the following export tags are |
| 524 |
available (B<:all> will export all of them): |
| 525 |
|
| 526 |
=over 4 |
| 527 |
|
| 528 |
=item B<:plugin> |
| 529 |
|
| 530 |
=over 4 |
| 531 |
|
| 532 |
=item B<plugin_register> () |
| 533 |
|
| 534 |
=item B<plugin_unregister> () |
| 535 |
|
| 536 |
=item B<plugin_dispatch_values> () |
| 537 |
|
| 538 |
=item B<plugin_flush> () |
| 539 |
|
| 540 |
=item B<plugin_flush_one> () |
| 541 |
|
| 542 |
=item B<plugin_flush_all> () |
| 543 |
|
| 544 |
=item B<plugin_dispatch_notification> () |
| 545 |
|
| 546 |
=item B<plugin_log> () |
| 547 |
|
| 548 |
=back |
| 549 |
|
| 550 |
=item B<:types> |
| 551 |
|
| 552 |
=over 4 |
| 553 |
|
| 554 |
=item B<TYPE_CONFIG> |
| 555 |
|
| 556 |
=item B<TYPE_INIT> |
| 557 |
|
| 558 |
=item B<TYPE_READ> |
| 559 |
|
| 560 |
=item B<TYPE_WRITE> |
| 561 |
|
| 562 |
=item B<TYPE_FLUSH> |
| 563 |
|
| 564 |
=item B<TYPE_SHUTDOWN> |
| 565 |
|
| 566 |
=item B<TYPE_LOG> |
| 567 |
|
| 568 |
=item B<TYPE_DATASET> |
| 569 |
|
| 570 |
=back |
| 571 |
|
| 572 |
=item B<:ds_types> |
| 573 |
|
| 574 |
=over 4 |
| 575 |
|
| 576 |
=item B<DS_TYPE_COUNTER> |
| 577 |
|
| 578 |
=item B<DS_TYPE_GAUGE> |
| 579 |
|
| 580 |
=item B<DS_TYPE_DERIVE> |
| 581 |
|
| 582 |
=item B<DS_TYPE_ABSOLUTE> |
| 583 |
|
| 584 |
=back |
| 585 |
|
| 586 |
=item B<:log> |
| 587 |
|
| 588 |
=over 4 |
| 589 |
|
| 590 |
=item B<ERROR> () |
| 591 |
|
| 592 |
=item B<WARNING> () |
| 593 |
|
| 594 |
=item B<NOTICE> () |
| 595 |
|
| 596 |
=item B<INFO> () |
| 597 |
|
| 598 |
=item B<DEBUG> () |
| 599 |
|
| 600 |
=item B<LOG_ERR> |
| 601 |
|
| 602 |
=item B<LOG_WARNING> |
| 603 |
|
| 604 |
=item B<LOG_NOTICE> |
| 605 |
|
| 606 |
=item B<LOG_INFO> |
| 607 |
|
| 608 |
=item B<LOG_DEBUG> |
| 609 |
|
| 610 |
=back |
| 611 |
|
| 612 |
=item B<:filter_chain> |
| 613 |
|
| 614 |
=over 4 |
| 615 |
|
| 616 |
=item B<fc_register> |
| 617 |
|
| 618 |
=item B<FC_MATCH_NO_MATCH> |
| 619 |
|
| 620 |
=item B<FC_MATCH_MATCHES> |
| 621 |
|
| 622 |
=item B<FC_TARGET_CONTINUE> |
| 623 |
|
| 624 |
=item B<FC_TARGET_STOP> |
| 625 |
|
| 626 |
=item B<FC_TARGET_RETURN> |
| 627 |
|
| 628 |
=back |
| 629 |
|
| 630 |
=item B<:fc_types> |
| 631 |
|
| 632 |
=over 4 |
| 633 |
|
| 634 |
=item B<FC_MATCH> |
| 635 |
|
| 636 |
=item B<FC_TARGET> |
| 637 |
|
| 638 |
=back |
| 639 |
|
| 640 |
=item B<:notif> |
| 641 |
|
| 642 |
=over 4 |
| 643 |
|
| 644 |
=item B<NOTIF_FAILURE> |
| 645 |
|
| 646 |
=item B<NOTIF_WARNING> |
| 647 |
|
| 648 |
=item B<NOTIF_OKAY> |
| 649 |
|
| 650 |
=back |
| 651 |
|
| 652 |
=item B<:globals> |
| 653 |
|
| 654 |
=over 4 |
| 655 |
|
| 656 |
=item B<$hostname_g> |
| 657 |
|
| 658 |
=item B<$interval_g> |
| 659 |
|
| 660 |
=back |
| 661 |
|
| 662 |
=back |
| 663 |
|
| 664 |
=head1 EXAMPLES |
| 665 |
|
| 666 |
Any Perl plugin will start similar to: |
| 667 |
|
| 668 |
package Collectd::Plugins::FooBar; |
| 669 |
|
| 670 |
use strict; |
| 671 |
use warnings; |
| 672 |
|
| 673 |
use Collectd qw( :all ); |
| 674 |
|
| 675 |
A very simple read function might look like: |
| 676 |
|
| 677 |
sub foobar_read |
| 678 |
{ |
| 679 |
my $vl = { plugin => 'foobar', type => 'gauge' }; |
| 680 |
$vl->{'values'} = [ rand(42) ]; |
| 681 |
plugin_dispatch_values ($vl); |
| 682 |
return 1; |
| 683 |
} |
| 684 |
|
| 685 |
A very simple write function might look like: |
| 686 |
|
| 687 |
sub foobar_write |
| 688 |
{ |
| 689 |
my ($type, $ds, $vl) = @_; |
| 690 |
for (my $i = 0; $i < scalar (@$ds); ++$i) { |
| 691 |
print "$vl->{'plugin'} ($vl->{'type'}): $vl->{'values'}->[$i]\n"; |
| 692 |
} |
| 693 |
return 1; |
| 694 |
} |
| 695 |
|
| 696 |
A very simple match callback might look like: |
| 697 |
|
| 698 |
sub foobar_match |
| 699 |
{ |
| 700 |
my ($ds, $vl, $meta, $user_data) = @_; |
| 701 |
if (matches($ds, $vl)) { |
| 702 |
return FC_MATCH_MATCHES; |
| 703 |
} else { |
| 704 |
return FC_MATCH_NO_MATCH; |
| 705 |
} |
| 706 |
} |
| 707 |
|
| 708 |
To register those functions with collectd: |
| 709 |
|
| 710 |
plugin_register (TYPE_READ, "foobar", "foobar_read"); |
| 711 |
plugin_register (TYPE_WRITE, "foobar", "foobar_write"); |
| 712 |
|
| 713 |
fc_register (FC_MATCH, "foobar", "foobar_match"); |
| 714 |
|
| 715 |
See the section "DATA TYPES" above for a complete documentation of the data |
| 716 |
types used by the read, write and match functions. |
| 717 |
|
| 718 |
=head1 NOTES |
| 719 |
|
| 720 |
=over 4 |
| 721 |
|
| 722 |
=item * |
| 723 |
|
| 724 |
Please feel free to send in new plugins to collectd's mailing list at |
| 725 |
E<lt>collectdE<nbsp>atE<nbsp>collectd.orgE<gt> for review and, possibly, |
| 726 |
inclusion in the main distribution. In the latter case, we will take care of |
| 727 |
keeping the plugin up to date and adapting it to new versions of collectd. |
| 728 |
|
| 729 |
Before submitting your plugin, please take a look at |
| 730 |
L<http://collectd.org/dev-info.shtml>. |
| 731 |
|
| 732 |
=back |
| 733 |
|
| 734 |
=head1 CAVEATS |
| 735 |
|
| 736 |
=over 4 |
| 737 |
|
| 738 |
=item * |
| 739 |
|
| 740 |
collectd is heavily multi-threaded. Each collectd thread accessing the perl |
| 741 |
plugin will be mapped to a Perl interpreter thread (see L<threads(3perl)>). |
| 742 |
Any such thread will be created and destroyed transparently and on-the-fly. |
| 743 |
|
| 744 |
Hence, any plugin has to be thread-safe if it provides several entry points |
| 745 |
from collectd (i.E<nbsp>e. if it registers more than one callback or if a |
| 746 |
registered callback may be called more than once in parallel). Please note |
| 747 |
that no data is shared between threads by default. You have to use the |
| 748 |
B<threads::shared> module to do so. |
| 749 |
|
| 750 |
=item * |
| 751 |
|
| 752 |
Each function name registered with collectd has to be available before the |
| 753 |
first thread has been created (i.E<nbsp>e. basically at compile time). This |
| 754 |
basically means that hacks (yes, I really consider this to be a hack) like |
| 755 |
C<*foo = \&bar; plugin_register (TYPE_READ, "plugin", "foo");> most likely |
| 756 |
will not work. This is due to the fact that the symbol table is not shared |
| 757 |
across different threads. |
| 758 |
|
| 759 |
=item * |
| 760 |
|
| 761 |
Each plugin is usually only loaded once and kept in memory for performance |
| 762 |
reasons. Therefore, END blocks are only executed once when collectd shuts |
| 763 |
down. You should not rely on END blocks anyway - use B<shutdown functions> |
| 764 |
instead. |
| 765 |
|
| 766 |
=item * |
| 767 |
|
| 768 |
The perl plugin exports the internal API of collectd which is considered |
| 769 |
unstable and subject to change at any time. We try hard to not break backwards |
| 770 |
compatibility in the Perl API during the life cycle of one major release. |
| 771 |
However, this cannot be guaranteed at all times. Watch out for warnings |
| 772 |
dispatched by the perl plugin after upgrades. |
| 773 |
|
| 774 |
=back |
| 775 |
|
| 776 |
=head1 SEE ALSO |
| 777 |
|
| 778 |
L<collectd(1)>, |
| 779 |
L<collectd.conf(5)>, |
| 780 |
L<collectd-exec(5)>, |
| 781 |
L<types.db(5)>, |
| 782 |
L<perl(1)>, |
| 783 |
L<threads(3perl)>, |
| 784 |
L<threads::shared(3perl)>, |
| 785 |
L<perldebug(1)> |
| 786 |
|
| 787 |
=head1 AUTHOR |
| 788 |
|
| 789 |
The C<perl plugin> has been written by Sebastian Harl |
| 790 |
E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>. |
| 791 |
|
| 792 |
This manpage has been written by Florian Forster |
| 793 |
E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt> and Sebastian Harl |
| 794 |
E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>. |
| 795 |
|
| 796 |
=cut |
| 797 |
|