


RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


NNNNAAAAMMMMEEEE
       rrdtool graph - Create a graph based on data from one or
       several RRD

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
       rrrrrrrrddddttttoooooooollll ggggrrrraaaapppphhhh _f_i_l_e_n_a_m_e [----ssss|--------ssssttttaaaarrrrtttt _s_e_c_o_n_d_s]
       [----eeee|--------eeeennnndddd _s_e_c_o_n_d_s] [----xxxx|--------xxxx----ggggrrrriiiidddd _x_-_a_x_i_s _g_r_i_d _a_n_d _l_a_b_e_l]
       [----yyyy|--------yyyy----ggggrrrriiiidddd _y_-_a_x_i_s _g_r_i_d _a_n_d _l_a_b_e_l] [--------aaaalllltttt----yyyy----ggggrrrriiiidddd] [--------aaaalllltttt----
       yyyy----mmmmrrrrttttgggg] [--------aaaalllltttt----aaaauuuuttttoooossssccccaaaalllleeee] [--------aaaalllltttt----aaaauuuuttttoooossssccccaaaalllleeee----mmmmaaaaxxxx] [--------uuuunnnniiiittttssss----
       eeeexxxxppppoooonnnneeeennnntttt] _v_a_l_u_e]> [----vvvv|--------vvvveeeerrrrttttiiiiccccaaaallll----llllaaaabbbbeeeellll _t_e_x_t]
       [----wwww|--------wwwwiiiiddddtttthhhh _p_i_x_e_l_s] [----hhhh|--------hhhheeeeiiiigggghhhhtttt _p_i_x_e_l_s] [----iiii|--------iiiinnnntttteeeerrrrllllaaaacccceeeedddd]
       [----ffff|--------iiiimmmmggggiiiinnnnffffoooo _f_o_r_m_a_t_s_t_r_i_n_g] [----aaaa|--------iiiimmmmggggffffoooorrrrmmmmaaaatttt GGGGIIIIFFFF|PPPPNNNNGGGG|GGGGDDDD]
       [----BBBB|--------bbbbaaaacccckkkkggggrrrroooouuuunnnndddd _v_a_l_u_e] [----OOOO|--------oooovvvveeeerrrrllllaaaayyyy _v_a_l_u_e]
       [----UUUU|--------uuuunnnniiiitttt _v_a_l_u_e] [----zzzz|--------llllaaaazzzzyyyy] [----oooo|--------llllooooggggaaaarrrriiiitttthhhhmmmmiiiicccc]
       [----uuuu|--------uuuuppppppppeeeerrrr----lllliiiimmmmiiiitttt _v_a_l_u_e] [----llll|--------lllloooowwwweeeerrrr----lllliiiimmmmiiiitttt _v_a_l_u_e]
       [----gggg|--------nnnnoooo----lllleeeeggggeeeennnndddd] [----rrrr|--------rrrriiiiggggiiiidddd] [--------sssstttteeeepppp _v_a_l_u_e]
       [----bbbb|--------bbbbaaaasssseeee _v_a_l_u_e] [----cccc|--------ccccoooolllloooorrrr _C_O_L_O_R_T_A_G####_r_r_g_g_b_b]
       [----tttt|--------ttttiiiittttlllleeee _t_i_t_l_e] [DDDDEEEEFFFF::::_v_n_a_m_e====_r_r_d::::_d_s_-_n_a_m_e::::_C_F]
       [CCCCDDDDEEEEFFFF::::_v_n_a_m_e====_r_p_n_-_e_x_p_r_e_s_s_i_o_n] [PPPPRRRRIIIINNNNTTTT::::_v_n_a_m_e::::_C_F::::_f_o_r_m_a_t]
       [GGGGPPPPRRRRIIIINNNNTTTT::::_v_n_a_m_e::::_C_F::::_f_o_r_m_a_t] [CCCCOOOOMMMMMMMMEEEENNNNTTTT::::_t_e_x_t]
       [HHHHRRRRUUUULLLLEEEE::::_v_a_l_u_e####_r_r_g_g_b_b[::::_l_e_g_e_n_d]] [VVVVRRRRUUUULLLLEEEE::::_t_i_m_e####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]
       [LLLLIIIINNNNEEEE{1111|2222|3333}::::_v_n_a_m_e[####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]]
       [AAAARRRREEEEAAAA::::_v_n_a_m_e[####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]]
       [SSSSTTTTAAAACCCCKKKK::::_v_n_a_m_e[####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]]

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
       The ggggrrrraaaapppphhhh functions main purpose is to create graphical
       representations of the data stored in one or several RRRRRRRRDDDDs.
       Apart from generating graphs, it can also extract
       numerical reports.

       _f_i_l_e_n_a_m_e
            The name of the graph to generate. Since rrrrrrrrddddttttoooooooollll
            outputs GIFs and PNGs, it's recommended that the
            filename end in either _._g_i_f or _._p_n_g.  rrrrrrrrddddttttoooooooollll does
            not enforce this, however.  If the  _f_i_l_e_n_a_m_e 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sss|--------ssssttttaaaarrrrtttt _s_e_c_o_n_d_s (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 _r_r_d_f_e_t_c_h
            documentation for a detailed explanation on how to
            specify time.



14/Apr/2002                   1.0.38                            1





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       ----eeee|--------eeeennnndddd _s_e_c_o_n_d_s (default now)
            The time when the graph should end. Time in seconds
            since epoch.  See also AT-STYLE TIME SPECIFICATION
            section in the _r_r_d_f_e_t_c_h documentation for a detailed
            explanation of ways to specify time.

       ----xxxx|--------xxxx----ggggrrrriiiidddd _x_-_a_x_i_s _g_r_i_d _a_n_d _l_a_b_e_l (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.

            If you want no x-grid at all, use the magic setting
            nnnnoooonnnneeee.

            The x-axis label and grid can be configured, using
            the following format:

            _G_T_M::::_G_S_T::::_M_T_M::::_M_S_T::::_L_T_M:_L_S_T::::_L_P_R::::_L_F_M

            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 (_?_T_M) and then say how many times it
            has to pass between each grid line or label (_?_S_T).
            For the label you have to define two additional
            items: The precision of the label in seconds (_L_P_R)
            and the strftime format used to generate the text of
            the label (_L_F_M).

            The _?_T_M elements must be one of the following
            keywords: SSSSEEEECCCCOOOONNNNDDDD, MMMMIIIINNNNUUUUTTTTEEEE, HHHHOOOOUUUURRRR, DDDDAAAAYYYY, WWWWEEEEEEEEKKKK, MMMMOOOONNNNTTTTHHHH or
            YYYYEEEEAAAARRRR.

            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.

            If you want to alter the genertated text to another
            language, use the LC_TIME environment variable to set
            the locale you prefere prior to calling the graph
            function.




14/Apr/2002                   1.0.38                            2





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       ----yyyy|--------yyyy----ggggrrrriiiidddd _g_r_i_d _s_t_e_p:_l_a_b_e_l _f_a_c_t_o_r (default autoconfigure)
            Makes vertical grid lines appear at _g_r_i_d _s_t_e_p
            interval. Every _l_a_b_e_l _f_a_c_t_o_r gridstep, a major grid
            line is printed, along with label showing the value
            of the grid line.

            If you want no y-grid at all set specify the magic
            word nnnnoooonnnneeee.

       --------aaaalllltttt----yyyy----ggggrrrriiiidddd
            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)

       --------aaaalllltttt----yyyy----mmmmrrrrttttgggg
            Y grid placed on graph Y range mimmics mrtg's
            (rateup-generated) graphs.  Currently axis is split
            into 4 parts, just as rateup does.

       --------aaaalllltttt----aaaauuuuttttoooossssccccaaaalllleeee
            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 * _s_i_n(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)

       --------aaaalllltttt----aaaauuuuttttoooossssccccaaaalllleeee----mmmmaaaaxxxx
            Where --alt-autoscale will modify both the absolute
            maximum AND minimum values, this option will only
            affect the maximum value. The minimum value, if not
            defined on the command line, will be 0. This option
            can be useful when graphing router traffic when the
            WAN line uses compression, and thus the throughput
            may be higher than the WAN line speed.

       --------uuuunnnniiiittttssss----eeeexxxxppppoooonnnneeeennnntttt _v_a_l_u_e (default autoconfigure)
            This sets the 10**exponent scaling of the y-axis
            values.  Normally values will be scaled to the
            appropriate units (k, M, etc.).  However you may wish
            to display units always in k (Kilo, 10e3) even if the
            data is in the M (Mega, 10e6) range for instance.
            Value should be an integer which is a multiple of 3
            between -18 and 18 inclusive.  It is the exponent on
            the units you which to use.  For example, use 3 to
            display the y-axis values in k (Kilo, 10e3,
            thousands), use -6 to display the y-axis values in u
            (Micro, 10e-6, millionths).  Use a value of 0 to



14/Apr/2002                   1.0.38                            3





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


            prevent any scaling of the y-axis values.

       ----vvvv|--------vvvveeeerrrrttttiiiiccccaaaallll----llllaaaabbbbeeeellll _t_e_x_t
            vertical label on the left side of the graph. This is
            normally used to specify the units used.

       ----wwww|--------wwwwiiiiddddtttthhhh _p_i_x_e_l_s (default 400 pixel)
            Width of the drawing area within the graph. This
            affects the size of the gif.

       ----hhhh|--------hhhheeeeiiiigggghhhhtttt _p_i_x_e_l_s (default 100 pixel)
            Width of the drawing area within the graph. This
            affects the size of the gif.

       ----iiii|--------iiiinnnntttteeeerrrrllllaaaacccceeeedddd (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fff|--------iiiimmmmggggiiiinnnnffffoooo _f_o_r_m_a_t_s_t_r_i_n_g
            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
            _f_i_l_e_n_a_m_e, _x_s_i_z_e and _y_s_i_z_e. In order to generate an
            IIIIMMMMGGGG 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">'


       ----aaaa|--------iiiimmmmggggffffoooorrrrmmmmaaaatttt GGGGIIIIFFFF|PPPPNNNNGGGG|GGGGDDDD (default: GIF)
            Allows you to produce PNG or GD output from rrdtool.

       ----BBBB|--------bbbbaaaacccckkkkggggrrrroooouuuunnnndddd _v_a_l_u_e
            You could use image in (currently only) GD format for
            background. It is used as background at the very
            beginning of graph creation.

       ----OOOO|--------oooovvvveeeerrrrllllaaaayyyy _v_a_l_u_e
            You could use image in (currently only) GD format as
            overlay. It is placed over created graph so that
            white pixel (color 255,255,255) is considered
            transparent, all other is replacing corresponding
            pixel in created graph.

       ----UUUU|--------uuuunnnniiiitttt _v_a_l_u_e
            You could use unit to be displayed on y axis. It is
            wise to use only short units on graph, however.




14/Apr/2002                   1.0.38                            4





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       ----zzzz|--------llllaaaazzzzyyyy (default: false)
            Only generate the graph, if the current gif is out of
            date or not existent.

       ----uuuu|--------uuuuppppppppeeeerrrr----lllliiiimmmmiiiitttt _v_a_l_u_e (default autoconfigure)
            Defines the value normally located at the upper
            border of the graph. If the graph contains higher
            values, the upper border will move upwards to
            accomodate these values as well.

            If you want to define an upper-limit which will not
            move in any event you have to set the --------rrrriiiiggggiiiidddd option
            as well.

       ----llll|--------lllloooowwwweeeerrrr----lllliiiimmmmiiiitttt _v_a_l_u_e (default autoconfigure)
            This is not the lower limit of a graph.  But rather,
            this is the maximum lower bound of a graph.  For
            example, the value -100 will result in a graph that
            has a lower limit of -100 or less.  Use this keyword
            to expand graphs down.

       ----rrrr|--------rrrriiiiggggiiiidddd
            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bbb|--------bbbbaaaasssseeee _v_a_l_u_e
            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ooo|--------llllooooggggaaaarrrriiiitttthhhhmmmmiiiicccc
            logarithmic y-axis scaling

       ----cccc|--------ccccoooolllloooorrrr _C_O_L_O_R_T_A_G####_r_r_g_g_b_b (default colors)
            override the colors for the standard elements of the
            graph. The _C_O_L_O_R_T_A_G must be one of the following
            symbolic names: BBBBAAAACCCCKKKK ground, CCCCAAAANNNNVVVVAAAASSSS, SSSSHHHHAAAADDDDEEEEAAAA left/top
            border, SSSSHHHHAAAADDDDEEEEBBBB right/bottom border, GGGGRRRRIIIIDDDD, MMMMGGGGRRRRIIIIDDDD major
            grid, FFFFOOOONNNNTTTT, FFFFRRRRAAAAMMMMEEEE and axis of the graph or AAAARRRRRRRROOOOWWWW.
            This option can be called multiple times to set
            several colors.

       ----gggg|--------nnnnoooo----lllleeeeggggeeeennnndddd
            Suppress generation of legend; only render the graph.

       ----tttt|--------ttttiiiittttlllleeee _t_e_x_t (default no title)
            Define a title to be written into the graph

       --------sssstttteeeepppp _v_a_l_u_e (default automatic)
            By default rrdgraph calculates the width of one pixle
            in the time domain and tries to get data at that



14/Apr/2002                   1.0.38                            5





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


            resolution from the RRD. With this switch you can
            override this behaviour. If you want rrdgraph to get
            data at 1 hour resolution from the RRD, then you can
            set the step to 3600 seconds. Note, that a step
            smaller than 1 pixle will be silently ignored.

       DDDDEEEEFFFF::::_v_n_a_m_e====_r_r_d::::_d_s_-_n_a_m_e::::_C_F
            Define virtual name for a data source. This name can
            then be used in the functions explained below. The
            DEF call automatically chooses an RRRRRRRRAAAA which contains
            _C_F consolidated data in a resolution appropriate for
            the size of the graph to be drawn.  Ideally this
            means that one data point from the RRRRRRRRAAAA should be
            represented by one pixel in the graph.  If the
            resolution of the RRRRRRRRAAAA is higher than the resolution
            of the graph, the data in the RRA will be further
            consolidated according to the consolidation function
            (_C_F) chosen.

       CCCCDDDDEEEEFFFF::::_v_n_a_m_e====_r_p_n_-_e_x_p_r_e_s_s_i_o_n
            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
            _v_n_a_m_e_+_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 _r_p_n_-_e_x_p_r_e_s_s_i_o_n in the CCCCDDDDEEEEFFFF function takes both,
            constant values as well as _v_n_a_m_e 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



14/Apr/2002                   1.0.38                            6





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


                 modulo operation.

       SIN, COS, LOG, EXP, FLOOR, CEIL
                 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.

       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.

       MIN, MAX  selects the lesser or larger of the two top
                 stack values respectively

       LIMIT     replaces the value with _*_U_N_K_N_O_W_N_* if it is
                 outside the limits specified by the two values
                 above it on the stack.

                  CDEF:a=alpha,0,100,LIMIT


       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
                 _*_U_N_K_N_O_W_N_*, 1 will be pushed back otherwise 0.

       UNKN      Push an _*_U_N_K_N_O_W_N_* value onto the stack.

       PREV      Push _*_U_N_K_N_O_W_N_* if its at the first value of a
                 data set or otherwise the value of this CDEF at
                 the previous time step. This allows you to
                 perform calculations across the data.




14/Apr/2002                   1.0.38                            7





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       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. This is the number of non-skip
                 seconds since 0:00:00 January 1, 1970.

       LTIME     This is like TIME ++++ ccccuuuurrrrrrrreeeennnntttt ttttiiiimmmmeeeezzzzoooonnnneeee ooooffffffffsssseeeetttt iiiinnnn
                 sssseeeeccccoooonnnnddddssss. The current offset takes daylight
                 saving time into account, given your OS supports
                 this. If you were looking at a sample, in
                 Zurich, in summer, the offset would be 2*3600
                 seconds, as Zurich at that time of year is 2
                 hours ahead of UTC.

                 Note that the timezone offset is always
                 calculated for the time the current sample was
                 taken at. It has nuthing todo with the time you
                 are doing the calculation.

                 Please note that you may only use _v_n_a_m_e
                 variables that you previously defined by either
                 DDDDEEEEFFFF or CCCCDDDDEEEEFFFF. Furthermore, as of this writing
                 (version 0.99.25), you must use at least one
                 _v_n_a_m_e per expression, that is
                 "CDEF:fourtytwo=2,40,+" will yield an error
                 message but not a _v_n_a_m_e fourtytwo that's always
                 equal to 42.

       PPPPRRRRIIIINNNNTTTT::::_v_n_a_m_e::::_C_F::::_f_o_r_m_a_t
            Calculate the chosen consolidation function _C_F over
            the data-source variable _v_n_a_m_e and printf the result
            to stdout using _f_o_r_m_a_t.  In the _f_o_r_m_a_t 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



14/Apr/2002                   1.0.38                            8





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


            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.

            If you want to put a '%' into your PRINT string, use
            '%%' instead.

       GGGGPPPPRRRRIIIINNNNTTTT::::_v_n_a_m_e::::_C_F::::_f_o_r_m_a_t
            Same as PPPPRRRRIIIINNNNTTTT but the result is printed into the
            graph below the legend.

       CCCCaaaavvvveeeeaaaatttt:::: When using the PPPPRRRRIIIINNNNTTTT and GGGGRRRRPPPPRRRRIIIINNNNTTTT functions to
       calculate data summaries over time periods bounded by the
       current time, it is important to note that the last sample
       will almost always yield a value of UNKNOWN as it lies
       after the last update time.  This can result in slight
       data skewing, particularly with the AAAAVVVVEEEERRRRAAAAGGGGEEEE function.  In
       order to avoid this, make sure that your end time is at
       least one heartbeat prior to the current time.

       CCCCOOOOMMMMMMMMEEEENNNNTTTT::::_t_e_x_t
            Like GGGGPPPPRRRRIIIINNNNTTTT but the _t_e_x_t is simply printed into the
            graph.

       HHHHRRRRUUUULLLLEEEE::::_v_a_l_u_e####_r_r_g_g_b_b[::::_l_e_g_e_n_d]
            Draw a horizontal rule into the graph and optionally
            add a legend

       VVVVRRRRUUUULLLLEEEE::::_t_i_m_e####_r_r_g_g_b_b[::::_l_e_g_e_n_d]
            Draw a vertical rule into the graph and optionally
            add a legend

       LLLLIIIINNNNEEEE{1111|2222|3333}::::_v_n_a_m_e[####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]
            Plot for the requested data, using the color
            specified. Write a legend into the graph. The 3
            possible keywords LLLLIIIINNNNEEEE1111, LLLLIIIINNNNEEEE2222, and LLLLIIIINNNNEEEE3333 generate
            increasingly wide lines. If no color is defined, the
            drawing is done 'blind' this is useful in connection
            with the SSSSTTTTAAAACCCCKKKK function when you want to ADD the
            values of two data-sources without showing it in the
            graph.

       AAAARRRREEEEAAAA:_v_n_a_m_e[####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]
            Does the same as LLLLIIIINNNNEEEE????, but the area between 0 and
            the graph will be filled with the color specified.

       SSSSTTTTAAAACCCCKKKK:_v_n_a_m_e[####_r_r_g_g_b_b[::::_l_e_g_e_n_d]]
            Does the same as LLLLIIIINNNNEEEE????, but the graph gets stacked on
            top of the previous LLLLIIIINNNNEEEE????, AAAARRRREEEEAAAA or SSSSTTTTAAAACCCCKKKK graph.
            Depending on the type of the previous graph, the
            SSSSTTTTAAAACCCCKKKK will be either a LLLLIIIINNNNEEEE???? or an AAAARRRREEEEAAAA.  This



14/Apr/2002                   1.0.38                            9





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


            obviously implies that the first SSSSTTTTAAAACCCCKKKK must be
            preceded by an AAAARRRREEEEAAAA or LLLLIIIINNNNEEEE???? -- 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 ...

NNNNOOOOTTTTEEEESSSS oooonnnn lllleeeeggggeeeennnndddd aaaarrrrgggguuuummmmeeeennnnttttssss
       EEEEssssccccaaaappppiiiinnnngggg tttthhhheeee ccccoooolllloooonnnn

       In a ':' in a _l_e_g_e_n_d 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.

       SSSSttttrrrriiiinnnngggg FFFFoooorrrrmmmmaaaattttttttiiiinnnngggg

       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 markers are: \\\\jjjj for justified, \\\\llll for left aligned,
       \\\\rrrr for right aligned and \\\\cccc for centered. In the next
       section there is an example showing how to use centered
       formating.

       Normally there are two space characters inserted between
       every two items printed into the graph. The space
       following a string can be suppressed by putting a \\\\gggg at
       the end of the string. The \\\\gggg also squshes any space
       inside the string if it is at the very end of the string.
       This can be used in connection with %%%%ssss to supress empty
       unit strings.

        GPRINT:a:MAX:%lf%s\g

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

NNNNOOOOTTTTEEEE oooonnnn RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
       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.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE 1111





14/Apr/2002                   1.0.38                           10





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


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


EEEEXXXXAAAAMMMMPPPPLLLLEEEE 2222
       This example demonstrates the syntax for using IF and UN
       to set _*_U_N_K_N_O_W_N_* values to 0.  This technique is useful if
       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:aggoutput#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.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE 3333
       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:wipeout#FF0000:Unknown




14/Apr/2002                   1.0.38                           11





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)


       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
       _s_u_m(val1,val2,val3,val4). Again, INF is returned when the
       condition is true, UNKN is used to not plot the data.

       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 assumes that 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.

AAAAUUUUTTTTHHHHOOOORRRR
       Tobias Oetiker <oetiker@ee.ethz.ch>

RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
       [1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm






























14/Apr/2002                   1.0.38                           12





RRDGRAPH(1)                  rrdtool                  RRDGRAPH(1)



























































14/Apr/2002                   1.0.38                           13


