


RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


NAME
       rrdtool graph - Create a graph based on data from one or
       several RRD

SYNOPSIS
       rrdtool graph filename [-s|--start seconds]
       [-e|--end seconds] [-x|--x-grid x-axis grid and label]
       [-y|--y-grid y-axis grid and label] [--alt-y-grid] [--alt-
       autoscale] [-v|--vertical-label text] [-w|--width pixels]
       [-h|--height pixels] [-i|--interlaced]
       [-f|--imginfo formatstring] [-a|--imgformat GIF|PNG]
       [-z|--lazy] [-o|--logarithmic] [-u|--upper-limit value]
       [-l|--lower-limit value] [-r|--rigid] [-b|--base value]
       [-c|--color COLORTAG#rrggbb]

       [-t|--title title] [DEF:vname=rrd:ds-name:CF]
       [CDEF:vname=rpn-expression] [PRINT:vname:CF:format]
       [GPRINT:vname:CF:format] [COMMENT:text]
       [HRULE:value#rrggbb[:legend]] [VRULE:time#rrggbb[:legend]]
       [LINE{1|2|3}:vname[#rrggbb[:legend]]]
       [AREA:vname[#rrggbb[:legend]]]
       [STACK:vname[#rrggbb[:legend]]]

DESCRIPTION
       The graph functions main purpose is to create graphical
       representations of the data stored in one or several RRDs.
       Apart from generating graphs, it can also extract
       numerical reports.

       filename
               The name of the graph to generate. Since rrdtool
               outputs GIFs and PNGs, it's recommended that the
               filename end in either .gif or .png.  rrdtool does
               not enforce this, however.  If the  filename is
               set to '-' the image file will be written to
               standard out.  All other output will get
               suppressed.

               PNG output is recommended, since it takes up to
               40% less disk space and 20-30% less time to
               generate than a GIF file.

               If no graph functions are called, the graph will
               not be created.

       -s|--start seconds (default end-1day)
               The time when the graph should begin. Time in
               seconds since epoch (1970-01-01) is required.
               Negative numbers are relative to the current time.
               By default one day worth of data will be graphed.
               See also AT-STYLE TIME SPECIFICATION section in
               the rrdfetch documentation for a detailed
               explanation on how to specify time.




14/Aug/99                     1.0.7                             1





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       -e|--end seconds (default now)
               The time when the graph should end. Time in
               seconds since epoch.  See also AT-STYLE TIME
               SPECIFICATION section in the rrdfetch
               documentation for a detailed explanation of ways
               to specify time.

       -x|--x-grid x-axis grid and label (default autoconfigure)
               The x-axis label is quite complex to configure. So
               if you don't have very special needs, you can rely
               on the autoconfiguration to get this right.

               The x-axis label is configured, using the
               following format:

               GTM:GST:MTM:MST:LTM:LST:LPR:LFM

               You have to configure three elements making up the
               x-axis labels and grid. The base grid (G??), the
               major grid (M??) and the labels (L??). The
               configuration is based on the idea that you first
               specify a well known amount of time (?TM) and then
               say how many times it has to pass between each
               grid line or label (?ST). For the label you have
               to define two additional items: The precision of
               the label in seconds (LPR) and the strftime format
               used to generate the text of the label (LFM).

               The ?TM elements must be one of the following
               keywords: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH
               or YEAR.

               If you wanted a graph with a base grid every 10
               minutes and a major one every hour, with labels
               every hour you would use the following x-axis
               definition.

               MINUTE:10:HOUR:1:HOUR:1:0:%X

               The precision in this example is 0 because the %X
               format is exact. If the label was the name of the
               day, we would have had a precision of 24 hours,
               because when you say something like 'Monday' you
               mean the whole day and not Monday morning 00:00.
               Thus the label should be positioned at noon. By
               defining a precision of 24 hours or rather 86400
               seconds, you make sure that this happens.

       -y--y-grid grid step:label factor (default autoconfigure)
               Makes vertical grid lines appear at grid step
               interval. Every label factor gridstep, a major
               grid line is printed, along with label showing the
               value of the grid line.




14/Aug/99                     1.0.7                             2





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       --alt-y-grid
               Place Y grid dynamically based on graph Y range.
               Algorithm ensures that you always have grid, that
               there are enough but not too many grid lines and
               the grid is metric. That is grid lines are placed
               every 1, 2, 5 or 10 units.  (contributed by Sasha
               Mikheev)

       --alt-autoscale
               Compute Y range  based on function absolute
               minimum and maximum values. Default algorithm uses
               predefined set of ranges.  This is good in many
               cases but it fails miserably when you need to
               graph something like 260 + 0.001 * sin(x). Default
               algorithm will use Y range from 250 to 300 and on
               the graph you will see almost straight line. With
               --alt-autoscale Y range will be from slightly less
               the 260 - 0.001 to slightly more then 260 + 0.001
               and periodic behavior will be seen.   (contributed
               by Sasha Mikheev)

       -v|--vertical-label text
               vertical label on the left side of the graph. This
               is normally used to specify the units used.

       -w|--width pixels (default 400 pixel)
               Width of the drawing area within the graph. This
               affects the size of the gif.

       -h|--height pixels (default 100 pixel)
               Width of the drawing area within the graph. This
               affects the size of the gif.

       -i|--interlaced (default: false)
               If you set this option, then the resulting GIF
               will be interlaced.  Most web browsers display
               these incrementally as they load. If you do not
               use this option, the GIFs default to being
               progressive scanned. The only effect of this
               option is to control the format of the GIF on
               disk. It makes no changes to the layout or
               contents of the graph.

       -f|--imginfo formatstring
               After the image has been created, the graph
               function uses printf together with this format
               string to create output similar to the PRINT
               function, only that the printf is supplied with
               the parameters filename, xsize and ysize. In order
               to generate an IMG tag suitable for including the
               graph into a web page, the command line would look
               like this:

                --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'



14/Aug/99                     1.0.7                             3





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       -a|--imgformat GIF|PNG (default: GIF)
               Allows you to produce PNG output from rrdtool.

       -z|--lazy (default: false)
               Only generate the graph, if the current gif is out
               of date or not existent.

       -u|--upper-limit value (default autoconfigure)
               The maximum value to be graphed. By default This
               will be autoconfigured from the data you select
               with the graphing functions.

       -l|--lower-limit value (default autoconfigure)
               The minimum value to be graphed. By default This
               will be autoconfigured from the data you select
               with the graphing functions.

       -r|--rigid
               rigid boundaries mode.  Normally rrdgraph will
               automatically expand the lower and upper limit if
               the graph contains a value outside the valid
               range. With the r option you can disable this
               behavior

       -b|--base value
               if you are graphing memory (and NOT network
               traffic) this switch should be set to 1024 so that
               one Kb is 1024 byte. For traffic measurement, 1
               kb/s is 1000 b/s.

       -o|--logarithmic
               logarithmic y-axis scaling

       -c|--color COLORTAG#rrggbb (default colors)
               override the colors for the standard elements of
               the graph. The COLORTAG must be one of the
               following symbolic names: BACK ground, CANVAS,
               SHADEA left/top border, SHADEB right/bottom
               border, GRID, MGRID major grid, FONT, FRAME and
               axis of the graph or ARROW. This option can be
               called multiple times to set several colors.

       -t|--title text (default no title)
               Define a title to be written into the graph

       DEF:vname=rrd:ds-name:CF
               Define virtual name for a data source. This name
               can then be used in the functions explained below.
               The DEF call automatically chooses an RRA which
               provides data in a resolution appropriate for the
               size of the graph to be drawn.  Ideally this means
               that one data point from the RRA should be
               represented by one pixel in the graph.  If the
               resolution of the RRA is higher than the



14/Aug/99                     1.0.7                             4





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


               resolution of the graph, the data in the RRA will
               be consolidated according to the consolidation
               function (CF) chosen.

       CDEF:vname=rpn-expression
               Create a new virtual data source by evaluating a
               mathematical expression, specified in Reverse
               Polish Notation (RPN). If you have ever used a
               traditional HP calculator you already know RPN.
               The idea behind RPN notation is, that you have a
               stack and push your data onto this stack. When
               ever you execute an operation, it takes as many
               data values from the stack as needed. The pushing
               of data is implicit, so when ever you specify a
               number or a variable, it gets pushed
               automatically.

               If this is all a big load of incomprehensible
               words for you, maybe an example helps (a more
               complete explanation is given in [1]): The
               expression vname+3/2 becomes vname,3,2,/,+ in RPN.
               First the three values get pushed onto the stack
               (which now contains (the current value of) vname,
               a 3 and a 2).  Then the / operator pops two values
               from the stack (3 and 2), divides the first
               argument by the second (3/2) and pushes the result
               (1.5) back onto the stack. Then the + operator
               pops two values (vname and 1.5) from the stack;
               both values are added up and the result gets
               pushes back onto the stack. In the end there is
               only one value left on the stack: The result of
               the expression.

               The rpn-expression in the CDEF function takes
               both, constant values as well as vname variables.
               The following operators can be used on these
               values:

       +, -, *, /, %   pops two values from the stack applies the
                       selected operator and pushes the result
                       back onto the stack. The % operator stands
                       for the modulo operation.

       SIN, COS, LOG, EXP
                       pops one value from the stack, applies the
                       selected function and pushes the result
                       back onto the stack.

       LT, LE, GT, GE, EQ
                       pops two values from the stack, compares
                       them according to the selected condition
                       and pushes either 1 back onto the stack if
                       the condition is true and 0 if the
                       condition was not true.



14/Aug/99                     1.0.7                             5





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       IF              pops three values from the stack. If the
                       last value is not 0, the second value will
                       be pushed back onto the stack, otherwise
                       the first value is pushed back.

                       If the stack contains the values A, B, C,
                       D, E are presently on the stack, the IF
                       operator will pop the values E D and C of
                       the stack. It will look at C and if it is
                       not 0 it will push D back onto the stack,
                       otherwise E will be sent back to the
                       stack.

       DUP, EXC, POP   These manipulate the stack directly.  DUP
                       will duplicate the top of the stack,
                       pushing the result back onto the stack.
                       EXC will exchange the top two elements of
                       the stack, and POP will pop off the top
                       element of the stack.  Having insufficient
                       elements on the stack for these operations
                       is an error.

       UN              Pops one value off the stack, if it is
                       *UNKNOWN*, 1 will be pushed back otherwise
                       0.

       UNKN            Push an *UNKNOWN* value onto the stack.

       INF, NEGINF     Push a positive or negative infinite (oo)
                       value onto the stack. When drawing an
                       infinite number it appears right at the
                       top or bottom edge of the graph, depending
                       whether you have a positive or negative
                       infinite number.

       NOW             Push the current (real world) time onto
                       the stack.

       TIME            Push the time the current sample was taken
                       onto the stack.

                       Please note that you may only use vname
                       variables that you previously defined by
                       either DEF or CDEF. Furthermore, as of
                       this writing (version 0.99.25), you must
                       use at least one vname per expression,
                       that is "CDEF:fourtytwo=2,40,+" will yield
                       an error message but not a vname fourtytwo
                       that's always equal to 42.

       PRINT:vname:CF:format
               Calculate the chosen consolidation function CF
               over the data-source variable vname and printf the
               result to stdout using format.  In the format



14/Aug/99                     1.0.7                             6





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


               string there should be a '%lf' or '%le' marker in
               the place where the number should be printed.

               If an additional '%s' is found AFTER the marker,
               the value will be scaled and an appropriate SI
               magnitude unit will be printed in place of the
               '%s' marker. The scaling will take the '--base'
               argument into consideration!

               If a '%S' is used instead of a '%s', then instead
               of calculating the appropriate SI magnitude unit
               for this value, the previously calculated SI
               magnitude unit will be used.  This is useful if
               you want all the values in a PRINT statement to
               have the same SI magnitude unit.  If there was no
               previous SI magnitude calculation made, then '%S'
               behaves like a '%s', unless the value is 0, in
               which case it does not remember a SI magnitude
               unit and a SI magnitude unit will only be
               calculated when the next '%s' is seen or the next
               '%S' for a non-zero value.

       GPRINT:vname:CF:format
               Same as PRINT but the result is printed into the
               graph below the legend.

       COMMENT:text
               Like GPRINT but the text is simply printed into
               the graph.

       HRULE:value#rrggbb[:legend]
               Draw a horizontal rule into the graph and
               optionally add a legend

       VRULE:time#rrggbb[:legend]
               Draw a vertical rule into the graph and optionally
               add a legend

       LINE{1|2|3}:vname[#rrggbb[:legend]]
               Plot for the requested data, using the color
               specified. Write a legend into the graph. The 3
               possible keywords LINE1, LINE2, and LINE3 generate
               increasingly wide lines. If no color is defined,
               the drawing is done 'blind' this is useful in
               connection with the STACK function when you want
               to ADD the values of two data-sources without
               showing it in the graph.

       AREA:vname[#rrggbb[:legend]]
               Does the same as LINE?, but the area between 0 and
               the graph will be filled with the color specified.

       STACK:vname[#rrggbb[:legend]]
               Does the same as LINE?, but the graph gets stacked



14/Aug/99                     1.0.7                             7





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


               on top of the previous LINE?, AREA or STACK graph.
               Depending on the type of the previous graph, the
               STACK will be either a LINE? or an AREA.  This
               obviously implies that the first STACK must be
               preceded by an AREA or LINE? -- you need something
               to stack something onto in the first place ;)

               Note, that when you STACK onto *UNKNOWN* data,
               rrdtool will not draw any graphics ... *UNKNOWN*
               is not zero ... if you want it to zero then you
               might want to use a CDEF argument with IF and UN
               functions to turn *UNKNOWN* into zero ...

               =back

NOTE
       In a ':' in a legend argument will mark the end of the
       legend. To enter a ':' into a legend, the colon must be
       escaped with a backslash '\:'.  Beware, that many
       environments look for backslashes themselves, so it may be
       necessary to write two backslashes so that one is passed
       onto rrd_graph.

NOTE 2
       The text printed below the actual graph can be formated by
       appending special escaped characters at the end of a text.
       When ever such a character occurs, all pending text is
       pushed onto the graph according to the character
       specified.

       Valid characters are: j for justified, l for left aligned,
       r for right aligned and c for centered. In the next
       section there is an example showing how to use centered
       formating.

       A special case is COMMENT:\s this inserts some additional
       vertical space before placing the next row of legends.

NOTE 3
       Whenever rrd_graph gets called, it prints a line telling
       the size of the gif it has just created to STDOUT. This
       line looks like this: XSIZExYSIZE.

EXAMPLE
         rrdtool graph demo.gif --title="Demo Graph" \
                 DEF:cel=demo.rrd:exhaust:AVERAGE \
                 "CDEF:far=cel,32,-,0.55555,*" \
                 LINE2:cel#00a000:"D. Celsius" \
                 LINE2:far#ff0000:"D. Fahrenheit\c"


EXAMPLE2
       This example demonstrates the syntax for using IF and UN
       to set *UNKNOWN* values to 0.  This technique is useful if



14/Aug/99                     1.0.7                             8





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       you are aggregating interface data where the start dates
       of the data sets doesn't match.

         rrdtool graph demo.gif --title="Demo Graph" \
                DEF:idat1=interface1.rrd:ds0:AVERAGE \
                DEF:idat2=interface2.rrd:ds0:AVERAGE \
                DEF:odat1=interface1.rrd:ds1:AVERAGE \
                DEF:odat2=interface2.rrd:ds1:AVERAGE \
                CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \
                CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \
                AREA:agginput#00cc00:Input Aggregate \
                LINE1:agginput#0000FF:Output Aggregate

       Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression

        idat1,UN,0,idat1,IF

       leaves us with a stack with contents of 1,0,NaN and the IF
       function will pop off the 3 values and replace them with
       0.  If idat1 had a real value like 7942099, then the stack
       would have 0,0,7942099 and the real value would be the
       replacement.

EXAMPLE3
       This example shows two ways to use the INF function. First
       it makes the background change color during half of the
       hours. Then, it uses AREA and STACK to draw a picture. If
       one of the inputs was UNKNOWN, all inputs are overlaid
       with another AREA.

         rrdtool graph example.png --title="INF demo" \
                DEF:val1=some.rrd:ds0:AVERAGE \
                DEF:val2=some.rrd:ds1:AVERAGE \
                DEF:val3=some.rrd:ds2:AVERAGE \
                DEF:val4=other.rrd:ds0:AVERAGE \
                CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \
                CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \
                AREA:background#F0F0F0 \
                AREA:val1#0000FF:Value1 \
                STACK:val2#00C000:Value2 \
                STACK:val3#FFFF00:Value3 \
                STACK:val4#FFC000:Value4 \
                AREA:whipeout#FF0000:Unknown

       The first CDEF uses val4 as a dummy value. It's value is
       removed immediately from the stack. Then a decision is
       made based on the time that a sample was taken. If it is
       an even hour (UTC time !) then the area will be filled. If
       it is not, the value is set to UNKN and is not plotted.

       The second CDEF looks if any of val1,val2,val3,val4 is
       unknown. It does so by checking the outcome of
       sum(val1,val2,val3,val4). Again, INF is returned when the
       condition is true, UNKN is used to not plot the data.



14/Aug/99                     1.0.7                             9





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       The different items are plotted in a particular order.
       First do the background,+then use a normal area to overlay
       it with data. Stack the other data until they+are all
       plotted. Last but not least, overlay everything with eye-
       hurting red to signal any unknown data.

       Note that this example assumesthat your data is in the
       positive half of the y-axis otherwhise you would would
       have to add NEGINF in order to extend the coverage of the
       rea to whole graph.

       =head1 AUTHOR

       Tobias Oetiker <oetiker@ee.ethz.ch>

REFERENCES
       [1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm








































14/Aug/99                     1.0.7                            10





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)



























































14/Aug/99                     1.0.7                            11


