Introduction
This post covers some of the basic techniques for generating graphs using RRD tool. The demonstration examples assumes that the data has been created as described in the RRD Example Data posting. It should provide a basic understanding of how to specify data sources and transform them into basic line graphs using some of RRDTool’s built-in graphing options.
Data Definitions
The data definition is the source of the data to be graphed. It provides a label that is referenced by the graphing directives. There can be multiple data definitions in a single graph and the data may be manipulated extensively by other operations (CDEFs and VDEFs). In addition, it is possible to specify data from multiple files to be combined in a single graph.
The basic format for a Data Definition (DEF) is as follows:
DEF:Label=RRD File:Data Source:Consolidation Function
Label is the name of the data definition. It may be from 1-19 characters long and consists of characters in the set [a-zA-Z0-9_]. The label should be descriptive of the data being graphed and may be the same label as used in the original Data Source. Example labels include “temperature”, “BytesIn”, “bytes_out”, etc.
RRD File is the path and name of the data file. If the full path is not specified, then rrdtool assumes the current working directory.
Data Source is the name of the data source (DS) within the RRD file. See the posting on Creating a RRD File for a reference of the DS definition if necessary.
Consolidation Function specifies how rrdtool may consolidate data prior to display. This does not affect the actual data stored in the RRD file; it is used to aggregate data points if the resolution of the graph is too low to display each data point individually. There available consolidation functions are MIN, MAX, AVERAGE, and LAST.
MIN uses only the smallest value of the Primary Data Points within the resolution’s time span.
MAX uses only the largest value of the Primary Data Points within the resolution’s time span.
AVERAGE uses the average of the all Primary Data Points within the resolution’s time span.
LAST uses only the last (most recent) Primary Data Point within the resolution’s time span.
Graphing Directive for Lines
With the data definitions established, graphing directives can be used to specify how the data will be displayed. Note that the graphing directives should be specified only after the data definitions (DEF) have been declared. The general format for a line directive is as follows:
LINE[Width]:Label#Color:Legend
Width is an optional element for line graphs. It defines the width of the line used to draw the graph.
Label refers to the label given to a previously defined data definition (DEF). This defines the source of the data to be graphed.
Color defines the color of the line or area graph. This is expressed in the web-standard RGB hexadecimal triplet and must be separated from the label by a ‘#’. Example color definitions are: 333399 (blue), 33FF00 (bright green), and CC0000 (red). If the color is not specified, then the line will be “invisible”.
Legend is the text associated with the legend entry for the graph. It is an optional element, and if it is omitted the ‘:’ separator should also be omitted.
Display Options
There are a number of options available that define how the graph is rendered. These options can define the size, format, time span, legend, title, etc. of the graph. None of them are explicitly required (default values will be used), but they help provide some basic customization of the graphs.
--width specifies the width (in pixels) of the graphing canvas. The actual image width may be wider to accommodate any border or label elements.
--height specifies the height (in pixels) of the graphing canvas. The actual image height may be taller to accommodate any border, title, or legend elements.
--imgformat specifies the desired output format of the graph. Available options include: PNG, SVG, EPS, and PDF.
--start specifies the start time (in absolute or relative terms) for the data displayed on the graphing canvas. Frequently, the start time is a relative offset of the end time (e.g. “end-24 hours”, “end-1 month”, “end-2 weeks”)
--end specifies the end time (in absolute or relative terms) for the data displayed on the graphing canvas. The most frequently used value for the end time is “now”, which results in a graph showing the latest data.
--title specifies the text to be displayed above the graphing canvas.
--vertical-label specifies the text to be displayed next to the y-axis. Typically, this indicates the units of the measurement.
Examples
Example 1
This basic example creates a graph with the filename “Example 1.png”. As specified by the start and end dates, it encompasses the entire year of 2009. The resulting PNG file will have a data canvas of 500 x 120 pixels, although the full size of the image will be larger to accommodate the legend and border. This example uses only one data definition (DEF) which references the sysinfo.rrd file’s “load” data element (but note that the label for the DEF itself is called “sysload”). The line directive (LINE1) in turn references the “sysload” label to draw a 1 pixel wide blue line.
rrdtool graph "Example 1.png" \
--start="Jan 1, 2009" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
DEF:sysload=sysinfo.rrd:load:AVERAGE \
LINE1:sysload#0000FF
Example 2
This example is similar to the first with the exception that it illustrates the use of relative dates to define the graphing period. In this case, the start time is defined as 2 weeks less than the end time. A frequent use of relative dates is specifying the end time as “now” and the start time relative to that (such as “end-24 hours” or “end-1 week”). Note also RRDTool adjusts the x-axis legend to reflect the different time span.
rrdtool graph "Example 2.png" \
--start="end-2 weeks" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
DEF:load=sysinfo.rrd:load:AVERAGE \
LINE1:load#0000FF
Example 3
This example extends the previous example by adding an additional data definition and line. Note that the lines are drawn in the order they are specified, which means that where lines overlap, the line specified latest in the graph command will be on top.
rrdtool graph "Example 3.png" \
--start="end-2 weeks" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
DEF:load=sysinfo.rrd:load:AVERAGE \
DEF:temp=sysinfo.rrd:temperature:AVERAGE \
LINE1:load#0000FF \
LINE1:temp#FF0000
Example 4
Extending the example further, this iteration introduces some basic legend and title information. This example creates a title for the graph (“Example 4″) and a label for the vertical axis (“Units”). In addition, each of the line directives are amended to include a legend specification. RRDTool will create the appropriate “color squares” for the legend entries.
rrdtool graph "Example 4.png" \
--start="end-2 weeks" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 4" \
--vertical-label "Units" \
DEF:load=sysinfo.rrd:load:AVERAGE \
DEF:temp=sysinfo.rrd:temperature:AVERAGE \
LINE1:load#0000FF:"System Load" \
LINE1:temp#FF0000:"CPU Temperature"
Example 5
This example simply illustrates a variation of the width of the line element. In this case, the line representing the temperature has been specified as being 3 pixels wide (LINE3). Line width can be specified as 1, 2 or 3 pixels wide.
rrdtool graph "Example 5.png" \
--start="end-2 weeks" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 5" \
--vertical-label "Units" \
DEF:load=sysinfo.rrd:load:AVERAGE \
DEF:temp=sysinfo.rrd:temperature:AVERAGE \
LINE1:load#0000FF:"System Load" \
LINE3:temp#FF0000:"CPU Temperature"
Example 6
This final example illustrates the use of different round-robin archives (RRAs) within a graph definition. In this case, the different RRAs use a different consolidation function (CF) in order to record different aspects of the data patterns. Specifying the MIN and MAX consolidation functions in the DEFs allow us to retrieve and plot the min and max temperature readings.
rrdtool graph "Example 6.png" \
--start="end-30 days" --end "Dec 31, 2009" \
--imgformat PNG --width 500 --height 120 \
--title "Example 6" \
--vertical-label "Celsius" \
DEF:mintemp=sysinfo.rrd:temperature:MIN \
DEF:maxtemp=sysinfo.rrd:temperature:MAX \
LINE1:mintemp#0000FF:"Minimum Temperature" \
LINE1:maxtemp#FF0000:"Maximum Temperature"
