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")
36
Note that --template=in:out is also valid.
38
=head2 Using with Lua 5.1
40
Start your programs with:
42
---------------------------------------------------------------
43
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
46
---------------------------------------------------------------
48
OBS: If you configured with --enable-lua-site-install, you don't need
49
to set package.cpath like above.
51
=head2 Using with Lua 5.0
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:
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:
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'
69
LUA_PATH = original_LUA_PATH
70
original_LUA_PATH = nil
71
--- end of code to require compat-5.1 ---------------------------
73
Now we can require the rrd module in the same way we did for 5.1 above:
75
---------------------------------------------------------------
76
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
79
---------------------------------------------------------------
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'.
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'
97
-- here we use a protected call to require compat-5.1
98
local r = pcall(require, 'compat-5.1')
100
print('** could not load compat-5.1.lua')
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 ---------------------------
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:
113
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
116
local rrd = require 'rrd'
117
rrd.update ("mydemo.rrd","N:12:13")
119
If we execute the program above we'll get:
123
lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
125
[C]: in function `update'
126
t.lua:27: in main chunk
131
The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
132
return their findings.
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):
138
local firstdate = rrd.first('example.rrd', '--rraindex', 2)
140
B<rrd.last> returns a single INTEGER representing the last update time.
142
local lastupdate = rrd.last('example.rrd')
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.
147
local xsize, ysize, averages = rrd.graph ...
148
print(string.format("Image size: %dx%d", xsize, ysize)
149
print("Averages: ", table.concat(averages, ', '))
151
B<rrd.info> returns a table where the keys and the values represent property
152
names and property values of the RRD.
154
local info = rrd.info("test.rrd")
155
for key, value in pairs(info) do
156
print(key, ' = ', value)
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').
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.
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
175
--require compat-5.1 if necessary
177
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
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")
190
for i,dp in ipairs(data) do
191
io.write(os.date("%t", start), " (", start, "): ")
193
for j,v in ipairs(dp) do
201
Fidelis Assis E<lt>fidelis@pobox.comE<gt>
added
removed
doc/rrdlua.pod
