Imported upstream version 1.3rc4.

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

diff --git a/doc/rrdgraph_examples.txt b/doc/rrdgraph_examples.txt
index ca58ce7696ad29b0f477179e27f1b50f3a83e366..8dc2e6e72c08dff91d30e68451fecff4fe095007 100644 (file)
--- a/doc/rrdgraph_examples.txt
+++ b/doc/rrdgraph_examples.txt
@@ -91,6 +91,17 @@ E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
 
                LINE1:data#FF0000:"Data with offset":STACK
 
+       D\bDr\bra\baw\bwi\bin\bng\bg d\bda\bas\bsh\bhe\bed\bd l\bli\bin\bne\bes\bs
+
+       Also works for HRULE and VRULE
+
+       ·   default style: - - - - -
+               LINE1:data#FF0000:"dashed line":dashes
+
+       ·   more fancy style with offset: - -  --- -  --- -
+               LINE1:data#FF0000:"another dashed
+           line":dashes=15,5,5,10:dash-offset=10
+
        T\bTi\bim\bme\be r\bra\ban\bng\bge\bes\bs
 
            Last four weeks: --start end-4w --end 00:00
@@ -113,6 +124,63 @@ E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
            AREA:lastweek#0000FF:Last\ week
            LINE1:thisweek#FF0000:This\ week
 
+       A\bAb\bbe\ber\brr\bra\ban\bnt\bt B\bBe\beh\bha\bav\bvi\bio\bou\bur\br D\bDe\bet\bte\bec\bct\bti\bio\bon\bn
+
+       If the specialized function R\bRR\bRA\bAs\bs 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.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:"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 (scaledup-
+       per 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 R\bRR\bRA\bA, 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
+       R\bRR\bRA\bA. The predicted deviations (think standard deviation) values are
+       stored in the DEVPREDICT R\bRR\bRA\bA. Finally, the FAILURES R\bRR\bRA\bA contains indi-
+       cators, 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 R\bRR\bRA\bA 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 R\bRR\bRA\bA. If the internal value is changed (see
+       rrdtune), this graphing command should be changed to be consistent.
+
+       _\bA _\bn_\bo_\bt_\be _\bo_\bn _\bd_\ba_\bt_\ba _\br_\be_\bd_\bu_\bc_\bt_\bi_\bo_\bn_\b:
+
+       The r\brr\brd\bdt\bto\boo\bol\bl _\bg_\br_\ba_\bp_\bh command is designed to plot data at a specified tem-
+       poral resolution, regardless of the actually resolution of the data in
+       the RRD file.  This can present a problem for the specialized consoli-
+       dation 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 R\bRR\bRA\bAs\bs on a coarser temporal scale, the _\bg_\br_\ba_\bp_\bh com-
+       mand tries to do something intelligent, but the confidence bands and
+       failures no longer have the same meaning and may be misleading.
+
 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
        rrdgraph gives an overview of how r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh works.  rrdgraph_data
        describes D\bDE\bEF\bF,C\bCD\bDE\bEF\bF and V\bVD\bDE\bEF\bF in detail.  rrdgraph_rpn describes the R\bRP\bPN\bN
@@ -128,4 +196,4 @@ A\bAU\bUT\bTH\bHO\bOR\bR
 
 
 
-1.2.27                            2008-02-17              RRDGRAPH_EXAMPLES(1)
+1.3rc4                            2008-03-25              RRDGRAPH_EXAMPLES(1)