_R_R_D_G_R_A_P_H___D_A_T_A(1)                     rrdtool                    _R_R_D_G_R_A_P_H___D_A_T_A(1)

NNAAMMEE
     rrdgraph_data - preparing data for graphing in rrdtool graph

SSYYNNOOPPSSIISS
     DDEEFF::_<_v_n_a_m_e_>=_<_r_r_d_‐
     _f_i_l_e_>:_<_d_s_-_n_a_m_e_>:_<_C_F_>[:step=_<_s_t_e_p_>][:start=_<_t_i_m_e_>][:end=_<_t_i_m_e_>][:re‐
     duce=_<_CC_FF_>][:daemon=_<_a_d_d_r_e_s_s_>]

     VVDDEEFF:_v_n_a_m_e=_R_P_N _e_x_p_r_e_s_s_i_o_n

     CCDDEEFF:_v_n_a_m_e=_R_P_N _e_x_p_r_e_s_s_i_o_n

DDEESSCCRRIIPPTTIIOONN
     These  three instructions extract data values out of the RRRRDD files, option‐
     ally altering them (think, for example, of a bytes to bits conversion).  If
     so  desired,  you  can  also define variables containing useful information
     such as maximum, minimum etcetera. Two of the instructions use  a  language
     called RRPPNN which is described in its own manual page.

     Variable  names (_v_n_a_m_e) must be made up strings of the following characters
     "A-Z, a-z, 0-9, _, -" and a maximum length of 255 characters.

     When picking variable names, make sure you do not choose a name that is al‐
     ready taken by an RPN operator. A safe bet is to  use  lowercase  or  mixed
     case names for variables since operators will always be in uppercase.

DDEEFF
     DDEEFF::_<_v_n_a_m_e_>=_<_r_r_d_‐
     _f_i_l_e_>:_<_d_s_-_n_a_m_e_>:_<_C_F_>[:step=_<_s_t_e_p_>][:start=_<_t_i_m_e_>][:end=_<_t_i_m_e_>][:re‐
     duce=_<_CC_FF_>][:daemon=_<_a_d_d_r_e_s_s_>]

     This  command  fetches  data  from an RRRRDD file.  The virtual name _v_n_a_m_e can
     then be used throughout the rest of the script. By default,  an  RRRRAA  which
     contains the correct consolidated data at an appropriate resolution will be
     chosen.  The resolution can be overridden with the --step option.  The res‐
     olution can again be overridden by specifying the sstteepp ssiizzee.  The time span
     of this data is the same as for the graph by default, you can override this
     by  specifying ssttaarrtt aanndd eenndd.  Remember to escape colons in the time speci‐
     fication!

     If the resolution of the data is higher than the resolution of  the  graph,
     the  data  will  be  further  consolidated. This may result in a graph that
     spans slightly more time than requested.  Ideally each point in  the  graph
     should  correspond with one CCDDPP from an RRRRAA.  For instance, if your RRRRDD has
     an RRRRAA with a resolution of 1800 seconds per CCDDPP, you should create an  im‐
     age  with  width  400 and time span 400*1800 seconds (use appropriate start
     and end times, such as "--start end-8days8hours").

     If consolidation needs to be done, the CCFF of the RRRRAA specified in  the  DDEEFF
     itself  will  be  used  to  reduce  the  data density. This behavior can be
     changed using ":reduce=_<CCFF_>".  This optional parameter specifies the CCFF  to
     use during the data reduction phase.

     It  is  possible  to request single data sources from a specific _R_R_D_C_a_c_h_e_D,
     see rrdcached, using the ":daemon=_<_a_d_d_r_e_s_s_>" parameter. The value given  to
     this  parameter  follows  the same syntax as other means to specify the ad‐
     dress of the caching daemon. It is described in detail  in  rrdcached.  Be‐
     ware,  however, that colons (in IPv6 addresses and as a port separator, for
     example) need to be escaped using a backslash.

     Example:

             DEF:ds0=router.rrd:ds0:AVERAGE
             DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
             DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h
             DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h
             DEF:ds0weekly=router.rrd:ds0:AVERAGE:daemon=collect1.example.com

VVDDEEFF
     VVDDEEFF:_v_n_a_m_e=_R_P_N _e_x_p_r_e_s_s_i_o_n

     This command returns a value and/or a time according to the RRPPNN  statements
     used.  The  resulting  _v_n_a_m_e  will, depending on the functions used, have a
     value and a time component.  When you use this _v_n_a_m_e in another RRPPNN expres‐
     sion, you are effectively inserting its value just as if you had put a num‐
     ber at that place.  The variable can also be used in the various graph  and
     print elements.

     Example: "VDEF:avg=mydata,AVERAGE"

     Note  that  currently  only  aggregation functions work in VDEF rpn expres‐
     sions.  Patches to change this are welcome.

CCDDEEFF
     CCDDEEFF:_v_n_a_m_e=_R_P_N _e_x_p_r_e_s_s_i_o_n

     This command creates a new set of data points (in memory only, not  in  the
     RRRRDD  file)  out  of one or more other data series. The RRPPNN instructions are
     used to evaluate a mathematical function on each data point. The  resulting
     _v_n_a_m_e  can then be used further on in the script, just as if it were gener‐
     ated by a DDEEFF instruction.

     Example: "CDEF:mydatabits=mydata,8,*"

AAbboouutt CCDDEEFF vveerrssuuss VVDDEEFF
     At some point in processing, RRRRDDttooooll has gathered an array of  rates  ready
     to display.

     CCDDEEFF  works on such an array.  For example, _C_D_E_F_:_n_e_w_=_d_s_0_,_8_,_* would multiply
     each of the array members by eight (probably transforming bytes into bits).
     The result is an array containing the new values.

     VVDDEEFF also works on such an array but in  a  different  way.   For  example,
     _V_D_E_F_:_m_a_x_=_d_s_0_,_M_A_X_I_M_U_M  would  scan  each  of the array members and store the
     maximum value.

   WWhheenn ddoo yyoouu uussee VVDDEEFF vveerrssuuss CCDDEEFF??
     Use CCDDEEFF to transform your data prior to graphing.  In the  above  example,
     we'd use a CCDDEEFF to transform bytes to bits before graphing the bits.

     You  use  a  VVDDEEFF  if you want _m_a_x_(_1_,_5_,_3_,_2_,_4_) to return five which would be
     displayed in the graph's legend (to answer, what was the maximum value dur‐
     ing the graph period).

     If you want to apply 'complex' operations to the result of a VDEF you  have
     to use a CDEF again since VDEFs only look like RPN expressions, they aren't
     really.

SSEEEE AALLSSOO
     rrdgraph  gives  an overview of how rrrrddttooooll ggrraapphh works.  rrdgraph_data de‐
     scribes DDEEFF,CCDDEEFF and VVDDEEFF in detail.  rrdgraph_rpn describes the  RRPPNN  lan‐
     guage  used  in  the ??DDEEFF statements.  rrdgraph_graph page describes all of
     the graph and print functions.

     Make sure to read rrdgraph_examples for tips&tricks.

AAUUTTHHOORR
     Program by Tobias Oetiker <tobi@oetiker.ch>

     This manual page by Alex van  den  Bogaerdt  <alex@vandenbogaerdt.nl>  with
     corrections and/or additions by several people

1.10.3                             2026-06-13                   _R_R_D_G_R_A_P_H___D_A_T_A(1)
