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