S<[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
S<[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
S<[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
+S<[B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]]>
=head1 DESCRIPTION
the first place ;)
Note, that when you STACK onto *UNKNOWN* data, rrdtool will not draw
-any graphics ... *UNKNOWN* is not zero ... if you want it to zero
+any graphics ... *UNKNOWN* is not zero ... if you want it to be zero
then you might want to use a CDEF argument with IF and UN functions to
turn *UNKNOWN* into zero ...
+=item B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]
+
+Plot a tick mark (a vertical line) for each value of I<vname> that is
+non-zero and not *UNKNOWN*. The I<axis-fraction> argument specifies the
+length of the tick mark as a fraction of the y-axis; the default value
+is 0.1 (10% of the axis). Note that the color specification is not
+optional.
+
=back
=head1 NOTES on legend arguments
otherwhise you would would have to add NEGINF in order to extend the coverage
of the rea to whole graph.
+=head1 EXAMPLE 4
+
+If the specialized function B<RRAs> exist for aberrant behavior detection, they
+can be used to generate the graph of a time series with confidence bands and
+failures.
+
+ rrdtool graph example.gif \
+ DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \
+ DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \
+ DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \
+ DEF:fail=monitor.rrd:ifOutOctets:FAILURES \
+ TICK:fail#ffffa0:1.0:"Failures\: Average bits out" \
+ CDEF:scaledobs=obs,8,* \
+ CDEF:upper=pred,dev,2,*,+ \
+ CDEF:lower=pred,dev,2,*,- \
+ CDEF:scaledupper=upper,8,* \
+ CDEF:scaledlower=lower,8,* \
+ LINE2:scaledobs#0000ff:"Average bits out" \
+ LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \
+ LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out"
+
+This example generates a graph of the data series in blue (LINE2 with the scaledobs
+virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
+data sources), and potential failures (i.e. potential aberrant aberrant behavior)
+marked by vertical yellow lines (the fail data source).
+
+The raw data comes from an AVERAGE B<RRA>, the finest resolution of the observed
+time series (one consolidated data point per primary data point). The predicted
+(or smoothed) values are stored in the HWPREDICT B<RRA>. The predicted deviations
+(think standard deviation) values are stored in the DEVPREDICT B<RRA>. Finally,
+the FAILURES B<RRA> contains indicators, with 1 denoting a potential failure.
+
+All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
+The confidence bounds are computed by an offset of 2 deviations both above
+and below the predicted values (the CDEFs upper and lower). Vertical lines
+indicated potential failures are graphed via the TICK graph element, which
+converts non-zero values in an B<RRA> into tick marks. Here an axis-fraction
+argument of 1.0 means the tick marks span the entire y-axis, and hence become
+vertical lines on the graph.
+
+The choice of 2 deviations (a scaling factor) matches the default used internally
+by the FAILURES B<RRA>. If the internal value is changed (see L<rrdtune>), this
+graphing command should be changed to be consistent.
+
+=head2 A note on data reduction:
+
+The B<rrdtool> I<graph> command is designed to plot data at a specified temporal
+resolution, regardless of the actually resolution of the data in the RRD file.
+This can present a problem for the specialized consolidation functions which
+maintain a one-to-one mapping between primary data points and consolidated
+data points. If a graph insists on viewing the contents of these B<RRAs> on a
+coarser temporal scale, the I<graph> command tries to do something intelligent,
+but the confidence bands and failures no longer have the same meaning and may
+be misleading.
+
=head1 AUTHOR
Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
projects / rrdtool.git / blobdiff