


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----
     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]
     [----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] [----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.




2001-02-20             Last change: 1.0.33                      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.

     ----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.



2001-02-20             Last change: 1.0.33                      2






rrdtool                                               RRDGRAPH(1)



         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----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 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.




2001-02-20             Last change: 1.0.33                      3






rrdtool                                               RRDGRAPH(1)



     ----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 (default: GIF)
         Allows you to produce PNG output from rrdtool.

     ----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



2001-02-20             Last change: 1.0.33                      4






rrdtool                                               RRDGRAPH(1)



         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 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



2001-02-20             Last change: 1.0.33                      5






rrdtool                                               RRDGRAPH(1)



         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 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




2001-02-20             Last change: 1.0.33                      6






rrdtool                                               RRDGRAPH(1)



         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.

         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



2001-02-20             Last change: 1.0.33                      7






rrdtool                                               RRDGRAPH(1)



             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 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



2001-02-20             Last change: 1.0.33                      8






rrdtool                                               RRDGRAPH(1)



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



2001-02-20             Last change: 1.0.33                      9






rrdtool                                               RRDGRAPH(1)



     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
       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:agginput#0000FF:Output Aggregate

     Assuming that idat1 has a data value of _*_U_N_K_N_O_W_N_*, the CDEF
     expression





2001-02-20             Last change: 1.0.33                     10






rrdtool                                               RRDGRAPH(1)



      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

     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.

     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.





2001-02-20             Last change: 1.0.33                     11






rrdtool                                               RRDGRAPH(1)



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


















































2001-02-20             Last change: 1.0.33                     12



