diff --git a/doc/rrdgraph_data.pod b/doc/rrdgraph_data.pod
index 9e37efdc8a85cc2463ed8a40a788030980e350a2..57b9d0a70da66212ae590d37018d40f1241c066d 100644 (file)
--- a/doc/rrdgraph_data.pod
+++ b/doc/rrdgraph_data.pod
=head1 NAME
-rrdgraph_data - Preparing data for graphing
+rrdgraph_data - preparing data for graphing in rrdtool graph
=head1 SYNOPSIS
-B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>]
+B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>][:daemon=I<E<lt>addressE<gt>>]
B<VDEF>:I<vname>=I<RPN expression>
=head1 DESCRIPTION
-These three instructions collect the data out of the B<RRD> files,
-optionally altering it (think of a bytes to bits conversion) and
-if desired you can define variables containing useful information
-such as maximum, minimum etcetera. Two of the instructions use
-a language called B<RPN> which is described in its own manual page.
+These three instructions extract data values out of the B<RRD> files,
+optionally altering them (think, for example, of a bytes to bits
+conversion). If so desired, you can also define variables containing
+useful information such as maximum, minimum etcetera. Two of the
+instructions use a language called B<RPN> which is described in its
+own manual page.
+
+Variable names (I<vname>) must be made up strings of the following characters
+C<A-Z, a-z, 0-9, -,_> and a maximum length of 255 characters.
+
+When picking variable names, make sure you do not choose a name that is
+already taken by an RPN operator. A safe bet it to use lowercase or
+mixed case names for variables since operators will always be in uppercase.
=head1 DEF
-B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>]
+B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>][:daemon=I<E<lt>addressE<gt>>]
This command fetches data from an B<RRD> file. The virtual name
I<vname> can then be used throughout the rest of the script. By
default, an B<RRA> which contains the correct consolidated data
at an appropriate resolution will be chosen. The resolution can
-be overridden with the L<--step|rrdgraph/item_Time> option.
+be overridden with the L<--step|rrdgraph/item_Time> option.
The resolution can again be overridden by specifying the B<step size>.
The time span of this data is the same as for the graph by default,
you can override this by specifying B<start and end>. Remember to
escape colons in the time specification!
-If the resolution of the data is higher than the resolution of off
-graph, the data will be further consolidated. This may result in
+If the resolution of the data is higher than the resolution of the
+graph, the data will be further consolidated. This may result in
a graph that spans slightly more time than requested.
Ideally each point in the graph should correspond with one B<CDP>
from an B<RRA>. For instance, if your B<RRD> has an B<RRA> with
start and end times, such as C<--start end-8days8hours>).
If consolidation needs to be done, the B<CF> of the B<RRA> specified in the
-B<DEF> itself will be used to reduce the data density. This behaviour can
+B<DEF> itself will be used to reduce the data density. This behavior can
be changed using C<:reduce=I<E<lt>B<CF>E<gt>>>. This optional parameter
specifies the B<CF> to use during the data reduction phase.
+It is possible to request single data sources from a specific I<RRDCacheD>, see
+L<rrdcached(1)>, using the C<:daemon=I<E<lt>addressE<gt>>> parameter. The
+value given to this parameter follows the same syntax as other means to specify
+the address of the caching daemon. It is described in detail in the
+L<rrdcached(1)> manual page. Beware, however, that colons (in IPv6 addresses
+and as a port separator, for example) need to be escaped using a backslash.
+
Example:
DEF:ds0=router.rrd:ds0:AVERAGE
DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h
DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h
+ DEF:ds0weekly=router.rrd:ds0:AVERAGE:daemon=collect1.example.com
=head1 VDEF
Example: C<VDEF:avg=mydata,AVERAGE>
+Note that currently only aggregation functions work in VDEF rpn expressions.
+Patches to change this are welcome.
+
=head1 CDEF
B<CDEF>:I<vname>=I<RPN expression>
Example: C<CDEF:mydatabits=mydata,8,*>
+=head1 About CDEF versus VDEF
+
+At some point in processing, B<RRDtool> has gathered an array of rates
+ready to display.
+
+B<CDEF> works on such an array. For example, I<CDEF:new=ds0,8,*>
+would multiply each of the array members by eight (probably
+transforming bytes into bits). The result is an array containing the
+new values.
+
+B<VDEF> also works on such an array but in a different way. For
+example, I<VDEF:max=ds0,MAXIMUM> would scan each of the array members
+and store the maximum value.
+
+=head2 When do you use B<VDEF> versus B<CDEF>?
+
+Use B<CDEF> to transform your data prior to graphing. In the above
+example, we'd use a B<CDEF> to transform bytes to bits before
+graphing the bits.
+
+You use a B<VDEF> if you want I<max(1,5,3,2,4)> to return five which
+would be displayed in the graph's legend (to answer, what was the
+maximum value during the graph period).
+
+If you want to apply 'complex' operations to the result of a VDEF you have
+to use a CDEF again since VDEFs only look like RPN expressions, they aren't
+really.
+
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
L<rrdgraph_graph> page describes all of the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
=head1 AUTHOR
-Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
-This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
+This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt>
+with corrections and/or additions by several people