X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-perl.pod;h=b8d72f06fd8605574acc5f4a5a87cb400252d85e;hb=4858a84e3e51830a103a5ff4aee6b844b708ce62;hp=18dbafdc8c93cfa9c7cf00f64b62985200b1c71a;hpb=6597f3a6584704f92f824f3cf7bac3369102e8a0;p=collectd.git diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod index 18dbafdc..b8d72f06 100644 --- a/src/collectd-perl.pod +++ b/src/collectd-perl.pod @@ -182,7 +182,7 @@ structure. The general layout looks like this: [{ name => 'data_source_name', - type => DS_TYPE_COUNTER || DS_TYPE_GAUGE, + type => DS_TYPE_COUNTER || DS_TYPE_GAUGE || DS_TYPE_DERIVE || DS_TYPE_ABSOLUTE, min => value || undef, max => value || undef }, ...] @@ -198,6 +198,7 @@ layout looks like this: { values => [123, 0.5], time => time (), + interval => $interval_g, host => $hostname_g, plugin => 'myplugin', type => 'myplugin', @@ -208,7 +209,9 @@ layout looks like this: =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: +status message as well as an identification of a data instance. Also, it +includes an optional list of user-defined meta information represented as +(name, value) pairs: { severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY, @@ -218,7 +221,30 @@ status message as well as an identification of a data instance: plugin => 'myplugin', type => 'mytype', plugin_instance => '', - type_instance => '' + type_instance => '', + meta => [ { name => , value => }, ... ] + } + +=item Match-Proc + +A match-proc is one structure storing the callbacks of a "match" of the filter +chain infrastructure. The general layout looks like this: + + { + create => 'my_create', + destroy => 'my_destroy', + match => 'my_match' + } + +=item Target-Proc + +A target-proc is one structure storing the callbacks of a "target" of the +filter chain infrastructure. The general layout looks like this: + + { + create => 'my_create', + destroy => 'my_destroy', + invoke => 'my_invoke' } =back @@ -271,6 +297,10 @@ there is a large number of predefined data-sets available in the B file which are automatically registered with collectd - see L for a description of the format of this file. +B: Using B to register a data-set is deprecated. Add +the new type to a custom L file instead. This functionality might +be removed in a future version of collectd. + If the I argument is any of the other types (B, B, ...) then I is expected to be a function name. If the name is not prefixed with the plugin's package name collectd will add it automatically. @@ -399,6 +429,68 @@ B, B and B respectively as I. =back +The following function provides the filter chain C-interface to Perl-modules. +It is exported by the ":filter_chain" export tag (see the section "EXPORTS" +below). + +=over 4 + +=item B (I, I, I) + +Registers filter chain callbacks with collectd. + +I may be any of: + +=over 4 + +=item FC_MATCH + +=item FC_TARGET + +=back + +I is the name of the match or target. By this name, the callbacks are +identified in the configuration file when specifying a B or B +block (see L for details). + +I is a hash reference. The hash includes up to three callbacks: an +optional constructor (B) and destructor (B) and a mandatory +B or B callback. B is called whenever processing an +appropriate match, while B is called whenever processing an +appropriate target (see the section "FILTER CONFIGURATION" in +L for details). Just like any other callbacks, filter chain +callbacks are identified by the function name rather than a function pointer +because Perl does not support to share references to subroutines between +threads. The following arguments are passed to the callbacks: + +=over 4 + +=item create + +The arguments passed are I and I. See above for the +layout of the config-item data-type. I is a reference to a scalar +value that may be used to store any information specific to this particular +instance. The daemon does not care about this information at all. It's for the +plugin's use only. + +=item destroy + +The only argument passed is I which is a reference to the user data +initialized in the B callback. This callback may be used to cleanup +instance-specific information and settings. + +=item match, invoke + +The arguments passed are I, I, I and I. +See above for the layout of the data-set and value-list data-types. I is +a pointer to an array of meta information, just like the B member of the +notification data-type (see above). I is a reference to the user +data initialized in the B callback. + +=back + +=back + =head1 GLOBAL VARIABLES =over 4 @@ -477,6 +569,10 @@ available (B<:all> will export all of them): =item B +=item B + +=item B + =back =item B<:log> @@ -505,6 +601,34 @@ available (B<:all> will export all of them): =back +=item B<:filter_chain> + +=over 4 + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=back + +=item B<:fc_types> + +=over 4 + +=item B + +=item B + +=back + =item B<:notif> =over 4 @@ -540,7 +664,7 @@ Any Perl plugin will start similar to: use Collectd qw( :all ); -A very simple read function will look like: +A very simple read function might look like: sub foobar_read { @@ -550,7 +674,7 @@ A very simple read function will look like: return 1; } -A very simple write function will look like: +A very simple write function might look like: sub foobar_write { @@ -561,13 +685,27 @@ A very simple write function will look like: return 1; } +A very simple match callback might look like: + + sub foobar_match + { + my ($ds, $vl, $meta, $user_data) = @_; + if (matches($ds, $vl)) { + return FC_MATCH_MATCHES; + } else { + return FC_MATCH_NO_MATCH; + } + } + To register those functions with collectd: plugin_register (TYPE_READ, "foobar", "foobar_read"); plugin_register (TYPE_WRITE, "foobar", "foobar_write"); + fc_register (FC_MATCH, "foobar", "foobar_match"); + See the section "DATA TYPES" above for a complete documentation of the data -types used by the read and write functions. +types used by the read, write and match functions. =head1 NOTES