RRDLUA(1)                            rrdtool                           RRDLUA(1)

NAME
     RRDLua -  Lua binding for RRDtool

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(...)

DESCRIPTION
   Calling Sequence
     This  module  accesses RRDtool functionality directly from within Lua.  The
     arguments to the functions listed in the SYNOPSIS are explained in the reg‐
     ular RRDtool documentation. 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")

     Note that --template=in:out is also valid.

   Using with Lua 5.1
     Start your programs with:

         ---------------------------------------------------------------
         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.

   Using with Lua 5.0
     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 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,  un‐
     der  the  subdir .../lib/lua/5.0. In this case, you must tell your Lua pro‐
     grams 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
     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.
     However, you can capture and handle the errors yourself,  instead  of  just
     letting the program abort, by calling the module functions through Lua pro‐
     tected calls - 'pcall' or 'xpcall'.

          Ex: 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]: ?

   Return Values
     The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch return
     their findings.

     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 time‐
     stamp 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').

     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 re‐
     turns 5 values: the initial timestamp, the step, two parallel  arrays  con‐
     taining  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

AUTHOR
     Fidelis Assis <fidelis@pobox.com>

1.11.0                             2026-08-08                          RRDLUA(1)
