doc/rrdlua.1

   1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "RRDLUA 1"
 127 .TH RRDLUA 1 "2009-06-09" "1.3.999" "rrdtool"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 RRDLua \-  Lua binding for RRDTool
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 10
 137 \&  require \*(Aqrrd\*(Aq
 138 \&  rrd.create(...)
 139 \&  rrd.dump(...)
 140 \&  rrd.fetch(...)
 141 \&  rrd.first(...)
 142 \&  rrd.graph(...)
 143 \&  rrd.graphv(...)
 144 \&  rrd.info(...)
 145 \&  rrd.last(...)
 146 \&  rrd.resize(...)
 147 \&  rrd.restore(...)
 148 \&  rrd.tune(...)
 149 \&  rrd.update(...)
 150 \&  rrd.updatev(...)
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 .SS "Calling Sequence"
 155 .IX Subsection "Calling Sequence"
 156 This module accesses RRDtool functionality directly from within Lua.
 157 The arguments to the functions listed in the \s-1SYNOPSIS\s0 are explained in
 158 the regular RRDtool documentation. The command-line call
 159 .PP
 160 .Vb 1
 161 \&    rrdtool update mydemo.rrd \-\-template in:out N:12:13
 162 .Ve
 163 .PP
 164 gets turned into
 165 .PP
 166 .Vb 1
 167 \&    rrd.update ("mydemo.rrd", "\-\-template", "in:out", "N:12:13")
 168 .Ve
 169 .PP
 170 Note that \-\-template=in:out is also valid.
 171 .SS "Using with Lua 5.1"
 172 .IX Subsection "Using with Lua 5.1"
 173 Start your programs with:
 174 .PP
 175 .Vb 5
 176 \&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 177 \&    package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.1/?.so;\*(Aq ..
 178 \&                    package.cpath
 179 \&    require \*(Aqrrd\*(Aq
 180 \&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 181 .Ve
 182 .PP
 183 \&\s-1OBS:\s0 If you configured with \-\-enable\-lua\-site\-install, you don't need
 184 to set package.cpath like above.
 185 .SS "Using with Lua 5.0"
 186 .IX Subsection "Using with Lua 5.0"
 187 The Lua binding for RRDtool needs the Lua module compat\-5.1 to work with
 188 Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it already
 189 integrated in Lua 5.0 \-dev packages, so you just have to require it:
 190 .PP
 191 .Vb 1
 192 \&    require \*(Aqcompat\-5.1\*(Aq
 193 .Ve
 194 .PP
 195 For other platforms, the compat\-5.1 module that comes with this binding
 196 will be installed for you in the same dir where RRDtool was installed,
 197 under the subdir .../lib/lua/5.0. In this case, you must tell your Lua
 198 programs where to find it by changing the Lua var \s-1LUA_PATH:\s0
 199 .PP
 200 .Vb 8
 201 \&    \-\- compat\-5.1.lua is only necessary for Lua 5.0 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 202 \&    \-\- try only compat\-5.1 installed with RRDtool package
 203 \&    local original_LUA_PATH = LUA_PATH
 204 \&    LUA_PATH = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.lua\*(Aq
 205 \&    require \*(Aqcompat\-5.1\*(Aq
 206 \&    LUA_PATH = original_LUA_PATH
 207 \&    original_LUA_PATH = nil
 208 \&    \-\-\- end of code to require compat\-5.1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 209 \&
 210 \&    Now we can require the rrd module in the same way we did for 5.1 above:
 211 \&
 212 \&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 213 \&    package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.so;\*(Aq ..
 214 \&                    package.cpath
 215 \&    require \*(Aqrrd\*(Aq
 216 \&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 217 .Ve
 218 .SS "Error Handling"
 219 .IX Subsection "Error Handling"
 220 The Lua RRDTool module functions will abort your program with a stack
 221 traceback when they can not make sense out of the arguments you fed them.
 222 However, you can capture and handle the errors yourself, instead of just
 223 letting the program abort, by calling the module functions through Lua
 224 protected calls \- 'pcall' or 'xpcall'.
 225 .PP
 226 .Vb 1
 227 \&     Ex: program t.lua
 228 \&
 229 \&     \-\-\- compat\-5.1.lua is only necessary for Lua 5.0 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 230 \&     \-\- uncomment below if your distro has not compat\-5.1
 231 \&     \-\- original_LUA_PATH = LUA_PATH
 232 \&     \-\- try only compat\-5.1.lua installed with RRDtool package
 233 \&     \-\- LUA_PATH = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.lua\*(Aq
 234 \&
 235 \&     \-\- here we use a protected call to require compat\-5.1
 236 \&     local r = pcall(require, \*(Aqcompat\-5.1\*(Aq)
 237 \&     if not r then
 238 \&       print(\*(Aq** could not load compat\-5.1.lua\*(Aq)
 239 \&       os.exit(1)
 240 \&     end
 241 \&
 242 \&     \-\- uncomment below if your distro has not compat\-5.1
 243 \&     \-\- LUA_PATH = original_LUA_PATH
 244 \&     \-\- original_LUA_PATH = nil
 245 \&     \-\-\- end of code to require compat\-5.1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 246 \&
 247 \&     \-\- If the Lua RRDTool module was installed together with RRDTool,
 248 \&     \-\- in /usr/local/rrdtool\-1.3.2/lib/lua/5.0, package.cpath must be
 249 \&     \-\- set accordingly so that \*(Aqrequire\*(Aq can find the module:
 250 \&
 251 \&     package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.so;\*(Aq ..
 252 \&                     package.cpath
 253 \&
 254 \&     local rrd = require \*(Aqrrd\*(Aq
 255 \&     rrd.update ("mydemo.rrd","N:12:13")
 256 .Ve
 257 .PP
 258 If we execute the program above we'll get:
 259 .PP
 260 .Vb 1
 261 \&     $ lua t.lua
 262 \&
 263 \&     lua: t.lua:27: opening \*(Aqmydemo.rrd\*(Aq: No such file or directory
 264 \&     stack traceback:
 265 \&           [C]: in function \`update\*(Aq
 266 \&           t.lua:27: in main chunk
 267 \&           [C]: ?
 268 .Ve
 269 .SS "Return Values"
 270 .IX Subsection "Return Values"
 271 The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
 272 return their findings.
 273 .PP
 274 \&\fBrrd.first\fR returns a single \s-1INTEGER\s0 representing the timestamp of the
 275 first data sample in an \s-1RRA\s0 within an \s-1RRD\s0 file. Example returning the
 276 first timestamp of the third \s-1RRA\s0 (index 2):
 277 .PP
 278 .Vb 1
 279 \&     local firstdate = rrd.first(\*(Aqexample.rrd\*(Aq, \*(Aq\-\-rraindex\*(Aq, 2)
 280 .Ve
 281 .PP
 282 \&\fBrrd.last\fR returns a single \s-1INTEGER\s0 representing the last update time.
 283 .PP
 284 .Vb 1
 285 \&     local lastupdate = rrd.last(\*(Aqexample.rrd\*(Aq)
 286 .Ve
 287 .PP
 288 \&\fBrrd.graph\fR returns the x\-size and y\-size of the created image and a table
 289 with the results of the \s-1PRINT\s0 arguments.
 290 .PP
 291 .Vb 3
 292 \&     local xsize, ysize, averages = rrd.graph ...
 293 \&     print(string.format("Image size: %dx%d", xsize, ysize)
 294 \&     print("Averages: ", table.concat(averages, \*(Aq, \*(Aq))
 295 .Ve
 296 .PP
 297 \&\fBrrd.info\fR returns a table where the keys and the values represent property
 298 names and property values of the \s-1RRD\s0.
 299 .PP
 300 .Vb 4
 301 \&     local info = rrd.info("test.rrd")
 302 \&     for key, value in pairs(info) do
 303 \&       print(key, \*(Aq = \*(Aq, value)
 304 \&     end
 305 .Ve
 306 .PP
 307 \&\fBrrd.graphv\fR takes the same parameters as rrd.graph but it returns a table
 308 only. The table returned contains meta information about the graph, like
 309 its size as well as the position of the graph area on the image. When
 310 called with and empty filename, the contents of the graph will be returned
 311 in the table as well (key 'image').
 312 .PP
 313 \&\fBrrd.updatev\fR also returns a table. The keys of the table are strings
 314 formed by the concatenation of timestamp, \s-1RRA\s0 index and data source name
 315 for each consolidated data point (\s-1CDP\s0) written to disk as a result of the
 316 current update call. The key values are \s-1CDP\s0 values.
 317 .PP
 318 \&\fBrrd.fetch\fR is the most complex of the pack regarding return values. It
 319 returns 5 values: the initial timestamp, the step, two parallel arrays
 320 containing the data source names and their data points respectively, and
 321 the final timestamp.
 322 .PP
 323 .Vb 1
 324 \&     \-\-require compat\-5.1 if necessary
 325 \&
 326 \&     package.cpath = \*(Aq/usr/local/rrdtool\-1.3.2/lib/lua/5.0/?.so;\*(Aq ..
 327 \&                     package.cpath
 328 \&
 329 \&     local rrd = require "rrd"
 330 \&     local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
 331 \&     local start, step, names, data =
 332 \&       rrd.fetch("test.rrd", "\-\-start", first, "\-\-end", last, "AVERAGE")
 333 \&     io.write(string.format("Start:       %s (%d)\en",
 334 \&                            os.date("%c", start),start))
 335 \&     io.write("Step size:   ", step, " seconds\en")
 336 \&     io.write("DS names:    ", table.concat(names, \*(Aq, \*(Aq), "\en")
 337 \&     io.write("Data points: ", #data[1], "\en")
 338 \&     io.write("Data:\en")
 339 \&     for i,dp in ipairs(data) do
 340 \&       io.write(os.date("%t", start), " (", start, "): ")
 341 \&       start = start + step
 342 \&       for j,v in ipairs(dp) do
 343 \&         io.write(v, " ")
 344 \&       end
 345 \&     io.write("\en")
 346 \&     end
 347 .Ve
 348 .SH "AUTHOR"
 349 .IX Header "AUTHOR"
 350 Fidelis Assis <fidelis@pobox.com>