NAME

       collectd-lua - Documentation of collectd's "Lua plugin"

SYNOPSIS

         LoadPlugin lua
         # ...
         <Plugin lua>
           BasePath "/path/to/your/lua/scripts"
           Script "script1.lua"
           Script "script2.lua"
         </Plugin>

DESCRIPTION

       The "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 "exec plugin" (see collectd-exec(5))
       and provides a lot more functionality, too.

       The minimum required Lua version is 5.1.

CONFIGURATION

       LoadPlugin Lua
           Loads the Lua plugin.

       BasePath Name
           The  directory  the  "Lua  plugin" looks in to find script Script.  If set, this is also prepended to
           package.path.

       Script Name
           The script the "Lua plugin" is going to run.  If BasePath is not  specified,  this  needs  to  be  an
           absolute path.

WRITING YOUR OWN PLUGINS

       Writing  your  own plugins is quite simple. collectd manages plugins by means of dispatch functions which
       call the appropriate 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  callback
       functions are implemented in the Lua plugin (all of them are optional):

       read functions
           These  are  used  to  collect  the  actual  data.  It  is  called once per interval (see the Interval
           configuration option of collectd). Usually it will  call  collectd.dispatch_values  to  dispatch  the
           values  to  collectd which will pass them on to all registered 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.

       write functions
           These  are  used  to  write  the  dispatched  values.  They  are called once for every value that was
           dispatched by any plugin.

FUNCTIONS

       The following functions are provided to Lua modules:

       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.

       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.

       log_error, log_warning, log_notice, log_info, log_debug(message)
           Log a message with the specified severity.

EXAMPLES

           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)

SEE ALSO

       collectd(1), collectd.conf(5), lua(1),

AUTHOR

       The "Lua plugin"  has  been  written  by  Julien  Ammous  <j.ammous<nbsp>at gmail.com>,  Florian  Forster
       <octo at collectd.org> and Ruben Kerkhof <ruben<nbsp>at rubenkerkhof.com<gt> and

       This  manpage  has been written by Ruben Kerkhof <ruben<nbsp>at rubenkerkhof.com<gt>.  It is based on the
       collectd-perl(5)  manual  page   by   Florian   Forster   <octo at collectd.org>   and   Sebastian   Harl
       <sh at tokkee.org>.

5.7.2.git                                          2020-03-04                                    COLLECTD-LUA(5)