COLLECTD-LUA(5)

🎀 NAME 🎀

collectd-lua(5) is literally the manual for collectd's Lua plugin — yes bestie, the whole page, and it's giving embedded-interpreter realness 💅

✨ SYNOPSIS ✨

LoadPlugin lua
# ...
<Plugin lua>
  BasePath "/path/to/your/lua/scripts"
  Script "script1.lua"
  Script "script2.lua"
</Plugin>

💖 DESCRIPTION 💖

okay so the Lua plugin embeds a Lua interpreter right into collectd and gives you an interface to collectd's plugin system. That means you can write plugins for collectd in Lua. It's a lot more efficient than executing a Lua script every single time you wanna read a value with the exec plugin (go see collectd-exec(5)), and it gives you a lot more functionality too. The minimum required Lua version is 5.1 — do not come at it with anything older, bestie 😭

🌸 CONFIGURATION 🌸

• LoadPlugin Lua — loads the Lua plugin. iconic.
• BasePath Name — the directory the Lua plugin looks in to find the script Script. If it's set, it's also prepended to package.path.
• Script Name — the script the Lua plugin is gonna run. If BasePath is not specified, this needs to be an absolute path.

🦋 WRITING YOUR OWN PLUGINS 🦋

Writing your own plugins is quite simple — fr fr. collectd manages plugins by means of dispatch functions that call the appropriate callback functions registered by the plugins. Any plugin basically consists of the implementation of these callback functions plus some initializing code that registers the functions with collectd. Peep the EXAMPLES section below for a really basic example. The following types of callback functions are implemented in the Lua plugin, and all of them are optional:

💜 read functions 💜

These are used to collect the actual data. It's called once per interval (see the Interval configuration option of collectd). Usually it will call collectd.dispatch_values to dispatch the values to collectd, which will pass them on to all registered write functions. If this function does not return 0, the interval between its calls will grow until the function returns 0 again. See the MaxReadInterval configuration option of collectd.

💜 write functions 💜

These are used to write the dispatched values. They're called once for every value that was dispatched by any plugin.

💅 FUNCTIONS 💅

The following functions are provided to Lua modules:

• 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.
• 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, the next call will be delayed by an increasing interval.
• log_error, log_warning, log_notice, log_info, log_debug(message) — log a message with the specified severity.

🌈 EXAMPLES 🌈

A very simple read function might look like:

function read()
  collectd.log_info("read function called")
  t = {
      host = 'localhost',
      plugin = 'myplugin',
      type = 'counter',
      values = {42},
  }
  collectd.dispatch_values(t)
  return 0
end

A very simple write function might look like:

function write(vl)
  for i = 1, #vl.values do
    collectd.log_info(vl.host .. '.' .. vl.plugin .. '.' .. vl.type .. ' ' .. vl.values[i])
  end
  return 0
end

To register those functions with collectd:

collectd.register_read(read)     -- pass function as variable
collectd.register_write("write") -- pass by global-scope function name

👑 SEE ALSO 👑

• collectd(1)
• collectd.conf(5)
• lua(1)

go read those too, bestie 🫶

🍓 AUTHOR 🍓

The Lua plugin has been written by Julien Ammous <j.ammous at gmail.com>, Florian Forster <octo at collectd.org> and Ruben Kerkhof <ruben at rubenkerkhof.com>.

This manpage has been written by Ruben Kerkhof <ruben at rubenkerkhof.com>. It is based on the collectd-perl(5) manual page by Florian Forster <octo at collectd.org> and Sebastian Harl <sh at tokkee.org>.

---

okay bye, this page is 5.12.0.git from 2026-08-22 — and yeah, the manual is COLLECTD-LUA(5). slay 💖