huschi.net

COLLECTD-LUA(5)                    collectd                    COLLECTD-LUA(5)
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, interval between its
           calls will grow until function returns 0 again. See the
           MaxReadInterval configuration option of collectd.
       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)
           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.
       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.
       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)     -- pass function as variable
             collectd.register_write("write") -- pass by global-scope function name
SEE ALSO
       collectd(1), collectd.conf(5), lua(1),
AUTHOR
       The "Lua plugin" has been written by Julien Ammous
       <j.ammous at gmail.com>, Florian Forster <octo at collectd.org> and
       Ruben Kerkhof <ruben at rubenkerkhof.com>.
       This manpage has been written by Ruben Kerkhof
       <ruben at rubenkerkhof.com>.  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.11.0.94.g41b1e33                2020-07-20                   COLLECTD-LUA(5)