RRDLUA(1)

💅 RRDLUA — the Lua binding for RRDtool (yes, this is RRDLUA(1), hi bestie)

okay so picture this: you're in Lua, you want RRDtool energy, and you do NOT want to shell out. That's literally this whole page. Let's go 💖

---

✨ SYNOPSIS ✨

  require 'rrd'
  rrd.create(...)
  rrd.dump(...)
  rrd.fetch(...)
  rrd.first(...)
  rrd.graph(...)
  rrd.graphv(...)
  rrd.info(...)
  rrd.last(...)
  rrd.resize(...)
  rrd.restore(...)
  rrd.tune(...)
  rrd.update(...)
  rrd.updatev(...)

like, that's the whole roster. iconic lineup ngl 🫶

---

🌸 DESCRIPTION 🌸

🎀 Calling Sequence 🎀

So this module lets you access RRDtool functionality directly from within Lua — no middleman, no vibes lost in transit. The arguments to all the functions listed up in the SYNOPSIS are explained in the regular RRDtool documentation (go read that too, bestie, it's the lore).

The command-line call

rrdtool update mydemo.rrd --template in:out N:12:13

gets turned into

rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")

and just so you know: --template=in:out is also valid. both slay. 🦋

---

🌈 Using with Lua 5.1 🌈

Start your programs with this, periodt:

---------------------------------------------------------------
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
                package.cpath
require 'rrd'
---------------------------------------------------------------

OBS: If you configured with --enable-lua-site-install, you don't need to set package.cpath like above. lucky you 💅

---

🦋 Using with Lua 5.0 🦋

okay so Lua 5.0 needs a little extra help. The Lua binding for RRDtool needs the Lua module compat-5.1 to work with Lua 5.0. Some Linux distros — like Ubuntu gutsy and hardy — have it already integrated in Lua 5.0 -dev packages, so you literally just have to require it:

require 'compat-5.1'

For other platforms, the compat-5.1 module that comes with this binding will be installed for you in the same dir where RRDtool was installed, under the subdir .../lib/lua/5.0. In that case, you must tell your Lua programs where to find it by changing the Lua var LUA_PATH:

-- compat-5.1.lua is only necessary for Lua 5.0 ----------------
-- try only compat-5.1 installed with RRDtool package
local original_LUA_PATH = LUA_PATH
LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
require 'compat-5.1'
LUA_PATH = original_LUA_PATH
original_LUA_PATH = nil
--- end of code to require compat-5.1 ---------------------------

Now we can require the rrd module in the same way we did for 5.1 above:

---------------------------------------------------------------
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
                package.cpath
require 'rrd'
---------------------------------------------------------------

---

💀 Error Handling 💀

Real talk: the Lua RRDtool module functions will abort your program with a stack traceback when they cannot make sense out of the arguments you fed them. (rude, but okay.)

BUT — you can capture and handle the errors yourself instead of just letting the program abort, by calling the module functions through Lua protected calls — pcall or xpcall. main character energy tbh 👑

Here's the example program t.lua:

--- compat-5.1.lua is only necessary for Lua 5.0 ----------------
-- uncomment below if your distro has not compat-5.1
-- original_LUA_PATH = LUA_PATH
-- try only compat-5.1.lua installed with RRDtool package
-- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'

-- here we use a protected call to require compat-5.1
local r = pcall(require, 'compat-5.1')
if not r then
  print('** could not load compat-5.1.lua')
  os.exit(1)
end

-- uncomment below if your distro has not compat-5.1
-- LUA_PATH = original_LUA_PATH
-- original_LUA_PATH = nil
--- end of code to require compat-5.1 ---------------------------

-- If the Lua RRDtool module was installed together with RRDtool,
-- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be
-- set accordingly so that 'require' can find the module:

package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
                package.cpath

local rrd = require 'rrd'
rrd.update ("mydemo.rrd","N:12:13")

If we execute the program above we'll get:

$ lua t.lua

lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
stack traceback:
      [C]: in function `update'
      t.lua:27: in main chunk
      [C]: ?

😭 yeah. that's the mydemo.rrd not existing thing. it happens to the best of us.

---

💖 Return Values 💖

The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch return their findings. Let's go one by one, because the way these are all different is genuinely a lot 😭

• rrd.first returns a single INTEGER representing the timestamp of the first data sample in an RRA within an RRD file. Example returning the first timestamp of the third RRA (index 2):

local firstdate = rrd.first('example.rrd', '--rraindex', 2)

• rrd.last returns a single INTEGER representing the last update time.

local lastupdate = rrd.last('example.rrd')

• rrd.graph returns the x-size and y-size of the created image and a table with the results of the PRINT arguments.

local xsize, ysize, averages = rrd.graph ...
print(string.format("Image size: %dx%d", xsize, ysize)
print("Averages: ", table.concat(averages, ', '))

• rrd.info returns a table where the keys and the values represent property names and property values of the RRD.

local info = rrd.info("test.rrd")
for key, value in pairs(info) do
  print(key, ' = ', value)
end

• rrd.graphv takes the same parameters as rrd.graph but it returns a table only. The table returned contains meta information about the graph, like its size as well as the position of the graph area on the image. When called with an empty filename, the contents of the graph will be returned in the table as well (key 'image'). obsessed with the empty-filename trick honestly ✨
• rrd.updatev also returns a table. The keys of the table are strings formed by the concatenation of timestamp, RRA index and data source name for each consolidated data point (CDP) written to disk as a result of the current update call. The key values are CDP values.
• rrd.fetch is the most complex of the pack regarding return values. It returns 5 values: the initial timestamp, the step, two parallel arrays containing the data source names and their data points respectively, and the final timestamp.

--require compat-5.1 if necessary

package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
                package.cpath

local rrd = require "rrd"
local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
local start, step, names, data =
  rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
io.write(string.format("Start:       %s (%d)\n",
                       os.date("%c", start),start))
io.write("Step size:   ", step, " seconds\n")
io.write("DS names:    ", table.concat(names, ', '), "\n")
io.write("Data points: ", #data[1], "\n")
io.write("Data:\n")
for i,dp in ipairs(data) do
  io.write(os.date("%t", start), " (", start, "): ")
  start = start + step
  for j,v in ipairs(dp) do
    io.write(v, " ")
  end
io.write("\n")
end

like, five return values. she's high maintenance but she's worth it 💜

---

👑 AUTHOR 👑

Fidelis Assis <fidelis@pobox.com>

---

and that's the whole page, bestie!! 🎀 this was RRDLUA(1) from the rrdtool manual, version 1.11.0, dated 2026-10-17. go forth and require 'rrd' responsibly. mwah 💋💅