Install Now
collectd-lua - Documentation of collectd's "Lua plugin"
Contents
Configuration
LoadPluginLua
Loads the Lua plugin.
BasePathName
The directory the "Lua plugin" looks in to find script Script. If set, this is also prepended to
package.path.
ScriptName
The script the "Lua plugin" is going to run. If BasePath is not specified, this needs to be an
absolute path.
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.
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
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.
Name
collectd-lua - Documentation of collectd's "Lua plugin"
See Also
collectd(1), collectd.conf(5), lua(1),
Synopsis
LoadPlugin lua
# ...
<Plugin lua>
BasePath "/path/to/your/lua/scripts"
Script "script1.lua"
Script "script2.lua"
</Plugin>
Writing Your Own Plugins
Writing your own plugins is quite simple. collectd manages plugins by means of dispatchfunctions which
call the appropriate callbackfunctions 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 callbackfunctions 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 writefunctions. 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.
PNG Icons
