doc/rrdgraph_data.src

   1 =include name
   2
   3 =head1 SYNOPSYS
   4
   5 B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:step=I<step size>][:<time range>>]
   6
   7 B<VDEF>:I<vname>=I<RPN expression>
   8
   9 B<CDEF>:I<vname>=I<RPN expression>
  10
  11 =head1 DESCRIPTION
  12
  13 These three instructions collect the data out of the B<RRD> files,
  14 optionally altering it (think of a bytes to bits conversion) and
  15 if desired you can define variables containing useful information
  16 such as maximum, mininimum etcetera. Two of the instructions use
  17 a language called B<RPN> which is described in its own manual page.
  18
  19 =head1 DEF
  20
  21 B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:step=I<step size>][:<time range>>]
  22
  23 This command fetches data from an B<RRD> file.  The virtual name
  24 I<vname> can then be used throughout the rest of the script. By
  25 default, an B<RRA> which contains the correct consolidated data
  26 at an appropriate resolution will be chosen.  The resolution can
  27 be overriden with the L<--step|rrdgraph/item_Time> option.
  28 The resolution can again be overriden by specifying the B<step size>.
  29 I<Not yet implemented:> [ The time span of this data
  30 is the same as for the graph by default, you can override this by
  31 specifying the B<time range>. ]
  32
  33 If the resolution of the data is higher than the resolution of off
  34 graph, the data will be further consolidated.  This may result in
  35 a graph that spans slightly more time than requested.
  36 Ideally each point in the graph should correspond with one B<CDP>
  37 from an B<RRA>.  For instance, if your B<RRD> has an B<RRA> with
  38 a resolution of 1800 seconds per B<CDP>, you should create an
  39 image with width 400 and time span 400*1800 seconds (use appropriate
  40 start and end times, such as C<--start end-8days8hours>).
  41
  42 Example:
  43
  44         DEF:ds0=router.rrd:ds0:AVERAGE
  45         DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
  46
  47 =head1 VDEF
  48
  49 B<VDEF>:I<vname>=I<RPN expression>
  50
  51 This command returns a value and/or a time according to the B<RPN>
  52 statements used. The resulting I<vname> will, depending on the
  53 functions used, have a value and a time component.  When you use
  54 this I<vname> in another B<RPN> expression, you are effectively
  55 inserting its value just as if you had put a number at that place.
  56 The variable can also be used in the various graph and print
  57 elements. I<Not yet implemented:> [ Everywhere you can insert a
  58 number, you can also use the B<VDEF> (provided that it is set of course) ]
  59
  60 Example: C<VDEF:avg=mydata,AVERAGE>
  61
  62 =head1 CDEF
  63
  64 B<CDEF>:I<vname>=I<RPN expression>
  65
  66 This command creates a new set of data points (in memory only, not
  67 in the B<RRD> file) out of one or more other data series. The B<RPN>
  68 instructions are used to evaluate a mathematical function on each
  69 data point. The resulting I<vname> can then be used further on in
  70 the script, just as if it were generated by a B<DEF> instruction.
  71
  72 Example: C<CDEF:mydatabits=mydata,8,*>
  73
  74 =include see_also