rrdtool graph - Create a graph based on data from one or several RRD
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]
[-f|--imginfo formatstring]
[-a|--imgformat GIF|PNG]
[-z|--lazy]
[-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]]]
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 GIFs and PNGs, it's recommended that the filename end in either
.gif or .png. rrdtool does not enforce this, however. If the filename is set to '-' the image file will be written to standard out. All other
output will get suppressed.
PNG output is recommended, since it takes up to 40% less disk space and
20-30% less time to generate than a GIF file.
If no graph functions are called, the graph will not be created.
- -s|--start seconds (default end-1day)
-
The time when the graph should begin. Time in seconds since epoch
(1970-01-01) is required. Negative numbers are relative to the current
time. By default one day worth of data will be graphed. See also AT-STYLE
TIME SPECIFICATION section in the rrdfetch
documentation for a detailed explanation on how to specify time.
- -e|--end seconds (default now)
-
The time when the graph should end. Time in seconds since epoch. See also
AT-STYLE TIME SPECIFICATION section in the rrdfetch
documentation for a detailed explanation of ways to specify 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.
- -f|--imginfo formatstring
-
After the image has been created, the graph function uses printf together
with this format string to create output similar to the PRINT function,
only that the printf is supplied with the parameters
filename, xsize and ysize. In order to generate an IMG tag suitable for including the graph into a web page, the command line
would look like this:
--imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
- -a|--imgformat GIF|PNG (default: GIF)
-
Allows you to produce PNG output from rrdtool.
- -z|--lazy (default: false)
-
Only generate the graph, if the current gif is out of date or not existent.
- -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 memory (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 calculator 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 or a variable, it gets pushed automatically.
If this is all a big load of incomprehensible words for you, maybe an
example helps (a more complete explanation is given in [1]): The expression vname+3/2 becomes vname,3,2,/,+
in RPN. First the three values get pushed onto the stack (which now
contains (the current value of) vname, a 3 and a 2). Then the / operator
pops two values from the stack (3 and 2), divides the first argument by the
second (3/2) and pushes the result (1.5) back onto the stack. Then the +
operator pops two values (vname and 1.5) from the stack; both values are
added up and the result gets pushes 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.
If the stack contains the values A, B, C, D, E are presently on the stack,
the IF operator will pop the values E D and C of the stack. It will look at
C and if it is not 0 it will push D back onto the stack, otherwise E will
be sent back to the stack.
- UN
-
Pops one value of the stack, if it is *UNKNOWN*, 1 will be pushed back otherwise 0.
- UNKN
-
Push an *UNKNOWN* value onto the stack
- NOW
-
Push the current (real world) time onto the stack
- TIME
-
Push the time the current sample was taken onto the stack
Please note that you may only use vname variables that you previously defined by either DEF or CDEF. Furthermore, as of this writing (version 0.99.25), you must use at least
one vname
per expression, that is ``CDEF:fourtytwo=2,40,+'' will yield an error
message but not a vname fourtytwo that's always equal to 42.
- PRINT:vname:CF:format
-
Calculate the chosen consolidation function CF over the data-source variable vname and
printf
the result to stdout using format. In the format string there should be a '%lf' or '%le' marker in the place where the
number should be printed.
If an additional '%s' is found AFTER the marker, the value will be scaled
and an appropriate SI magnitude unit will be printed in place of the '%s'
marker. The scaling will take the '--base' argument into consideration!
If a '%S' is used instead of a '%s', then instead of calculating the
appropriate SI magnitude unit for this value, the previously calculated SI
magnitude unit will be used. This is useful if you want all the values in a
PRINT statement to have the same SI magnitude unit. If there was no
previous SI magnitude calculation made, then '%S' behaves like a '%s',
unless the value is 0, in which case it does not remember a SI magnitude
unit and a SI magnitude unit will only be calculated when the next '%s' is
seen or the next '%S' for a non-zero value.
- 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. This obviously implies that the first STACK must be preceded by an
AREA or LINE? -- you need something to stack something onto in the first place ;)
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.
The text printed below the actual graph can be formated by appending
special escaped characters at the end of a text. When ever such a character
occurs, all pending text is pushed onto the graph according 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.
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.
rrdtool graph demo.gif --title="Demo Graph" \
DEF:cel=demo.rrd:exhaust:AVERAGE \
"CDEF:far=cel,32,-,0.55555,*" \
LINE2:cel#00a000:"D. Celsius" \
LINE2:far#ff0000:"D. Fahrenheit\c"
This example demonstrates the syntax for using IF and UN to set
*UNKNOWN* values to 0. This technique is useful if you are aggregating interface data
where the start dates of the data sets doesn't match.
rrdtool graph demo.gif --title="Demo Graph" \
DEF:idat1=interface1.rrd:ds0:AVERAGE \
DEF:idat2=interface2.rrd:ds0:AVERAGE \
DEF:odat1=interface1.rrd:ds1:AVERAGE \
DEF:odat2=interface2.rrd:ds1:AVERAGE \
CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \
CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \
AREA:agginput#00cc00:Input Aggregate \
LINE1:agginput#0000FF:Output Aggregate
Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression
idat1,UN,0,idat1,IF
leaves us with a stack with contents of 1,0,NaN and the IF function will
pop off the 3 values and replace them with 0. If idat1 had a real value
like 7942099, then the stack would have 0,0,7942099 and the real value
would be the replacement.
Tobias Oetiker
[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm