Imported upstream version 1.3rc4.

[pkg-rrdtool.git] / doc / rrdgraph_examples.html

diff --git a/doc/rrdgraph_examples.html b/doc/rrdgraph_examples.html
index 5ba61d6e47c5930a7d91168cae5061c175a243a1..f8d3809290877cee25f2ccf892c81a3edf2baea1 100644 (file)
--- a/doc/rrdgraph_examples.html
+++ b/doc/rrdgraph_examples.html
@@ -24,8 +24,15 @@
                <li><a href="#data_with_multiple_resolutions">Data with multiple resolutions</a></li>
                <li><a href="#nicely_formatted_legend_section">Nicely formatted legend section</a></li>
                <li><a href="#offsetting_a_line_on_the_yaxis">Offsetting a line on the y-axis</a></li>
+               <li><a href="#drawing_dashed_lines">Drawing dashed lines</a></li>
                <li><a href="#time_ranges">Time ranges</a></li>
                <li><a href="#viewing_the_current_and_previous_week_together">Viewing the current and previous week together</a></li>
+               <li><a href="#aberrant_behaviour_detection">Aberrant Behaviour Detection</a></li>
+               <ul>
+
+                       <li><a href="#a_note_on_data_reduction_">A note on data reduction:</a></li>
+               </ul>
+
        </ul>
 
        <li><a href="#see_also">SEE ALSO</a></li>
@@ -132,6 +139,20 @@ ready because comments are intermixed with the examples.</p>
 </ul>
 <p>
 </p>
+<h2><a name="drawing_dashed_lines">Drawing dashed lines</a></h2>
+<p>Also works for HRULE and VRULE</p>
+<ul>
+<li>
+<p>default style: - - - - -
+    LINE1:data#FF0000:``dashed line'':dashes</p>
+</li>
+<li>
+<p>more fancy style with offset: - -  --- -  --- -
+    LINE1:data#FF0000:``another dashed line'':dashes=15,5,5,10:dash-offset=10</p>
+</li>
+</ul>
+<p>
+</p>
 <h2><a name="time_ranges">Time ranges</a></h2>
 <pre>
     Last four weeks: --start end-4w --end 00:00
@@ -155,6 +176,57 @@ ready because comments are intermixed with the examples.</p>
     LINE1:thisweek#FF0000:This\ week</pre>
 <p>
 </p>
+<h2><a name="aberrant_behaviour_detection">Aberrant Behaviour Detection</a></h2>
+<p>If the specialized function <strong>RRAs</strong> exist for aberrant behavior detection, they
+can be used to generate the graph of a time series with confidence bands and
+failures.</p>
+<pre>
+   rrdtool graph example.png \
+          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:&quot;Failures\: Average bits out&quot; \
+          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:&quot;Average bits out&quot; \
+          LINE1:scaledupper#ff0000:&quot;Upper Confidence Bound: Average bits out&quot; \
+          LINE1:scaledlower#ff0000:&quot;Lower Confidence Bound: Average bits out&quot;</pre>
+<p>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).</p>
+<p>The raw data comes from an AVERAGE <strong>RRA</strong>, 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 <strong>RRA</strong>. The predicted deviations
+(think standard deviation) values are stored in the DEVPREDICT <strong>RRA</strong>. Finally,
+the FAILURES <strong>RRA</strong> contains indicators, with 1 denoting a potential failure.</p>
+<p>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 <strong>RRA</strong> 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.</p>
+<p>The choice of 2 deviations (a scaling factor) matches the default used internally
+by the FAILURES <strong>RRA</strong>. If the internal value is changed (see <a href="././rrdtune.html">the rrdtune manpage</a>), this
+graphing command should be changed to be consistent.</p>
+<p>
+</p>
+<h3><a name="a_note_on_data_reduction_">A note on data reduction:</a></h3>
+<p>The <strong>rrdtool</strong> <em>graph</em> 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 <strong>RRAs</strong> on a
+coarser temporal scale, the <em>graph</em> command tries to do something intelligent,
+but the confidence bands and failures no longer have the same meaning and may
+be misleading.</p>
+<p>
+</p>
 <hr />
 <h1><a name="see_also">SEE ALSO</a></h1>
 <p><a href="././rrdgraph.html">the rrdgraph manpage</a> gives an overview of how <strong>rrdtool graph</strong> works.