1COLLECTD-LUA(5)                    collectd                    COLLECTD-LUA(5)
2
3
4

NAME

6       collectd-lua - Documentation of collectd's "Lua plugin"
7

SYNOPSIS

9         LoadPlugin lua
10         # ...
11         <Plugin lua>
12           BasePath "/path/to/your/lua/scripts"
13           Script "script1.lua"
14           Script "script2.lua"
15         </Plugin>
16

DESCRIPTION

18       The "Lua plugin" embeds a Lua interpreter into collectd and provides an
19       interface to collectd's plugin system. This makes it possible to write
20       plugins for collectd in Lua. This is a lot more efficient than
21       executing a Lua script every time you want to read a value with the
22       "exec plugin" (see collectd-exec(5)) and provides a lot more
23       functionality, too.
24
25       The minimum required Lua version is 5.1.
26

CONFIGURATION

28       LoadPlugin Lua
29           Loads the Lua plugin.
30
31       BasePath Name
32           The directory the "Lua plugin" looks in to find script Script.  If
33           set, this is also prepended to package.path.
34
35       Script Name
36           The script the "Lua plugin" is going to run.  If BasePath is not
37           specified, this needs to be an absolute path.
38

WRITING YOUR OWN PLUGINS

40       Writing your own plugins is quite simple. collectd manages plugins by
41       means of dispatch functions which call the appropriate callback
42       functions registered by the plugins. Any plugin basically consists of
43       the implementation of these callback functions and initializing code
44       which registers the functions with collectd. See the section "EXAMPLES"
45       below for a really basic example. The following types of callback
46       functions are implemented in the Lua plugin (all of them are optional):
47
48       read functions
49           These are used to collect the actual data. It is called once per
50           interval (see the Interval configuration option of collectd).
51           Usually it will call collectd.dispatch_values to dispatch the
52           values to collectd which will pass them on to all registered write
53           functions. If this function does not return 0, interval between its
54           calls will grow until function returns 0 again. See the
55           MaxReadInterval configuration option of collectd.
56
57       write functions
58           These are used to write the dispatched values. They are called once
59           for every value that was dispatched by any plugin.
60

FUNCTIONS

62       The following functions are provided to Lua modules:
63
64       register_read(callback)
65           Function to register read callbacks.  The callback will be called
66           without arguments.  If this callback function does not return 0 the
67           next call will be delayed by an increasing interval.
68
69       register_write(callback)
70           Function to register write callbacks.  The callback function will
71           be called with one argument passed, which will be a table of
72           values.  If this callback function does not return 0 next call will
73           be delayed by an increasing interval.
74
75       log_error, log_warning, log_notice, log_info, log_debug(message)
76           Log a message with the specified severity.
77

EXAMPLES

79           A very simple read function might look like:
80
81             function read()
82               collectd.log_info("read function called")
83               t = {
84                   host = 'localhost',
85                   plugin = 'myplugin',
86                   type = 'counter',
87                   values = {42},
88               }
89               collectd.dispatch_values(t)
90               return 0
91             end
92
93           A very simple write function might look like:
94
95             function write(vl)
96               for i = 1, #vl.values do
97                 collectd.log_info(vl.host .. '.' .. vl.plugin .. '.' .. vl.type .. ' ' .. vl.values[i])
98               end
99               return 0
100             end
101
102           To register those functions with collectd:
103
104             collectd.register_read(read)     -- pass function as variable
105             collectd.register_write("write") -- pass by global-scope function name
106

SEE ALSO

108       collectd(1), collectd.conf(5), lua(1),
109

AUTHOR

111       The "Lua plugin" has been written by Julien Ammous
112       <j.ammous at gmail.com>, Florian Forster <octo at collectd.org> and
113       Ruben Kerkhof <ruben at rubenkerkhof.com>.
114
115       This manpage has been written by Ruben Kerkhof
116       <ruben at rubenkerkhof.com>.  It is based on the collectd-perl(5)
117       manual page by Florian Forster <octo at collectd.org> and Sebastian
118       Harl <sh at tokkee.org>.
119
120
121
1225.9.2                             2019-09-16                   COLLECTD-LUA(5)
Impressum