doc/rrdgraph_data.pod

   1 =head1 NAME
   2
   3 rrdtool graph - Round Robin Database tool grapher functions
   4
   5 WARNING: This is for version 1.1.x which is B<I<BETA>> software.
   6 The software may contain serious bugs. Some of the items
   7 described in here may not yet exist (although this should
   8 be mentioned) or still be in the alpha stage.  As with every
   9 other RRDtool release: use at your own risk.  In contrast with
  10 the stable version of RRDtool, this release may contain bugs
  11 known to the authors.  It is highly recommended that you subscribe
  12 to the mailing list.
  13
  14 =head1 SYNOPSYS
  15
  16 B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]]
  17
  18 B<VDEF>:I<vname>=I<RPN expression>
  19
  20 B<CDEF>:I<vname>=I<RPN expression>
  21
  22 =head1 DESCRIPTION
  23
  24 These three instructions collect the data out of the B<RRD> files,
  25 optionally altering it (think of a bytes to bits conversion) and
  26 if desired you can define variables containing useful information
  27 such as maximum, mininimum etcetera. Two of the instructions use
  28 a language called B<RPN> which is described in its own manual page.
  29
  30 =head1 DEF
  31
  32 B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]]
  33
  34 This command fetches data from an B<RRD> file.  The virtual name
  35 I<vname> can then be used throughout the rest of the script. By
  36 default, an B<RRA> which contains the correct consolidated data
  37 at an appropriate resolution will be chosen.  The resolution can
  38 be overriden with the L<--step|rrdgraph/item_Time> option.
  39 I<Not yet implemented:>[ The resolution can be overriden by specifying
  40 the B<step size>.]  I<Not yet implemented:> [ The time span of this data
  41 is the same as for the graph by default, you can override this by
  42 specifying the B<time range>. ]
  43
  44 If the resolution of the data is higher than the resolution of off
  45 graph, the data will be further consolidated.  This may result in
  46 a graph that spans slightly more time than requested.
  47 Ideally each point in the graph should correspond with one B<CDP>
  48 from an B<RRA>.  For instance, if your B<RRD> has an B<RRA> with
  49 a resolution of 1800 seconds per B<CDP>, you should create an
  50 image with width 400 and time span 400*1800 seconds (use appropriate
  51 start and end times, such as C<--start end-8days8hours>).
  52
  53 Example: C<DEF:mydata=router.rrd:ds0:AVERAGE>
  54
  55 Example: C<DEF:januari=router.rrd:ds0:AVERAGE:start=20010101 end=20010201>
  56
  57 =head1 VDEF
  58
  59 B<VDEF>:I<vname>=I<RPN expression>
  60
  61 This command returns a value and/or a time according to the B<RPN>
  62 statements used. The resulting I<vname> will, depending on the
  63 functions used, have a value and a time component.  When you use
  64 this I<vname> in another B<RPN> expression, you are effectively
  65 inserting its value just as if you had put a number at that place.
  66 The variable can also be used in the various graph and print
  67 elements. I<Not yet implemented:> [ Everywhere you can insert a
  68 number, you can also use the B<VDEF> (provided that it is set of course) ]
  69
  70 Example: C<VDEF:avg=mydata,AVERAGE>
  71
  72 =head1 CDEF
  73
  74 B<CDEF>:I<vname>=I<RPN expression>
  75
  76 This command creates a new set of data points (in memory only, not
  77 in the B<RRD> file) out of one or more other data series. The B<RPN>
  78 instructions are used to evaluate a mathematical function on each
  79 data point. The resulting I<vname> can then be used further on in
  80 the script, just as if it were generated by a B<DEF> instruction.
  81
  82 Example: C<CDEF:mydatabits=mydata,8,*>
  83
  84 =head1 SEE ALSO
  85
  86 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
  87 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
  88 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
  89 L<rrdgraph_graph> page describes all of the graph and print functions.
  90
  91 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
  92
  93 =head1 AUTHOR
  94
  95 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
  96
  97 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>