table of contents
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" <Module "script1.lua"> Key1 Value1 </Module> <Module "script2.lua"> Key2 Value2 </Module> </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.
- Module Name
- The definition of module variables which will be passed to Script
Name config function. The concept is similar to
collectd-python(5) "Module". The
matched Script Name must be placed before this Module
block.
Module Name must match existing Script Name, but if you specify only Module, the module variables are applied to any existing Script Name. This mean that you can define common module variables in Module and the rest of changed variables in Module Name block.
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.
- init functions
- These are used to initialize the internal state. They are called once for every startup phase.
- config functions
- These are used to configure the dispatched values. They are called once for every after init functions.
- shutdown functions
- These are used to clean-up the internal state. They are called once for
every shutting down phase. - notification functions
- These are used to receive a PUTNOTIF event. They are called once for
every notification phase.
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.
- register_init(callback)
- Function to register init callbacks. The callback function will be called without arguments.
- register_config(callback)
- Function to register config callbacks. The callback function will be called with one argument passed, which will be a table of values.
- register_shutdown(callback)
- Function to register shutdown callbacks. The callback function will be called without arguments.
- register_notification(callback)
- Function to register notification callbacks. The callback function will be called with one argument passed, which will be a table of values.
- log_error, log_warning, log_notice, log_info, log_debug(message)
- Log a message with the specified severity.
EXAMPLES¶
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¶
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>.
2024-12-18 | 5.12.0.348.g93f9bdcb |