Lua plugin: add a manpage

diff --git a/src/Makefile.am b/src/Makefile.am
index 9a8e346dbb2c4891b47243adf9bd7dddb2d59016..6076581892491c2bd6f36d093120a4130c60f68a 100644 (file)
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -1368,6 +1368,7 @@ dist_man_MANS = collectd.1 \
                collectd-exec.5 \
                collectdctl.1 \
                collectd-java.5 \
+               collectd-lua.5 \
                collectdmon.1 \
                collectd-nagios.1 \
                collectd-perl.5 \
@@ -1383,6 +1384,7 @@ EXTRA_DIST =      collectd.conf.pod \
                collectd-exec.pod \
                collectdctl.pod \
                collectd-java.pod \
+               collectd-lua.pod \
                collectdmon.pod \
                collectd-nagios.pod \
                collectd-perl.pod \

diff --git a/src/collectd-lua.pod b/src/collectd-lua.pod
new file mode 100644 (file)
index 0000000..62dd850
--- /dev/null
+++ b/src/collectd-lua.pod
@@ -0,0 +1,161 @@
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+=encoding UTF-8
+
+=head1 NAME
+
+collectd-lua - Documentation of Collectd's C<Lua plugin>
+
+=head1 SYNOPSIS
+
+  LoadPlugin lua
+  # ...
+  <Plugin lua>
+    BasePath "/path/to/your/lua/scripts"
+    Script "script1.lua"
+    Script "script2.lua"
+  </Plugin>
+
+=head1 DESCRIPTION
+
+The C<Lua plugin> embeds a Lua interpreter into Collectd and provides an
+interface to Collectd's plugin system. This makes it possible to write plugins
+for Collectd in Lua. This is a lot more efficient than executing a
+Lua script every time you want to read a value with the C<exec plugin> (see
+L<collectd-exec(5)>) and provides a lot more functionality, too.
+
+The minimum required Lua version is I<5.1>.
+
+=head1 CONFIGURATION
+
+=over 4
+
+=item B<LoadPlugin> I<Lua>
+
+Loads the Lua plugin.
+
+=item B<BasePath> I<Name>
+
+The directory the C<Lua plugin> looks in to find script B<Script>.
+If set, this is also prepended to B<package.path>.
+
+=item B<Script> I<Name>
+
+The script the C<Lua plugin> is going to run.
+If B<BasePath> is not specified, this needs to be an absolute path.
+
+=back
+
+=head1 WRITING YOUR OWN PLUGINS
+
+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
+functions with Collectd. See the section "EXAMPLES" below for a really basic
+example. The following types of B<callback functions> are implemented in the
+Lua plugin (all of them are optional):
+
+=over 4
+
+=item read functions
+
+These are used to collect the actual data. It is called once
+per interval (see the B<Interval> configuration option of Collectd). Usually
+it will call B<collectd.dispatch_values> to dispatch the values to Collectd
+which will pass them on to all registered B<write functions>. If this function
+does not return 0 the plugin will be skipped for an increasing
+amount of time until it returns normally again.
+
+=item write functions
+
+These are used to write the dispatched values. They are called
+once for every value that was dispatched by any plugin.
+
+=back
+
+=head1 FUNCTIONS
+
+The following functions are provided to Lua modules:
+
+=item register_read(callback)
+
+The callback will be called without arguments.
+If this callback function does not return 0 the next call will be delayed by
+an increasing interval.
+
+=item register_write
+
+The callback function will be called with one argument passed, which will be a
+table of values.
+If this callback function does not return 0 next call will be delayed by
+an increasing interval.
+
+=item log_error, log_warning, log_notice, log_info, log_debug(I<message>)
+
+Log a message with the specified severity.
+
+=back
+
+=head1 EXAMPLES
+
+=over 4
+
+A very simple read function might look like:
+
+  function read()
+    collectd.log_info("read function called")
+    t = {
+        host = 'localhost',
+        plugin = 'myplugin',
+        type = 'counter',
+        values = {42},
+    }
+    collectd.dispatch_values(t)
+    return 0
+  end
+
+A very simple write function might look like:
+
+  function write(vl)
+    for i = 1, #vl.values do
+      collectd.log_info(vl.host .. '.' .. vl.plugin .. '.' .. vl.type .. ' ' .. vl.values[i])
+    end
+    return 0
+  end
+
+To register those functions with collectd:
+
+  collectd.register_read(read)
+  collectd.register_write(write)
+
+=back
+
+=head1 SEE ALSO
+
+L<collectd(1)>,
+L<collectd.conf(5)>,
+L<lua(1)>,
+
+=head1 AUTHOR
+
+The C<Lua plugin> has been written by
+Julien Ammous E<lt>j.ammous<nbsp>atE<nbsp>gmail.comE<gt>,
+Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt> and
+Ruben Kerkhof E<lt>ruben<nbsp>atE<nbsp>rubenkerkhof.com<gt> and
+
+This manpage has been written by Ruben Kerkhof
+E<lt>ruben<nbsp>atE<nbsp>rubenkerkhof.com<gt>.
+It is based on the L<collectd-perl(5)> manual page by
+Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt> and
+Sebastian Harl E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.
+
+=cut