# 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, interval between its calls will grow until function returns
0 again. See the B<MaxReadInterval> configuration option of collectd.

=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:

=over 4

=item register_read(callback)

Function to register read callbacks.
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(callback)

Function to register write callbacks.
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)     -- pass function as variable
  collectd.register_write("write") -- pass by global-scope function name

=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.ammousE<nbsp>atE<nbsp>gmail.comE<gt>,
Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt> and
Ruben Kerkhof E<lt>rubenE<nbsp>atE<nbsp>rubenkerkhof.comE<gt>.

This manpage has been written by Ruben Kerkhof
E<lt>rubenE<nbsp>atE<nbsp>rubenkerkhof.comE<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