1 # Permission is hereby granted, free of charge, to any person obtaining a
2 # copy of this software and associated documentation files (the "Software"),
3 # to deal in the Software without restriction, including without limitation
4 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
5 # and/or sell copies of the Software, and to permit persons to whom the
6 # Software is furnished to do so, subject to the following conditions:
8 # The above copyright notice and this permission notice shall be included in
9 # all copies or substantial portions of the Software.
15 collectd-lua - Documentation of collectd's C<Lua plugin>
22 BasePath "/path/to/your/lua/scripts"
29 The C<Lua plugin> embeds a Lua interpreter into collectd and provides an
30 interface to collectd's plugin system. This makes it possible to write plugins
31 for collectd in Lua. This is a lot more efficient than executing a
32 Lua script every time you want to read a value with the C<exec plugin> (see
33 L<collectd-exec(5)>) and provides a lot more functionality, too.
35 The minimum required Lua version is I<5.1>.
41 =item B<LoadPlugin> I<Lua>
45 =item B<BasePath> I<Name>
47 The directory the C<Lua plugin> looks in to find script B<Script>.
48 If set, this is also prepended to B<package.path>.
50 =item B<Script> I<Name>
52 The script the C<Lua plugin> is going to run.
53 If B<BasePath> is not specified, this needs to be an absolute path.
57 =head1 WRITING YOUR OWN PLUGINS
59 Writing your own plugins is quite simple. collectd manages plugins by means of
60 B<dispatch functions> which call the appropriate B<callback functions>
61 registered by the plugins. Any plugin basically consists of the implementation
62 of these callback functions and initializing code which registers the
63 functions with collectd. See the section "EXAMPLES" below for a really basic
64 example. The following types of B<callback functions> are implemented in the
65 Lua plugin (all of them are optional):
71 These are used to collect the actual data. It is called once
72 per interval (see the B<Interval> configuration option of collectd). Usually
73 it will call B<collectd.dispatch_values> to dispatch the values to collectd
74 which will pass them on to all registered B<write functions>. If this function
75 does not return 0, interval between its calls will grow until function returns
76 0 again. See the B<MaxReadInterval> configuration option of collectd.
80 These are used to write the dispatched values. They are called
81 once for every value that was dispatched by any plugin.
87 The following functions are provided to Lua modules:
91 =item register_read(callback)
93 Function to register read callbacks.
94 The callback will be called without arguments.
95 If this callback function does not return 0 the next call will be delayed by
96 an increasing interval.
98 =item register_write(callback)
100 Function to register write callbacks.
101 The callback function will be called with one argument passed, which will be a
103 If this callback function does not return 0 next call will be delayed by
104 an increasing interval.
106 =item log_error, log_warning, log_notice, log_info, log_debug(I<message>)
108 Log a message with the specified severity.
116 A very simple read function might look like:
119 collectd.log_info("read function called")
126 collectd.dispatch_values(t)
130 A very simple write function might look like:
133 for i = 1, #vl.values do
134 collectd.log_info(vl.host .. '.' .. vl.plugin .. '.' .. vl.type .. ' ' .. vl.values[i])
139 To register those functions with collectd:
141 collectd.register_read(read) -- pass function as variable
142 collectd.register_write("write") -- pass by global-scope function name
154 The C<Lua plugin> has been written by
155 Julien Ammous E<lt>j.ammousE<nbsp>atE<nbsp>gmail.comE<gt>,
156 Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt> and
157 Ruben Kerkhof E<lt>rubenE<nbsp>atE<nbsp>rubenkerkhof.comE<gt>.
159 This manpage has been written by Ruben Kerkhof
160 E<lt>rubenE<nbsp>atE<nbsp>rubenkerkhof.comE<gt>.
161 It is based on the L<collectd-perl(5)> manual page by
162 Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt> and
163 Sebastian Harl E<lt>shE<nbsp>atE<nbsp>tokkee.orgE<gt>.