doc/rrdgraph_data.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>rrdgraph_data</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 <p><a name="__index__"></a></p>
  13 <!-- INDEX BEGIN -->
  14 <!--
  15
  16 <ul>
  17
  18         <li><a href="#name">NAME</a></li>
  19         <li><a href="#synopsis">SYNOPSIS</a></li>
  20         <li><a href="#description">DESCRIPTION</a></li>
  21         <li><a href="#def">DEF</a></li>
  22         <li><a href="#vdef">VDEF</a></li>
  23         <li><a href="#cdef">CDEF</a></li>
  24         <li><a href="#see_also">SEE ALSO</a></li>
  25         <li><a href="#author">AUTHOR</a></li>
  26 </ul>
  27 -->
  28 <!-- INDEX END -->
  29
  30 <p>
  31 </p>
  32 <h1><a name="name">NAME</a></h1>
  33 <p>rrdgraph_data - preparing data for graphing in rrdtool graph</p>
  34 <p>
  35 </p>
  36 <hr />
  37 <h1><a name="synopsis">SYNOPSIS</a></h1>
  38 <p><strong>DEF:</strong><em>&lt;vname&gt;</em>=<em>&lt;rrdfile&gt;</em>:<em>&lt;ds-name&gt;</em>:<em>&lt;CF&gt;</em>[:step=<em>&lt;step&gt;</em>][:start=<em>&lt;time&gt;</em>][:end=<em>&lt;time&gt;</em>][:reduce=<em>&lt;<strong>CF</strong>&gt;</em>]</p>
  39 <p><strong>VDEF</strong>:<em>vname</em>=<em>RPN expression</em></p>
  40 <p><strong>CDEF</strong>:<em>vname</em>=<em>RPN expression</em></p>
  41 <p>
  42 </p>
  43 <hr />
  44 <h1><a name="description">DESCRIPTION</a></h1>
  45 <p>These three instructions extract data values out of the <strong>RRD</strong> files,
  46 optionally altering them (think, for example, of a bytes to bits
  47 conversion). If so desired, you can also define variables containing
  48 useful information such as maximum, minimum etcetera. Two of the
  49 instructions use a language called <strong>RPN</strong> which is described in its
  50 own manual page.</p>
  51 <p>Variable names (<em>vname</em>) must be made up strings of the following characters
  52 <code>A-Z, a-z, 0-9, -,_</code> and a maximum length of 255 characters.</p>
  53 <p>When picking variable names, make sure you do not choose a name that is
  54 already taken by an RPN operator. A save bet it to use lowercase or
  55 mixedcase names for variables since operators will always be in uppercase.</p>
  56 <p>
  57 </p>
  58 <hr />
  59 <h1><a name="def">DEF</a></h1>
  60 <p><strong>DEF:</strong><em>&lt;vname&gt;</em>=<em>&lt;rrdfile&gt;</em>:<em>&lt;ds-name&gt;</em>:<em>&lt;CF&gt;</em>[:step=<em>&lt;step&gt;</em>][:start=<em>&lt;time&gt;</em>][:end=<em>&lt;time&gt;</em>][:reduce=<em>&lt;<strong>CF</strong>&gt;</em>]</p>
  61 <p>This command fetches data from an <strong>RRD</strong> file.  The virtual name
  62 <em>vname</em> can then be used throughout the rest of the script. By
  63 default, an <strong>RRA</strong> which contains the correct consolidated data
  64 at an appropriate resolution will be chosen.  The resolution can
  65 be overridden with the <a href="././rrdgraph.html#item_time">--step</a> option.
  66 The resolution can again be overridden by specifying the <strong>step size</strong>.
  67 The time span of this data is the same as for the graph by default,
  68 you can override this by specifying <strong>start and end</strong>.  Remember to
  69 escape colons in the time specification!</p>
  70 <p>If the resolution of the data is higher than the resolution of the
  71 graph, the data will be further consolidated. This may result in
  72 a graph that spans slightly more time than requested.
  73 Ideally each point in the graph should correspond with one <strong>CDP</strong>
  74 from an <strong>RRA</strong>.  For instance, if your <strong>RRD</strong> has an <strong>RRA</strong> with
  75 a resolution of 1800 seconds per <strong>CDP</strong>, you should create an
  76 image with width 400 and time span 400*1800 seconds (use appropriate
  77 start and end times, such as <code>--start end-8days8hours</code>).</p>
  78 <p>If consolidation needs to be done, the <strong>CF</strong> of the <strong>RRA</strong> specified in the
  79 <strong>DEF</strong> itself will be used to reduce the data density. This behaviour can
  80 be changed using <code>:reduce=&lt;CF&gt;</code>.  This optional parameter
  81 specifies the <strong>CF</strong> to use during the data reduction phase.</p>
  82 <p>Example:</p>
  83 <pre>
  84         DEF:ds0=router.rrd:ds0:AVERAGE
  85         DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
  86         DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h
  87         DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h</pre>
  88 <p>
  89 </p>
  90 <hr />
  91 <h1><a name="vdef">VDEF</a></h1>
  92 <p><strong>VDEF</strong>:<em>vname</em>=<em>RPN expression</em></p>
  93 <p>This command returns a value and/or a time according to the <strong>RPN</strong>
  94 statements used. The resulting <em>vname</em> will, depending on the
  95 functions used, have a value and a time component.  When you use
  96 this <em>vname</em> in another <strong>RPN</strong> expression, you are effectively
  97 inserting its value just as if you had put a number at that place.
  98 The variable can also be used in the various graph and print
  99 elements.</p>
 100 <p>Example: <code>VDEF:avg=mydata,AVERAGE</code></p>
 101 <p>Note that currently only agregation functions work in VDEF rpn expressions.
 102 Patches to change this are welcome.</p>
 103 <p>
 104 </p>
 105 <hr />
 106 <h1><a name="cdef">CDEF</a></h1>
 107 <p><strong>CDEF</strong>:<em>vname</em>=<em>RPN expression</em></p>
 108 <p>This command creates a new set of data points (in memory only, not
 109 in the <strong>RRD</strong> file) out of one or more other data series. The <strong>RPN</strong>
 110 instructions are used to evaluate a mathematical function on each
 111 data point. The resulting <em>vname</em> can then be used further on in
 112 the script, just as if it were generated by a <strong>DEF</strong> instruction.</p>
 113 <p>Example: <code>CDEF:mydatabits=mydata,8,*</code></p>
 114 <p>
 115 </p>
 116 <hr />
 117 <h1><a name="see_also">SEE ALSO</a></h1>
 118 <p><a href="././rrdgraph.html">the rrdgraph manpage</a> gives an overview of how <strong>rrdtool graph</strong> works.
 119 <a href="././rrdgraph_data.html">the rrdgraph_data manpage</a> describes <strong>DEF</strong>,<strong>CDEF</strong> and <strong>VDEF</strong> in detail.
 120 <a href="././rrdgraph_rpn.html">the rrdgraph_rpn manpage</a> describes the <strong>RPN</strong> language used in the <strong>?DEF</strong> statements.
 121 <a href="././rrdgraph_graph.html">the rrdgraph_graph manpage</a> page describes all of the graph and print functions.</p>
 122 <p>Make sure to read <a href="././rrdgraph_examples.html">the rrdgraph_examples manpage</a> for tips&amp;tricks.</p>
 123 <p>
 124 </p>
 125 <hr />
 126 <h1><a name="author">AUTHOR</a></h1>
 127 <p>Program by Tobias Oetiker &lt;<a href="mailto:tobi@oetiker.ch">tobi@oetiker.ch</a>&gt;</p>
 128 <p>This manual page by Alex van den Bogaerdt &lt;<a href="mailto:alex@ergens.op.het.net">alex@ergens.op.het.net</a>&gt;</p>
 129
 130 </body>
 131
 132 </html>