mirror of
https://github.com/ntop/ntopng.git
synced 2026-07-28 00:58:40 +00:00
204 lines
6.8 KiB
Text
204 lines
6.8 KiB
Text
=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 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]: ?
|
|
|
|
=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 and 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>
|
|
|
|
|
|
|