ترتیب فراخوانی (Calling Sequence)

این پودمان امکان دسترسی مستقیم به قابلیت‌های RRDtool را از درون Lua فراهم می‌کند. آرگومان‌های توابع فهرست‌شده در بخش خلاصه دستور (SYNOPSIS) در مستندات اصلی RRDtool توضیح داده شده‌اند. فراخوانی خط فرمانی

rrdtool update mydemo.rrd --template in:out N:12:13

به شکل زیر تبدیل می‌شود:

rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")

توجه داشته باشید که استفاده از --template=in:out نیز معتبر است.

استفاده با Lua 5.1 (Using with Lua 5.1)

برنامه‌های خود را به این صورت آغاز کنید:

---------------------------------------------------------------
package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
                package.cpath
require 'rrd'
---------------------------------------------------------------

نکته: اگر با گزینهٔ --enable-lua-site-install پیکربندی کرده‌اید، نیازی به تنظیم package.cpath مانند بالا نخواهید داشت.

استفاده با Lua 5.0 (Using with Lua 5.0)

رابط Lua برای RRDtool جهت کار با Lua 5.0 به پودمان compat-5.1 در Lua نیاز دارد. برخی از توزیع‌های لینوکس مانند Ubuntu gutsy و hardy، از پیش آن را در بسته‌های -dev مربوط به Lua 5.0 ادغام کرده‌اند، بنابراین تنها کافی است آن را با require فراخوانی کنید:

require 'compat-5.1'

برای سایر پلتفرم‌ها، پودمان compat-5.1 که به همراه این رابط ارائه می‌شود در همان دایرکتوری محل نصب RRDtool و در زیرشاخهٔ .../lib/lua/5.0 نصب خواهد شد. در این حالت، باید با تغییر دادن متغیر LUA_PATH در Lua به برنامه‌های خود مشخص کنید آن را در کجا پیدا کنند:

-- 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'
---------------------------------------------------------------

مدیریت خطا (Error Handling)

توابع پودمان Lua برای RRDtool در صورتی که نتوانند آرگومان‌های ارائه‌شده را تحلیل کنند، برنامهٔ شما را با نمایش ردگیری پشته (stack traceback) متوقف خواهند کرد. با این حال، به جای این که بگذارید برنامه متوقف شود، می‌توانید با فراخوانی توابع پودمان از طریق فراخوانی‌های حفاظت‌شدهٔ Lua یعنی 'pcall' یا '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")

اگر برنامهٔ بالا را اجرا کنیم، خروجی زیر را خواهیم گرفت:

$ 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)

توابع rrd.first، rrd.last، rrd.graph، rrd.info و rrd.fetch مقادیر حاصل از پردازش خود را بازمی‌گردانند.

rrd.first یک مقدار INTEGER منفرد را برمی‌گرداند که نشان‌دهندهٔ برچسب زمانی (timestamp) نخستین نمونهٔ داده در یک RRA درون یک فایل RRD است. نمونه‌ای برای بازگرداندن برچسب زمانی نخستین داده در سومین RRA (اندیس ۲):

local firstdate = rrd.first('example.rrd', '--rraindex', 2)

rrd.last یک مقدار INTEGER منفرد را برمی‌گرداند که نشان‌دهندهٔ زمان آخرین به‌روزرسانی است.

local lastupdate = rrd.last('example.rrd')

rrd.graph مقادیر x-size و y-size تصویر ایجادشده و یک جدول شامل نتایج آرگومان‌های PRINT را برمی‌گرداند.

local xsize, ysize, averages = rrd.graph ...
print(string.format("Image size: %dx%d", xsize, ysize)
print("Averages: ", table.concat(averages, ', '))

rrd.info یک جدول بازمی‌گرداند که در آن کلیدها و مقادیر نشان‌دهندهٔ نام‌ها و مقادیر ویژگی‌های RRD هستند.

local info = rrd.info("test.rrd")
for key, value in pairs(info) do
  print(key, ' = ', value)
end

rrd.graphv همان پارامترهای rrd.graph را می‌گیرد، اما تنها یک جدول برمی‌گرداند. جدول بازگردانده‌شده حاوی اطلاعات فراداده‌ای دربارهٔ نمودار، مانند ابعاد آن و موقعیت ناحیهٔ نمودار روی تصویر است. هنگامی که با یک نام فایل خالی فراخوانی شود، محتوای تصویر نمودار نیز درون جدول قرار می‌گیرد (کلید 'image').

rrd.updatev نیز یک جدول برمی‌گرداند. کلیدهای این جدول رشته‌هایی هستند که از پیوند دادن برچسب زمانی، اندیس RRA و نام منبع داده (DS) به ازای هر نقطه دادهٔ تجمیع‌شده (CDP) که در نتیجهٔ فراخوانی به‌روزرسانی جاری روی دیسک ذخیره شده، ساخته شده‌اند. مقادیر این کلیدها همان مقادیر CDP هستند.

rrd.fetch در میان این توابع از نظر مقادیر بازگشتی پیچیده‌ترین است. این تابع ۵ مقدار برمی‌گرداند: برچسب زمانی اولیه، گام (step)، دو آرایهٔ موازی به ترتیب شامل نام‌های منبع داده و نقاط دادهٔ آنها، و برچسب زمانی نهایی.

--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