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