mirror of
https://github.com/ntop/ntopng.git
synced 2026-08-10 17:03:29 +00:00
135 lines
5.3 KiB
Text
135 lines
5.3 KiB
Text
=head1 NAME
|
|
|
|
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<VDEF>:I<vname>=I<RPN expression>
|
|
|
|
B<CDEF>:I<vname>=I<RPN expression>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
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>>]
|
|
|
|
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.
|
|
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 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
|
|
a resolution of 1800 seconds per B<CDP>, you should create an
|
|
image with width 400 and time span 400*1800 seconds (use appropriate
|
|
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 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.
|
|
|
|
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
|
|
|
|
=head1 VDEF
|
|
|
|
B<VDEF>:I<vname>=I<RPN expression>
|
|
|
|
This command returns a value and/or a time according to the B<RPN>
|
|
statements used. The resulting I<vname> will, depending on the
|
|
functions used, have a value and a time component. When you use
|
|
this I<vname> in another B<RPN> expression, you are effectively
|
|
inserting its value just as if you had put a number at that place.
|
|
The variable can also be used in the various graph and print
|
|
elements.
|
|
|
|
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>
|
|
|
|
This command creates a new set of data points (in memory only, not
|
|
in the B<RRD> file) out of one or more other data series. The B<RPN>
|
|
instructions are used to evaluate a mathematical function on each
|
|
data point. The resulting I<vname> can then be used further on in
|
|
the script, just as if it were generated by a B<DEF> instruction.
|
|
|
|
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_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>tobi@oetiker.chE<gt>
|
|
|
|
This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt>
|
|
with corrections and/or additions by several people
|