X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.pod;h=6d29804981e4b72ec04b0a40bfbc35b31a113f91;hb=4059b7f729ee092d59d41a92804c83c1dd0d5332;hp=96c3fcdb43632cb9460c64a138be11ce1ee63375;hpb=1e7a1563af4e3a82e2f2e017dcabe9616624175d;p=collectd.git

diff --git a/src/collectd.pod b/src/collectd.pod
index 96c3fcdb..6d298049 100644
--- a/src/collectd.pod
+++ b/src/collectd.pod
@@ -76,6 +76,10 @@ NFS utilization (I<nfs>, Linux only)
 
 =item
 
+Embedded Perl interpreter (I<perl>)
+
+=item
+
 Network latency (I<ping>)
 
 =item
@@ -219,6 +223,39 @@ Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
 Each line is limited to 256 characters (including the newline character). 
 Longer lines will be ignored.
 
+=head2 exec
+
+The C<exec> plugin forks of an executable and reads back values that it writes
+to C<STDOUT>. The executable is forked kind of as L<init> does: It is forked
+once and not again until it exits. If it exited, it will be forked again after
+at most I<Interval> seconds. It is perfectly legal for the executable to run
+for a long time and continuously write values to C<STDOUT>.
+
+The forked executable is expected to print values to C<STDOUT>. The expected
+format is as follows:
+
+=over 4
+
+=item
+
+Each line beginning with a C<#> (hash mark) is ignored.
+
+=item
+
+Any other line must be of the form C<I<type>,I<type-instance>,I<value>>, where
+I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
+C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
+integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
+B<gauge>).
+
+=back
+
+The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
+"now".
+
+When collectd exits it sends a B<SIGTERM> to all still running
+child-processes upon which they have to quit.
+
 =head2 mysql
 
 Requires B<mysqlclient> to be installed. It connects to the database when
@@ -233,6 +270,133 @@ C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
 I<5.2.4. Server Status Variables> for an explanation of these values.
 
+=head2 perl
+
+The C<perl plugin> includes a Perl-interpreter in collectd and provides
+Perl-equivalents of the plugin-functions. This makes it possible to write
+plugins in Perl.
+
+There are two more complex types you need to know about:
+
+=over 4
+
+=item Data-Set
+
+A data-set is a list of one or more data-sources. Each data-source defines a
+name, type, min- and max-value and the data-set wraps them up into one
+structure. The general layout looks like this:
+
+  [{
+    name => 'data_source_name',
+    type => DS_TYPE_COUNTER || DS_TYPE_GAUGE
+    min  => value || undef,
+    max  => value || undef
+  }, ...]
+
+=item Value-List
+
+A value-list is one structure which features an array of values and fields to
+identify the values, i. e. time and host, plugin name and plugin-instance as
+well as a type and type-instance. Since the "type" is not included in the
+value-list but is passed as an extra argument, the general layout looks like
+this:
+
+  {
+    values => [123, 0.5],
+    time   => time (),
+    host   => 'localhost',
+    plugin => 'myplugin',
+    plugin_instance => '',
+    type_instance   => ''
+  }
+
+=back
+
+The following functions provide the C-interface to Perl-modules:
+
+=over 4
+
+=item B<plugin_register> (I<type>, I<name>, I<data>)
+
+Registers a callback-function or data-set.
+
+I<type> can be one of:
+
+=over 4
+
+=item TYPE_INIT
+
+=item TYPE_READ
+
+=item TYPE_WRITE
+
+=item TYPE_LOG
+
+=item TYPE_SHUTDOWN
+
+=item TYPE_DATASET
+
+=back
+
+I<name> is the name of the callback-function or the type of the data-set,
+depending on the value of I<type>. (Please note that the type of the data-set
+is the value passed as I<name> here and has nothing to do with the I<type>
+argument which simply tells B<plugin_register> what is being registered.)
+
+The last argument, I<data>, is either a function- 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.
+
+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 reference. These functions are
+called in the various stages of the daemon and are passed the following
+arguments:
+
+=over 4
+
+=item TYPE_INIT
+
+=item TYPE_READ
+
+=item TYPE_SHUTDOWN
+
+No arguments are passed
+
+=item TYPE_WRITE
+
+The arguments passed are I<type>, I<data-set>, and I<value-list>. I<type> is a
+string. For the layout of I<data-set> and I<value-list> see above.
+
+=item TYPE_LOG
+
+The arguments are I<log-level> and I<message>. The log level is small for
+important messages and high for less important messages. The least important
+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.
+
+=back
+
+=item B<plugin_unregister> (I<type>, I<plugin>)
+
+Removes a callback or data-set from collectd's internal list of
+functionsE<nbsp>/ datasets.
+
+=item B<plugin_dispatch_values> (I<type>, I<value-list>)
+
+Submits a I<value-list> of type I<type> to the daemon. If the data-set I<type>
+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.
+
+=item B<plugin_log> (I<log-level>, I<message>)
+
+Submits a I<message> of level I<log-level> to collectd's logging mechanism.
+The message is passed to all log-callbacks that are registered with collectd.
+
+=back
+
 =head2 sensors
 
 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means