doc/rrdlua.txt

   1 RRDLUA(1)                           rrdtool                          RRDLUA(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        RRDLua -  Lua binding for RRDTool
   7
   8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   9          require 'rrd'
  10          rrd.create(...)
  11          rrd.dump(...)
  12          rrd.fetch(...)
  13          rrd.first(...)
  14          rrd.graph(...)
  15          rrd.graphv(...)
  16          rrd.info(...)
  17          rrd.last(...)
  18          rrd.resize(...)
  19          rrd.restore(...)
  20          rrd.tune(...)
  21          rrd.update(...)
  22          rrd.updatev(...)
  23
  24 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  25    C\bCa\bal\bll\bli\bin\bng\bg S\bSe\beq\bqu\bue\ben\bnc\bce\be
  26        This module accesses RRDtool functionality directly from within Lua.
  27        The arguments to the functions listed in the SYNOPSIS are explained in
  28        the regular RRDtool documentation. The command-line call
  29
  30            rrdtool update mydemo.rrd --template in:out N:12:13
  31
  32        gets turned into
  33
  34            rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")
  35
  36        Note that --template=in:out is also valid.
  37
  38    U\bUs\bsi\bin\bng\bg w\bwi\bit\bth\bh L\bLu\bua\ba 5\b5.\b.1\b1
  39        Start your programs with:
  40
  41            ---------------------------------------------------------------
  42            package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
  43                            package.cpath
  44            require 'rrd'
  45            ---------------------------------------------------------------
  46
  47        OBS: If you configured with --enable-lua-site-install, you don't need
  48        to set package.cpath like above.
  49
  50    U\bUs\bsi\bin\bng\bg w\bwi\bit\bth\bh L\bLu\bua\ba 5\b5.\b.0\b0
  51        The Lua binding for RRDtool needs the Lua module compat-5.1 to work
  52        with Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it
  53        already integrated in Lua 5.0 -dev packages, so you just have to
  54        require it:
  55
  56            require 'compat-5.1'
  57
  58        For other platforms, the compat-5.1 module that comes with this binding
  59        will be installed for you in the same dir where RRDtool was installed,
  60        under the subdir .../lib/lua/5.0. In this case, you must tell your Lua
  61        programs where to find it by changing the Lua var LUA_PATH:
  62
  63            -- compat-5.1.lua is only necessary for Lua 5.0 ----------------
  64            -- try only compat-5.1 installed with RRDtool package
  65            local original_LUA_PATH = LUA_PATH
  66            LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
  67            require 'compat-5.1'
  68            LUA_PATH = original_LUA_PATH
  69            original_LUA_PATH = nil
  70            --- end of code to require compat-5.1 ---------------------------
  71
  72            Now we can require the rrd module in the same way we did for 5.1 above:
  73
  74            ---------------------------------------------------------------
  75            package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
  76                            package.cpath
  77            require 'rrd'
  78            ---------------------------------------------------------------
  79
  80    E\bEr\brr\bro\bor\br H\bHa\ban\bnd\bdl\bli\bin\bng\bg
  81        The Lua RRDTool module functions will abort your program with a stack
  82        traceback when they can not make sense out of the arguments you fed
  83        them.  However, you can capture and handle the errors yourself, instead
  84        of just letting the program abort, by calling the module functions
  85        through Lua protected calls - 'pcall' or 'xpcall'.
  86
  87             Ex: program t.lua
  88
  89             --- compat-5.1.lua is only necessary for Lua 5.0 ----------------
  90             -- uncomment below if your distro has not compat-5.1
  91             -- original_LUA_PATH = LUA_PATH
  92             -- try only compat-5.1.lua installed with RRDtool package
  93             -- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
  94
  95             -- here we use a protected call to require compat-5.1
  96             local r = pcall(require, 'compat-5.1')
  97             if not r then
  98               print('** could not load compat-5.1.lua')
  99               os.exit(1)
 100             end
 101
 102             -- uncomment below if your distro has not compat-5.1
 103             -- LUA_PATH = original_LUA_PATH
 104             -- original_LUA_PATH = nil
 105             --- end of code to require compat-5.1 ---------------------------
 106
 107             -- If the Lua RRDTool module was installed together with RRDTool,
 108             -- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be
 109             -- set accordingly so that 'require' can find the module:
 110
 111             package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 112                             package.cpath
 113
 114             local rrd = require 'rrd'
 115             rrd.update ("mydemo.rrd","N:12:13")
 116
 117        If we execute the program above we'll get:
 118
 119             $ lua t.lua
 120
 121             lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
 122             stack traceback:
 123                   [C]: in function `update'
 124                   t.lua:27: in main chunk
 125                   [C]: ?
 126
 127    R\bRe\bet\btu\bur\brn\bn V\bVa\bal\blu\bue\bes\bs
 128        The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
 129        return their findings.
 130
 131        r\brr\brd\bd.\b.f\bfi\bir\brs\bst\bt returns a single INTEGER representing the timestamp of the
 132        first data sample in an RRA within an RRD file. Example returning the
 133        first timestamp of the third RRA (index 2):
 134
 135             local firstdate = rrd.first('example.rrd', '--rraindex', 2)
 136
 137        r\brr\brd\bd.\b.l\bla\bas\bst\bt returns a single INTEGER representing the last update time.
 138
 139             local lastupdate = rrd.last('example.rrd')
 140
 141        r\brr\brd\bd.\b.g\bgr\bra\bap\bph\bh returns the x-size and y-size of the created image and a
 142        table with the results of the PRINT arguments.
 143
 144             local xsize, ysize, averages = rrd.graph ...
 145             print(string.format("Image size: %dx%d", xsize, ysize)
 146             print("Averages: ", table.concat(averages, ', '))
 147
 148        r\brr\brd\bd.\b.i\bin\bnf\bfo\bo returns a table where the keys and the values represent
 149        property names and property values of the RRD.
 150
 151             local info = rrd.info("test.rrd")
 152             for key, value in pairs(info) do
 153               print(key, ' = ', value)
 154             end
 155
 156        r\brr\brd\bd.\b.g\bgr\bra\bap\bph\bhv\bv takes the same parameters as rrd.graph but it returns a
 157        table only. The table returned contains meta information about the
 158        graph, like its size as well as the position of the graph area on the
 159        image. When called with and empty filename, the contents of the graph
 160        will be returned in the table as well (key 'image').
 161
 162        r\brr\brd\bd.\b.u\bup\bpd\bda\bat\bte\bev\bv also returns a table. The keys of the table are strings
 163        formed by the concatenation of timestamp, RRA index and data source
 164        name for each consolidated data point (CDP) written to disk as a result
 165        of the current update call. The key values are CDP values.
 166
 167        r\brr\brd\bd.\b.f\bfe\bet\btc\bch\bh is the most complex of the pack regarding return values. It
 168        returns 5 values: the initial timestamp, the step, two parallel arrays
 169        containing the data source names and their data points respectively,
 170        and the final timestamp.
 171
 172             --require compat-5.1 if necessary
 173
 174             package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 175                             package.cpath
 176
 177             local rrd = require "rrd"
 178             local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
 179             local start, step, names, data =
 180               rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
 181             io.write(string.format("Start:       %s (%d)\n",
 182                                    os.date("%c", start),start))
 183             io.write("Step size:   ", step, " seconds\n")
 184             io.write("DS names:    ", table.concat(names, ', '), "\n")
 185             io.write("Data points: ", #data[1], "\n")
 186             io.write("Data:\n")
 187             for i,dp in ipairs(data) do
 188               io.write(os.date("%t", start), " (", start, "): ")
 189               start = start + step
 190               for j,v in ipairs(dp) do
 191                 io.write(v, " ")
 192               end
 193             io.write("\n")
 194             end
 195
 196 A\bAU\bUT\bTH\bHO\bOR\bR
 197        Fidelis Assis <fidelis@pobox.com>
 198
 199
 200
 201 1.3.999                           2009-06-09                         RRDLUA(1)