.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "COLLECTD-LUA 5"
.TH COLLECTD-LUA 5 2024-02-04 5.12.0.git collectd
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
collectd\-lua \- Documentation of collectd's "Lua plugin"
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 7
\& LoadPlugin lua
\& # ...
\&
\& BasePath "/path/to/your/lua/scripts"
\& Script "script1.lua"
\& Script "script2.lua"
\&
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Lua plugin\*(C'\fR 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 \f(CW\*(C`exec plugin\*(C'\fR (see
\&\fBcollectd\-exec\fR\|(5)) and provides a lot more functionality, too.
.PP
The minimum required Lua version is \fI5.1\fR.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
.IP "\fBLoadPlugin\fR \fILua\fR" 4
.IX Item "LoadPlugin Lua"
Loads the Lua plugin.
.IP "\fBBasePath\fR \fIName\fR" 4
.IX Item "BasePath Name"
The directory the \f(CW\*(C`Lua plugin\*(C'\fR looks in to find script \fBScript\fR.
If set, this is also prepended to \fBpackage.path\fR.
.IP "\fBScript\fR \fIName\fR" 4
.IX Item "Script Name"
The script the \f(CW\*(C`Lua plugin\*(C'\fR is going to run.
If \fBBasePath\fR is not specified, this needs to be an absolute path.
.SH "WRITING YOUR OWN PLUGINS"
.IX Header "WRITING YOUR OWN PLUGINS"
Writing your own plugins is quite simple. collectd manages plugins by means of
\&\fBdispatch functions\fR which call the appropriate \fBcallback functions\fR
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 \fBcallback functions\fR are implemented in the
Lua plugin (all of them are optional):
.IP "read functions" 4
.IX Item "read functions"
These are used to collect the actual data. It is called once
per interval (see the \fBInterval\fR configuration option of collectd). Usually
it will call \fBcollectd.dispatch_values\fR to dispatch the values to collectd
which will pass them on to all registered \fBwrite functions\fR. If this function
does not return 0, interval between its calls will grow until function returns
0 again. See the \fBMaxReadInterval\fR configuration option of collectd.
.IP "write functions" 4
.IX Item "write functions"
These are used to write the dispatched values. They are called
once for every value that was dispatched by any plugin.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
The following functions are provided to Lua modules:
.IP register_read(callback) 4
.IX Item "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.
.IP register_write(callback) 4
.IX Item "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.
.IP "log_error, log_warning, log_notice, log_info, log_debug(\fImessage\fR)" 4
.IX Item "log_error, log_warning, log_notice, log_info, log_debug(message)"
Log a message with the specified severity.
.SH EXAMPLES
.IX Header "EXAMPLES"
.RS 4
A very simple read function might look like:
.Sp
.Vb 11
\& function read()
\& collectd.log_info("read function called")
\& t = {
\& host = \*(Aqlocalhost\*(Aq,
\& plugin = \*(Aqmyplugin\*(Aq,
\& type = \*(Aqcounter\*(Aq,
\& values = {42},
\& }
\& collectd.dispatch_values(t)
\& return 0
\& end
.Ve
.Sp
A very simple write function might look like:
.Sp
.Vb 6
\& function write(vl)
\& for i = 1, #vl.values do
\& collectd.log_info(vl.host .. \*(Aq.\*(Aq .. vl.plugin .. \*(Aq.\*(Aq .. vl.type .. \*(Aq \*(Aq .. vl.values[i])
\& end
\& return 0
\& end
.Ve
.Sp
To register those functions with collectd:
.Sp
.Vb 2
\& collectd.register_read(read) \-\- pass function as variable
\& collectd.register_write("write") \-\- pass by global\-scope function name
.Ve
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBcollectd\fR\|(1),
\&\fBcollectd.conf\fR\|(5),
\&\fBlua\fR\|(1),
.SH AUTHOR
.IX Header "AUTHOR"
The \f(CW\*(C`Lua plugin\*(C'\fR has been written by
Julien Ammous ,
Florian Forster and
Ruben Kerkhof .
.PP
This manpage has been written by Ruben Kerkhof
.
It is based on the \fBcollectd\-perl\fR\|(5) manual page by
Florian Forster and
Sebastian Harl .