1RRDLUA(1)                           rrdtool                          RRDLUA(1)
2
3
4

NAME

6       RRDLua -  Lua binding for RRDtool
7

SYNOPSIS

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

DESCRIPTION

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
30           rrdtool update mydemo.rrd --template in:out N:12:13
31
32       gets turned into
33
34           rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")
35
36       Note that --template=in:out is also valid.
37
38   Using with Lua 5.1
39       Start your programs with:
40
41           ---------------------------------------------------------------
42           package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
43                           package.cpath
44           require 'rrd'
45           ---------------------------------------------------------------
46
47       OBS: If you configured with --enable-lua-site-install, you don't need
48       to set package.cpath like above.
49
50   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
56           require 'compat-5.1'
57
58       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
63           -- 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
72           Now we can require the rrd module in the same way we did for 5.1 above:
73
74           ---------------------------------------------------------------
75           package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
76                           package.cpath
77           require 'rrd'
78           ---------------------------------------------------------------
79
80   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
87            Ex: program t.lua
88
89            --- 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
95            -- 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
102            -- 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
107            -- 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
111            package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
112                            package.cpath
113
114            local rrd = require 'rrd'
115            rrd.update ("mydemo.rrd","N:12:13")
116
117       If we execute the program above we'll get:
118
119            $ lua t.lua
120
121            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
127   Return Values
128       The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
129       return their findings.
130
131       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
135            local firstdate = rrd.first('example.rrd', '--rraindex', 2)
136
137       rrd.last returns a single INTEGER representing the last update time.
138
139            local lastupdate = rrd.last('example.rrd')
140
141       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
144            local xsize, ysize, averages = rrd.graph ...
145            print(string.format("Image size: %dx%d", xsize, ysize)
146            print("Averages: ", table.concat(averages, ', '))
147
148       rrd.info returns a table where the keys and the values represent
149       property names and property values of the RRD.
150
151            local info = rrd.info("test.rrd")
152            for key, value in pairs(info) do
153              print(key, ' = ', value)
154            end
155
156       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
162       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
167       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
172            --require compat-5.1 if necessary
173
174            package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
175                            package.cpath
176
177            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

AUTHOR

197       Fidelis Assis <fidelis@pobox.com>
198
199
200
2011.7.2                             2021-07-23                         RRDLUA(1)
Impressum