src/collectd-lua.pod

   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:
   7 #
   8 # The above copyright notice and this permission notice shall be included in
   9 # all copies or substantial portions of the Software.
  10
  11 =encoding UTF-8
  12
  13 =head1 NAME
  14
  15 collectd-lua - Documentation of collectd's C<Lua plugin>
  16
  17 =head1 SYNOPSIS
  18
  19   LoadPlugin lua
  20   # ...
  21   <Plugin lua>
  22     BasePath "/path/to/your/lua/scripts"
  23     Script "script1.lua"
  24     Script "script2.lua"
  25   </Plugin>
  26
  27 =head1 DESCRIPTION
  28
  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.
  34
  35 The minimum required Lua version is I<5.1>.
  36
  37 =head1 CONFIGURATION
  38
  39 =over 4
  40
  41 =item B<LoadPlugin> I<Lua>
  42
  43 Loads the Lua plugin.
  44
  45 =item B<BasePath> I<Name>
  46
  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>.
  49
  50 =item B<Script> I<Name>
  51
  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.
  54
  55 =back
  56
  57 =head1 WRITING YOUR OWN PLUGINS
  58
  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):
  66
  67 =over 4
  68
  69 =item read functions
  70
  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.
  77
  78 =item write functions
  79
  80 These are used to write the dispatched values. They are called
  81 once for every value that was dispatched by any plugin.
  82
  83 =back
  84
  85 =head1 FUNCTIONS
  86
  87 The following functions are provided to Lua modules:
  88
  89 =over 4
  90
  91 =item register_read(callback)
  92
  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.
  97
  98 =item register_write(callback)
  99
 100 Function to register write callbacks.
 101 The callback function will be called with one argument passed, which will be a
 102 table of values.
 103 If this callback function does not return 0 next call will be delayed by
 104 an increasing interval.
 105
 106 =item log_error, log_warning, log_notice, log_info, log_debug(I<message>)
 107
 108 Log a message with the specified severity.
 109
 110 =back
 111
 112 =head1 EXAMPLES
 113
 114 =over 4
 115
 116 A very simple read function might look like:
 117
 118   function read()
 119     collectd.log_info("read function called")
 120     t = {
 121         host = 'localhost',
 122         plugin = 'myplugin',
 123         type = 'counter',
 124         values = {42},
 125     }
 126     collectd.dispatch_values(t)
 127     return 0
 128   end
 129
 130 A very simple write function might look like:
 131
 132   function write(vl)
 133     for i = 1, #vl.values do
 134       collectd.log_info(vl.host .. '.' .. vl.plugin .. '.' .. vl.type .. ' ' .. vl.values[i])
 135     end
 136     return 0
 137   end
 138
 139 To register those functions with collectd:
 140
 141   collectd.register_read(read)     -- pass function as variable
 142   collectd.register_write("write") -- pass by global-scope function name
 143
 144 =back
 145
 146 =head1 SEE ALSO
 147
 148 L<collectd(1)>,
 149 L<collectd.conf(5)>,
 150 L<lua(1)>,
 151
 152 =head1 AUTHOR
 153
 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>.
 158
 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>.
 164
 165 =cut