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