


     RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))              1111....7777....0000 ((((2222000011112222----00009999----11113333))))               RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))



     NNNNAAAAMMMMEEEE
          RRDLua -  Lua binding for RRDTool

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
            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(...)

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
        CCCCaaaalllllllliiiinnnngggg SSSSeeeeqqqquuuueeeennnncccceeee
          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.

        UUUUssssiiiinnnngggg wwwwiiiitttthhhh LLLLuuuuaaaa 5555....111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.

        UUUUssssiiiinnnngggg wwwwiiiitttthhhh LLLLuuuuaaaa 5555....000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:




     Page 1                                         (printed 2/19/18)






     RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))              1111....7777....0000 ((((2222000011112222----00009999----11113333))))               RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))



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

        EEEErrrrrrrroooorrrr HHHHaaaannnnddddlllliiiinnnngggg
          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 ---------------------------



     Page 2                                         (printed 2/19/18)






     RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))              1111....7777....0000 ((((2222000011112222----00009999----11113333))))               RRRRRRRRDDDDLLLLUUUUAAAA((((111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]: ?

        RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
          The functions rrd.first, rrd.last, rrd.graph, rrd.info and
          rrd.fetch return their findings.

          rrrrrrrrdddd....ffffiiiirrrrsssstttt 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)

          rrrrrrrrdddd....llllaaaasssstttt returns a single INTEGER representing the last
          update time.

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

          rrrrrrrrdddd....ggggrrrraaaapppphhhh 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, ', '))

          rrrrrrrrdddd....iiiinnnnffffoooo 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




     Page 3                                         (printed 2/19/18)






     RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))              1111....7777....0000 ((((2222000011112222----00009999----11113333))))               RRRRRRRRDDDDLLLLUUUUAAAA((((1111))))



          rrrrrrrrdddd....ggggrrrraaaapppphhhhvvvv 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').

          rrrrrrrrdddd....uuuuppppddddaaaatttteeeevvvv 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.

          rrrrrrrrdddd....ffffeeeettttcccchhhh 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

     AAAAUUUUTTTTHHHHOOOORRRR
          Fidelis Assis <fidelis@pobox.com>











     Page 4                                         (printed 2/19/18)



