RRDLUA(1) rrdtool RRDLUA(1)
NAME
RRDLua - Lua binding for RRDTool
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(...)
DESCRIPTION
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.
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.
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
---------------------------------------------------------------
Error Handling
The Lua RRDTool module functions will abort your program with a stack traceback when they can not 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]: ?
Return Values
The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch return their findings.
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)
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
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 and empty filename, the contents of the graph will be returned in the table as well (key 'image').
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.
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
AUTHOR
Fidelis Assis <[email protected]>
1.4.8 2013-05-23 RRDLUA(1)
Back to main site | Back to man page index