.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "RRDGRAPH 1"
.TH RRDGRAPH 1 "2022-04-14" "1.0.50" "RRDtool"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
rrdgraph \- Create a graph based on data from one or several RRD
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBgraph\fR \fIfilename\fR
[\fB\-s\fR|\fB\-\-start\fR\ \fIseconds\fR]
[\fB\-e\fR|\fB\-\-end\fR\ \fIseconds\fR]
[\fB\-x\fR|\fB\-\-x\-grid\fR\ \fIx\-axis\ grid\ and\ label\fR]
[\fB\-y\fR|\fB\-\-y\-grid\fR\ \fIy\-axis\ grid\ and\ label\fR]
[\fB\-Y\fR|\fB\-\-alt\-y\-grid\fR]
[\fB\-R\fR|\fB\-\-alt\-y\-mrtg\fR]
[\fB\-A\fR|\fB\-\-alt\-autoscale\fR]
[\fB\-M\fR|\fB\-\-alt\-autoscale\-max\fR]
[\fB\-N\fR|\fB\-\-no\-minor\fR]
[\fB\-X\fR|\fB\-\-units\-exponent\fR] \fIvalue\fR]>
[\fB\-L\fR|\fB\-\-units\-length\fR] \fIvalue\fR]>
[\fB\-v\fR|\fB\-\-vertical\-label\fR\ \fItext\fR]
[\fB\-w\fR|\fB\-\-width\fR\ \fIpixels\fR]
[\fB\-h\fR|\fB\-\-height\fR\ \fIpixels\fR]
[\fB\-i\fR|\fB\-\-interlaced\fR]
[\fB\-f\fR|\fB\-\-imginfo\fR\ \fIformatstring\fR]
[\fB\-a\fR|\fB\-\-imgformat\fR\ \fB\s-1GIF\s0\fR|\fB\s-1PNG\s0\fR|\fB\s-1GD\s0\fR]
[\fB\-B\fR|\fB\-\-background\fR\ \fIvalue\fR]
[\fB\-O\fR|\fB\-\-overlay\fR\ \fIvalue\fR]
[\fB\-U\fR|\fB\-\-unit\fR\ \fIvalue\fR]
[\fB\-z\fR|\fB\-\-lazy\fR]
[\fB\-o\fR|\fB\-\-logarithmic\fR]
[\fB\-u\fR|\fB\-\-upper\-limit\fR\ \fIvalue\fR]
[\fB\-l\fR|\fB\-\-lower\-limit\fR\ \fIvalue\fR]
[\fB\-g\fR|\fB\-\-no\-legend\fR]
[\fB\-j\fR|\fB\-\-only\-graph\fR]
[\fB\-F\fR|\fB\-\-force\-rules\-legend\fR]
[\fB\-r\fR|\fB\-\-rigid\fR]
[\fB\-S\fR|\fB\-\-step\fR\ \fIvalue\fR]
[\fB\-b\fR|\fB\-\-base\fR\ \fIvalue\fR]
[\fB\-c\fR|\fB\-\-color\fR\ \fI\s-1COLORTAG\s0\fR\fB#\fR\fIrrggbb\fR]
[\fB\-t\fR|\fB\-\-title\fR\ \fItitle\fR]
[\fB\s-1DEF:\s0\fR\fIvname\fR\fB=\fR\fIrrd\fR\fB:\fR\fIds-name\fR\fB:\fR\fI\s-1CF\s0\fR]
[\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR]
[\fB\s-1PRINT:\s0\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR]
[\fB\s-1GPRINT:\s0\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR]
[\fB\s-1COMMENT:\s0\fR\fItext\fR]
[\fB\s-1HRULE:\s0\fR\fIvalue\fR\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]
[\fB\s-1VRULE:\s0\fR\fItime\fR\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]
[\fB\s-1LINE\s0\fR{\fB1\fR|\fB2\fR|\fB3\fR}\fB:\fR\fIvname\fR[\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]]
[\fB\s-1AREA:\s0\fR\fIvname\fR[\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]]
[\fB\s-1STACK:\s0\fR\fIvname\fR[\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBgraph\fR functions main purpose is to create graphical
representations of the data stored in one or several \fB\s-1RRD\s0\fRs. Apart
from generating graphs, it can also extract numerical reports.
.IP "\fIfilename\fR" 4
.IX Item "filename"
The name of the graph to generate. Since \fBRRDTool\fR outputs
GIFs and PNGs, it's recommended that the filename end in either
\&\fI.gif\fR or \fI.png\fR. \fBRRDTool\fR does not enforce this, however.
If the \fIfilename\fR is set to '\-' the image file will be written
to standard out. All other output will get suppressed.
.Sp
\&\s-1PNG\s0 output is recommended, since it takes up to 40% less disk space
and 20\-30% less time to generate than a \s-1GIF\s0 file.
.Sp
If no graph functions are called, the graph will not be created.
.IP "\fB\-s\fR|\fB\-\-start\fR \fIseconds\fR (default end\-1day)" 4
.IX Item "-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 \s-1TIME SPECIFICATION\s0 section in the \fIrrdfetch\fR
documentation for a detailed explanation on how to specify time.
.IP "\fB\-e\fR|\fB\-\-end\fR \fIseconds\fR (default now)" 4
.IX Item "-e|--end seconds (default now)"
The time when the graph should end. Time in seconds since epoch.
See also AT-STYLE \s-1TIME SPECIFICATION\s0 section in the \fIrrdfetch\fR
documentation for a detailed explanation of ways to specify time.
.IP "\fB\-x\fR|\fB\-\-x\-grid\fR \fIx\-axis grid and label\fR (default autoconfigure)" 4
.IX Item "-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 rely on the autoconfiguration to get this
right.
.Sp
If you want no x\-grid at all, use the magic setting \fBnone\fR.
.Sp
The x\-axis label and grid can be configured, using the following format:
.Sp
\&\fI\s-1GTM\s0\fR\fB:\fR\fI\s-1GST\s0\fR\fB:\fR\fI\s-1MTM\s0\fR\fB:\fR\fI\s-1MST\s0\fR\fB:\fR\fI\s-1LTM\s0\fR:\fI\s-1LST\s0\fR\fB:\fR\fI\s-1LPR\s0\fR\fB:\fR\fI\s-1LFM\s0\fR
.Sp
You have to configure three elements making up the x\-axis labels and
grid. The base grid (\fIG??\fR), the major grid (\fIM??\fR) and the labels
(\fIL??\fR). The configuration is based on the idea that you first
specify a well known amount of time (\fI?TM\fR) and then say how many
times it has to pass between each grid line or label (\fI?ST\fR). For the
label you have to define two additional items: The precision of the
label in seconds (\fI\s-1LPR\s0\fR) and the strftime format used to generate the
text of the label (\fI\s-1LFM\s0\fR).
.Sp
The \fI?TM\fR elements must be one of the following keywords: \fB\s-1SECOND\s0\fR,
\&\fB\s-1MINUTE\s0\fR, \fB\s-1HOUR\s0\fR, \fB\s-1DAY\s0\fR, \fB\s-1WEEK\s0\fR, \fB\s-1MONTH\s0\fR or \fB\s-1YEAR\s0\fR.
.Sp
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.
.Sp
\&\f(CW\*(C`MINUTE:10:HOUR:1:HOUR:1:0:%X\*(C'\fR
.Sp
The precision in this example is 0 because the \f(CW%X\fR 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.
.Sp
If you want to alter the generated text to another language, use the
\&\s-1LC_TIME\s0 environment variable to set the locale you prefer prior to calling
the graph function.
.IP "\fB\-y\fR|\fB\-\-y\-grid\fR \fIgrid step\fR:\fIlabel factor\fR (default autoconfigure)" 4
.IX Item "-y|--y-grid grid step:label factor (default autoconfigure)"
Makes vertical grid lines appear at \fIgrid step\fR interval. Every
\&\fIlabel factor\fR gridstep, a major grid line is printed, along with
label showing the value of the grid line.
.Sp
If you want no y\-grid at all set specify the magic word \fBnone\fR.
.IP "\fB\-Y\fR|\fB\-\-alt\-y\-grid\fR" 4
.IX Item "-Y|--alt-y-grid"
Place Y grid dynamically based on graph Y range. Algorithm ensures
that you always have grid, that there are enough but not too many
grid lines and the grid is metric. That is grid lines are placed
every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev)
.IP "\fB\-\-no\-minor\fR" 4
.IX Item "--no-minor"
Turn off the minor grid lines. This is particularly useful for small
graphs which can be cluttered with the minor grid lines. (contributed
by Travis Brown)
.IP "\fB\-R\fR|\fB\-\-alt\-y\-mrtg\fR" 4
.IX Item "-R|--alt-y-mrtg"
Y grid placed on graph Y range mimics \s-1MRTG\s0's (rateup-generated) graphs.
Currently axis is split into 4 parts, just as rateup does.
.IP "\fB\-A\fR|\fB\-\-alt\-autoscale\fR" 4
.IX Item "-A|--alt-autoscale"
Compute Y range based on function absolute minimum and
maximum values. Default algorithm uses predefined set of ranges.
This is good in many cases but it fails miserably when you need
to graph something like 260 + 0.001 * sin(x). Default algorithm
will use Y range from 250 to 300 and on the graph you will see
almost straight line. With \-\-alt\-autoscale Y range will be
from slightly less the 260 \- 0.001 to slightly more then 260 + 0.001
and periodic behavior will be seen. (contributed by Sasha Mikheev)
.IP "\fB\-M\fR|\fB\-\-alt\-autoscale\-max\fR" 4
.IX Item "-M|--alt-autoscale-max"
Where \-\-alt\-autoscale will modify both the absolute maximum \s-1AND\s0 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 \s-1WAN\s0 line uses compression,
and thus the throughput may be higher than the \s-1WAN\s0 line speed.
.IP "\fB\-X\fR|\fB\-\-units\-exponent\fR \fIvalue\fR (default autoconfigure)" 4
.IX Item "-X|--units-exponent value (default autoconfigure)"
This sets the 10**exponent scaling of the y\-axis values. Normally
values will be scaled to the appropriate units (k, M, etc.). However
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 inclusive. It is
the exponent on the units you which to use. For example, use 3 to
display the y\-axis values in k (Kilo, 10e3, thousands), 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 values.
.IP "\fB\-L\fR|\fB\-\-units\-length\fR \fIvalue\fR (default 9 characters)" 4
.IX Item "-L|--units-length value (default 9 characters)"
This sets the character width on the left side of the graph for y\-axis
values.
.IP "\fB\-v\fR|\fB\-\-vertical\-label\fR \fItext\fR" 4
.IX Item "-v|--vertical-label text"
vertical label on the left side of the graph. This is normally used to
specify the units used.
.IP "\fB\-w\fR|\fB\-\-width\fR \fIpixels\fR (default 400 pixel)" 4
.IX Item "-w|--width pixels (default 400 pixel)"
Width of the drawing area within the graph. This affects the size of the gif.
.IP "\fB\-h\fR|\fB\-\-height\fR \fIpixels\fR (default 100 pixel)" 4
.IX Item "-h|--height pixels (default 100 pixel)"
Height of the drawing area within the graph. This affects the size of the gif.
.IP "\fB\-i\fR|\fB\-\-interlaced\fR (default: false)" 4
.IX Item "-i|--interlaced (default: false)"
If you set this option, then the resulting \s-1GIF\s0 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 \s-1GIF\s0 on disk. It makes no changes to the layout or contents
of the graph.
.IP "\fB\-f\fR|\fB\-\-imginfo\fR \fIformatstring\fR" 4
.IX Item "-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 \s-1PRINT\s0
function, only that the printf is supplied with the parameters
\&\fIfilename\fR, \fIxsize\fR and \fIysize\fR. In order to generate an \fB\s-1IMG\s0\fR tag
suitable for including the graph into a web page, the command line
would look like this:
.Sp
.Vb 1
\& \-\-imginfo \*(Aq
\*(Aq
.Ve
.IP "\fB\-a\fR|\fB\-\-imgformat\fR \fB\s-1GIF\s0\fR|\fB\s-1PNG\s0\fR|\fB\s-1GD\s0\fR (default: \s-1GIF\s0)" 4
.IX Item "-a|--imgformat GIF|PNG|GD (default: GIF)"
Allows you to produce \s-1PNG\s0 or \s-1GD\s0 output from RRDTool.
.IP "\fB\-B\fR|\fB\-\-background\fR \fIvalue\fR" 4
.IX Item "-B|--background value"
You could use image in (currently only) \s-1GD\s0 format for background. It is
used as background at the very beginning of graph creation.
.IP "\fB\-O\fR|\fB\-\-overlay\fR \fIvalue\fR" 4
.IX Item "-O|--overlay value"
You could use image in (currently only) \s-1GD\s0 format as overlay. It is
placed over created graph so that white pixel (color 255,255,255) is
considered transparent, all other is replacing corresponding pixel in created graph.
.IP "\fB\-U\fR|\fB\-\-unit\fR \fIvalue\fR" 4
.IX Item "-U|--unit value"
You could use unit to be displayed on y axis. It is wise to use only short
units on graph, however.
.IP "\fB\-z\fR|\fB\-\-lazy\fR (default: false)" 4
.IX Item "-z|--lazy (default: false)"
Only generate the graph, if the current gif is out of date or not
existent.
.IP "\fB\-u\fR|\fB\-\-upper\-limit\fR \fIvalue\fR (default autoconfigure)" 4
.IX Item "-u|--upper-limit value (default autoconfigure)"
Defines the value normally located at the upper border of the
graph. If the graph contains higher values, the upper border will
move upwards to accommodate these values as well.
.Sp
If you want to define an upper-limit which will not move in any
event you have to set the \fB\-\-rigid\fR option as well.
.IP "\fB\-l\fR|\fB\-\-lower\-limit\fR \fIvalue\fR (default autoconfigure)" 4
.IX Item "-l|--lower-limit value (default autoconfigure)"
This is not the lower limit of a graph. But rather, this is the
maximum lower bound of a graph. For example, the value \-100 will
result in a graph that has a lower limit of \-100 or less. Use this
keyword to expand graphs down.
.IP "\fB\-r\fR|\fB\-\-rigid\fR" 4
.IX Item "-r|--rigid"
rigid boundaries mode. Normally \fBrrdgraph\fR 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
.IP "\fB\-b\fR|\fB\-\-base\fR \fIvalue\fR" 4
.IX Item "-b|--base value"
if you are graphing memory (and \s-1NOT\s0 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.
.IP "\fB\-o\fR|\fB\-\-logarithmic\fR" 4
.IX Item "-o|--logarithmic"
logarithmic y\-axis scaling
.IP "\fB\-c\fR|\fB\-\-color\fR \fI\s-1COLORTAG\s0\fR\fB#\fR\fIrrggbb\fR (default colors)" 4
.IX Item "-c|--color COLORTAG#rrggbb (default colors)"
override the colors for the standard elements of the graph. The \fI\s-1COLORTAG\s0\fR
must be one of the following symbolic names: \fB\s-1BACK\s0\fR ground, \fB\s-1CANVAS\s0\fR,
\&\fB\s-1SHADEA\s0\fR left/top border, \fB\s-1SHADEB\s0\fR right/bottom border, \fB\s-1GRID\s0\fR, \fB\s-1MGRID\s0\fR
major grid, \fB\s-1FONT\s0\fR, \fB\s-1FRAME\s0\fR and axis of the graph or \fB\s-1ARROW\s0\fR. This option
can be called multiple times to set several colors.
.IP "\fB\-g\fR|\fB\-\-no\-legend\fR" 4
.IX Item "-g|--no-legend"
Suppress generation of legend; only render the graph.
.IP "\fB\-j\fR|\fB\-\-only\-graph\fR" 4
.IX Item "-j|--only-graph"
Suppress anything but the graph.
.IP "\fB\-F\fR|\fB\-\-force\-rules\-legend\fR" 4
.IX Item "-F|--force-rules-legend"
Force the generation of \s-1HRULE\s0 and \s-1VRULE\s0 legend even if those \s-1HRULE\s0 or \s-1VRULE\s0 will not be drawn because out of graph boundaries (mimics behaviour of pre 1.0.42 versions).
.IP "\fB\-t\fR|\fB\-\-title\fR \fItext\fR (default no title)" 4
.IX Item "-t|--title text (default no title)"
Define a title to be written into the graph
.IP "\fB\-S\fR|\fB\-\-step\fR \fIvalue\fR (default automatic)" 4
.IX Item "-S|--step value (default automatic)"
By default \fBrrdgraph\fR calculates the width of one pixel in the time domain and
tries to get data at that resolution from the \s-1RRD.\s0 With this switch you can
override this behavior. If you want \fBrrdgraph\fR to get data at 1 hour
resolution from the \s-1RRD,\s0 then you can set the step to 3600 seconds. Note,
that a step smaller than 1 pixel will be silently ignored.
.IP "\fB\s-1DEF:\s0\fR\fIvname\fR\fB=\fR\fIrrd\fR\fB:\fR\fIds-name\fR\fB:\fR\fI\s-1CF\s0\fR" 4
.IX Item "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
\&\s-1DEF\s0 call automatically chooses an \fB\s-1RRA\s0\fR which contains \fI\s-1CF\s0\fR consolidated data in a
resolution appropriate for the size of the graph to be drawn. Ideally
this means that one data point from the \fB\s-1RRA\s0\fR should be represented
by one pixel in the graph. If the resolution of the \fB\s-1RRA\s0\fR is higher
than the resolution of the graph, the data in the \s-1RRA\s0 will be further
consolidated according to the consolidation function (\fI\s-1CF\s0\fR) chosen.
.IP "\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR" 4
.IX Item "CDEF:vname=rpn-expression"
Create a new virtual data source by evaluating a mathematical expression,
specified in Reverse Polish Notation (\s-1RPN\s0). If you have ever used a traditional
\&\s-1HP\s0 calculator you already know \s-1RPN.\s0 The idea behind \s-1RPN\s0 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.
.Sp
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 \fIvname+3/2\fR becomes \f(CW\*(C`vname,3,2,/,+\*(C'\fR in \s-1RPN.\s0 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.
.Sp
The \fIrpn-expression\fR in the \fB\s-1CDEF\s0\fR function takes both, constant values
as well as \fIvname\fR variables. The following operators can be used on these
values:
.RS 4
.IP "+, \-, *, /, %" 4
pops two values from the stack applies the selected operator and pushes
the result back onto the stack. The % operator stands for the modulo
operation.
.IP "\s-1SIN, COS, LOG, EXP, FLOOR, CEIL\s0" 4
.IX Item "SIN, COS, LOG, EXP, FLOOR, CEIL"
pops one value from the stack, applies the selected function and pushes
the result back onto the stack.
.IP "\s-1LT, LE, GT, GE, EQ\s0" 4
.IX Item "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.
.IP "\s-1IF\s0" 4
.IX Item "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.
.Sp
If the stack contains the values A, B, C, D, E are presently on the
stack, the \s-1IF\s0 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.
.IP "\s-1MIN, MAX\s0" 4
.IX Item "MIN, MAX"
selects the lesser or larger of the two top stack values respectively
.IP "\s-1LIMIT\s0" 4
.IX Item "LIMIT"
replaces the value with \fI*UNKNOWN*\fR if it is outside the limits specified
by the two values above it on the stack.
.Sp
.Vb 1
\& CDEF:a=alpha,0,100,LIMIT
.Ve
.IP "\s-1DUP, EXC, POP\s0" 4
.IX Item "DUP, EXC, POP"
These manipulate the stack directly. \s-1DUP\s0 will duplicate the top of the
stack, pushing the result back onto the stack. \s-1EXC\s0 will exchange the top
two elements of the stack, and \s-1POP\s0 will pop off the top element of the
stack. Having insufficient elements on the stack for these operations is
an error.
.IP "\s-1UN\s0" 4
.IX Item "UN"
Pops one value off the stack, if it is \fI*UNKNOWN*\fR, 1 will be pushed
back otherwise 0.
.IP "\s-1UNKN\s0" 4
.IX Item "UNKN"
Push an \fI*UNKNOWN*\fR value onto the stack.
.IP "\s-1PREV\s0" 4
.IX Item "PREV"
Push \fI*UNKNOWN*\fR if its at the first value of a data set or otherwise
the value of this \s-1CDEF\s0 at the previous time step. This allows you to
perform calculations across the data.
.IP "\s-1PREV\s0(vname)" 4
.IX Item "PREV(vname)"
Push \fI*UNKNOWN*\fR if its at the first value of the data set named vname
or otherwise the value of the \s-1CDEF\s0 named vname at the previous time step.
This allows you to perform complex calculations across the data.
.IP "\s-1INF, NEGINF\s0" 4
.IX Item "INF, NEGINF"
Push a positive or negative infinite (oo) value onto the stack. When
drawing an infinite number it appears right at the top or bottom edge of the
graph, depending whether you have a positive or negative infinite number.
.IP "\s-1NOW\s0" 4
.IX Item "NOW"
Push the current (real world) time onto the stack.
.IP "\s-1TIME\s0" 4
.IX Item "TIME"
Push the time the current sample was taken onto the stack. This is the
number of non-skip seconds since 0:00:00 January 1, 1970.
.IP "\s-1LTIME\s0" 4
.IX Item "LTIME"
This is like \s-1TIME\s0 \fB+ current timezone offset in seconds\fR. The current
offset takes daylight saving time into account, given your \s-1OS\s0 supports
this. If you were looking at a sample, in Zurich, in summer, the
offset would be 2*3600 seconds, as Zurich at that time of year is 2
hours ahead of \s-1UTC.\s0
.Sp
Note that the timezone offset is always calculated for the time the
current sample was taken at. It has nothing to do with the time you are
doing the calculation.
.RE
.RS 4
.Sp
Please note that you may only use \fIvname\fR variables that you
previously defined by either \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR. Furthermore, as of
this writing (version 0.99.25), you must use at least one \fIvname\fR
per expression, that is \*(L"CDEF:fourtytwo=2,40,+\*(R" will yield an error
message but not a \fIvname\fR fourtytwo that's always equal to 42.
.RE
.IP "\fB\s-1PRINT:\s0\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR" 4
.IX Item "PRINT:vname:CF:format"
Calculate the chosen consolidation function \fI\s-1CF\s0\fR over the data-source
variable \fIvname\fR and \f(CW\*(C`printf\*(C'\fR the result to stdout using \fIformat\fR.
In the \fIformat\fR string there should be a '%lf', '%lg' or '%le' marker in the
place where the number should be printed.
.Sp
If an additional '%s' is found \s-1AFTER\s0 the marker, the value will be scaled
and an appropriate \s-1SI\s0 magnitude unit will be printed in place of the '%s'
marker. The scaling will take the '\-\-base' argument into consideration!
.Sp
If a '%S' is used instead of a '%s', then instead of calculating the
appropriate \s-1SI\s0 magnitude unit for this value, the previously calculated
\&\s-1SI\s0 magnitude unit will be used. This is useful if you want all the values
in a \s-1PRINT\s0 statement to have the same \s-1SI\s0 magnitude unit. If there was
no previous \s-1SI\s0 magnitude calculation made, then '%S' behaves like a '%s',
unless the value is 0, in which case it does not remember a \s-1SI\s0 magnitude
unit and a \s-1SI\s0 magnitude unit will only be calculated when the next '%s' is
seen or the next '%S' for a non-zero value.
.Sp
If you want to put a '%' into your \s-1PRINT\s0 string, use '%%' instead.
.IP "\fB\s-1GPRINT:\s0\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR" 4
.IX Item "GPRINT:vname:CF:format"
Same as \fB\s-1PRINT\s0\fR but the result is printed into the graph below the legend.
.PP
\&\fBCaveat:\fR When using the \fB\s-1PRINT\s0\fR and \fB\s-1GRPRINT\s0\fR functions to
calculate data summaries over time periods bounded by the current
time, it is important to note that the last sample will almost always
yield a value of \s-1UNKNOWN\s0 as it lies after the last update time. This
can result in slight data skewing, particularly with the \fB\s-1AVERAGE\s0\fR
function. In order to avoid this, make sure that your end time is at
least one heartbeat prior to the current time.
.IP "\fB\s-1COMMENT:\s0\fR\fItext\fR" 4
.IX Item "COMMENT:text"
Like \fB\s-1GPRINT\s0\fR but the \fItext\fR is simply printed into the graph.
.IP "\fB\s-1HRULE:\s0\fR\fIvalue\fR\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]" 4
.IX Item "HRULE:value#rrggbb[:legend]"
Draw a horizontal rule into the graph and optionally add a legend
.IP "\fB\s-1VRULE:\s0\fR\fItime\fR\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]" 4
.IX Item "VRULE:time#rrggbb[:legend]"
Draw a vertical rule into the graph and optionally add a legend
.IP "\fB\s-1LINE\s0\fR{\fB1\fR|\fB2\fR|\fB3\fR}\fB:\fR\fIvname\fR[\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]" 4
.IX Item "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 \fB\s-1LINE1\s0\fR, \fB\s-1LINE2\s0\fR, and \fB\s-1LINE3\s0\fR
generate increasingly wide lines. If no color is defined,
the drawing is done 'blind' this is useful in connection with the
\&\fB\s-1STACK\s0\fR function when you want to \s-1ADD\s0 the values of two
data-sources without showing it in the graph.
.IP "\fB\s-1AREA\s0\fR:\fIvname\fR[\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]" 4
.IX Item "AREA:vname[#rrggbb[:legend]]"
Does the same as \fB\s-1LINE\s0?\fR, but the area between 0 and
the graph will be filled with the color specified.
.IP "\fB\s-1STACK\s0\fR:\fIvname\fR[\fB#\fR\fIrrggbb\fR[\fB:\fR\fIlegend\fR]]" 4
.IX Item "STACK:vname[#rrggbb[:legend]]"
Does the same as \fB\s-1LINE\s0?\fR, but the graph gets stacked on top of the previous
\&\fB\s-1LINE\s0?\fR, \fB\s-1AREA\s0\fR or \fB\s-1STACK\s0\fR graph. Depending on the type of the
previous graph, the \fB\s-1STACK\s0\fR will be either a \fB\s-1LINE\s0?\fR or an \fB\s-1AREA\s0\fR.
This obviously implies that the first \fB\s-1STACK\s0\fR must be preceded by an
\&\fB\s-1AREA\s0\fR or \fB\s-1LINE\s0?\fR \*(-- you need something to stack something onto in
the first place ;)
.Sp
Note, that when you \s-1STACK\s0 onto *UNKNOWN* data, RRDTool will not draw
any graphics ... *UNKNOWN* is not zero ... if you want it to zero
then you might want to use a \s-1CDEF\s0 argument with \s-1IF\s0 and \s-1UN\s0 functions to
turn *UNKNOWN* into zero ...
.SH "NOTES on legend arguments"
.IX Header "NOTES on legend arguments"
.SS "Escaping the colon"
.IX Subsection "Escaping the colon"
In a ':' in a \fIlegend\fR argument will mark the end of the legend. To
enter a ':' into a legend, the colon must be escaped with a backslash '\e:'.
Beware, that many environments look for backslashes themselves, so it may
be necessary to write two backslashes so that one is passed onto \fBrrdgraph\fR.
.SS "String Formatting"
.IX Subsection "String Formatting"
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.
.PP
Valid markers are: \fB\ej\fR for justified, \fB\el\fR for left aligned, \fB\er\fR for
right aligned and \fB\ec\fR for centered. In the next section there is an
example showing how to use centered formating.
.PP
Normally there are two space characters inserted between every two items
printed into the graph. The space following a string can be suppressed by
putting a \fB\eg\fR at the end of the string. The \fB\eg\fR also squashes any space
inside the string if it is at the very end of the string. This can be used
in connection with \fB\f(CB%s\fB\fR to suppress empty unit strings.
.PP
.Vb 1
\& GPRINT:a:MAX:%lf%s\eg
.Ve
.PP
A special case is \s-1COMMENT:\s0\fB\es\fR this inserts some additional vertical space
before placing the next row of legends.
.PP
When text has to be formated without special instructions from your side,
RRDTool will automatically justify the text as soon as one string goes over
the right edge. If you want to prevent the justification without forcing a
newline, you can use the special tag \fB\eJ\fR at the end of the string to
disable the auto justification.
.SH "NOTE on Return Values"
.IX Header "NOTE on Return Values"
Whenever \fBrrdgraph\fR gets called, it prints a line telling the size of
the gif it has just created to \s-1STDOUT.\s0 This line looks like this: XSIZExYSIZE.
.SH "EXAMPLE 1"
.IX Header "EXAMPLE 1"
.Vb 5
\& rrdtool graph demo.gif \-\-title="Demo Graph" \e
\& DEF:cel=demo.rrd:exhaust:AVERAGE \e
\& "CDEF:far=cel,1.8,*,32,+"" \e
\& LINE2:cel#00a000:"D. Celsius" \e
\& LINE2:far#ff0000:"D. Fahrenheit\ec"
.Ve
.SH "EXAMPLE 2"
.IX Header "EXAMPLE 2"
This example demonstrates the syntax for using \s-1IF\s0 and \s-1UN\s0 to set
\&\fI*UNKNOWN*\fR values to 0. This technique is useful if you are
aggregating interface data where the start dates of the data sets
doesn't match.
.PP
.Vb 9
\& rrdtool graph demo.gif \-\-title="Demo Graph" \e
\& DEF:idat1=interface1.rrd:ds0:AVERAGE \e
\& DEF:idat2=interface2.rrd:ds0:AVERAGE \e
\& DEF:odat1=interface1.rrd:ds1:AVERAGE \e
\& DEF:odat2=interface2.rrd:ds1:AVERAGE \e
\& CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \e
\& CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \e
\& AREA:agginput#00cc00:Input Aggregate \e
\& LINE1:aggoutput#0000FF:Output Aggregate
.Ve
.PP
Assuming that idat1 has a data value of \fI*UNKNOWN*\fR, the \s-1CDEF\s0 expression
.PP
.Vb 1
\& idat1,UN,0,idat1,IF
.Ve
.PP
leaves us with a stack with contents of 1,0,NaN and the \s-1IF\s0 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.
.SH "EXAMPLE 3"
.IX Header "EXAMPLE 3"
This example shows two ways to use the \s-1INF\s0 function. First it makes
the background change color during half of the hours. Then, it uses
\&\s-1AREA\s0 and \s-1STACK\s0 to draw a picture. If one of the inputs was \s-1UNKNOWN,\s0
all inputs are overlaid with another \s-1AREA.\s0
.PP
.Vb 10
\& rrdtool graph example.png \-\-title="INF demo" \e
\& DEF:val1=some.rrd:ds0:AVERAGE \e
\& DEF:val2=some.rrd:ds1:AVERAGE \e
\& DEF:val3=some.rrd:ds2:AVERAGE \e
\& DEF:val4=other.rrd:ds0:AVERAGE \e
\& CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \e
\& CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \e
\& AREA:background#F0F0F0 \e
\& AREA:val1#0000FF:Value1 \e
\& STACK:val2#00C000:Value2 \e
\& STACK:val3#FFFF00:Value3 \e
\& STACK:val4#FFC000:Value4 \e
\& AREA:wipeout#FF0000:Unknown
.Ve
.PP
The first \s-1CDEF\s0 uses val4 as a dummy value. It's value is removed immediately
from the stack. Then a decision is made based on the time that a sample was
taken. If it is an even hour (\s-1UTC\s0 time !) then the area will be filled. If
it is not, the value is set to \s-1UNKN\s0 and is not plotted.
.PP
The second \s-1CDEF\s0 looks if any of val1,val2,val3,val4 is unknown. It does so by
checking the outcome of sum(val1,val2,val3,val4). Again, \s-1INF\s0 is returned when
the condition is true, \s-1UNKN\s0 is used to not plot the data.
.PP
The different items are plotted in a particular order. First do the background, then use a
normal area to overlay it with data. Stack the other data until they are all plotted. Last but
not least, overlay everything with eye-hurting red
to signal any unknown data.
.PP
Note that this example assumes that your data is in the positive half of the y\-axis
otherwise you would have to add \s-1NEGINF\s0 in order to extend the coverage
of the rea to whole graph.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
.SH "REFERENCES"
.IX Header "REFERENCES"
[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm