NAME

rrdtool graph - Create a graph based on data from one or several RRD

SYNOPSIS

rrdtool graph filename [-s|--start seconds] [-e|--end seconds] [-x|--x-grid x-axis grid and label] [-y|--y-grid y-axis grid and label] [-v|--vertical-label text] [-w|--width pixels] [-h|--height pixels] [-i|--interlaced] [-o|--logarithmic] [-u|--upper-limit value] [-l|--lower-limit value] [-r|--rigid] [-b|--base value] [-c|--color COLORTAG#rrggbb] [-t|--title title] [DEF:vname=rrd:ds-name:CF] [CDEF:vname=rpn-expression] [PRINT:vname:CF:format] [GPRINT:vname:CF:format] [COMMENT:text] [HRULE:value#rrggbb[:legend]] [VRULE:time#rrggbb[:legend]] [LINE{1|2|3}:vname[#rrggbb[:legend]]] [AREA:vname[#rrggbb[:legend]]] [STACK:vname[#rrggbb[:legend]]]

DESCRIPTION

The graph functions main purpose is to create graphical representations of the data stored in one or several RRDs. Apart from generating graphs, it can also extract numerical reports.

filename

The name of the graph to generate. Since rrdtool outputs GIF's, it's recommended that the filename end in .gif. rrdtool does not enforce this, however.

If no graph functions are called, the graph will not be created.

-s|--start seconds (default -24*3600)

The time when the graph should begin. Time in seconds since epoch (1970-01-01) is required. Negative numbers are relative to the end time. By default one day worth of data will be graphed. See also AT-STYLE TIME SPECIFICATION section in the rrdfetch documentation for alternative ways to specify start time.

-e|--end seconds (default current time)

The time when the graph should end. Time in seconds since epoch. See also AT-STYLE TIME SPECIFICATION section in the rrdfetch documentation for alternative ways to specify end time.

-x|--x-grid x-axis grid and label (default autoconfigure)

The x-axis label is quite complex to configure. So if you don't have very special needs, you can relay on the autoconfiguration to get this right.

The x-axis label is configured, using the following format:

GTM:GST:MTM:MST:LTM:LST:LPR:LFM

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 (?TM) and then say how many times it has to pass between each grid line or label (?ST). For the label you have to define two additional items: The precision of the label in seconds (LPR) and the strftime format used to generate the text of the label (LFM).

The ?TM elements must be one of the following keywords: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH or YEAR.

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-grid grid step:label factor (default autoconfigure)

Makes vertical grid lines appear at grid step interval. Every label factor gridstep, a major grid line is printed, along with label showing the value of the grid line.

-v|--vertical-label text

vertical label on the left side of the graph. This is normally used to specify the units used.

-w|--width pixels (default 400 pixel)

Width of the drawing area within the graph. This affects the size of the gif.

-h|--height pixels (default 100 pixel)

Width of the drawing area within the graph. This affects the size of the gif.

-i|--interlaced (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.

-u|--upper-limit value (default autoconfigure)

The maximum value to be graphed. By default This will be autoconfigured from the data you select with the graphing functions.

-l|--lower-limit value (default autoconfigure)

The minimum value to be graphed. By default This will be autoconfigured from the data you select with the graphing functions.

-r|--rigid

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 r option you can disable this behavior

-b|--base value

if you are graphing memmory (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|--logarithmic

logarithmic y-axis scaling

-c|--color COLORTAG#rrggbb (default colors)

override the colors for the standard elements of the graph. The COLORTAG must be one of the following symbolic names: BACK ground, CANVAS, SHADEA left/top border, SHADEB right/bottom border, GRID, MGRID major grid, FONT, FRAME and axis of the graph or ARROW. This option can be called multiple times to set several colors.

-t|--title text (default no title)

Define a title to be written into the graph

DEF:vname=rrd:ds-name:CF

Define virtual name for a data source. This name can then be used in the functions explained below. The DEF call automatically chooses an RRA which provides data in a resolution appropriate for the size of the graph to be drawn. Ideally this means that one data point from the RRA should be represented by one pixel in the graph. If the resolution of the RRA is higher than the resolution of the graph, the data in the RRA will be consolidated according to the consolidation function (CF) chosen.

CDEF:vname=rpn-expression

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 calculate r you already know RPN. The idea behind RPN notation is, that you have a stack and push your data 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 of a variable it gets pushed automatically.

If this is all a big load of incomprehensible words for you, maybe this example helps: The expression 5+3*2 becomes 5,3,2,*,+ in RPN. First the three numbers get pushed onto the stack, then the * operator pops two values from the stack multiplies them and pushes them back onto the stack. Then the + operator pops again two values from the stack, adds them and pushes the result back onto the stack. In the end there is only one value left on the stack: The result of the expression.

The rpn-expression in the CDEF function takes both, constant values as well as vname 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.
SIN, COS, LOG, EXP: 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.
UN: pops one value of the stack, if it is *UNKNOWN*, 1 will be pushed back otherwise 0.

PRINT:vname:CF:format

Calculate the chosen consolidation function CF over the data-source variable vname and printf the result to stdout using format.

GPRINT:vname:CF:format

Same as PRINT but the result is printed into the graph below the legend.

COMMENT:text

Like GPRINT but the text is simply printed into the graph.

HRULE:value#rrggbb[:legend]

Draw a horizontal rule into the graph and optionally add a legend

VRULE:time#rrggbb[:legend]

Draw a vertical rule into the graph and optionally add a legend

LINE{1|2|3}:vname[#rrggbb[:legend]]

Plot for the requested data, using the color specified. Write a legend into the graph. The 3 possible keywords LINE1, LINE2, and LINE3 generate increasingly wide lines. If no color is defined, the drawing is done 'blind' this is useful in connection with the STACK function when you want to ADD the values of two data-sources without showing it in the graph.

AREA:vname[#rrggbb[:legend]]

Does the same as LINE?, but the area between 0 and the graph will be filled with the color specified.

STACK:vname[#rrggbb[:legend]]

Does the same as LINE?, but the graph gets stacked on top of the previous LINE?, AREA or STACK graph. Depending on the type of the previous graph, the STACK will be either a LINE? or an AREA.

NOTE

In a ':' in a legend 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.

NOTE 2

The text printed below the actual graph can be formated by appending special escaped charactes at the end of a text. When ever such a character occurs, all pending text is pushed onto the grah acording to the character specified.

Valid characters are: j for justified, l for left aligned, r for right aligned and c for centered. In the next section there is an example showing how to use centered formating.

A special case is COMMENT:\s this inserts some additional vertical space before placing the next row of legends.

NOTE 3

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.

EXAMPLE

  rrdtool graph demo.gif --title="Demo Graph" \
          DEF:cel=demo.rrd:exhaust:AVERAGE \
          "CDEF:far=temp,32,-,0.55555,*" \
          LINE2:cel#00a000:"D. Celsius" \
          LINE2:far#ff0000:"D. Fahrenheit\c"

AUTHOR

Tobias Oetiker