doc/rrdgraph_examples.pod

   1 =head1 NAME
   2
   3 rrdtool graph - Round Robin Database tool grapher functions
   4
   5 WARNING: This is for version 1.1.x which is B<I<BETA>> software.
   6 The software may contain serious bugs. Some of the items
   7 described in here may not yet exist (although this should
   8 be mentioned) or still be in the alpha stage.  As with every
   9 other RRDtool release: use at your own risk.  In contrast with
  10 the stable version of RRDtool, this release may contain bugs
  11 known to the authors.  It is highly recommended that you subscribe
  12 to the mailing list.
  13
  14 =head1 SYNOPSYS
  15
  16 B<rrdtool graph /home/httpd/html/test.png --img-format PNG \>
  17
  18 followed by any of the examples below
  19
  20 =head1 DESCRIPTION
  21
  22 For your convenience some of the commands are explained here
  23 by using detailed examples. They are not always cut-and-paste
  24 ready because comments are intermixed with the examples.
  25
  26 =head1 EXAMPLES
  27
  28 =head2 Nicely formatted legend section
  29
  30     DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
  31     DEF:ds1=/home/rrdtool/data/router1.rrd:ds1:AVERAGE
  32     VDEF:ds0max=ds0,MAXIMUM,8,*
  33     VDEF:ds0avg=ds0,AVERAGE,8,*
  34     VDEF:ds0min=ds0,MINIMUM,8,*
  35     VDEF:ds0pct=95,ds0,PERCENTILE,8,*
  36     VDEF:ds1max=ds1,MAXIMUM,8,*
  37     VDEF:ds1avg=ds1,AVERAGE,8,*
  38     VDEF:ds1min=ds1,MINIMUM,8,*
  39     VDEF:ds1pct=95,ds1,PERCENTILE,8,*
  40 Note: consolidation occurs here.
  41     CDEF:ds0bits=ds0,8,*
  42     CDEF:ds1bits=ds1,8,*
  43 Note: 10 spaces to move text to the right
  44     COMMENT:"          "
  45 Note: three times size == 11 chars, "###.## xBps"
  46     COMMENT:"Maximum    "
  47     COMMENT:"Average    "
  48     COMMENT:"Minimum    "
  49 Note: last line contains new-line character
  50     COMMENT:"95th percentile\n"
  51     AREA:ds0bits#00C000:"Inbound "
  52     GPRINT:ds0max:"%6.2lf %Sbps"
  53     GPRINT:ds0avg:"%6.2lf %Sbps"
  54     GPRINT:ds0min:"%6.2lf %Sbps"
  55     GPRINT:ds0pct:"%6.2lf %Sbps\n"
  56     LINE1:ds1bits#0000FF:"Outbound"
  57     GPRINT:ds1max:"%6.2lf %Sbps"
  58     GPRINT:ds1avg:"%6.2lf %Sbps"
  59     GPRINT:ds1min:"%6.2lf %Sbps"
  60     GPRINT:ds1pct:"%6.2lf %Sbps\n"
  61
  62 =head2 Offsetting a line on the y-axis
  63
  64 Depending on your needs you can do this in two ways:
  65
  66 =over 4
  67
  68 =item *
  69
  70 Offset the data, then graph this
  71
  72     DEF:mydata=my.rrd:ds:AVERAGE
  73 Note: this will also influence anything that uses "data"
  74     CDEF:data=mydata,100,+
  75     LINE1:data#FF0000:"Data with offset"
  76
  77 =item *
  78
  79 Graph the original data, with an offset
  80
  81     DEF:mydata=my.rrd:ds:AVERAGE
  82 Note: no color in the first line so it is not visible
  83     LINE1:100
  84 Note: the second line gets stacked on top of the first one
  85     LINE1:data#FF0000:"Data with offset":STACK
  86
  87 =back
  88
  89 =head2 Time ranges
  90
  91     Last four weeks: --start end-4w --end 00:00
  92     Januari 2001:    --start 200101010000 --end start+31d
  93     Januari 2001:    --start 200101010000 --end 200102010000
  94     Last hour:       --start end-1h
  95     Last 24 hours:   <nothing at all>
  96     Yesterday:       --end 00:00
  97
  98 =head2 Viewing Januari+Februari 2000 and 2001 together
  99
 100 Define a graph area of 31+29 days (!) spanning Jan. and Feb.
 101     --start 20000101 --end 20000301
 102     DEF:jan2000=router.rrd:ds0:AVERAGE:start 20000101 end start+31d
 103     DEF:jan2001=router.rrd:ds0:AVERAGE:start 20010101 end start+31d
 104 Note: mind the extra day in 2000 ...
 105     DEF:feb2000=router.rrd:ds0:AVERAGE:start 20000201 end start+29d
 106 Note: 29 feb 2001 is *unknown*
 107     DEF:feb2001=router.rrd:ds0:AVERAGE:start 20010201 end start+28d
 108     VDEF:offset=jan2001,FIRST,jan2000,FIRST,-,-1,*
 109     [ more of the usual VDEF and CDEF stuff if you like ]
 110     LINE1:jan2000#00003F:"Januari 2000"
 111     [ gprint stuff ]
 112     LINE1:feb2001#003F00:"Februari 2000"
 113     [ gprint stuff ]
 114 Note: offset is made negative by the VDEF statement
 115     SHIFT:offset
 116     LINE1:jan2001#0000FF:"Januari 2001"
 117     [ gprint stuff ]
 118     LINE1:feb2001#00FF00:"Februari 2001"
 119     [ gprint stuff ]
 120
 121 =head1 SEE ALSO
 122
 123 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 124 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
 125 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
 126 L<rrdgraph_graph> page describes all of the graph and print functions.
 127
 128 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 129
 130 =head1 AUTHOR
 131
 132 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
 133
 134 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
 135