Introduction
The CDEF directive provides a means for manipulating the “raw” data stored in a round-robin archive (RRA). It is typically used to apply a mathematical function to each data point referenced by one or more DEF statements which results in an array of new values — each of remains associated with the respective time of the original “raw” data point. This is an in-memory transformation only; the original data remains unchanged in the RRA.
There is often much confusion regarding the differences of the DEF, CDEF, and VDEF directives. It may help to think of the different directives in the following manner:
- A DEF directive references a set of “raw” data as it is stored in a RRA
- A CDEF directive applies a function to each data point it references
- A VDEF directive applies a function to an aggregate of data points
The CDEF Directive
The basic format for a CDEF directive is as follows:
CDEF:Label=RPN Expression
Label is the name of the CDEF. It may be referenced in other directives for inclusion in LINE, AREA charts or even other CDEF calculations. It may be from 1-19 characters long and consists of characters in the set [a-zA-Z0-9_]. Note that the label must be unique and cannot overlap with any labels assigned to other DEFs, CDEFs, or VDEFs.
RPN Expression is the mathematical or logical expression that may be used to manipulate the raw data values as referenced by DEF or CDEF directives or even a pure mathematical function. The expression uses Reverse Polish Notation to eliminate confusion or errors that may occur with the precedence rules required of traditional infix notation. There are a number of mathematical, boolean and logical operators available for inclusion in a CDEF directive.
CDEF Examples
Example 1
This example illustrates the commonly used transformation of bytes to megabytes. Disk and memory readings are often reported in bytes, but frequently this is not the most convenient unit for visualization. In this case, the CDEF directive divides the “raw” data value as referenced by the DEF and divides it by 1048576 (1024 x 1024). Note that the AREA directive now references the CDEF label and that the vertical label has been updated to reflect the proper units.
rrdtool graph "Example 1 CDEF.png" \
--start "end-48 hours" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 1" \
--vertical-label "Megabytes" \
DEF:disk1=sysinfo.rrd:disk_used:AVERAGE \
CDEF:megadisk1=disk1,1048576,/ \
AREA:megadisk1#0000FF:"Disk 1"
Example 2
This example shows a slightly more complex instance of the reverse-polish math that may be referenced in a CDEF. In this case, the CDEF first sums up the the “raw” values as referenced by the two DEF statements and then converts the sum to megabytes.
rrdtool graph "Example 2 CDEF.png" \
--start "end-48 hours" --end "Nov 1, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 2" \
--vertical-label "Megabytes" \
DEF:disk1=sysinfo.rrd:disk_used:AVERAGE \
DEF:disk2=sysinfo.rrd:disk2_used:AVERAGE \
CDEF:megadisk=disk1,disk2,+,1048576,/ \
AREA:megadisk#0000FF:"Total Disk Used"
Example 3
This example illustrates a common technique for differentiating several types of related measurements. It is a frequent graphing style for disk IO (reads vs. writes) as well as network IO (octets in vs. octets out). It is achieved by simply negating the values of one of the operations and graphing the result. In this example, a horizontal rule (HRULE) at the 0 point has also been added in order to highlight the baseline. Note that the HRULE is specified as the last element to be drawn, which ensures that it will overlay the other graphed elements.
rrdtool graph "Example 3 CDEF.png" \
--start "end-48 hours" --end "Nov 1, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 3" \
--vertical-label "Bytes" \
DEF:read=sysinfo.rrd:bytes_read:AVERAGE \
DEF:write=sysinfo.rrd:bytes_written:AVERAGE \
CDEF:negwrite=0,write,- \
AREA:read#0000FF:"Bytes Read" \
AREA:negwrite#00FF00:"Bytes Written" \
HRULE:0#000000
Example 4
This is a more complex example which illustrates the use of the IF operation as well as a more advanced graphing style useful to call out anomalous behaviors. In this case, the temperature values (referenced by the DEF “temp”) are first assessed by the LE (less than or equal to) and GT (greater than) operations. The values assigned in these CDEFs (iscool, ishot) will then be used in the CDEFs with the IF operations. The IF operations evaluate iscool/ishot and if it is “true” (i.e. not zero), then the value for temp is returned. Otherwise, the special constant “unknown” is returned. These values for the cool/hot CDEFs are then graphed and result in a clear demarcation where the system is over-heated.
rrdtool graph "Example 4 CDEF.png" \
--start "end-48 hours" --end "Nov 1, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 4" \
--vertical-label "Temperature" \
DEF:temp=sysinfo.rrd:temperature:AVERAGE \
CDEF:iscool=temp,175,LE \
CDEF:ishot=temp,175,GT \
CDEF:cool=iscool,temp,UNKN,IF \
CDEF:hot=ishot,temp,UNKN,IF \
AREA:cool#0000FF:"cool" \
AREA:hot#FF0000:"hot"
Example 5
This example illustrates the use of the LIMIT operation to achieve a similar effect for highlighting anomalous conditions. In this case, the entire data set is initially graphed using the “hot” color and then the “cool” data set is overlayed on top of the appropriate sections.
rrdtool graph "Example 5 CDEF.png" \
--start "end-48 hours" --end "12am Nov 1, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 5" \
--vertical-label "Temperature" \
DEF:temp=sysinfo.rrd:temperature:AVERAGE \
CDEF:cool=temp,0,175,LIMIT \
AREA:temp#FF0000:"hot" \
AREA:cool#0000FF:"cool"
Example 6
This example shows the use of the MIN operation to provide a “layer cake effect” in the graph. This is a popular graphing technique that can be used either to signify a state change above a given threshold or simply to provide a color gradient in the graph for extra polish. This particular example again relies on overlaying the “cool” graph to mask out the relevant sections of the data.
rrdtool graph "Example 6 CDEF.png" \
--start "end-48 hours" --end "12am Nov 1, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 6" \
--vertical-label "Temperature" \
DEF:temp=sysinfo.rrd:temperature:AVERAGE \
CDEF:cool=temp,175,MIN \
AREA:temp#FF0000:"hot" \
AREA:cool#0000FF:"cool"
