bionic (5) collectd-lua.5.gz

Provided by: collectd-core_5.7.2-2ubuntu1.2_amd64 bug

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>.