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

NNAAMMEE
     rrdgraph_data - preparing data for graphing in rrdtool graph

SSYYNNOOPPSSIISS
     DDEEFF::_<_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=_<_CC_FF_>][:daemon=_<_a_d_d_r_e_s_s_>]

     VVDDEEFF:_v_n_a_m_e=_R_P_N _e_x_p_r_e_s_s_i_o_n

     CCDDEEFF:_v_n_a_m_e=_R_P_N _e_x_p_r_e_s_s_i_o_n

DDEESSCCRRIIPPTTIIOONN
     These  three instructions extract data values out of the RRRRDD 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 RRPPNN 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.

DDEEFF
     DDEEFF::_<_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=_<_CC_FF_>][:daemon=_<_a_d_d_r_e_s_s_>]

     This  command  fetches  data  from an RRRRDD file.  The virtual name _v_n_a_m_e can
     then be used throughout the rest of the script. By default,  an  RRRRAA  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 sstteepp ssiizzee.  The time span
     of this data is the same as for the graph by default, you can override this
     by  specifying ssttaarrtt aanndd eenndd.  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 CCDDPP from an RRRRAA.  For instance, if your RRRRDD has
     an RRRRAA with a resolution of 1800 seconds per CCDDPP, 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 CCFF of the RRRRAA specified in  the  DDEEFF
     itself  will  be  used  to  reduce  the  data density. This behavior can be
     changed using ":reduce=_<CCFF_>".  This optional parameter specifies the CCFF  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

VVDDEEFF
     VVDDEEFF:_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 RRPPNN  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 RRPPNN 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.

CCDDEEFF
     CCDDEEFF:_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
     RRRRDD  file)  out  of one or more other data series. The RRPPNN 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 DDEEFF instruction.

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

AAbboouutt CCDDEEFF vveerrssuuss VVDDEEFF
     At some point in processing, RRRRDDttooooll has gathered an array of  rates  ready
     to display.

     CCDDEEFF  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.

     VVDDEEFF 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.

   WWhheenn ddoo yyoouu uussee VVDDEEFF vveerrssuuss CCDDEEFF??
     Use CCDDEEFF to transform your data prior to graphing.  In the  above  example,
     we'd use a CCDDEEFF to transform bytes to bits before graphing the bits.

     You  use  a  VVDDEEFF  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.

SSEEEE AALLSSOO
     rrdgraph  gives  an overview of how rrrrddttooooll ggrraapphh works.  rrdgraph_data de‐
     scribes DDEEFF,CCDDEEFF and VVDDEEFF in detail.  rrdgraph_rpn describes the  RRPPNN  lan‐
     guage  used  in  the ??DDEEFF statements.  rrdgraph_graph page describes all of
     the graph and print functions.

     Make sure to read rrdgraph_examples for tips&tricks.

AAUUTTHHOORR
     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.0                             2026-05-23                   _R_R_D_G_R_A_P_H___D_A_T_A(1)
