X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdlua.pod;h=7d234fe3244c77e02e75cf33bd89382cd6450c15;hp=a6240f28fbaae41860eabeb8766acfbbd4d3e6fd;hb=3501907ea29f921eefcae6bd50c3f31eca0e49b2;hpb=9b60b973b11307d6c812db001334352fbda4cdb9 diff --git a/doc/rrdlua.pod b/doc/rrdlua.pod index a6240f2..7d234fe 100644 --- a/doc/rrdlua.pod +++ b/doc/rrdlua.pod @@ -27,43 +27,104 @@ 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 + 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. + 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. - - Ex: - - -- If the Lua RRDTool module was installed together with RRDTool, - -- in $prefix/lib/lua/$lua_version, package.cpath must be set like - -- in the example below, so that 'require' can find the module: - - package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' .. - package.cpath - local rrd = require 'rrd' - rrd.update ("mydemo.rrd","N:12:13") - - $ lua t.lua - - lua: t.lua:8: opening 'mydemo.rrd': No such file or directory - stack traceback: - [C]: in function 'update' - t.lua:8: in main chunk - [C]: ? - -You may 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'. +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 @@ -74,26 +135,26 @@ B 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) + local firstdate = rrd.first('example.rrd', '--rraindex', 2) B returns a single INTEGER representing the last update time. - local lastupdate = rrd.last('example.rrd') + local lastupdate = rrd.last('example.rrd') B 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, ', ')) + local xsize, ysize, averages = rrd.graph ... + print(string.format("Image size: %dx%d", xsize, ysize) + print("Averages: ", table.concat(averages, ', ')) B 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 + local info = rrd.info("test.rrd") + for key, value in pairs(info) do + print(key, ' = ', value) + end B takes the same parameters as rrd.graph but it returns a table only. The table returned contains meta information about the graph, like @@ -111,27 +172,33 @@ 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. - package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.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 + --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 Efidelis@pobox.comE + + +