snmp plugin: Fix a possible memory leak.

[collectd.git] / src / collectd-perl.pod

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index 3306f39..4a01d14 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -61,7 +61,7 @@ only has effect on plugins loaded after this option.
 
 =head1 WRITING YOUR OWN PLUGINS
 
 
 =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
 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


@@ -97,6 +97,15 @@ once for each call to B<plugin_dispatch_values>.
 This type of function is used to pass messages of plugins or the daemon itself
 to the user.
 
 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
 =item shutdown functions
 
 This type of function is called once before the daemon shuts down. It should


@@ -104,8 +113,9 @@ be used to clean up the plugin (e.g. close sockets, ...).
 
 =back
 
 
 =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
 
 See the documentation of the B<plugin_register> method in the section
 "METHODS" below for the number and types of arguments passed to each


@@ -132,7 +142,7 @@ structure. The general layout looks like this:
 
   [{
     name => 'data_source_name',
 
   [{
     name => 'data_source_name',

-    type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+    type => DS_TYPE_COUNTER || DS_TYPE_GAUGE,

     min  => value || undef,
     max  => value || undef
   }, ...]
     min  => value || undef,
     max  => value || undef
   }, ...]


@@ -148,12 +158,28 @@ layout looks like this:
   {
     values => [123, 0.5],
     time   => time (),
   {
     values => [123, 0.5],
     time   => time (),

-    host   => 'localhost',
+    host   => $hostname_g,

     plugin => 'myplugin',
     plugin_instance => '',
     type_instance   => ''
   }
 
     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
 =back
 
 =head1 METHODS


@@ -179,6 +205,8 @@ I<type> can be one of:
 
 =item TYPE_LOG
 
 
 =item TYPE_LOG
 

+=item TYPE_NOTIF
+

 =item TYPE_SHUTDOWN
 
 =item TYPE_DATASET
 =item TYPE_SHUTDOWN
 
 =item TYPE_DATASET


@@ -193,9 +221,10 @@ argument which simply tells B<plugin_register> what is being registered.)
 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
 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>
 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
 
 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


@@ -231,6 +260,11 @@ level is B<LOG_DEBUG>, the most important level is B<LOG_ERR>. In between there
 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.
 
 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>)
 =back
 
 =item B<plugin_unregister> (I<type>, I<plugin>)


@@ -245,6 +279,11 @@ is found (and the number of values matches the number of data-sources) then the
 type, data-set and value-list is passed to all write-callbacks that are
 registered with the daemon.
 
 type, data-set and value-list is passed to all write-callbacks that are
 registered with the daemon.
 

+=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.
 =item B<plugin_log> (I<log-level>, I<message>)
 
 Submits a I<message> of level I<log-level> to collectd's logging mechanism.


@@ -293,6 +332,8 @@ available (B<:all> will export all of them):
 
 =item B<plugin_dispatch_values> ()
 
 
 =item B<plugin_dispatch_values> ()
 

+=item B<plugin_dispatch_notification> ()
+

 =item B<plugin_log> ()
 
 =back
 =item B<plugin_log> ()
 
 =back


@@ -349,6 +390,18 @@ available (B<:all> will export all of them):
 
 =back
 
 
 =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<:globals>
 
 =over 4


@@ -401,6 +454,22 @@ To register those functions with collectd:
 See the section "DATA TYPES" above for a complete documentation of the data
 types used by the read and write functions.
 
 See the section "DATA TYPES" above for a complete documentation of the data
 types used by the read and write functions.
 

+=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>.
+
+=back
+

 =head1 CAVEATS
 
 =over 4
 =head1 CAVEATS
 
 =over 4


@@ -412,8 +481,9 @@ 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
 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). Please
-note that no data is shared between threads by default. You have to use the
+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
 B<threads::shared> module to do so.
 
 =item


@@ -439,6 +509,7 @@ instead.
 L<collectd(1)>,
 L<collectd.conf(5)>,
 L<collectd-exec(5)>,
 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<perl(1)>,
 L<threads(3perl)>,
 L<threads::shared(3perl)>,