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
  37
  38   --template=in:out is also valid.
  39
  40 =head2 Error Handling
  41
  42 The Lua RRDTool module functions will abort your program with a stack
  43 traceback when they can not make sense out of the arguments you fed them.
  44
  45   Ex:
  46
  47   -- If the Lua RRDTool module was installed together with RRDTool,
  48   -- in $prefix/lib/lua/$lua_version, package.cpath must be set like
  49   -- in the example below, so that 'require' can find the module:
  50
  51   package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' ..
  52                   package.cpath
  53   local rrd = require 'rrd'
  54   rrd.update ("mydemo.rrd","N:12:13")
  55
  56   $ lua t.lua
  57
  58   lua: t.lua:8: opening 'mydemo.rrd': No such file or directory
  59   stack traceback:
  60           [C]: in function 'update'
  61           t.lua:8: in main chunk
  62           [C]: ?
  63
  64 You may capture and handle the errors yourself, instead of just letting
  65 the program abort, by calling the module functions through Lua protected
  66 calls - 'pcall' or 'xpcall'.
  67
  68 =head2 Return Values
  69
  70 The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
  71 return their findings.
  72
  73 B<rrd.first> returns a single INTEGER representing the timestamp of the
  74 first data sample in an RRA within an RRD file. Example returning the
  75 first timestamp of the third RRA (index 2):
  76
  77   local firstdate = rrd.first('example.rrd', '--rraindex', 2)
  78
  79 B<rrd.last> returns a single INTEGER representing the last update time.
  80
  81   local lastupdate = rrd.last('example.rrd')
  82
  83 B<rrd.graph> returns the x-size and y-size of the created image and a table
  84 with the results of the PRINT arguments.
  85
  86   local xsize, ysize, averages = rrd.graph ...
  87   print(string.format("Image size: %dx%d", xsize, ysize)
  88   print("Averages: ", table.concat(averages, ', '))
  89
  90 B<rrd.info> returns a table where the keys and the values represent property
  91 names and property values of the RRD.
  92
  93   local info = rrd.info("test.rrd")
  94   for key, value in pairs(info) do
  95     print(key, ' = ', value)
  96   end
  97
  98 B<rrd.graphv> takes the same parameters as rrd.graph but it returns a table
  99 only. The table returned contains meta information about the graph, like
 100 its size as well as the position of the graph area on the image. When
 101 called with and empty filename, the contents of the graph will be returned
 102 in the table as well (key 'image').
 103
 104 B<rrd.updatev> also returns a table. The keys of the table are strings
 105 formed by the concatenation of timestamp, RRA index and data source name
 106 for each consolidated data point (CDP) written to disk as a result of the
 107 current update call. The key values are CDP values.
 108
 109 B<rrd.fetch> is the most complex of the pack regarding return values. It
 110 returns 5 values: the initial timestamp, the step, two parallel arrays
 111 containing the data source names and their data points respectively, and
 112 the final timestamp.
 113
 114   package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' ..
 115                    package.cpath
 116   local rrd = require "rrd"
 117   local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
 118   local start, step, names, data =
 119     rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
 120   io.write(string.format("Start:       %s (%d)\n",
 121                          os.date("%c", start),start))
 122   io.write("Step size:   ", step, " seconds\n")
 123   io.write("DS names:    ", table.concat(names, ', '), "\n")
 124   io.write("Data points: ", #data[1], "\n")
 125   io.write("Data:\n")
 126   for i,dp in ipairs(data) do
 127     io.write(os.date("%t", start), " (", start, "): ")
 128     start = start + step
 129     for j,v in ipairs(dp) do
 130       io.write(v, " ")
 131     end
 132   io.write("\n")
 133   end
 134
 135 =head1 AUTHOR
 136
 137 Fidelis Assis E<lt>fidelis@pobox.comE<gt>