doc/rrdgraph_examples.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>rrdgraph_examples</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body style="background-color: white">
  11
  12
  13 <!-- INDEX BEGIN -->
  14 <div name="index">
  15 <p><a name="__index__"></a></p>
  16 <!--
  17
  18 <ul>
  19
  20         <li><a href="#name">NAME</a></li>
  21         <li><a href="#synopsis">SYNOPSIS</a></li>
  22         <li><a href="#description">DESCRIPTION</a></li>
  23         <li><a href="#examples">EXAMPLES</a></li>
  24         <ul>
  25
  26                 <li><a href="#data_with_multiple_resolutions">Data with multiple resolutions</a></li>
  27                 <li><a href="#nicely_formatted_legend_section">Nicely formatted legend section</a></li>
  28                 <li><a href="#offsetting_a_line_on_the_y_axis">Offsetting a line on the y-axis</a></li>
  29                 <li><a href="#drawing_dashed_lines">Drawing dashed lines</a></li>
  30                 <li><a href="#time_ranges">Time ranges</a></li>
  31                 <li><a href="#viewing_the_current_and_previous_week_together">Viewing the current and previous week together</a></li>
  32                 <li><a href="#aberrant_behaviour_detection">Aberrant Behaviour Detection</a></li>
  33                 <ul>
  34
  35                         <li><a href="#a_note_on_data_reduction_">A note on data reduction:</a></li>
  36                 </ul>
  37
  38         </ul>
  39
  40         <li><a href="#see_also">SEE ALSO</a></li>
  41         <li><a href="#author">AUTHOR</a></li>
  42 </ul>
  43
  44 -->
  45
  46
  47 </div>
  48 <!-- INDEX END -->
  49
  50 <p>
  51 </p>
  52 <h1><a name="name">NAME</a></h1>
  53 <p>rrdgraph_examples - Examples for rrdtool graph</p>
  54 <p>
  55 </p>
  56 <hr />
  57 <h1><a name="synopsis">SYNOPSIS</a></h1>
  58 <p><strong>rrdtool graph /home/httpd/html/test.png --img-format PNG</strong></p>
  59 <p>followed by any of the examples below</p>
  60 <p>
  61 </p>
  62 <hr />
  63 <h1><a name="description">DESCRIPTION</a></h1>
  64 <p>For your convenience some of the commands are explained here
  65 by using detailed examples. They are not always cut-and-paste
  66 ready because comments are intermixed with the examples.</p>
  67 <p>
  68 </p>
  69 <hr />
  70 <h1><a name="examples">EXAMPLES</a></h1>
  71 <p>
  72 </p>
  73 <h2><a name="data_with_multiple_resolutions">Data with multiple resolutions</a></h2>
  74 <pre>
  75     --end now --start end-120000s --width 400
  76     DEF:ds0a=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
  77     DEF:ds0b=/home/rrdtool/data/router1.rrd:ds0:AVERAGE:step=1800
  78     DEF:ds0c=/home/rrdtool/data/router1.rrd:ds0:AVERAGE:step=7200
  79     LINE1:ds0a#0000FF:&quot;default resolution\l&quot;
  80     LINE1:ds0b#00CCFF:&quot;resolution 1800 seconds per interval\l&quot;
  81     LINE1:ds0c#FF00FF:&quot;resolution 7200 seconds per interval\l&quot;</pre>
  82 <p>
  83 </p>
  84 <h2><a name="nicely_formatted_legend_section">Nicely formatted legend section</a></h2>
  85 <pre>
  86     DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
  87     DEF:ds1=/home/rrdtool/data/router1.rrd:ds1:AVERAGE
  88     VDEF:ds0max=ds0,MAXIMUM
  89     VDEF:ds0avg=ds0,AVERAGE
  90     VDEF:ds0min=ds0,MINIMUM
  91     VDEF:ds0pct=ds0,95,PERCENT
  92     VDEF:ds1max=ds1,MAXIMUM
  93     VDEF:ds1avg=ds1,AVERAGE
  94     VDEF:ds1min=ds1,MINIMUM
  95     VDEF:ds1pct=ds1,95,PERCENT</pre>
  96 <p>Note: consolidation occurs here.</p>
  97 <pre>
  98     CDEF:ds0bits=ds0,8,*
  99     CDEF:ds1bits=ds1,8,*</pre>
 100 <p>Note: 10 spaces to move text to the right</p>
 101 <pre>
 102     COMMENT:&quot;          &quot;</pre>
 103 <p>Note: the column titles have to be as wide as the columns</p>
 104 <pre>
 105     COMMENT:&quot;Maximum    &quot;
 106     COMMENT:&quot;Average    &quot;
 107     COMMENT:&quot;Minimum    &quot;</pre>
 108 <pre>
 109     COMMENT:&quot;95th percentile\l&quot;
 110     AREA:ds0bits#00C000:&quot;Inbound &quot;
 111     GPRINT:ds0max:&quot;%6.2lf %Sbps&quot;
 112     GPRINT:ds0avg:&quot;%6.2lf %Sbps&quot;
 113     GPRINT:ds0min:&quot;%6.2lf %Sbps&quot;
 114     GPRINT:ds0pct:&quot;%6.2lf %Sbps\l&quot;
 115     LINE1:ds1bits#0000FF:&quot;Outbound&quot;
 116     GPRINT:ds1max:&quot;%6.2lf %Sbps&quot;
 117     GPRINT:ds1avg:&quot;%6.2lf %Sbps&quot;
 118     GPRINT:ds1min:&quot;%6.2lf %Sbps&quot;
 119     GPRINT:ds1pct:&quot;%6.2lf %Sbps\l&quot;</pre>
 120 <p>
 121 </p>
 122 <h2><a name="offsetting_a_line_on_the_y_axis">Offsetting a line on the y-axis</a></h2>
 123 <p>Depending on your needs you can do this in two ways:</p>
 124 <ul>
 125 <li>
 126 <p>Offset the data, then graph this</p>
 127 <pre>
 128     DEF:mydata=my.rrd:ds:AVERAGE</pre>
 129 <p>Note: this will also influence any other command that uses &quot;data&quot;</p>
 130 <pre>
 131     CDEF:data=mydata,100,+
 132     LINE1:data#FF0000:&quot;Data with offset&quot;</pre>
 133 </li>
 134 <li>
 135 <p>Graph the original data, with an offset</p>
 136 <pre>
 137     DEF:mydata=my.rrd:ds:AVERAGE</pre>
 138 <p>Note: no color in the first line so it is not visible</p>
 139 <pre>
 140     LINE1:100</pre>
 141 <p>Note: the second line gets stacked on top of the first one</p>
 142 <pre>
 143     LINE1:data#FF0000:&quot;Data with offset&quot;:STACK</pre>
 144 </li>
 145 </ul>
 146 <p>
 147 </p>
 148 <h2><a name="drawing_dashed_lines">Drawing dashed lines</a></h2>
 149 <p>Also works for HRULE and VRULE</p>
 150 <ul>
 151 <li>
 152 <p>default style: - - - - -
 153     LINE1:data#FF0000:&quot;dashed line&quot;:dashes</p>
 154 </li>
 155 <li>
 156 <p>more fancy style with offset: - -  --- -  --- -
 157     LINE1:data#FF0000:&quot;another dashed line&quot;:dashes=15,5,5,10:dash-offset=10</p>
 158 </li>
 159 </ul>
 160 <p>
 161 </p>
 162 <h2><a name="time_ranges">Time ranges</a></h2>
 163 <pre>
 164     Last four weeks: --start end-4w --end 00:00
 165     January 2001:    --start 20010101 --end start+31d
 166     January 2001:    --start 20010101 --end 20010201
 167     Last hour:       --start end-1h
 168     Last 24 hours:   &lt;nothing at all&gt;
 169     Yesterday:       --end 00:00</pre>
 170 <p>
 171 </p>
 172 <h2><a name="viewing_the_current_and_previous_week_together">Viewing the current and previous week together</a></h2>
 173 <pre>
 174     --end now --start end-1w
 175     DEF:thisweek=router.rrd:ds0:AVERAGE
 176     DEF:lastweek=router.rrd:ds0:AVERAGE:end=now-1w:start=end-1w</pre>
 177 <p>Shift the data forward by one week (604800 seconds)</p>
 178 <pre>
 179     SHIFT:lastweek:604800
 180     [ more of the usual VDEF and CDEF stuff if you like ]
 181     AREA:lastweek#0000FF:Last\ week
 182     LINE1:thisweek#FF0000:This\ week</pre>
 183 <p>
 184 </p>
 185 <h2><a name="aberrant_behaviour_detection">Aberrant Behaviour Detection</a></h2>
 186 <p>If the specialized function <strong>RRAs</strong> exist for aberrant behavior detection, they
 187 can be used to generate the graph of a time series with confidence bands and
 188 failures.</p>
 189 <pre>
 190    rrdtool graph example.png \
 191           DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \
 192           DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \
 193           DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \
 194           DEF:fail=monitor.rrd:ifOutOctets:FAILURES \
 195           TICK:fail#ffffa0:1.0:&quot;Failures\: Average bits out&quot; \
 196           CDEF:scaledobs=obs,8,* \
 197           CDEF:upper=pred,dev,2,*,+ \
 198           CDEF:lower=pred,dev,2,*,- \
 199           CDEF:scaledupper=upper,8,* \
 200           CDEF:scaledlower=lower,8,* \
 201           LINE2:scaledobs#0000ff:&quot;Average bits out&quot; \
 202           LINE1:scaledupper#ff0000:&quot;Upper Confidence Bound: Average bits out&quot; \
 203           LINE1:scaledlower#ff0000:&quot;Lower Confidence Bound: Average bits out&quot;</pre>
 204 <p>This example generates a graph of the data series in blue (LINE2 with the scaledobs
 205 virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
 206 data sources), and potential failures (i.e. potential aberrant aberrant behavior)
 207 marked by vertical yellow lines (the fail data source).</p>
 208 <p>The raw data comes from an AVERAGE <strong>RRA</strong>, the finest resolution of the observed
 209 time series (one consolidated data point per primary data point). The predicted
 210 (or smoothed) values are stored in the HWPREDICT <strong>RRA</strong>. The predicted deviations
 211 (think standard deviation) values are stored in the DEVPREDICT <strong>RRA</strong>. Finally,
 212 the FAILURES <strong>RRA</strong> contains indicators, with 1 denoting a potential failure.</p>
 213 <p>All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
 214 The confidence bounds are computed by an offset of 2 deviations both above
 215 and below the predicted values (the CDEFs upper and lower). Vertical lines
 216 indicated potential failures are graphed via the TICK graph element, which
 217 converts non-zero values in an <strong>RRA</strong> into tick marks. Here an axis-fraction
 218 argument of 1.0 means the tick marks span the entire y-axis, and hence become
 219 vertical lines on the graph.</p>
 220 <p>The choice of 2 deviations (a scaling factor) matches the default used internally
 221 by the FAILURES <strong>RRA</strong>. If the internal value is changed (see <a href="././rrdtune.html">the rrdtune manpage</a>), this
 222 graphing command should be changed to be consistent.</p>
 223 <p>
 224 </p>
 225 <h3><a name="a_note_on_data_reduction_">A note on data reduction:</a></h3>
 226 <p>The <strong>rrdtool</strong> <em>graph</em> command is designed to plot data at a specified temporal
 227 resolution, regardless of the actually resolution of the data in the RRD file.
 228 This can present a problem for the specialized consolidation functions which
 229 maintain a one-to-one mapping between primary data points and consolidated
 230 data points. If a graph insists on viewing the contents of these <strong>RRAs</strong> on a
 231 coarser temporal scale, the <em>graph</em> command tries to do something intelligent,
 232 but the confidence bands and failures no longer have the same meaning and may
 233 be misleading.</p>
 234 <p>
 235 </p>
 236 <hr />
 237 <h1><a name="see_also">SEE ALSO</a></h1>
 238 <p><a href="././rrdgraph.html">the rrdgraph manpage</a> gives an overview of how <strong>rrdtool graph</strong> works.
 239 <a href="././rrdgraph_data.html">the rrdgraph_data manpage</a> describes <strong>DEF</strong>,<strong>CDEF</strong> and <strong>VDEF</strong> in detail.
 240 <a href="././rrdgraph_rpn.html">the rrdgraph_rpn manpage</a> describes the <strong>RPN</strong> language used in the <strong>xDEF</strong> statements.
 241 <a href="././rrdgraph_graph.html">the rrdgraph_graph manpage</a> page describes all the graph and print functions.</p>
 242 <p>
 243 </p>
 244 <hr />
 245 <h1><a name="author">AUTHOR</a></h1>
 246 <p>Program by Tobias Oetiker &lt;<a href="mailto:tobi@oetiker.ch">tobi@oetiker.ch</a>&gt;</p>
 247 <p>This manual page by Alex van den Bogaerdt &lt;<a href="mailto:alex@vandenbogaerdt.nl">alex@vandenbogaerdt.nl</a>&gt;
 248 with corrections and/or additions by several people</p>
 249
 250 </body>
 251
 252 </html>