program/doc/rrdlua.pod

   1 =head1 NAME
   2
   3 RRDLua -  Lua binding for RRDTool
   4
   5 =head1 SYNOPSIS
   6
   7   require 'rrd'
   8   rrd.create(...)
   9   rrd.dump(...)
  10   rrd.fetch(...)
  11   rrd.first(...)
  12   rrd.graph(...)
  13   rrd.graphv(...)
  14   rrd.info(...)
  15   rrd.last(...)
  16   rrd.resize(...)
  17   rrd.restore(...)
  18   rrd.tune(...)
  19   rrd.update(...)
  20   rrd.updatev(...)
  21
  22 =head1 DESCRIPTION
  23
  24 =head2 Calling Sequence
  25
  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 =head2 Using with Lua 5.1
  39
  40 Start your programs with:
  41
  42     ---------------------------------------------------------------
  43     package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
  44                     package.cpath
  45     require 'rrd'
  46     ---------------------------------------------------------------
  47
  48 OBS: If you configured with --enable-lua-site-install, you don't need
  49 to set package.cpath like above.
  50
  51 =head2 Using with Lua 5.0
  52
  53 The Lua binding for RRDtool needs the Lua module compat-5.1 to work with
  54 Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it already
  55 integrated in Lua 5.0 -dev packages, so you just have to require it:
  56
  57     require 'compat-5.1'
  58
  59 For other platforms, the compat-5.1 module that comes with this binding
  60 will be installed for you in the same dir where RRDtool was installed,
  61 under the subdir .../lib/lua/5.0. In this case, you must tell your Lua
  62 programs where to find it by changing the Lua var LUA_PATH:
  63
  64     -- compat-5.1.lua is only necessary for Lua 5.0 ----------------
  65     -- try only compat-5.1 installed with RRDtool package
  66     local original_LUA_PATH = LUA_PATH
  67     LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
  68     require 'compat-5.1'
  69     LUA_PATH = original_LUA_PATH
  70     original_LUA_PATH = nil
  71     --- end of code to require compat-5.1 ---------------------------
  72
  73     Now we can require the rrd module in the same way we did for 5.1 above:
  74
  75     ---------------------------------------------------------------
  76     package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
  77                     package.cpath
  78     require 'rrd'
  79     ---------------------------------------------------------------
  80
  81 =head2 Error Handling
  82
  83 The Lua RRDTool module functions will abort your program with a stack
  84 traceback when they can not make sense out of the arguments you fed them.
  85 However, you can capture and handle the errors yourself, instead of just
  86 letting the program abort, by calling the module functions through Lua
  87 protected calls - 'pcall' or 'xpcall'.
  88
  89      Ex: program t.lua
  90
  91      --- compat-5.1.lua is only necessary for Lua 5.0 ----------------
  92      -- uncomment below if your distro has not compat-5.1
  93      -- original_LUA_PATH = LUA_PATH
  94      -- try only compat-5.1.lua installed with RRDtool package
  95      -- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
  96
  97      -- here we use a protected call to require compat-5.1
  98      local r = pcall(require, 'compat-5.1')
  99      if not r then
 100        print('** could not load compat-5.1.lua')
 101        os.exit(1)
 102      end
 103
 104      -- uncomment below if your distro has not compat-5.1
 105      -- LUA_PATH = original_LUA_PATH
 106      -- original_LUA_PATH = nil
 107      --- end of code to require compat-5.1 ---------------------------
 108
 109      -- If the Lua RRDTool module was installed together with RRDTool,
 110      -- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be
 111      -- set accordingly so that 'require' can find the module:
 112
 113      package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 114                      package.cpath
 115
 116      local rrd = require 'rrd'
 117      rrd.update ("mydemo.rrd","N:12:13")
 118
 119 If we execute the program above we'll get:
 120
 121      $ lua t.lua
 122
 123      lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
 124      stack traceback:
 125            [C]: in function `update'
 126            t.lua:27: in main chunk
 127            [C]: ?
 128
 129 =head2 Return Values
 130
 131 The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
 132 return their findings.
 133
 134 B<rrd.first> returns a single INTEGER representing the timestamp of the
 135 first data sample in an RRA within an RRD file. Example returning the
 136 first timestamp of the third RRA (index 2):
 137
 138      local firstdate = rrd.first('example.rrd', '--rraindex', 2)
 139
 140 B<rrd.last> returns a single INTEGER representing the last update time.
 141
 142      local lastupdate = rrd.last('example.rrd')
 143
 144 B<rrd.graph> returns the x-size and y-size of the created image and a table
 145 with the results of the PRINT arguments.
 146
 147      local xsize, ysize, averages = rrd.graph ...
 148      print(string.format("Image size: %dx%d", xsize, ysize)
 149      print("Averages: ", table.concat(averages, ', '))
 150
 151 B<rrd.info> returns a table where the keys and the values represent property
 152 names and property values of the RRD.
 153
 154      local info = rrd.info("test.rrd")
 155      for key, value in pairs(info) do
 156        print(key, ' = ', value)
 157      end
 158
 159 B<rrd.graphv> takes the same parameters as rrd.graph but it returns a table
 160 only. The table returned contains meta information about the graph, like
 161 its size as well as the position of the graph area on the image. When
 162 called with and empty filename, the contents of the graph will be returned
 163 in the table as well (key 'image').
 164
 165 B<rrd.updatev> also returns a table. The keys of the table are strings
 166 formed by the concatenation of timestamp, RRA index and data source name
 167 for each consolidated data point (CDP) written to disk as a result of the
 168 current update call. The key values are CDP values.
 169
 170 B<rrd.fetch> is the most complex of the pack regarding return values. It
 171 returns 5 values: the initial timestamp, the step, two parallel arrays
 172 containing the data source names and their data points respectively, and
 173 the final timestamp.
 174
 175      --require compat-5.1 if necessary
 176
 177      package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 178                      package.cpath
 179
 180      local rrd = require "rrd"
 181      local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
 182      local start, step, names, data =
 183        rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
 184      io.write(string.format("Start:       %s (%d)\n",
 185                             os.date("%c", start),start))
 186      io.write("Step size:   ", step, " seconds\n")
 187      io.write("DS names:    ", table.concat(names, ', '), "\n")
 188      io.write("Data points: ", #data[1], "\n")
 189      io.write("Data:\n")
 190      for i,dp in ipairs(data) do
 191        io.write(os.date("%t", start), " (", start, "): ")
 192        start = start + step
 193        for j,v in ipairs(dp) do
 194          io.write(v, " ")
 195        end
 196      io.write("\n")
 197      end
 198
 199 =head1 AUTHOR
 200
 201 Fidelis Assis E<lt>fidelis@pobox.comE<gt>
 202
 203
 204