doc/rrdlua.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>rrdlua</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body style="background-color: white">
  11
  12
  13 <!-- INDEX BEGIN -->
  14 <div name="index">
  15 <p><a name="__index__"></a></p>
  16 <!--
  17
  18 <ul>
  19
  20         <li><a href="#name">NAME</a></li>
  21         <li><a href="#synopsis">SYNOPSIS</a></li>
  22         <li><a href="#description">DESCRIPTION</a></li>
  23         <ul>
  24
  25                 <li><a href="#calling_sequence">Calling Sequence</a></li>
  26                 <li><a href="#using_with_lua_5_1">Using with Lua 5.1</a></li>
  27                 <li><a href="#using_with_lua_5_0">Using with Lua 5.0</a></li>
  28                 <li><a href="#error_handling">Error Handling</a></li>
  29                 <li><a href="#return_values">Return Values</a></li>
  30         </ul>
  31
  32         <li><a href="#author">AUTHOR</a></li>
  33 </ul>
  34
  35 -->
  36
  37
  38 </div>
  39 <!-- INDEX END -->
  40
  41 <p>
  42 </p>
  43 <h1><a name="name">NAME</a></h1>
  44 <p>RRDLua -  Lua binding for RRDTool</p>
  45 <p>
  46 </p>
  47 <hr />
  48 <h1><a name="synopsis">SYNOPSIS</a></h1>
  49 <pre>
  50   require 'rrd'
  51   rrd.create(...)
  52   rrd.dump(...)
  53   rrd.fetch(...)
  54   rrd.first(...)
  55   rrd.graph(...)
  56   rrd.graphv(...)
  57   rrd.info(...)
  58   rrd.last(...)
  59   rrd.resize(...)
  60   rrd.restore(...)
  61   rrd.tune(...)
  62   rrd.update(...)
  63   rrd.updatev(...)</pre>
  64 <p>
  65 </p>
  66 <hr />
  67 <h1><a name="description">DESCRIPTION</a></h1>
  68 <p>
  69 </p>
  70 <h2><a name="calling_sequence">Calling Sequence</a></h2>
  71 <p>This module accesses RRDtool functionality directly from within Lua.
  72 The arguments to the functions listed in the SYNOPSIS are explained in
  73 the regular RRDtool documentation. The command-line call</p>
  74 <pre>
  75     rrdtool update mydemo.rrd --template in:out N:12:13</pre>
  76 <p>gets turned into</p>
  77 <pre>
  78     rrd.update (&quot;mydemo.rrd&quot;, &quot;--template&quot;, &quot;in:out&quot;, &quot;N:12:13&quot;)</pre>
  79 <p>Note that --template=in:out is also valid.</p>
  80 <p>
  81 </p>
  82 <h2><a name="using_with_lua_5_1">Using with Lua 5.1</a></h2>
  83 <p>Start your programs with:</p>
  84 <pre>
  85     ---------------------------------------------------------------
  86     package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
  87                     package.cpath
  88     require 'rrd'
  89     ---------------------------------------------------------------
  90
  91 OBS: If you configured with --enable-lua-site-install, you don't need
  92 to set package.cpath like above.</pre>
  93 <p>
  94 </p>
  95 <h2><a name="using_with_lua_5_0">Using with Lua 5.0</a></h2>
  96 <p>The Lua binding for RRDtool needs the Lua module compat-5.1 to work with
  97 Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it already
  98 integrated in Lua 5.0 -dev packages, so you just have to require it:</p>
  99 <pre>
 100     require 'compat-5.1'</pre>
 101 <p>For other platforms, the compat-5.1 module that comes with this binding
 102 will be installed for you in the same dir where RRDtool was installed,
 103 under the subdir .../lib/lua/5.0. In this case, you must tell your Lua
 104 programs where to find it by changing the Lua var LUA_PATH:</p>
 105 <pre>
 106     -- compat-5.1.lua is only necessary for Lua 5.0 ----------------
 107     -- try only compat-5.1 installed with RRDtool package
 108     local original_LUA_PATH = LUA_PATH
 109     LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
 110     require 'compat-5.1'
 111     LUA_PATH = original_LUA_PATH
 112     original_LUA_PATH = nil
 113     --- end of code to require compat-5.1 ---------------------------
 114
 115     Now we can require the rrd module in the same way we did for 5.1 above:
 116
 117     ---------------------------------------------------------------
 118     package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 119                     package.cpath
 120     require 'rrd'
 121     ---------------------------------------------------------------</pre>
 122 <p>
 123 </p>
 124 <h2><a name="error_handling">Error Handling</a></h2>
 125 <p>The Lua RRDTool module functions will abort your program with a stack
 126 traceback when they can not make sense out of the arguments you fed them.
 127 However, you can capture and handle the errors yourself, instead of just
 128 letting the program abort, by calling the module functions through Lua
 129 protected calls - 'pcall' or 'xpcall'.</p>
 130 <pre>
 131      Ex: program t.lua
 132
 133      --- compat-5.1.lua is only necessary for Lua 5.0 ----------------
 134      -- uncomment below if your distro has not compat-5.1
 135      -- original_LUA_PATH = LUA_PATH
 136      -- try only compat-5.1.lua installed with RRDtool package
 137      -- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
 138
 139      -- here we use a protected call to require compat-5.1
 140      local r = pcall(require, 'compat-5.1')
 141      if not r then
 142        print('** could not load compat-5.1.lua')
 143        os.exit(1)
 144      end
 145
 146      -- uncomment below if your distro has not compat-5.1
 147      -- LUA_PATH = original_LUA_PATH
 148      -- original_LUA_PATH = nil
 149      --- end of code to require compat-5.1 ---------------------------
 150
 151      -- If the Lua RRDTool module was installed together with RRDTool,
 152      -- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be
 153      -- set accordingly so that 'require' can find the module:
 154
 155      package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 156                      package.cpath
 157
 158      local rrd = require 'rrd'
 159      rrd.update (&quot;mydemo.rrd&quot;,&quot;N:12:13&quot;)
 160
 161 If we execute the program above we'll get:</pre>
 162 <pre>
 163      $ lua t.lua
 164
 165      lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
 166      stack traceback:
 167            [C]: in function `update'
 168            t.lua:27: in main chunk
 169            [C]: ?</pre>
 170 <p>
 171 </p>
 172 <h2><a name="return_values">Return Values</a></h2>
 173 <p>The functions rrd.first, rrd.last, rrd.graph, rrd.info and rrd.fetch
 174 return their findings.</p>
 175 <p><strong>rrd.first</strong> returns a single INTEGER representing the timestamp of the
 176 first data sample in an RRA within an RRD file. Example returning the
 177 first timestamp of the third RRA (index 2):</p>
 178 <pre>
 179      local firstdate = rrd.first('example.rrd', '--rraindex', 2)</pre>
 180 <p><strong>rrd.last</strong> returns a single INTEGER representing the last update time.</p>
 181 <pre>
 182      local lastupdate = rrd.last('example.rrd')</pre>
 183 <p><strong>rrd.graph</strong> returns the x-size and y-size of the created image and a table
 184 with the results of the PRINT arguments.</p>
 185 <pre>
 186      local xsize, ysize, averages = rrd.graph ...
 187      print(string.format(&quot;Image size: %dx%d&quot;, xsize, ysize)
 188      print(&quot;Averages: &quot;, table.concat(averages, ', '))</pre>
 189 <p><strong>rrd.info</strong> returns a table where the keys and the values represent property
 190 names and property values of the RRD.</p>
 191 <pre>
 192      local info = rrd.info(&quot;test.rrd&quot;)
 193      for key, value in pairs(info) do
 194        print(key, ' = ', value)
 195      end</pre>
 196 <p><strong>rrd.graphv</strong> takes the same parameters as rrd.graph but it returns a table
 197 only. The table returned contains meta information about the graph, like
 198 its size as well as the position of the graph area on the image. When
 199 called with and empty filename, the contents of the graph will be returned
 200 in the table as well (key 'image').</p>
 201 <p><strong>rrd.updatev</strong> also returns a table. The keys of the table are strings
 202 formed by the concatenation of timestamp, RRA index and data source name
 203 for each consolidated data point (CDP) written to disk as a result of the
 204 current update call. The key values are CDP values.</p>
 205 <p><strong>rrd.fetch</strong> is the most complex of the pack regarding return values. It
 206 returns 5 values: the initial timestamp, the step, two parallel arrays
 207 containing the data source names and their data points respectively, and
 208 the final timestamp.</p>
 209 <pre>
 210      --require compat-5.1 if necessary
 211
 212      package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
 213                      package.cpath
 214
 215      local rrd = require &quot;rrd&quot;
 216      local first, last = rrd.first(&quot;test.rrd&quot;), rrd.last(&quot;test.rrd&quot;)
 217      local start, step, names, data =
 218        rrd.fetch(&quot;test.rrd&quot;, &quot;--start&quot;, first, &quot;--end&quot;, last, &quot;AVERAGE&quot;)
 219      io.write(string.format(&quot;Start:       %s (%d)\n&quot;,
 220                             os.date(&quot;%c&quot;, start),start))
 221      io.write(&quot;Step size:   &quot;, step, &quot; seconds\n&quot;)
 222      io.write(&quot;DS names:    &quot;, table.concat(names, ', '), &quot;\n&quot;)
 223      io.write(&quot;Data points: &quot;, #data[1], &quot;\n&quot;)
 224      io.write(&quot;Data:\n&quot;)
 225      for i,dp in ipairs(data) do
 226        io.write(os.date(&quot;%t&quot;, start), &quot; (&quot;, start, &quot;): &quot;)
 227        start = start + step
 228        for j,v in ipairs(dp) do
 229          io.write(v, &quot; &quot;)
 230        end
 231      io.write(&quot;\n&quot;)
 232      end</pre>
 233 <p>
 234 </p>
 235 <hr />
 236 <h1><a name="author">AUTHOR</a></h1>
 237 <p>Fidelis Assis &lt;<a href="mailto:fidelis@pobox.com">fidelis@pobox.com</a>&gt;</p>
 238
 239 </body>
 240
 241 </html>