3 RRDLua - Lua binding for RRDTool
24 =head2 Calling Sequence
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
30 rrdtool update mydemo.rrd --template in:out N:12:13
34 rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")
38 --template=in:out is also valid.
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.
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:
51 package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' ..
53 local rrd = require 'rrd'
54 rrd.update ("mydemo.rrd","N:12:13")
58 lua: t.lua:8: opening 'mydemo.rrd': No such file or directory
60 [C]: in function 'update'
61 t.lua:8: in main chunk
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'.
70 The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
71 return their findings.
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):
77 local firstdate = rrd.first('example.rrd', '--rraindex', 2)
79 B<rrd.last> returns a single INTEGER representing the last update time.
81 local lastupdate = rrd.last('example.rrd')
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.
86 local xsize, ysize, averages = rrd.graph ...
87 print(string.format("Image size: %dx%d", xsize, ysize)
88 print("Averages: ", table.concat(averages, ', '))
90 B<rrd.info> returns a table where the keys and the values represent property
91 names and property values of the RRD.
93 local info = rrd.info("test.rrd")
94 for key, value in pairs(info) do
95 print(key, ' = ', value)
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').
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.
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
114 package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' ..
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")
126 for i,dp in ipairs(data) do
127 io.write(os.date("%t", start), " (", start, "): ")
129 for j,v in ipairs(dp) do
137 Fidelis Assis E<lt>fidelis@pobox.comE<gt>