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 auto configuration 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> grid step, 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 behavior. 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