1COLLECTD-LUA(5) collectd COLLECTD-LUA(5)
2
6 collectd-lua - Documentation of collectd's "Lua plugin"
7
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
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 The minimum required Lua version is 5.1.
26
28 LoadPlugin Lua
29 Loads the Lua plugin.
30 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 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
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 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 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
62 The following functions are provided to Lua modules:
63 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 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 log_error, log_warning, log_notice, log_info, log_debug(message)
76 Log a message with the specified severity.
77
79 A very simple read function might look like:
80 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 A very simple write function might look like:
94 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 To register those functions with collectd:
103 collectd.register_read(read) -- pass function as variable
105 collectd.register_write("write") -- pass by global-scope function name
106
108 collectd(1), collectd.conf(5), lua(1),
109
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 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>.
1195.11.0.94.g41b1e33 2020-07-20 COLLECTD-LUA(5)