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