Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RRDGRAPH(1)			    rrdtool			   RRDGRAPH(1)

       rrdgraph	- Round	Robin Database tool grapher functions

       rrdtool graph filename [option ...]  [data definition ...]  [data cal-
       culation	...]  [variable	definition ...]	 [graph	element	...]  [print
       element ...]

       The graph function of RRDtool is	used to	present	the data from an RRD
       to a human viewer.  Its main purpose is to create a nice	graphical rep-
       resentation, but	it can also generate a numerical report.

       rrdtool graph needs data	to work	with, so you must use one or more data
       definition statements to	collect	this data.  You	are not	limited	to one
       database, it's perfectly	legal to collect data from two or more data-
       bases (one per statement, though).

       If you want to display averages,	maxima,	percentiles, etcetera it is
       best to collect them now	using the variable definition statement.  Cur-
       rently this makes no difference,	but in a future	version	of rrdtool you
       may want	to collect these values	before consolidation.

       The data	fetched	from the RRA is	then consolidated so that there	is ex-
       actly one datapoint per pixel in	the graph. If you do not take care
       yourself, RRDtool will expand the range slightly	if necessary. Note, in
       that case the first and/or last pixel may very well become unknown!

       Sometimes data is not exactly in	the format you would like to display
       it. For instance, you might be collecting bytes per second, but want to
       display bits per	second.	This is	what the data calculation command is
       designed	for. After consolidating the data, a copy is made and this
       copy is modified	using a	rather powerful	rrdgraph_rpn command set.

       When you	are done fetching and processing the data, it is time to graph
       it (or print it).  This ends the	rrdtool	graph sequence.

	   The name and	path of	the graph to generate. It is recommended to
	   end this in ".png", ".svg" or ".eps", but RRDtool does not enforce

	   filename can	be '"-"' to send the image to "stdout".	In this	case,
	   no other output is generated.

       Time range
	   [-s|--start time] [-e|--end time] [-S|--step	seconds]

	   The start and end of	the time series	you would like to display, and
	   which RRA the data should come from.	 Defaults are: 1 day ago until
	   now,	with the best possible resolution. Start and end can be	speci-
	   fied	in several formats, see	rrdfetch and rrdgraph_examples.	By de-
	   fault, rrdtool graph	calculates the width of	one pixel in the time
	   domain and tries to get data	from an	RRA with that resolution.
	   With	the step option	you can	alter this behaviour. If you want rrd-
	   tool	graph to get data at a one-hour	resolution from	the RRD, set
	   step	to 3'600. Note:	a step smaller than one	pixel will silently be

	   [-t|--title string] [-v|--vertical-label string]

	   A horizontal	string at the top of the graph and/or a	vertically
	   placed string at the	left hand side of the graph.

       Right Axis
	   [--right-axis scale:shift] [--right-axis-label label]

	   A second axis will be drawn to the right of the graph. It is	tied
	   to the left axis via	the scale and shift parameters.	You can	also
	   define a label for the right	axis.

	   [--right-axis-format	format-string]

	   By default the format of the	axis lables gets determined automati-
	   cally. If you want todo this	your self, use this option with	the
	   same	%lf arguments you know from the	PRING and GPRINT commands.

	   [-w|--width pixels] [-h|--height pixels] [-j|--only-graph]

	   The width and height	of the canvas (the part	of the graph with the
	   actual data and such). This defaults	to 400 pixels by 100 pixels.

	   If you specify the --only-graph option and set the height < 32 pix-
	   els you will	get a tiny graph image (thumbnail) to use as an	icon
	   for use in an overview, for example.	All labeling will be stripped
	   off the graph.

	   [-u|--upper-limit value] [-l|--lower-limit value] [-r|--rigid]

	   By default the graph	will be	autoscaling so that it will adjust the
	   y-axis to the range of the data. You	can change this	behaviour by
	   explicitly setting the limits. The displayed	y-axis will then range
	   at least from lower-limit to	upper-limit. Autoscaling will still
	   permit those	boundaries to be stretched unless the rigid option is


	   Sometimes the default algorithm for selecting the y-axis scale is
	   not satisfactory. Normally the scale	is selected from a predefined
	   set of ranges and this fails	miserably when you need	to graph some-
	   thing like "260 + 0.001 * sin(x)". This option calculates the mini-
	   mum and maximum y-axis from the actual minimum and maximum data
	   values. Our example would display slightly less than	"260-0.001" to
	   slightly more than "260+0.001" (this	feature	was contributed	by
	   Sasha Mikheev).


	   Where "--alt-autoscale" will	modify both the	absolute maximum AND
	   minimum values, this	option will only affect	the minimum value. The
	   maximum value, if not defined on the	command	line, will be 0. This
	   option can be useful	when graphing router traffic when the WAN line
	   uses	compression, and thus the throughput may be higher than	the
	   WAN line speed.


	   Where "--alt-autoscale" will	modify both the	absolute maximum AND
	   minimum values, this	option will only affect	the maximum value. The
	   minimum value, if not defined on the	command	line, will be 0. This
	   option can be useful	when graphing router traffic when the WAN line
	   uses	compression, and thus the throughput may be higher than	the
	   WAN line speed.


	   In order to avoid anti-aliasing effects gridlines are placed	on in-
	   teger pixel values. This is by default done by extending the	scale
	   so that gridlines happens to	be spaced using	an integer number of
	   pixels and also start on an integer pixel value.  This might	extend
	   the scale too much for some logarithmic scales and for linear
	   scales where	--alt-autoscale	is needed.  Using --no-gridfit dis-
	   ables modification of the scale.

	   [-x|--x-grid	GTM:GST:MTM:MST:LTM:LST:LPR:LFM]

	   [-x|--x-grid	none]

	   The x-axis label is quite complex to	configure. If you don't	have
	   very	special	needs it is probably best to rely on the autoconfigu-
	   ration to get this right. You can specify the string	"none" to sup-
	   press the grid and labels altogether.

	   The grid is defined by specifying a certain amount of time in the
	   ?TM positions. You can choose from "SECOND",	"MINUTE", "HOUR",
	   "DAY", "WEEK", "MONTH" or "YEAR". Then you define how many of these
	   should pass between each line or label.  This pair (?TM:?ST)	needs
	   to be specified for the base	grid (G??), the	major grid (M??) and
	   the labels (L??). For the labels you	also must define a precision
	   in LPR and a	strftime format	string in LFM.	LPR defines where each
	   label will be placed. If it is zero,	the label will be placed right
	   under the corresponding line	(useful	for hours, dates etcetera).
	   If you specify a number of seconds here the label is	centered on
	   this	interval (useful for Monday, January etcetera).

	    --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X

	   This	places grid lines every	10 minutes, major grid lines every
	   hour, and labels every 4 hours. The labels are placed under the ma-
	   jor grid lines as they specify exactly that time.

	    --x-grid HOUR:8:DAY:1:DAY:1:86400:%A

	   This	places grid lines every	8 hours, major grid lines and labels
	   each	day. The labels	are placed exactly between two major grid
	   lines as they specify the complete day and not just midnight.

	   [-y|--y-grid	grid step:label	factor]

	   [-y|--y-grid	none]

	   Y-axis grid lines appear at each grid step interval.	 Labels	are
	   placed every	label factor lines.  You can specify "-y none" to sup-
	   press the grid and labels altogether.  The default for this option
	   is to automatically select sensible values.

	   If you have set --y-grid to 'none' not only the labels get su-
	   pressed, also the space reserved for	the labels is removed. You can
	   still add space manually if you use the --units-length command to
	   explicitly reserve space.


	   Place the Y grid dynamically	based on the graph's Y range. The al-
	   gorithm ensures that	you always have	a grid,	that there are enough
	   but not too many grid lines,	and that the grid is metric. That is
	   the grid lines are placed every 1, 2, 5 or 10 units.	This parameter
	   will	also ensure that you get enough	decimals displayed even	if
	   your	graph goes from	69.998 to 70.001.  (contributed	by Sasha


	   Logarithmic y-axis scaling.

	   [-X|--units-exponent	value]

	   This	sets the 10**exponent scaling of the y-axis values. Normally,
	   values will be scaled to the	appropriate units (k, M, etc.).	 How-
	   ever, you may wish to display units always in k (Kilo, 10e3)	even
	   if the data is in the M (Mega, 10e6)	range, for instance. Value
	   should be an	integer	which is a multiple of 3 between -18 and 18
	   inclusively.	 It is the exponent on the units you wish to use. For
	   example, use	3 to display the y-axis	values in k (Kilo, 10e3, thou-
	   sands), use -6 to display the y-axis	values in u (Micro, 10e-6,
	   millionths).	 Use a value of	0 to prevent any scaling of the	y-axis

	   This	option is very effective at confusing the heck out of the de-
	   fault rrdtool autoscaler and	grid painter. If rrdtool detects that
	   it is not successful	in labeling the	graph under the	given circum-
	   stances, it will switch to the more robust --alt-y-grid mode.

	   [-L|--units-length value]

	   How many digits should rrdtool assume the y-axis labels to be? You
	   may have to use this	option to make enough space once you start fi-
	   deling with the y-axis labeling.


	   With	this option y-axis values on logarithmic graphs	will be	scaled
	   to the appropriate units (k,	M, etc.) instead of using exponential
	   notation.  Note that	for linear graphs, SI notation is used by de-


	   Only	generate the graph if the current graph	is out of date or not

	   [-f|--imginfo printfstr]

	   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	function 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">'

	   [-c|--color COLORTAG#rrggbb[aa]]

	   Override the	default	colors for the standard	elements of the	graph.
	   The COLORTAG	is one of "BACK" background, "CANVAS" for the back-
	   ground of the actual	graph, "SHADEA"	for the	left and top border,
	   "SHADEB" for	the right and bottom border, "GRID", "MGRID" for the
	   major grid, "FONT" for the color of the font, "AXIS"	for the	axis
	   of the graph, "FRAME" for the line around the color spots and fi-
	   nally "ARROW" for the arrow head pointing up	and forward. Each
	   color is composed out of three hexadecimal numbers specifying its
	   rgb color component (00 is off, FF is maximum) of red, green	and
	   blue. Optionally you	may add	another	hexadecimal number specifying
	   the transparency (FF	is solid). You may set this option several
	   times to alter multiple defaults.

	   A green arrow is made by: "--color ARROW#00FF00"

	   [--zoom factor]

	   Zoom	the graphics by	the given amount. The factor must be > 0

	   [-n|--font FONTTAG:size:[font]]

	   This	lets you customize which font to use for the various text ele-
	   ments on the	RRD graphs. "DEFAULT" sets the default value for all
	   elements, "TITLE" for the title, "AXIS" for the axis	labels,	"UNIT"
	   for the vertical unit label,	"LEGEND" for the graph legend.

	   Use Times for the title: "--font TITLE:13:/usr/lib/fonts/times.ttf"

	   If you do not give a	font string you	can modify just	the sice of
	   the default font: "--font TITLE:13:".

	   If you specify the size 0 then you can modify just the font without
	   touching the	size. This is especially usefull for altering the de-
	   fault font without resetting	the default fontsizes: "--font DE-

	   RRDtool comes with a	preset default font. You can set the environ-
	   ment	variable "RRD_DEFAULT_FONT" if you want	to change this.

	   Truetype fonts are only supported for PNG output. See below.

	   [-R|--font-render-mode {normal,light,mono}]

	   This	lets you customize the strength	of the font smoothing, or dis-
	   able	it entirely using mono.	By default, normal font	smoothing is

	   [-B|--font-smoothing-threshold size]

	   This	specifies the largest font size	which will be rendered
	   bitmapped, that is, without any font	smoothing. By default, no text
	   is rendered bitmapped.


	   RRDtool graphs are composed of stair	case curves by default.	This
	   is in line with the way RRDtool calculates its data.	Some people
	   favor a more	'organic' look for their graphs	even though it is not
	   all that true.

	   [-a|--imgformat PNG|SVG|EPS|PDF]

	   Image format	for the	generated graph. For the vector	formats	you
	   can choose among the	standard Postscript fonts Courier-Bold,
	   Courier-BoldOblique,	Courier-Oblique, Courier, Helvetica-Bold, Hel-
	   vetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
	   Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and	ZapfD-


	   If images are interlaced they become	visible	on browsers more


	   Suppress generation of the legend; only render the graph.


	   Force the generation	of HRULE and VRULE legends even	if those HRULE
	   or VRULE will not be	drawn because out of graph boundaries (mimics
	   behaviour of	pre 1.0.42 versions).

	   [-T|--tabwidth value]

	   By default the tab-width is 40 pixels, use this option to change

	   [-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 mea-
	   surement, 1 kb/s is 1000 b/s.

	   [-W|--watermark string]

	   Adds	the given string as a watermark, horizontally centred, at the
	   bottom of the graph.

       Data and	variables

	   CDEF:vname=RPN expression

	   VDEF:vname=RPN expression

	   You need at least one DEF statement to generate anything. The other
	   statements are useful but optional.	See rrdgraph_data and rrd-
	   graph_rpn for the exact format.

       Graph and print elements
	   You need at least one graph element to generate an image and/or at
	   least one print statement to	generate a report.  See	rrdgraph_graph
	   for the exact format.

       rrdgraph	gives an overview of how rrdtool graph works.  rrdgraph_data
       describes DEF,CDEF and VDEF in detail.  rrdgraph_rpn describes the RPN
       language	used in	the ?DEF statements.  rrdgraph_graph page describes
       all of the graph	and print functions.

       Make sure to read rrdgraph_examples for tips&tricks.

       Program by Tobias Oetiker <>

       This manual page	by Alex	van den	Bogaerdt <>

1.2.30				  2009-01-19			   RRDGRAPH(1)


Want to link to this manual page? Use this URL:

home | help