RRDLUA(1)                           rrdtool                          RRDLUA(1)


<?><?><?> (NAME)
       RRDLua - <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?><?> Lua
       <?><?><?><?> 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)
       <?><?><?> <?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?><?><?><?><?><?> RRDtool <?><?>
       <?><?> <?><?><?><?> Lua <?><?><?><?><?> <?><?><?><?><?><?>.
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?> <?><?><?> <?><?><?><?><?>
       <?><?><?><?><?> (SYNOPSIS) <?><?> <?><?><?><?><?><?><?> <?><?><?><?>
       RRDtool <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>.
       <?><?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?>

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

       <?><?> <?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?><?><?>:

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

       <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?> <?><?> --template=in:out <?><?><?>
       <?><?><?><?><?> <?><?><?>.

   <?><?><?><?><?><?><?> <?><?> Lua 5.1 (Using with Lua 5.1)
       <?><?><?><?><?><?><?><?><?><?> <?><?><?> <?><?> <?><?> <?><?><?>
       <?><?><?><?> <?><?><?><?> <?><?><?><?>:

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

       <?><?><?><?>: <?><?><?> <?><?> <?><?><?><?><?><?>
       --enable-lua-site-install <?><?><?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?> <?><?><?><?><?>
       package.cpath <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>
       <?><?><?><?>.

   <?><?><?><?><?><?><?> <?><?> Lua 5.0 (Using with Lua 5.0)
       <?><?><?><?> Lua <?><?><?><?> RRDtool <?><?><?> <?><?><?> <?><?> Lua
       5.0 <?><?> <?><?><?><?><?><?> compat-5.1 <?><?> Lua <?><?><?><?>
       <?><?><?><?>.  <?><?><?><?> <?><?> <?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?><?> <?><?><?><?><?> Ubuntu gutsy <?> hardy<?> <?><?>
       <?><?><?> <?><?> <?><?> <?><?> <?><?><?><?><?><?><?><?> -dev
       <?><?><?><?><?> <?><?> Lua 5.0 <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?> <?><?><?> <?><?> <?><?> <?><?> require
       <?><?><?><?><?><?><?><?> <?><?><?><?>:

           require 'compat-5.1'

       <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?><?> compat-5.1 <?><?> <?><?> <?><?><?><?><?> <?><?><?>
       <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?><?> <?><?><?> RRDtool <?> <?><?>
       <?><?><?><?><?><?><?><?> .../lib/lua/5.0 <?><?><?> <?><?><?><?><?>
       <?><?>. <?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> LUA_PATH <?><?> Lua <?><?>
       <?><?><?><?><?><?><?><?><?><?> <?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?> <?><?> <?><?> <?><?><?> <?><?><?><?> <?><?><?><?>:

           -- 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)
       <?><?><?><?><?> <?><?><?><?><?><?> Lua <?><?><?><?> RRDtool <?><?>
       <?><?><?><?><?> <?><?> <?><?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?> <?><?><?> <?><?>
       <?><?> <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?> (stack
       traceback) <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?>.  <?><?>
       <?><?><?> <?><?><?><?> <?><?> <?><?><?> <?><?><?> <?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?> Lua
       <?><?><?><?> 'pcall' <?><?> '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")

       <?><?><?> <?><?><?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?> <?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?>:

            $ 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)
       <?><?><?><?><?> rrd.first<?> rrd.last<?> rrd.graph<?> rrd.info <?>
       rrd.fetch <?><?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?> <?><?> <?><?><?><?><?><?><?><?><?><?><?><?><?>.

       rrd.first <?><?> <?><?><?><?><?> INTEGER <?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?>
       (timestamp) <?><?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?> <?><?>
       <?><?> RRA <?><?><?><?> <?><?> <?><?><?><?> RRD <?><?><?>.
       <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?> <?><?>
       <?><?><?><?><?> RRA (<?><?><?><?><?> <?>):

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

       rrd.last <?><?> <?><?><?><?><?> INTEGER <?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?>.

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

       rrd.graph <?><?><?><?><?><?> x-size <?> y-size <?><?><?><?><?>
       <?><?><?><?><?><?><?><?> <?> <?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> PRINT <?><?>
       <?><?><?><?><?><?><?><?><?><?><?>.

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

       rrd.info <?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?><?>
       <?><?> <?><?> <?><?> <?><?><?><?><?><?> <?> <?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?> <?>
       <?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?> RRD <?><?><?><?><?>.

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

       rrd.graphv <?><?><?><?> <?><?><?><?><?><?><?><?><?><?> rrd.graph <?><?>
       <?><?><?><?><?><?><?><?> <?><?><?> <?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?>.  <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?> <?><?> <?> <?><?><?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?>.
       <?><?><?><?><?><?> <?><?> <?><?> <?><?> <?><?><?> <?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?> (<?><?><?><?> 'image').

       rrd.updatev <?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?>. <?><?><?><?><?><?><?> <?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?> RRA <?> <?><?><?> <?><?><?><?> <?><?><?><?> (DS) <?><?>
       <?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?> (CDP) <?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?>. <?><?><?><?><?><?> <?><?><?> <?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?> CDP <?><?><?><?><?>.

       rrd.fetch <?><?> <?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?> <?><?><?><?><?><?> <?><?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?>. <?><?><?> <?><?><?><?> <?>
       <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?>: <?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?> (step)<?> <?><?>
       <?><?><?><?><?><?> <?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?> <?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?> <?> <?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?>.

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

<?><?><?><?><?><?><?><?><?> (AUTHORS)
       Fidelis Assis <fidelis@pobox.com>

1.11.0                            2026-08-08                         RRDLUA(1)