huschi.net

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 regular 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,
       under the subdir .../lib/lua/5.0. In this 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
       The Lua RRDTool module functions will abort your program with a stack
       traceback when they can not 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 protected 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 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 and 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
       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
AUTHOR
       Fidelis Assis <fidelis AT pobox.com>

1.4.8                             2013-05-23                         RRDLUA(1)