remove an excess =over
[rrdtool.git] / doc / rrdgraph-old.pod
1 =head1 NAME
2
3 rrdtool graph - Create a graph based on data from one or several RRD
4
5 =for html <div align="right"><a href="rrdgraph.pdf">PDF</a> version.</div>
6
7 =head1 SYNOPSIS
8
9 B<rrdtool> B<graph> I<filename>
10 S<[B<-s>|B<--start> I<seconds>]>
11 S<[B<-e>|B<--end> I<seconds>]>
12 S<[B<-x>|B<--x-grid> I<x-axis grid and label>]>
13 S<[B<-y>|B<--y-grid> I<y-axis grid and label>]>
14 S<[B<-Y>|B<--alt-y-grid>]>
15 S<[B<-A>|B<--alt-autoscale>]>
16 S<[B<-M>|B<--alt-autoscale-max>]>
17 S<[B<-X>|B<--units-exponent>]> I<value>]>
18 S<[B<-v>|B<--vertical-label> I<text>]>
19 S<[B<-w>|B<--width> I<pixels>]>
20 S<[B<-h>|B<--height> I<pixels>]>
21 S<[B<-i>|B<--interlaced>]>
22 S<[B<-f>|B<--imginfo> I<formatstring>]>
23 S<[B<-a>|B<--imgformat> B<SVG>|B<PNG>]>
24 S<[B<-z>|B<--lazy>]>
25 S<[B<-o>|B<--logarithmic>]>
26 S<[B<-u>|B<--upper-limit> I<value>]>
27 S<[B<-l>|B<--lower-limit> I<value>]>
28 S<[B<-g>|B<--no-legend>]>
29 S<[B<-r>|B<--rigid>]>
30 S<[B<-S>|B<--step> I<value>]>
31 S<[B<-b>|B<--base> I<value>]>
32 S<[B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb>]>
33 S<[B<-t>|B<--title> I<title>]>
34 S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]>
35 S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]>
36 S<[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]>
37 S<[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]>
38 S<[B<COMMENT:>I<text>]>
39 S<[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]>
40 S<[B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]]>
41 S<[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
42 S<[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
43 S<[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
44 S<[B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]]>
45
46 =head1 DESCRIPTION
47
48 The B<graph> functions main purpose is to create graphical
49 representations of the data stored in one or several B<RRD>s. Apart
50 from generating graphs, it can also extract numerical reports.
51
52 =over
53
54 =item I<filename>
55
56 The name of the graph to generate. Since B<RRDtool> outputs
57 SVGs and PNGs, it's recommended that the filename end in either
58 F<.svg> or F<.png>.  B<RRDtool> does not enforce this, however.
59 If the  I<filename> is set to '-' the image file will be written
60 to standard out.  All other output will get suppressed.
61
62 If no graph functions are called, the graph will not be created.
63
64 =item B<-s>|B<--start> I<seconds> (default end-1day)
65
66 The time when the graph should begin. Time in seconds since
67 epoch (1970-01-01) is required. Negative numbers are relative to the
68 current time. By default one day worth of data will be graphed.
69 See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
70 documentation for a detailed explanation on how to specify time.
71
72 =item B<-e>|B<--end> I<seconds> (default now)
73
74 The time when the graph should end. Time in seconds since epoch.
75 See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
76 documentation for a detailed explanation of ways to specify time.
77
78 =item B<-x>|B<--x-grid> I<x-axis grid and label> (default autoconfigure)
79
80 The x-axis label is quite complex to configure. So if you don't have
81 very special needs, you can rely on the autoconfiguration to get this
82 right.
83
84 If you want no x-grid at all, use the magic setting B<none>.
85
86 The x-axis label and grid can be configured, using the following format:
87
88 I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>:I<LST>B<:>I<LPR>B<:>I<LFM>
89
90 You have to configure three elements making up the x-axis labels and
91 grid. The base grid (I<G??>), the major grid (I<M??>) and the labels
92 (I<L??>). The configuration is based on the idea that you first
93 specify a well known amount of time (I<?TM>) and then say how many
94 times it has to pass between each grid line or label (I<?ST>). For the
95 label you have to define two additional items: The precision of the
96 label in seconds (I<LPR>) and the strftime format used to generate the
97 text of the label (I<LFM>).
98
99 The I<?TM> elements must be one of the following keywords: B<SECOND>,
100 B<MINUTE>, B<HOUR>, B<DAY>, B<WEEK>, B<MONTH> or B<YEAR>.
101
102 If you wanted a graph with a base grid every 10 minutes and a major
103 one every hour, with labels every hour you would use the following
104 x-axis definition.
105
106 C<MINUTE:10:HOUR:1:HOUR:1:0:%X>
107
108 The precision in this example is 0 because the %X format is exact. If
109 the label was the name of the day, we would have had a precision of 24
110 hours, because when you say something like 'Monday' you mean the whole
111 day and not Monday morning 00:00. Thus the label should be positioned
112 at noon. By defining a precision of 24 hours or rather 86400 seconds,
113 you make sure that this happens.
114
115 =item B<-y>|B<--y-grid> I<grid step>:I<label factor> (default autoconfigure)
116
117 Makes vertical grid lines appear at I<grid step> interval. Every
118 I<label factor> gridstep, a major grid line is printed, along with
119 label showing the value of the grid line.
120
121 If you want no y-grid at all set specify the magic word B<none>.
122
123 =item B<--alt-y-grid>
124
125 Place Y grid dynamically based on graph Y range. Algorithm ensures
126 that you always have grid, that there are enough but not too many
127 grid lines and the grid is metric. That is grid lines are placed
128 every 1, 2, 5 or 10 units.  (contributed by Sasha Mikheev)
129
130
131 =item B<--alt-autoscale>
132
133 Compute Y range  based on function absolute minimum and
134 maximum values. Default algorithm uses predefined set of ranges.
135 This is good in many cases but it fails miserably when you need
136 to graph something like 260 + 0.001 * sin(x). Default algorithm
137 will use Y range from 250 to 300 and on the graph you will see
138 almost straight line. With --alt-autoscale Y range will be
139 from slightly less the 260 - 0.001 to slightly more then 260 + 0.001
140 and periodic behavior will be seen.   (contributed by Sasha Mikheev)
141
142 =item B<--alt-autoscale-max>
143
144 Where --alt-autoscale will modify both the absolute maximum AND minimum
145 values, this option will only affect the maximum value. The minimum
146 value, if not defined on the command line, will be 0. This option can
147 be useful when graphing router traffic when the WAN line uses compression,
148 and thus the throughput may be higher than the WAN line speed.
149
150 =item B<--units-exponent> I<value> (default autoconfigure)
151
152 This sets the 10**exponent scaling of the y-axis values.  Normally
153 values will be scaled to the appropriate units (k, M, etc.).  However
154 you may wish to display units always in k (Kilo, 10e3) even if the data
155 is in the M (Mega, 10e6) range for instance.  Value should be an
156 integer which is a multiple of 3 between -18 and 18 inclusive.  It is
157 the exponent on the units you which to use.  For example, use 3 to
158 display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
159 display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
160 of 0 to prevent any scaling of the y-axis values.
161
162 =item B<-v>|B<--vertical-label> I<text>
163
164 vertical label on the left side of the graph. This is normally used to
165 specify the units used.
166
167 =item B<-w>|B<--width> I<pixels> (default 400 pixel)
168
169 Width of the drawing area within the graph. This affects the size of the
170 image.
171
172 =item B<-h>|B<--height> I<pixels> (default 100 pixel)
173
174 Width of the drawing area within the graph. This affects the size of the
175 image.
176
177 =item B<-i>|B<--interlaced> (default: false)
178
179 If you set this option, then the resulting image will be interlaced.
180 Most web browsers display these incrementally as they load. If
181 you do not use this option, the image defaults to being progressive
182 scanned. The only effect of this option is to control the format
183 of the image on disk. It makes no changes to the layout or contents
184 of the graph.
185
186 =item B<-f>|B<--imginfo> I<formatstring>
187
188 After the image has been created, the graph function uses printf
189 together with this format string to create output similar to the PRINT
190 function, only that the printf is supplied with the parameters
191 I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
192 suitable for including the graph into a web page, the command line
193 would look like this:
194
195  --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
196
197 =item B<-a>|B<--imgformat> B<SVG>|B<PNG> (default: PNG)
198
199 Allows you to produce PNG output from RRDtool.
200
201 =item B<-z>|B<--lazy> (default: false)
202
203 Only generate the graph, if the current image is out of date or not
204 existent.
205
206 =item B<-u>|B<--upper-limit> I<value> (default autoconfigure)
207
208 Defines the value normally located at the upper border of the
209 graph. If the graph contains higher values, the upper border will
210 move upward to accommodate these values as well.
211
212 If you want to define an upper-limit which will not move in any
213 event you have to set the B<--rigid> option as well.
214
215 =item B<-l>|B<--lower-limit> I<value> (default autoconfigure)
216
217 This is not the lower limit of a graph.  But rather, this is the
218 maximum lower bound of a graph.  For example, the value -100 will
219 result in a graph that has a lower limit of -100 or less.  Use this
220 keyword to expand graphs down.
221
222 =item B<-r>|B<--rigid>
223
224 rigid boundaries mode.  Normally rrdgraph will automatically expand the
225 lower and upper limit if the graph contains a value outside the valid
226 range. With the r option you can disable this behavior
227
228 =item B<-b>|B<--base> I<value>
229
230 if you are graphing memory (and NOT network traffic) this switch
231 should be set to 1024 so that one Kb is 1024 byte. For traffic
232 measurement, 1 kb/s is 1000 b/s.
233
234 =item B<-o>|B<--logarithmic>
235
236 logarithmic y-axis scaling
237
238 =item B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb> (default colors)
239
240 override the colors for the standard elements of the graph. The I<COLORTAG>
241 must be one of the following symbolic names: B<BACK> ground, B<CANVAS>,
242 B<SHADEA> left/top border, B<SHADEB> right/bottom border, B<GRID>, B<MGRID>
243 major grid, B<FONT>, B<FRAME> and axis of the graph or B<ARROW>. This option
244 can be called multiple times to set several colors.
245
246 =item B<-g>|B<--no-legend>
247
248 Suppress generation of legend; only render the graph.
249
250 =item B<-t>|B<--title> I<text> (default no title)
251
252 Define a title to be written into the graph
253
254 =item B<--step> I<value> (default automatic)
255
256 By default rrdgraph calculates the width of one pixel in the time domain and
257 tries to get data at that resolution from the RRD. With this switch you can
258 override this behaviour. If you want rrdgraph to get data at 1 hour
259 resolution from the RRD, then you can set the step to 3600 seconds. Note,
260 that a step smaller than 1 pixel will be silently ignored.
261
262 =item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>
263
264 Define virtual name for a data source. This name can then be used
265 in the functions explained below. The
266 DEF call automatically chooses an B<RRA> which contains I<CF> consolidated data in a
267 resolution appropriate for the size of the graph to be drawn.  Ideally
268 this means that one data point from the B<RRA> should be represented
269 by one pixel in the graph.  If the resolution of the B<RRA> is higher
270 than the resolution of the graph, the data in the RRA will be further
271 consolidated according to the consolidation function (I<CF>) chosen.
272
273 =item B<CDEF:>I<vname>B<=>I<rpn-expression>
274
275 Create a new virtual data source by evaluating a mathematical expression,
276 specified in Reverse Polish Notation (RPN). If you have ever used a traditional
277 HP calculator you already know RPN. The idea behind RPN notation is,
278 that you have a stack and push your data onto this stack. When ever
279 you execute an operation, it takes as many data values from the stack
280 as needed. The pushing of data is implicit, so when ever you specify a number
281 or a variable, it gets pushed automatically.
282
283 If this is all a big load of incomprehensible words for you, maybe an
284 example helps (a more complete explanation is given in [1]): The
285 expression I<vname+3/2> becomes C<vname,3,2,/,+> in RPN. First the three
286 values get pushed onto the stack (which now contains (the current
287 value of) vname, a 3 and a 2).  Then the / operator pops two values
288 from the stack (3 and 2), divides the first argument by the second
289 (3/2) and pushes the result (1.5) back onto the stack. Then the +
290 operator pops two values (vname and 1.5) from the stack; both values
291 are added up and the result gets pushes back onto the stack. In the
292 end there is only one value left on the stack: The result of the
293 expression.
294
295 The I<rpn-expression> in the B<CDEF> function takes both, constant values
296 as well as I<vname> variables. The following operators can be used on these
297 values:
298
299 =over
300
301 =item +, -, *, /, %
302
303 pops two values from the stack applies the selected operator and pushes
304 the result back onto the stack. The % operator stands for the modulo
305 operation.
306
307 =item SIN, COS, LOG, EXP, FLOOR, CEIL
308
309 pops one value from the stack, applies the selected function and pushes
310 the result back onto the stack.
311
312 =item LT, LE, GT, GE, EQ
313
314 pops two values from the stack, compares them according to the selected
315 condition and pushes either 1 back onto the stack if the condition is true
316 and 0 if the condition was not true.
317
318 =item IF
319
320 pops three values from the stack. If the last value is not 0, the
321 second value will be pushed back onto the stack, otherwise the
322 first value is pushed back.
323
324 If the stack contains the values A, B, C, D, E are presently on the
325 stack, the IF operator will pop the values E D and C of the stack. It will
326 look at C and if it is not 0 it will push D back onto the stack, otherwise
327 E will be sent back to the stack.
328
329 =item MIN, MAX
330
331 selects the lesser or larger of the two top stack values respectively
332
333 =item LIMIT
334
335 replaces the value with I<*UNKNOWN*> if it is outside the limits specified
336 by the two values above it on the stack.
337
338  CDEF:a=alpha,0,100,LIMIT
339
340 =item DUP, EXC, POP
341
342 These manipulate the stack directly.  DUP will duplicate the top of the
343 stack, pushing the result back onto the stack.  EXC will exchange the top
344 two elements of the stack, and POP will pop off the top element of the
345 stack.  Having insufficient elements on the stack for these operations is
346 an error.
347
348 =item UN
349
350 Pops one value off the stack, if it is I<*UNKNOWN*>, 1 will be pushed
351 back otherwise 0.
352
353 =item UNKN
354
355 Push an I<*UNKNOWN*> value onto the stack.
356
357 =item PREV
358
359 Push I<*UNKNOWN*> if its at the first value of a data set or otherwise
360 the value of this CDEF at the previous time step. This allows you to
361 perform calculations across the data.
362
363 =item COUNT
364
365 Pushes the number 1 if it is at the first value of the data set, the
366 number 2 if it is at the second, and so on. This special value, allows
367 you to make calculations based on the position of the value within
368 the data set.
369
370 =item INF, NEGINF
371
372 Push a positive or negative infinite (oo) value onto the stack. When
373 drawing an infinite number it appears right at the top or bottom edge of the
374 graph, depending whether you have a positive or negative infinite number.
375
376 =item NOW
377
378 Push the current (real world) time onto the stack.
379
380 =item TIME
381
382 Push the time the current sample was taken onto the stack. This is the
383 number of non-skip seconds since 0:00:00 January 1, 1970.
384
385 =item LTIME
386
387 This is like TIME B<+ current timezone offset in seconds>. The current
388 offset takes daylight saving time into account, given your OS supports
389 this. If you were looking at a sample, in Zurich, in summer, the
390 offset would be 2*3600 seconds, as Zurich at that time of year is 2
391 hours ahead of UTC.
392
393 Note that the timezone offset is always calculated for the time the
394 current sample was taken at. It has nothing to do with the time you are
395 doing the calculation.
396
397 =back
398
399 Please note that you may only use I<vname> variables that you
400 previously defined by either B<DEF> or B<CDEF>. Furthermore, as of
401 this writing (version 0.99.25), you must use at least one I<vname>
402 per expression, that is "CDEF:fourtytwo=2,40,+" will yield an error
403 message but not a I<vname> fourtytwo that's always equal to 42.
404
405 =item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
406
407 Calculate the chosen consolidation function I<CF> over the data-source
408 variable I<vname> and C<printf> the result to stdout using I<format>.
409 In the I<format> string there should be a '%lf', '%le' or'%lg' marker in the
410 place where the number should be printed.
411
412 If an additional '%s' is found AFTER the marker, the value will be scaled
413 and an appropriate SI magnitude unit will be printed in place of the '%s'
414 marker. The scaling will take the '--base' argument into consideration!
415
416 If a '%S' is used instead of a '%s', then instead of calculating the
417 appropriate SI magnitude unit for this value, the previously calculated
418 SI magnitude unit will be used.  This is useful if you want all the values
419 in a PRINT statement to have the same SI magnitude unit.  If there was
420 no previous SI magnitude calculation made, then '%S' behaves like a '%s',
421 unless the value is 0, in which case it does not remember a SI magnitude
422 unit and a SI magnitude unit will only be calculated when the next '%s' is
423 seen or the next '%S' for a non-zero value.
424
425 If you want to put a '%' into your PRINT string, use '%%' instead.
426
427 =item B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
428
429 Same as B<PRINT> but the result is printed into the graph below the legend.
430
431 =back
432
433 B<Caveat:> When using the B<PRINT> and B<GRPRINT> functions to
434 calculate data summaries over time periods bounded by the current
435 time, it is important to note that the last sample will almost always
436 yield a value of UNKNOWN as it lies after the last update time.  This
437 can result in slight data skewing, particularly with the B<AVERAGE>
438 function.  In order to avoid this, make sure that your end time is at
439 least one heartbeat prior to the current time.
440
441 =over
442
443
444 =item B<COMMENT:>I<text>
445
446 Like B<GPRINT> but the I<text> is simply printed into the graph.
447
448 =item B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
449
450 Draw a horizontal rule into the graph and optionally add a legend
451
452 =item B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
453
454 Draw a vertical rule into the graph and optionally add a legend
455
456 =item B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
457
458 Plot for the requested data, using the color specified. Write a legend
459 into the graph. The 3 possible keywords B<LINE1>, B<LINE2>, and B<LINE3>
460 generate increasingly wide lines. If no color is defined,
461 the drawing is done 'blind' this is useful in connection with the
462 B<STACK> function when you want to ADD the values of two
463 data-sources without showing it in the graph.
464
465 =item B<AREA>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
466
467 Does the same as B<LINE?>, but the area between 0 and
468 the graph will be filled with the color specified.
469
470 =item B<STACK>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
471
472 Does the same as B<LINE?>, but the graph gets stacked on top of the previous
473 B<LINE?>, B<AREA> or B<STACK> graph. Depending on the type of the
474 previous graph, the B<STACK> will be either a B<LINE?> or an B<AREA>.
475 This obviously implies that the first B<STACK> must be preceded by an
476 B<AREA> or B<LINE?> -- you need something to stack something onto in
477 the first place ;)
478
479 Note, that when you STACK onto *UNKNOWN* data, RRDtool will not draw
480 any graphics ... *UNKNOWN* is not zero ... if you want it to be zero
481 then you might want to use a CDEF argument with IF and UN functions to
482 turn *UNKNOWN* into zero ...
483
484 =item B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]
485
486 Plot a tick mark (a vertical line) for each value of I<vname> that is
487 non-zero and not *UNKNOWN*. The I<axis-fraction> argument specifies the
488 length of the tick mark as a fraction of the y-axis; the default value
489 is 0.1 (10% of the axis). Note that the color specification is not
490 optional.
491
492 =back
493
494 =head1 NOTES on legend arguments
495
496 =head2 Escaping the colon
497
498 In a ':' in a I<legend> argument will mark the end of the legend. To
499 enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
500 Beware, that many environments look for backslashes themselves, so it may
501 be necessary to write two backslashes so that one is passed onto rrd_graph.
502
503 =head2 String Formatting
504
505 The text printed below the actual graph can be formated by appending special
506 escaped characters at the end of a text. When ever such a character occurs,
507 all pending text is pushed onto the graph according to the character
508 specified.
509
510 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
511 right aligned and B<\c> for centered. In the next section there is an
512 example showing how to use centered formating.
513
514 Normally there are two space characters inserted between every two items
515 printed into the graph. The space following a string can be suppressed by
516 putting a B<\g> at the end of the string. The B<\g> also ignores any space
517 inside the string if it is at the very end of the string. This can be used
518 in connection with B<%s> to suppress empty unit strings.
519
520  GPRINT:a:MAX:%lf%s\g
521
522 A special case is COMMENT:B<\s> this inserts some additional vertical space
523 before placing the next row of legends.
524
525 =head1 NOTE on Return Values
526
527 Whenever rrd_graph gets called, it prints a line telling the size of
528 the image it has just created to stdout. This line looks like this: XSIZExYSIZE.
529
530 =head1 EXAMPLE 1
531
532   rrdtool graph demo.png --title="Demo Graph" \
533           DEF:cel=demo.rrd:exhaust:AVERAGE \
534           "CDEF:far=cel,1.8,*,32,+"" \
535           LINE2:cel#00a000:"D. Celsius" \
536           LINE2:far#ff0000:"D. Fahrenheit\c"
537
538 =head1 EXAMPLE 2
539
540 This example demonstrates the syntax for using IF and UN to set
541 I<*UNKNOWN*> values to 0.  This technique is useful if you are
542 aggregating interface data where the start dates of the data sets
543 doesn't match.
544
545   rrdtool graph demo.png --title="Demo Graph" \
546          DEF:idat1=interface1.rrd:ds0:AVERAGE \
547          DEF:idat2=interface2.rrd:ds0:AVERAGE \
548          DEF:odat1=interface1.rrd:ds1:AVERAGE \
549          DEF:odat2=interface2.rrd:ds1:AVERAGE \
550          CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \
551          CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \
552          AREA:agginput#00cc00:Input Aggregate \
553          LINE1:agginput#0000FF:Output Aggregate
554
555 Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression
556
557  idat1,UN,0,idat1,IF
558
559 leaves us with a stack with contents of 1,0,NaN and the IF function
560 will pop off the 3 values and replace them with 0.  If idat1 had a
561 real value like 7942099, then the stack would have 0,0,7942099 and the
562 real value would be the replacement.
563
564 =head1 EXAMPLE 3
565
566 This example shows two ways to use the INF function. First it makes
567 the background change color during half of the hours. Then, it uses
568 AREA and STACK to draw a picture. If one of the inputs was UNKNOWN,
569 all inputs are overlaid with another AREA.
570
571   rrdtool graph example.png --title="INF demo" \
572          DEF:val1=some.rrd:ds0:AVERAGE \
573          DEF:val2=some.rrd:ds1:AVERAGE \
574          DEF:val3=some.rrd:ds2:AVERAGE \
575          DEF:val4=other.rrd:ds0:AVERAGE \
576          CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \
577          CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \
578          AREA:background#F0F0F0 \
579          AREA:val1#0000FF:Value1 \
580          STACK:val2#00C000:Value2 \
581          STACK:val3#FFFF00:Value3 \
582          STACK:val4#FFC000:Value4 \
583          AREA:wipeout#FF0000:Unknown
584
585 The first CDEF uses val4 as a dummy value. It's value is removed immediately
586 from the stack. Then a decision is made based on the time that a sample was
587 taken. If it is an even hour (UTC time !) then the area will be filled. If
588 it is not, the value is set to UNKN and is not plotted.
589
590 The second CDEF looks if any of val1,val2,val3,val4 is unknown. It does so by
591 checking the outcome of sum(val1,val2,val3,val4). Again, INF is returned when
592 the condition is true, UNKN is used to not plot the data.
593
594 The different items are plotted in a particular order. First do the background, then use a
595 normal area to overlay it with data. Stack the other data until they are all plotted. Last but
596 not least, overlay everything with eye-hurting red
597 to signal any unknown data.
598
599 Note that this example assumes that your data is in the positive half of the y-axis
600 otherwise you would would have to add NEGINF in order to extend the coverage
601 of the area to whole graph.
602
603 =head1 EXAMPLE 4
604
605 If the specialized function B<RRAs> exist for aberrant behavior detection, they
606 can be used to generate the graph of a time series with confidence bands and
607 failures.
608
609    rrdtool graph example.png \
610           DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \
611           DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \
612           DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \
613           DEF:fail=monitor.rrd:ifOutOctets:FAILURES \
614           TICK:fail#ffffa0:1.0:"Failures\: Average bits out" \
615           CDEF:scaledobs=obs,8,* \
616           CDEF:upper=pred,dev,2,*,+ \
617           CDEF:lower=pred,dev,2,*,- \
618           CDEF:scaledupper=upper,8,* \
619           CDEF:scaledlower=lower,8,* \
620           LINE2:scaledobs#0000ff:"Average bits out" \
621           LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \
622           LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out"
623
624 This example generates a graph of the data series in blue (LINE2 with the scaledobs
625 virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
626 data sources), and potential failures (i.e. potential aberrant aberrant behavior)
627 marked by vertical yellow lines (the fail data source).
628
629 The raw data comes from an AVERAGE B<RRA>, the finest resolution of the observed
630 time series (one consolidated data point per primary data point). The predicted
631 (or smoothed) values are stored in the HWPREDICT B<RRA>. The predicted deviations
632 (think standard deviation) values are stored in the DEVPREDICT B<RRA>. Finally,
633 the FAILURES B<RRA> contains indicators, with 1 denoting a potential failure.
634
635 All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
636 The confidence bounds are computed by an offset of 2 deviations both above
637 and below the predicted values (the CDEFs upper and lower). Vertical lines
638 indicated potential failures are graphed via the TICK graph element, which
639 converts non-zero values in an B<RRA> into tick marks. Here an axis-fraction
640 argument of 1.0 means the tick marks span the entire y-axis, and hence become
641 vertical lines on the graph.
642
643 The choice of 2 deviations (a scaling factor) matches the default used internally
644 by the FAILURES B<RRA>. If the internal value is changed (see L<rrdtune>), this
645 graphing command should be changed to be consistent.
646
647 =head2 A note on data reduction:
648
649 The B<rrdtool> I<graph> command is designed to plot data at a specified temporal
650 resolution, regardless of the actually resolution of the data in the RRD file.
651 This can present a problem for the specialized consolidation functions which
652 maintain a one-to-one mapping between primary data points and consolidated
653 data points. If a graph insists on viewing the contents of these B<RRAs> on a
654 coarser temporal scale, the I<graph> command tries to do something intelligent,
655 but the confidence bands and failures no longer have the same meaning and may
656 be misleading.
657
658 =head1 AUTHOR
659
660 Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
661
662 =head1 REFERENCES
663
664 [1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm