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