\&
.Ve
.PP
The resulting data section is:
.PP
.Vb 10
\&
\& 10206117003.4000000000e+005.4400000000e+01
\& 10206120003.4000000000e+005.4400000000e+01
\& 10206123003.4000000000e+005.4400000000e+01
\& 10206126003.4113333333e+005.4581333333e+01
\& 10206129003.4000000000e+005.4400000000e+01
\& 10206132003.4000000000e+005.4400000000e+01
\& 10206135003.4000000000e+005.4400000000e+01
\& 10206138003.4000000000e+005.4400000000e+01
\& 10206141003.4000000000e+005.4400000000e+01
\& 10206144003.4000000000e+005.4400000000e+01
\& 10206147003.7333333333e+005.9733333333e+01
\& 10206150003.4000000000e+005.4400000000e+01
\& 10206153003.4000000000e+005.4400000000e+01
\& 1020615600NaNNaN
\&
.Ve
.SH "EXAMPLE 1"
.IX Header "EXAMPLE 1"
.Vb 3
\& rrdtool xport \e
\& DEF:out=if1\-inouts.rrd:outoctets:AVERAGE \e
\& XPORT:out:"out bytes"
.Ve
.SH "EXAMPLE 2"
.IX Header "EXAMPLE 2"
.Vb 7
\& rrdtool xport \e
\& DEF:out1=if1\-inouts.rrd:outoctets:AVERAGE \e
\& DEF:out2=if2\-inouts.rrd:outoctets:AVERAGE \e
\& CDEF:sum=out1,out2,+ \e
\& XPORT:out1:"if1 out bytes" \e
\& XPORT:out2:"if2 out bytes" \e
\& XPORT:sum:"output sum"
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ xport\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
0707010004751e000081a40000000000000000000000015295523500002b0a0000011f00010018ffffffffffffffff0000002a00000000root/usr/local/share/man/man1/rrdupdate.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDUPDATE 1"
.TH RRDUPDATE 1 "2009-06-02" "1.4.4" "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"
rrdupdate \- Store a new set of values into the RRD
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR {\fBupdate\fR | \fBupdatev\fR} \fIfilename\fR
[\fB\-\-template\fR|\fB\-t\fR\ \fIds-name\fR[\fB:\fR\fIds-name\fR]...]
[\fB\-\-daemon\fR\ \fIaddress\fR] [\fB\-\-\fR]
\&\fBN\fR|\fItimestamp\fR\fB:\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]
\&\fIat-timestamp\fR\fB@\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]
[\fItimestamp\fR\fB:\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]\ ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBupdate\fR function feeds new data values into an \fB\s-1RRD\s0\fR. The data
is time aligned (interpolated) according to the properties of the
\&\fB\s-1RRD\s0\fR to which the data is written.
.IP "\fBupdatev\fR" 8
.IX Item "updatev"
This alternate version of \fBupdate\fR takes the same arguments and
performs the same function. The \fIv\fR stands for \fIverbose\fR, which
describes the output returned. \fBupdatev\fR returns a list of any and all
consolidated data points (CDPs) written to disk as a result of the
invocation of update. The values are indexed by timestamp (time_t),
\&\s-1RRA\s0 (consolidation function and PDPs per \s-1CDP\s0), and data source (name).
Note that depending on the arguments of the current and previous call to
update, the list may have no entries or a large number of entries.
.Sp
Since \fBupdatev\fR requires direct disk access, the \fB\-\-daemon\fR option cannot be
used with this command.
.IP "\fIfilename\fR" 8
.IX Item "filename"
The name of the \fB\s-1RRD\s0\fR you want to update.
.IP "\fB\-\-template\fR|\fB\-t\fR \fIds-name\fR[\fB:\fR\fIds-name\fR]..." 8
.IX Item "--template|-t ds-name[:ds-name]..."
By default, the \fBupdate\fR function expects its data input in the order
the data sources are defined in the \s-1RRD\s0, excluding any \s-1COMPUTE\s0 data
sources (i.e. if the third data source \fB\s-1DST\s0\fR is \s-1COMPUTE\s0, the third
input value will be mapped to the fourth data source in the \fB\s-1RRD\s0\fR and
so on). This is not very error resistant, as you might be sending the
wrong data into an \s-1RRD\s0.
.Sp
The template switch allows you to specify which data sources you are
going to update and in which order. If the data sources specified in
the template are not available in the \s-1RRD\s0 file, the update process
will abort with an error message.
.Sp
While it appears possible with the template switch to update data sources
asynchronously, \fBRRDtool\fR implicitly assigns non-COMPUTE data sources missing
from the template the \fI*UNKNOWN*\fR value.
.Sp
Do not specify a value for a \s-1COMPUTE\s0 \fB\s-1DST\s0\fR in the \fBupdate\fR
function. If this is done accidentally (and this can only be done
using the template switch), \fBRRDtool\fR will ignore the value specified
for the \s-1COMPUTE\s0 \fB\s-1DST\s0\fR.
.IP "\fB\-\-daemon\fR \fIaddress\fR" 8
.IX Item "--daemon address"
If given, \fBRRDTool\fR will try to connect to the caching daemon rrdcached
at \fIaddress\fR and will fail if the connection cannot be established. If the
connection is successfully established the values will be sent to the daemon
instead of accessing the files directly.
.Sp
For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
.IP "\fBN\fR|\fItimestamp\fR\fB:\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]" 8
.IX Item "N|timestamp:value[:value...]"
The data used for updating the \s-1RRD\s0 was acquired at a certain
time. This time can either be defined in seconds since 1970\-01\-01 or
by using the letter 'N', in which case the update time is set to be
the current time. Negative time values are subtracted from the current
time. An \s-1AT_STYLE\s0 \s-1TIME\s0 \s-1SPECIFICATION\s0 (see the \fIrrdfetch\fR
documentation) may also be used by delimiting the end of the time
specification with the '@' character instead of a ':'. Getting the
timing right to the second is especially important when you are
working with data-sources of type \fB\s-1COUNTER\s0\fR, \fB\s-1DERIVE\s0\fR or
\&\fB\s-1ABSOLUTE\s0\fR.
.Sp
When using negative time values, options and data have to be separated
by two dashes (\fB\-\-\fR), else the time value would be parsed as an option.
See below for an example.
.Sp
When using negative time values, options and data have to be separated
by two dashes (\fB\-\-\fR), else the time value would be parsed as an option.
See below for an example.
.Sp
The remaining elements of the argument are \s-1DS\s0 updates. The order of
this list is the same as the order the data sources were defined in
the \s-1RRA\s0. If there is no data for a certain data-source, the letter
\&\fBU\fR (e.g., N:0.1:U:1) can be specified.
.Sp
The format of the value acquired from the data source is dependent on
the data source type chosen. Normally it will be numeric, but the data
acquisition modules may impose their very own parsing of this
parameter as long as the colon (\fB:\fR) remains the data source value
separator.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ update\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.IP "\(bu" 4
\&\f(CW\*(C`rrdtool update demo1.rrd N:3.44:3.15:U:23\*(C'\fR
.Sp
Update the database file demo1.rrd with 3 known and one \fI*UNKNOWN*\fR
value. Use the current time as the update time.
.IP "\(bu" 4
\&\f(CW\*(C`rrdtool update demo2.rrd 887457267:U 887457521:22 887457903:2.7\*(C'\fR
.Sp
Update the database file demo2.rrd which expects data from a single
data-source, three times. First with an \fI*UNKNOWN*\fR value then with two
regular readings. The update interval seems to be around 300 seconds.
.IP "\(bu" 4
\&\f(CW\*(C`rrdtool update demo3.rrd \-\- \-5:21 N:42\*(C'\fR
.Sp
Update the database file demo3.rrd two times, using five seconds in the
past and the current time as the update times.
.IP "\(bu" 4
\&\f(CW\*(C`rrdtool update \-\-cache /var/lib/rrd/demo3.rrd N:42\*(C'\fR
.Sp
Update the file \f(CW\*(C`/var/lib/rrd/demo3.rrd\*(C'\fR with a single data source, using the
current time. If the caching daemon cannot be reached, do \fBnot\fR fall back to
direct file access.
.IP "\(bu" 4
\&\f(CW\*(C`rrdtool update \-\-daemon unix:/tmp/rrdd.sock demo4.rrd N:23\*(C'\fR
.Sp
Use the \s-1UNIX\s0 domain socket \f(CW\*(C`/tmp/rrdd.sock\*(C'\fR to contact the caching daemon. If
the caching daemon is not available, update the file \f(CW\*(C`demo4.rrd\*(C'\fR directly.
\&\fB\s-1WARNING:\s0\fR Since a relative path is specified, the following disturbing effect
may occur: If the daemon is available, the file relative to the working
directory \fBof the daemon\fR is used. If the daemon is not available, the file
relative to the current working directory of the invoking process is used.
\&\fBThis may update two different files depending on whether the daemon could be
reached or not.\fR Don't do relative paths, kids!
.SH "AUTHORS"
.IX Header "AUTHORS"
Tobias Oetiker ,
Florian Forster
07070100047512000081a4000000000000000000000001529552350000606d0000011f00010018ffffffffffffffff0000002f00000000root/usr/local/share/man/man1/rrdgraph_graph.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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_GRAPH 1"
.TH RRDGRAPH_GRAPH 1 "2010-01-25" "1.4.4" "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_graph \- rrdtool graph command reference
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
.PP
\&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
.PP
\&\fB\s-1COMMENT\s0\fR\fB:\fR\fItext\fR
.PP
\&\fB\s-1VRULE\s0\fR\fB:\fR\fItime\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
.PP
\&\fB\s-1HRULE\s0\fR\fB:\fR\fIvalue\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
.PP
\&\fB\s-1LINE\s0\fR[\fIwidth\fR]\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
.PP
\&\fB\s-1AREA\s0\fR\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]
.PP
\&\fB\s-1TICK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIrrggbb\fR[\fIaa\fR][\fB:\fR\fIfraction\fR[\fB:\fR\fIlegend\fR]]
.PP
\&\fB\s-1SHIFT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIoffset\fR
.PP
\&\fB\s-1TEXTALIGN\s0\fR\fB:\fR{\fBleft\fR|\fBright\fR|\fBjustified\fR|\fBcenter\fR}
.PP
\&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
.PP
\&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
.PP
\&\fB\s-1STACK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR] (deprecated)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These instructions allow you to generate your image or report.
If you don't use any graph elements, no graph is generated.
Similarly, no report is generated if you don't use print options.
.SS "\s-1PRINT\s0"
.IX Subsection "PRINT"
\fI\f(BI\s-1PRINT:\s0\fI\fIvname\fI\f(BI:\fI\fIformat\fI[\f(BI:strftime\fI]\fR
.IX Subsection "PRINT:vname:format[:strftime]"
.PP
Depending on the context, either the value component or the time
component of a \fB\s-1VDEF\s0\fR is printed using \fIformat\fR. It is an error
to specify a \fIvname\fR generated by a \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR.
.PP
Any text in \fIformat\fR is printed literally with one exception:
The percent character introduces a formatter string. This string
can be:
.PP
For printing values:
.IP "\fB%%\fR" 4
.IX Item "%%"
just prints a literal '%' character
.IP "\fB%#.#le\fR" 4
.IX Item "%#.#le"
prints numbers like 1.2346e+04. The optional integers # denote field
width and decimal precision.
.IP "\fB%#.#lf\fR" 4
.IX Item "%#.#lf"
prints numbers like 12345.6789, with optional field width
and precision.
.ie n .IP "\fB\fB%s\fB\fR" 4
.el .IP "\fB\f(CB%s\fB\fR" 4
.IX Item "%s"
place this after \fB\f(CB%le\fB\fR, \fB\f(CB%lf\fB\fR or \fB\f(CB%lg\fB\fR. This will be replaced by the
appropriate \s-1SI\s0 magnitude unit and the value will be scaled
accordingly (123456 \-> 123.456 k).
.ie n .IP "\fB\fB%S\fB\fR" 4
.el .IP "\fB\f(CB%S\fB\fR" 4
.IX Item "%S"
is similar to \fB\f(CB%s\fB\fR. It does, however, use a previously defined
magnitude unit. If there is no such unit yet, it tries to define
one (just like \fB\f(CB%s\fB\fR) unless the value is zero, in which case the magnitude
unit stays undefined. Thus, formatter strings using \fB\f(CB%S\fB\fR and no \fB\f(CB%s\fB\fR
will all use the same magnitude unit except for zero values.
.PP
If you \s-1PRINT\s0 a \s-1VDEF\s0 value, you can also print the time associated with it by appending the string
\&\fB:strftime\fR to the format. Note that RRDtool uses the strftime function of your OSs C library. This means that
the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
conversion specifiers usually supported across the board.
.ie n .IP "\fB\fB%a\fB\fR" 4
.el .IP "\fB\f(CB%a\fB\fR" 4
.IX Item "%a"
The abbreviated weekday name according to the current locale.
.ie n .IP "\fB\fB%A\fB\fR" 4
.el .IP "\fB\f(CB%A\fB\fR" 4
.IX Item "%A"
The full weekday name according to the current locale.
.ie n .IP "\fB\fB%b\fB\fR" 4
.el .IP "\fB\f(CB%b\fB\fR" 4
.IX Item "%b"
The abbreviated month name according to the current locale.
.ie n .IP "\fB\fB%B\fB\fR" 4
.el .IP "\fB\f(CB%B\fB\fR" 4
.IX Item "%B"
The full month name according to the current locale.
.ie n .IP "\fB\fB%c\fB\fR" 4
.el .IP "\fB\f(CB%c\fB\fR" 4
.IX Item "%c"
The preferred date and time representation for the current locale.
.ie n .IP "\fB\fB%d\fB\fR" 4
.el .IP "\fB\f(CB%d\fB\fR" 4
.IX Item "%d"
The day of the month as a decimal number (range 01 to 31).
.ie n .IP "\fB\fB%H\fB\fR" 4
.el .IP "\fB\f(CB%H\fB\fR" 4
.IX Item "%H"
The hour as a decimal number using a 24\-hour clock (range 00 to 23).
.ie n .IP "\fB\fB%I\fB\fR" 4
.el .IP "\fB\f(CB%I\fB\fR" 4
.IX Item "%I"
The hour as a decimal number using a 12\-hour clock (range 01 to 12).
.ie n .IP "\fB\fB%j\fB\fR" 4
.el .IP "\fB\f(CB%j\fB\fR" 4
.IX Item "%j"
The day of the year as a decimal number (range 001 to 366).
.ie n .IP "\fB\fB%m\fB\fR" 4
.el .IP "\fB\f(CB%m\fB\fR" 4
.IX Item "%m"
The month as a decimal number (range 01 to 12).
.ie n .IP "\fB\fB%M\fB\fR" 4
.el .IP "\fB\f(CB%M\fB\fR" 4
.IX Item "%M"
The minute as a decimal number (range 00 to 59).
.ie n .IP "\fB\fB%p\fB\fR" 4
.el .IP "\fB\f(CB%p\fB\fR" 4
.IX Item "%p"
Either `\s-1AM\s0' or `\s-1PM\s0' according to the given time value, or the corresponding
strings for the current locale. Noon is treated as `pm' and midnight as
`am'. Note that in many locales and `pm' notation is unsupported and in
such cases \f(CW%p\fR will return an empty string.
.ie n .IP "\fB\fB%s\fB\fR" 4
.el .IP "\fB\f(CB%s\fB\fR" 4
.IX Item "%s"
The second as a decimal number (range 00 to 61).
.ie n .IP "\fB\fB%S\fB\fR" 4
.el .IP "\fB\f(CB%S\fB\fR" 4
.IX Item "%S"
The seconds since the epoch (1.1.1970) (libc dependent non standard!)
.ie n .IP "\fB\fB%U\fB\fR" 4
.el .IP "\fB\f(CB%U\fB\fR" 4
.IX Item "%U"
The week number of the current year as a decimal number, range 00 to 53, starting with the
first Sunday as the first day of week 01. See also \f(CW%V\fR and \f(CW%W\fR.
.ie n .IP "\fB\fB%V\fB\fR" 4
.el .IP "\fB\f(CB%V\fB\fR" 4
.IX Item "%V"
The \s-1ISO\s0 8601:1988 week number of the current year as a decimal number, range 01 to 53, where
week 1 is the first week that has at least 4 days in the current year, and with Monday as the
first day of the week. See also \f(CW%U\fR and \f(CW%W\fR.
.ie n .IP "\fB\fB%w\fB\fR" 4
.el .IP "\fB\f(CB%w\fB\fR" 4
.IX Item "%w"
The day of the week as a decimal, range 0 to 6, Sunday being 0. See also \f(CW%u\fR.
.ie n .IP "\fB\fB%W\fB\fR" 4
.el .IP "\fB\f(CB%W\fB\fR" 4
.IX Item "%W"
The week number of the current year as a decimal number, range 00 to 53, starting with the
first Monday as the first day of week 01.
.ie n .IP "\fB\fB%x\fB\fR" 4
.el .IP "\fB\f(CB%x\fB\fR" 4
.IX Item "%x"
The preferred date representation for the current locale without the time.
.ie n .IP "\fB\fB%X\fB\fR" 4
.el .IP "\fB\f(CB%X\fB\fR" 4
.IX Item "%X"
The preferred time representation for the current locale without the date.
.ie n .IP "\fB\fB%y\fB\fR" 4
.el .IP "\fB\f(CB%y\fB\fR" 4
.IX Item "%y"
The year as a decimal number without a century (range 00 to 99).
.ie n .IP "\fB\fB%Y\fB\fR" 4
.el .IP "\fB\f(CB%Y\fB\fR" 4
.IX Item "%Y"
The year as a decimal number including the century.
.ie n .IP "\fB\fB%Z\fB\fR" 4
.el .IP "\fB\f(CB%Z\fB\fR" 4
.IX Item "%Z"
The time zone or name or abbreviation.
.IP "\fB%%\fR" 4
.IX Item "%%"
A literal `%' character.
.PP
\fI\f(BI\s-1PRINT:\s0\fI\fIvname\fI\f(BI:\fI\fI\s-1CF\s0\fI\f(BI:\fI\fIformat\fI\fR
.IX Subsection "PRINT:vname:CF:format"
.PP
\&\fIDeprecated. Use the new form of this command in new scripts.\fR
The first form of this command is to be used with \fB\s-1CDEF\s0\fR \fIvname\fRs.
.SS "\s-1GRAPH\s0"
.IX Subsection "GRAPH"
\fI\f(BI\s-1GPRINT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fIformat\fI\fR
.IX Subsection "GPRINT:vname:format"
.PP
This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
.PP
\fI\f(BI\s-1GPRINT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fI\s-1CF\s0\fI\f(BI:\fI\fIformat\fI\fR
.IX Subsection "GPRINT:vname:CF:format"
.PP
\&\fIDeprecated. Use the new form of this command in new scripts.\fR
This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
.PP
\fI\f(BI\s-1COMMENT\s0\fI\f(BI:\fI\fItext\fI\fR
.IX Subsection "COMMENT:text"
.PP
Text is printed literally in the legend section of the graph. Note that in
RRDtool 1.2 you have to escape colons in \s-1COMMENT\s0 text in the same way you
have to escape them in \fB*PRINT\fR commands by writing \fB'\e:'\fR.
.PP
\fI\f(BI\s-1VRULE\s0\fI\f(BI:\fI\fItime\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
.IX Subsection "VRULE:time#color[:legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
.PP
Draw a vertical line at \fItime\fR. Its color is composed from three
hexadecimal numbers specifying the rgb color components (00 is off, \s-1FF\s0 is
maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
printed in the legend section. \fItime\fR may be a number or a variable
from a \fB\s-1VDEF\s0\fR. It is an error to use \fIvname\fRs from \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR here.
Dashed lines can be drawn using the \fBdashes\fR modifier. See \fB\s-1LINE\s0\fR for more
details.
.PP
\fI\f(BI\s-1HRULE\s0\fI\f(BI:\fI\fIvalue\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
.IX Subsection "HRULE:value#color[:legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
.PP
Draw a horizontal line at \fIvalue\fR. \s-1HRULE\s0 acts much like \s-1LINE\s0 except that
will have no effect on the scale of the graph. If a \s-1HRULE\s0 is outside the
graphing area it will just not be visible.
.PP
\fI\f(BI\s-1LINE\s0\fI[\fIwidth\fI]\f(BI:\fI\fIvalue\fI[\f(BI#\fI\fIcolor\fI][\f(BI:\fI[\fIlegend\fI][\f(BI:STACK\fI]][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
.IX Subsection "LINE[width]:value[#color][:[legend][:STACK]][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
.PP
Draw a line of the specified width onto the graph. \fIwidth\fR can be a
floating point number. If the color is not specified, the drawing is done
\&'invisibly'. This is useful when stacking something else on top of this
line. Also optional is the legend box and string which will be printed in
the legend section if specified. The \fBvalue\fR can be generated by \fB\s-1DEF\s0\fR,
\&\fB\s-1VDEF\s0\fR, and \fB\s-1CDEF\s0\fR. If the optional \fB\s-1STACK\s0\fR modifier is used, this line
is stacked on top of the previous element which can be a \fB\s-1LINE\s0\fR or an
\&\fB\s-1AREA\s0\fR.
.PP
The \fBdashes\fR modifier enables dashed line style. Without any further options
a symmetric dashed line with a segment length of 5 pixels will be drawn. The
dash pattern can be changed if the \fBdashes=\fR parameter is followed by either
one value or an even number (1, 2, 4, 6, ...) of positive values. Each value
provides the length of alternate \fIon_s\fR and \fIoff_s\fR portions of the
stroke. The \fBdash-offset\fR parameter specifies an \fIoffset\fR into the pattern
at which the stroke begins.
.PP
When you do not specify a color, you cannot specify a legend. Should
you want to use \s-1STACK\s0, use the \*(L"LINEx:::STACK\*(R" form.
.PP
\fI\f(BI\s-1AREA\s0\fI\f(BI:\fI\fIvalue\fI[\f(BI#\fI\fIcolor\fI][\f(BI:\fI[\fIlegend\fI][\f(BI:STACK\fI]]\fR
.IX Subsection "AREA:value[#color][:[legend][:STACK]]"
.PP
See \fB\s-1LINE\s0\fR, however the area between the x\-axis and the line will
be filled.
.PP
\fI\f(BI\s-1TICK\s0\fI\f(BI:\fI\fIvname\fI\f(BI#\fI\fIrrggbb\fI[\fIaa\fI][\f(BI:\fI\fIfraction\fI[\f(BI:\fI\fIlegend\fI]]\fR
.IX Subsection "TICK:vname#rrggbb[aa][:fraction[:legend]]"
.PP
Plot a tick mark (a vertical line) for each value of \fIvname\fR that is
non-zero and not *UNKNOWN*. The \fIfraction\fR argument specifies the length of
the tick mark as a fraction of the y\-axis; the default value is 0.1 (10% of
the axis). Note that the color specification is not optional. The \s-1TICK\s0 marks normally
start at the lower edge of the graphing area. If the fraction is negative they start
at the upper border of the graphing area.
.PP
\fI\f(BI\s-1SHIFT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fIoffset\fI\fR
.IX Subsection "SHIFT:vname:offset"
.PP
Using this command \fBRRDtool\fR will graph the following elements
with the specified offset. For instance, you can specify an
offset of (\ 7*24*60*60\ =\ )\ 604'800\ seconds to \*(L"look back\*(R" one
week. Make sure to tell the viewer of your graph you did this ...
As with the other graphing elements, you can specify a number or
a variable here.
.PP
\fI\f(BI\s-1TEXTALIGN\s0\fI\f(BI:\fI{\f(BIleft\fI|\f(BIright\fI|\f(BIjustified\fI|\f(BIcenter\fI}\fR
.IX Subsection "TEXTALIGN:{left|right|justified|center}"
.PP
Labels are placed below the graph. When they overflow to the left, they wrap
to the next line. By default, lines are justified left and right. The
\&\fB\s-1TEXTALIGN\s0\fR function lets you change this default. This is a command and
not an option, so that you can change the default several times in your
argument list.
.PP
\fI\f(BI\s-1STACK\s0\fI\f(BI:\fI\fIvname\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI]\fR
.IX Subsection "STACK:vname#color[:legend]"
.PP
\&\fIDeprecated. Use the \f(BI\s-1STACK\s0\fI modifiers on the other commands instead!\fR
.PP
\&\fBSome notes on stacking\fR
.PP
When stacking, an element is not placed above the X\-axis but rather
on top of the previous element. There must be something to stack
upon.
.PP
You can use an \fBinvisible\fR \s-1LINE\s0 or \s-1AREA\s0 to stacked upon.
.PP
An \fBunknown\fR value makes the entire stack unknown from that moment on.
You don't know where to begin (the unknown value) and therefore do
not know where to end.
.PP
If you want to make sure you will be displaying a certain variable,
make sure never to stack upon the unknown value. Use a \s-1CDEF\s0 instruction
with \fB\s-1IF\s0\fR and \fB\s-1UN\s0\fR to do so.
.SH "NOTES on legend arguments"
.IX Header "NOTES on legend arguments"
.SS "Escaping the colon"
.IX Subsection "Escaping the colon"
A colon ':' in a \fIlegend\fR argument will mark the end of the
legend. To enter a ':' as part of a legend, the colon must be escaped
with a backslash '\e:'. Beware that many environments process
backslashes themselves, so it may be necessary to write two
backslashes in order to one being passed onto rrd_graph.
.SS "String Formatting"
.IX Subsection "String Formatting"
The text printed below the actual graph can be formatted by appending special
escape 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 formatting.
.PP
\&\fB\en\fR is a valid alias for \fB\el\fR since incomplete parsing in earlier
versions of RRDtool lead to this behavior and a number of people has been using it.
.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 ignores 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 which inserts some additional vertical space
before placing the next row of legends.
.PP
If you want to have left and right aligned legends on the same line use \s-1COMMENT:\s0\fB\eu\fR
to go one line back like this:
.PP
.Vb 3
\& COMMENT:left\el
\& COMMENT:\eu
\& COMMENT:right\er
.Ve
.PP
When using a proportional font in your graph, the tab
characters or the sequence \fB\et\fR will line-up legend elements. Note that
the tabs inserted are relative to the start of the current legend
element!
.PP
Since RRDtool 1.3 is using Pango for rending text, you can use Pango markup.
Pango uses the xml \fBspan\fR tags for inline formatting instructions.:
.PP
A simple example of a marked-up string might be:
.PP
.Vb 1
\& Blue text is cool!
.Ve
.PP
The complete list of attributes for the span tag (taken from the pango documentation):
.IP "\fBfont_desc\fR" 4
.IX Item "font_desc"
A font description string, such as \*(L"Sans Italic 12\*(R"; note that any other span attributes will override this description. So if you have \*(L"Sans Italic\*(R" and also a style=\*(L"normal\*(R" attribute, you will get Sans normal, not italic.
.IP "\fBfont_family\fR" 4
.IX Item "font_family"
A font family name
.IP "\fBface\fR" 4
.IX Item "face"
Synonym for font_family
.IP "\fBsize\fR" 4
.IX Item "size"
Font size in 1024ths of a point, or one of the absolute sizes 'xx\-small', 'x\-small', 'small', 'medium', 'large', 'x\-large', 'xx\-large', or one of the relative sizes 'smaller' or 'larger'. If you want to specify a absolute size, it's usually easier to take advantage of the ability to specify a partial font description using 'font_desc'; you can use font_desc='12.5' rather than size='12800'.
.IP "\fBstyle\fR" 4
.IX Item "style"
One of 'normal', 'oblique', 'italic'
.IP "\fBweight\fR" 4
.IX Item "weight"
One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight
.IP "\fBvariant\fR" 4
.IX Item "variant"
\&'normal' or 'smallcaps'
.IP "\fBstretch\fR" 4
.IX Item "stretch"
One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'
.IP "\fBforeground\fR" 4
.IX Item "foreground"
An \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
.IP "\fBbackground\fR" 4
.IX Item "background"
An \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
.IP "\fBunderline\fR" 4
.IX Item "underline"
One of 'none', 'single', 'double', 'low', 'error'
.IP "\fBunderline_color\fR" 4
.IX Item "underline_color"
The color of underlines; an \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
.IP "\fBrise\fR" 4
.IX Item "rise"
Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
.IP "\fBstrikethrough\fR" 4
.IX Item "strikethrough"
\&'true' or 'false' whether to strike through the text
.IP "\fBstrikethrough_color\fR" 4
.IX Item "strikethrough_color"
The color of crossed out lines; an \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
.IP "\fBfallback\fR" 4
.IX Item "fallback"
\&'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
.IP "\fBlang\fR" 4
.IX Item "lang"
A language code, indicating the text language
.IP "\fBletter_spacing\fR" 4
.IX Item "letter_spacing"
Inter-letter spacing in 1024ths of a point.
.IP "\fBgravity\fR" 4
.IX Item "gravity"
One of 'south', 'east', 'north', 'west', 'auto'.
.IP "\fBgravity_hint\fR" 4
.IX Item "gravity_hint"
One of 'natural', 'strong', 'line'.
.PP
To save you some typing, there are also some shortcuts:
.IP "\fBb\fR" 4
.IX Item "b"
Bold
.IP "\fBbig\fR" 4
.IX Item "big"
Makes font relatively larger, equivalent to
.IP "\fBi\fR" 4
.IX Item "i"
Italic
.IP "\fBs\fR" 4
.IX Item "s"
Strike through
.IP "\fBsub\fR" 4
.IX Item "sub"
Subscript
.IP "\fBsup\fR" 4
.IX Item "sup"
Superscript
.IP "\fBsmall\fR" 4
.IX Item "small"
Makes font relatively smaller, equivalent to
.IP "\fBtt\fR" 4
.IX Item "tt"
Monospace font
.IP "\fBu\fR" 4
.IX Item "u"
Underline
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdgraph gives an overview of how \fBrrdtool graph\fR works.
rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
rrdgraph_graph page describes all of the graph and print functions.
.PP
Make sure to read rrdgraph_examples for tips&tricks.
.SH "AUTHOR"
.IX Header "AUTHOR"
Program by Tobias Oetiker
.PP
This manual page by Alex van den Bogaerdt
with corrections and/or additions by several people
07070100047506000081a40000000000000000000000015295523500004f240000011f00010018ffffffffffffffff0000002e00000000root/usr/local/share/man/man1/rrd-beginners.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRD-BEGINNERS 1"
.TH RRD-BEGINNERS 1 "2009-10-14" "1.4.4" "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"
rrd\-beginners \- RRDtool Beginners' Guide
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Helping new RRDtool users to understand the basics of RRDtool
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual is an attempt to assist beginners in understanding the concepts
of RRDtool. It sheds a light on differences between RRDtool and other
databases. With help of an example, it explains the structure of RRDtool
database. This is followed by an overview of the \*(L"graph\*(R" feature of RRDtool.
At the end, it has sample scripts that illustrate the
usage/wrapping of RRDtool within Shell or Perl scripts.
.SS "What makes RRDtool so special?"
.IX Subsection "What makes RRDtool so special?"
RRDtool is \s-1GNU\s0 licensed software developed by Tobias Oetiker, a system
manager at the Swiss Federal Institute of Technology. Though it is a
database, there are distinct differences between RRDtool databases and other
databases as listed below:
.IP "\(bu" 4
RRDtool stores data; that makes it a back-end tool. The RRDtool command set
allows the creation of graphs; that makes it a front-end tool as well. Other
databases just store data and can not create graphs.
.IP "\(bu" 4
In case of linear databases, new data gets appended at the bottom of
the database table. Thus its size keeps on increasing, whereas the size of
an RRDtool database is determined at creation time. Imagine an RRDtool
database as the perimeter of a circle. Data is added along the
perimeter. When new data reaches the starting point, it overwrites
existing data. This way, the size of an RRDtool database always
remains constant. The name \*(L"Round Robin\*(R" stems from this behavior.
.IP "\(bu" 4
Other databases store the values as supplied. RRDtool can be configured to
calculate the rate of change from the previous to the current value and
store this information instead.
.IP "\(bu" 4
Other databases get updated when values are supplied. The RRDtool database
is structured in such a way that it needs data at predefined time
intervals. If it does not get a new value during the interval, it stores an
\&\s-1UNKNOWN\s0 value for that interval. So, when using the RRDtool database, it is
imperative to use scripts that run at regular intervals to ensure a constant
data flow to update the RRDtool database.
.PP
RRDtool is designed to store time series of data. With every data
update, an associated time stamp is stored. Time is always expressed
in seconds passed since epoch (01\-01\-1970). RRDtool can be installed
on Unix as well as Windows. It comes with a command set to carry out
various operations on \s-1RRD\s0 databases. This command set can be accessed
from the command line, as well as from Shell or Perl scripts. The
scripts act as wrappers for accessing data stored in RRDtool
databases.
.SS "Understanding by an example"
.IX Subsection "Understanding by an example"
The structure of an \s-1RRD\s0 database is different than other linear databases.
Other databases define tables with columns, and many other parameters. These
definitions sometimes are very complex, especially in large databases.
RRDtool databases are primarily used for monitoring purposes and
hence are very simple in structure. The parameters
that need to be defined are variables that hold values and archives of those
values. Being time sensitive, a couple of time related parameters are also
defined. Because of its structure, the definition of an RRDtool database also
includes a provision to specify specific actions to take in the absence of
update values. Data Source (\s-1DS\s0), heartbeat, Date Source Type (\s-1DST\s0), Round
Robin Archive (\s-1RRA\s0), and Consolidation Function (\s-1CF\s0) are some of the
terminologies related to RRDtool databases.
.PP
The structure of a database and the terminology associated with it can be
best explained with an example.
.PP
.Vb 6
\& rrdtool create target.rrd \e
\& \-\-start 1023654125 \e
\& \-\-step 300 \e
\& DS:mem:GAUGE:600:0:671744 \e
\& RRA:AVERAGE:0.5:12:24 \e
\& RRA:AVERAGE:0.5:288:31
.Ve
.PP
This example creates a database named \fItarget.rrd\fR. Start time
(1'023'654'125) is specified in total number of seconds since epoch
(time in seconds since 01\-01\-1970). While updating the database, the
update time is also specified. This update time \s-1MUST\s0 be large (later)
then start time and \s-1MUST\s0 be in seconds since epoch.
.PP
The step of 300 seconds indicates that database expects new values every
300 seconds. The wrapper script should be scheduled to run every \fBstep\fR
seconds so that it updates the database every \fBstep\fR seconds.
.PP
\&\s-1DS\s0 (Data Source) is the actual variable which relates to the parameter on
the device that is monitored. Its syntax is
.PP
.Vb 1
\& DS:variable_name:DST:heartbeat:min:max
.Ve
.PP
\&\fB\s-1DS\s0\fR is a key word. \f(CW\*(C`variable_name\*(C'\fR is a name under which the parameter is
saved in the database. There can be as many DSs in a database as needed. After
every step interval, a new value of \s-1DS\s0 is supplied to update the database.
This value is also called Primary Data Point \fB(\s-1PDP\s0)\fR. In our example
mentioned above, a new \s-1PDP\s0 is generated every 300 seconds.
.PP
Note, that if you do \s-1NOT\s0 supply new data points exactly every 300 seconds,
this is not a problem, RRDtool will interpolate the data accordingly.
.PP
\&\fB\s-1DST\s0\fR (Data Source Type) defines the type of the \s-1DS\s0. It can be
\&\s-1COUNTER\s0, \s-1DERIVE\s0, \s-1ABSOLUTE\s0, \s-1GAUGE\s0. A \s-1DS\s0 declared as \s-1COUNTER\s0 will save
the rate of change of the value over a step period. This assumes that
the value is always increasing (the difference between the current and
the previous value is greater than 0). Traffic counters on a router
are an ideal candidate for using \s-1COUNTER\s0 as \s-1DST\s0. \s-1DERIVE\s0 is the same as
\&\s-1COUNTER\s0, but it allows negative values as well. If you want to see the
rate of \fIchange\fR in free disk space on your server, then you might
want to use the \s-1DERIVE\s0 data type. \s-1ABSOLUTE\s0 also saves the rate of
change, but it assumes that the previous value is set to 0. The
difference between the current and the previous value is always equal
to the current value. Thus it just stores the current value divided by
the step interval (300 seconds in our example). \s-1GAUGE\s0 does not save
the rate of change. It saves the actual value itself. There are no
divisions or calculations. Memory consumption in a server is a typical
example of gauge. The difference between the different types DSTs can be
explained better with the following example:
.PP
.Vb 6
\& Values = 300, 600, 900, 1200
\& Step = 300 seconds
\& COUNTER DS = 1, 1, 1, 1
\& DERIVE DS = 1, 1, 1, 1
\& ABSOLUTE DS = 1, 2, 3, 4
\& GAUGE DS = 300, 600, 900, 1200
.Ve
.PP
The next parameter is \fBheartbeat\fR. In our example, heartbeat is 600
seconds. If the database does not get a new \s-1PDP\s0 within 300 seconds, it
will wait for another 300 seconds (total 600 seconds). If it doesn't
receive any \s-1PDP\s0 within 600 seconds, it will save an \s-1UNKNOWN\s0 value into
the database. This \s-1UNKNOWN\s0 value is a special feature of RRDtool \- it
is much better than to assume a missing value was 0 (zero) or any
other number which might also be a valid data value. For example, the
traffic flow counter on a router keeps increasing. Lets say, a value
is missed for an interval and 0 is stored instead of \s-1UNKNOWN\s0. Now when
the next value becomes available, it will calculate the difference
between the current value and the previous value (0) which is not
correct. So, inserting the value \s-1UNKNOWN\s0 makes much more sense here.
.PP
The next two parameters are the minimum and maximum value,
respectively. If the variable to be stored has predictable maximum and
minimum values, this should be specified here. Any update value
falling out of this range will be stored as \s-1UNKNOWN\s0.
.PP
The next line declares a round robin archive (\s-1RRA\s0). The syntax for
declaring an \s-1RRA\s0 is
.PP
.Vb 1
\& RRA:CF:xff:step:rows
.Ve
.PP
\&\s-1RRA\s0 is the keyword to declare RRAs. The consolidation function (\s-1CF\s0)
can be \s-1AVERAGE\s0, \s-1MINIMUM\s0, \s-1MAXIMUM\s0, and \s-1LAST\s0. The concept of the
consolidated data point (\s-1CDP\s0) comes into the picture here. A \s-1CDP\s0 is
CFed (averaged, maximum/minimum value or last value) from \fIstep\fR
number of PDPs. This \s-1RRA\s0 will hold \fIrows\fR CDPs.
.PP
Lets have a look at the example above. For the first \s-1RRA\s0, 12 (steps)
PDPs (\s-1DS\s0 variables) are AVERAGEed (\s-1CF\s0) to form one \s-1CDP\s0. 24 (rows) of
theses CDPs are archived. Each \s-1PDP\s0 occurs at 300 seconds. 12 PDPs
represent 12 times 300 seconds which is 1 hour. It means 1 \s-1CDP\s0 (which
is equal to 12 PDPs) represents data worth 1 hour. 24 such CDPs
represent 1 day (1 hour times 24 CDPs). This means, this \s-1RRA\s0 is an
archive for one day. After 24 CDPs, \s-1CDP\s0 number 25 will replace the 1st
\&\s-1CDP\s0. The second \s-1RRA\s0 saves 31 CDPs; each \s-1CPD\s0 represents an \s-1AVERAGE\s0
value for a day (288 PDPs, each covering 300 seconds = 24
hours). Therefore this \s-1RRA\s0 is an archive for one month. A single
database can have many RRAs. If there are multiple DSs, each
individual \s-1RRA\s0 will save data for all the DSs in the database. For
example, if a database has 3 DSs and daily, weekly, monthly, and
yearly RRAs are declared, then each \s-1RRA\s0 will hold data from all 3 data
sources.
.SS "Graphical Magic"
.IX Subsection "Graphical Magic"
Another important feature of RRDtool is its ability to create
graphs. The \*(L"graph\*(R" command uses the \*(L"fetch\*(R" command internally to
retrieve values from the database. With the retrieved values it draws
graphs as defined by the parameters supplied on the command line. A
single graph can show different \s-1DS\s0 (Data Sources) from a database. It
is also possible to show the values from more than one database in a
single graph. Often, it is necessary to perform some math on the
values retrieved from the database before plotting them. For example,
in \s-1SNMP\s0 replies, memory consumption values are usually specified in
KBytes and traffic flow on interfaces is specified in Bytes. Graphs
for these values will be more meaningful if values are represented in
MBytes and mbps. The RRDtool graph command allows to define such
conversions. Apart from mathematical calculations, it is also possible
to perform logical operations such as greater than, less than, and
if/then/else. If a database contains more than one \s-1RRA\s0 archive, then a
question may arise \- how does RRDtool decide which \s-1RRA\s0 archive to use
for retrieving the values? RRDtool looks at several things when making
its choice. First it makes sure that the \s-1RRA\s0 covers as much of the
graphing time frame as possible. Second it looks at the resolution of
the \s-1RRA\s0 compared to the resolution of the graph. It tries to find one
which has the same or higher better resolution. With the \*(L"\-r\*(R" option
you can force RRDtool to assume a different resolution than the one
calculated from the pixel width of the graph.
.PP
Values of different variables can be presented in 5 different shapes
in a graph \- \s-1AREA\s0, \s-1LINE1\s0, \s-1LINE2\s0, \s-1LINE3\s0, and \s-1STACK\s0. \s-1AREA\s0 is represented
by a solid colored area with values as the boundary of this
area. \s-1LINE1/2/3\s0 (increasing width) are just plain lines representing
the values. \s-1STACK\s0 is also an area but it is \*(L"stack\*(R"ed on top \s-1AREA\s0 or
\&\s-1LINE1/2/3\s0. Another important thing to note is that variables are
plotted in the order they are defined in the graph command. Therefore
care must be taken to define \s-1STACK\s0 only after defining \s-1AREA/LINE\s0. It
is also possible to put formatted comments within the graph. Detailed
instructions can be found in the graph manual.
.SS "Wrapping RRDtool within Shell/Perl script"
.IX Subsection "Wrapping RRDtool within Shell/Perl script"
After understanding RRDtool it is now a time to actually use RRDtool
in scripts. Tasks involved in network management are data collection,
data storage, and data retrieval. In the following example, the
previously created target.rrd database is used. Data collection and
data storage is done using Shell scripts. Data retrieval and report
generation is done using Perl scripts. These scripts are shown below:
.PP
\fIShell script (collects data, updates database)\fR
.IX Subsection "Shell script (collects data, updates database)"
.PP
.Vb 10
\& #!/bin/sh
\& a=0
\& while [ "$a" == 0 ]; do
\& snmpwalk \-c public 192.168.1.250 hrSWRunPerfMem > snmp_reply
\& total_mem=\`awk \*(AqBEGIN {tot_mem=0}
\& { if ($NF == "KBytes")
\& {tot_mem=tot_mem+$(NF\-1)}
\& }
\& END {print tot_mem}\*(Aq snmp_reply\`
\& # I can use N as a replacement for the current time
\& rrdtool update target.rrd N:$total_mem
\& # sleep until the next 300 seconds are full
\& perl \-e \*(Aqsleep 300 \- time % 300\*(Aq
\& done # end of while loop
.Ve
.PP
\fIPerl script (retrieves data from database and generates graphs and statistics)\fR
.IX Subsection "Perl script (retrieves data from database and generates graphs and statistics)"
.PP
.Vb 3
\& #!/usr/bin/perl \-w
\& # This script fetches data from target.rrd, creates a graph of memory
\& # consumption on the target (Dual P3 Processor 1 GHz, 656 MB RAM)
\&
\& # call the RRD perl module
\& use lib qw( /usr/local/rrdtool\-1.0.41/lib/perl ../lib/perl );
\& use RRDs;
\& my $cur_time = time(); # set current time
\& my $end_time = $cur_time \- 86400; # set end time to 24 hours ago
\& my $start_time = $end_time \- 2592000; # set start 30 days in the past
\&
\& # fetch average values from the RRD database between start and end time
\& my ($start,$step,$ds_names,$data) =
\& RRDs::fetch("target.rrd", "AVERAGE",
\& "\-r", "600", "\-s", "$start_time", "\-e", "$end_time");
\& # save fetched values in a 2\-dimensional array
\& my $rows = 0;
\& my $columns = 0;
\& my $time_variable = $start;
\& foreach $line (@$data) {
\& $vals[$rows][$columns] = $time_variable;
\& $time_variable = $time_variable + $step;
\& foreach $val (@$line) {
\& $vals[$rows][++$columns] = $val;}
\& $rows++;
\& $columns = 0;
\& }
\& my $tot_time = 0;
\& my $count = 0;
\& # save the values from the 2\-dimensional into a 1\-dimensional array
\& for $i ( 0 .. $#vals ) {
\& $tot_mem[$count] = $vals[$i][1];
\& $count++;
\& }
\& my $tot_mem_sum = 0;
\& # calculate the total of all values
\& for $i ( 0 .. ($count\-1) ) {
\& $tot_mem_sum = $tot_mem_sum + $tot_mem[$i];
\& }
\& # calculate the average of the array
\& my $tot_mem_ave = $tot_mem_sum/($count);
\& # create the graph
\& RRDs::graph ("/images/mem_$count.png",
\& "\-\-title= Memory Usage",
\& "\-\-vertical\-label=Memory Consumption (MB)",
\& "\-\-start=$start_time",
\& "\-\-end=$end_time",
\& "\-\-color=BACK#CCCCCC",
\& "\-\-color=CANVAS#CCFFFF",
\& "\-\-color=SHADEB#9999CC",
\& "\-\-height=125",
\& "\-\-upper\-limit=656",
\& "\-\-lower\-limit=0",
\& "\-\-rigid",
\& "\-\-base=1024",
\& "DEF:tot_mem=target.rrd:mem:AVERAGE",
\& "CDEF:tot_mem_cor=tot_mem,0,671744,LIMIT,UN,0,tot_mem,IF,1024,/",
\& "CDEF:machine_mem=tot_mem,656,+,tot_mem,\-",
\& "COMMENT:Memory Consumption between $start_time",
\& "COMMENT: and $end_time ",
\& "HRULE:656#000000:Maximum Available Memory \- 656 MB",
\& "AREA:machine_mem#CCFFFF:Memory Unused",
\& "AREA:tot_mem_cor#6699CC:Total memory consumed in MB");
\& my $err=RRDs::error;
\& if ($err) {print "problem generating the graph: $err\en";}
\& # print the output
\& print "Average memory consumption is ";
\& printf "%5.2f",$tot_mem_ave/1024;
\& print " MB. Graphical representation can be found at /images/mem_$count.png.";
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ketan Patel
07070100047519000081a4000000000000000000000001529552350000128a0000011f00010018ffffffffffffffff0000002b00000000root/usr/local/share/man/man1/rrdrestore.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDRESTORE 1"
.TH RRDRESTORE 1 "2008-03-15" "1.4.4" "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"
rrdrestore \- Restore the contents of an RRD from its XML dump format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBrestore\fR \fIfilename.xml\fR \fIfilename.rrd\fR
[\fB\-\-range\-check\fR|\fB\-r\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBrestore\fR function reads the \s-1XML\s0 representation of an \s-1RRD\s0 and converts
it to the native \fB\s-1RRD\s0\fR format.
.IP "\fIfilename.xml\fR" 8
.IX Item "filename.xml"
The name of the \fB\s-1XML\s0\fR file you want to restore.
.IP "\fIfilename.rrd\fR" 8
.IX Item "filename.rrd"
The name of the \fB\s-1RRD\s0\fR to restore.
.IP "\fB\-\-range\-check\fR|\fB\-r\fR" 8
.IX Item "--range-check|-r"
Make sure the values in the RRAs do not exceed the limits defined for
the various data sources.
.IP "\fB\-\-force\-overwrite\fR|\fB\-f\fR" 8
.IX Item "--force-overwrite|-f"
Allows \fBRRDtool\fR to overwrite the destination \fB\s-1RRD\s0\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047510000081a400000000000000000000000152955235000027210000011f00010018ffffffffffffffff0000002e00000000root/usr/local/share/man/man1/rrdgraph_data.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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_DATA 1"
.TH RRDGRAPH_DATA 1 "2009-10-14" "1.4.4" "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_data \- preparing data for graphing in rrdtool graph
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fB\s-1DEF:\s0\fR\fI\fR=\fI\fR:\fI\fR:\fI\fR[:step=\fI\fR][:start=\fI\fR][:end=\fI\fR][:reduce=\fI\fR]
.PP
\&\fB\s-1VDEF\s0\fR:\fIvname\fR=\fI\s-1RPN\s0 expression\fR
.PP
\&\fB\s-1CDEF\s0\fR:\fIvname\fR=\fI\s-1RPN\s0 expression\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These three instructions extract data values out of the \fB\s-1RRD\s0\fR files,
optionally altering them (think, for example, of a bytes to bits
conversion). If so desired, you can also define variables containing
useful information such as maximum, minimum etcetera. Two of the
instructions use a language called \fB\s-1RPN\s0\fR which is described in its
own manual page.
.PP
Variable names (\fIvname\fR) must be made up strings of the following characters
\&\f(CW\*(C`A\-Z, a\-z, 0\-9, \-,_\*(C'\fR and a maximum length of 255 characters.
.PP
When picking variable names, make sure you do not choose a name that is
already taken by an \s-1RPN\s0 operator. A safe bet it to use lowercase or
mixed case names for variables since operators will always be in uppercase.
.SH "DEF"
.IX Header "DEF"
\&\fB\s-1DEF:\s0\fR\fI\fR=\fI\fR:\fI\fR:\fI\fR[:step=\fI\fR][:start=\fI\fR][:end=\fI\fR][:reduce=\fI\fR]
.PP
This command fetches data from an \fB\s-1RRD\s0\fR file. The virtual name
\&\fIvname\fR can then be used throughout the rest of the script. By
default, an \fB\s-1RRA\s0\fR which contains the correct consolidated data
at an appropriate resolution will be chosen. The resolution can
be overridden with the \-\-step option.
The resolution can again be overridden by specifying the \fBstep size\fR.
The time span of this data is the same as for the graph by default,
you can override this by specifying \fBstart and end\fR. Remember to
escape colons in the time specification!
.PP
If the resolution of the data is higher than the resolution of the
graph, the data will be further consolidated. This may result in
a graph that spans slightly more time than requested.
Ideally each point in the graph should correspond with one \fB\s-1CDP\s0\fR
from an \fB\s-1RRA\s0\fR. For instance, if your \fB\s-1RRD\s0\fR has an \fB\s-1RRA\s0\fR with
a resolution of 1800 seconds per \fB\s-1CDP\s0\fR, you should create an
image with width 400 and time span 400*1800 seconds (use appropriate
start and end times, such as \f(CW\*(C`\-\-start end\-8days8hours\*(C'\fR).
.PP
If consolidation needs to be done, the \fB\s-1CF\s0\fR of the \fB\s-1RRA\s0\fR specified in the
\&\fB\s-1DEF\s0\fR itself will be used to reduce the data density. This behavior can
be changed using \f(CW\*(C`:reduce=\f(CI\f(CW\*(C'\fR. This optional parameter
specifies the \fB\s-1CF\s0\fR to use during the data reduction phase.
.PP
Example:
.PP
.Vb 4
\& DEF:ds0=router.rrd:ds0:AVERAGE
\& DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
\& DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end\-1h
\& DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\e:00:end=start+1h
.Ve
.SH "VDEF"
.IX Header "VDEF"
\&\fB\s-1VDEF\s0\fR:\fIvname\fR=\fI\s-1RPN\s0 expression\fR
.PP
This command returns a value and/or a time according to the \fB\s-1RPN\s0\fR
statements used. The resulting \fIvname\fR will, depending on the
functions used, have a value and a time component. When you use
this \fIvname\fR in another \fB\s-1RPN\s0\fR expression, you are effectively
inserting its value just as if you had put a number at that place.
The variable can also be used in the various graph and print
elements.
.PP
Example: \f(CW\*(C`VDEF:avg=mydata,AVERAGE\*(C'\fR
.PP
Note that currently only aggregation functions work in \s-1VDEF\s0 rpn expressions.
Patches to change this are welcome.
.SH "CDEF"
.IX Header "CDEF"
\&\fB\s-1CDEF\s0\fR:\fIvname\fR=\fI\s-1RPN\s0 expression\fR
.PP
This command creates a new set of data points (in memory only, not
in the \fB\s-1RRD\s0\fR file) out of one or more other data series. The \fB\s-1RPN\s0\fR
instructions are used to evaluate a mathematical function on each
data point. The resulting \fIvname\fR can then be used further on in
the script, just as if it were generated by a \fB\s-1DEF\s0\fR instruction.
.PP
Example: \f(CW\*(C`CDEF:mydatabits=mydata,8,*\*(C'\fR
.SH "About CDEF versus VDEF"
.IX Header "About CDEF versus VDEF"
At some point in processing, \fBRRDtool\fR has gathered an array of rates
ready to display.
.PP
\&\fB\s-1CDEF\s0\fR works on such an array. For example, \fICDEF:new=ds0,8,*\fR
would multiply each of the array members by eight (probably
transforming bytes into bits). The result is an array containing the
new values.
.PP
\&\fB\s-1VDEF\s0\fR also works on such an array but in a different way. For
example, \fIVDEF:max=ds0,MAXIMUM\fR would scan each of the array members
and store the maximum value.
.SS "When do you use \fB\s-1VDEF\s0\fP versus \fB\s-1CDEF\s0\fP?"
.IX Subsection "When do you use VDEF versus CDEF?"
Use \fB\s-1CDEF\s0\fR to transform your data prior to graphing. In the above
example, we'd use a \fB\s-1CDEF\s0\fR to transform bytes to bits before
graphing the bits.
.PP
You use a \fB\s-1VDEF\s0\fR if you want \fImax(1,5,3,2,4)\fR to return five which
would be displayed in the graph's legend (to answer, what was the
maximum value during the graph period).
.PP
If you want to apply 'complex' operations to the result of a \s-1VDEF\s0 you have
to use a \s-1CDEF\s0 again since VDEFs only look like \s-1RPN\s0 expressions, they aren't
really.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdgraph gives an overview of how \fBrrdtool graph\fR works.
rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
rrdgraph_graph page describes all of the graph and print functions.
.PP
Make sure to read rrdgraph_examples for tips&tricks.
.SH "AUTHOR"
.IX Header "AUTHOR"
Program by Tobias Oetiker
.PP
This manual page by Alex van den Bogaerdt
with corrections and/or additions by several people
0707010004750f000081a40000000000000000000000015295523500006b050000011f00010018ffffffffffffffff0000002900000000root/usr/local/share/man/man1/rrdgraph.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "2010-06-11" "1.4.4" "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 \- Round Robin Database tool graphing functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool graph|graphv\fR \fIfilename\fR
[\fIoption\fR ...]
[\fIdata definition\fR ...]
[\fIdata calculation\fR ...]
[\fIvariable definition\fR ...]
[\fIgraph element\fR ...]
[\fIprint element\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBgraph\fR function of \fBRRDtool\fR is used to present the
data from an \fB\s-1RRD\s0\fR to a human viewer. Its main purpose is to
create a nice graphical representation, but it can also generate
a numerical report.
.SH "OVERVIEW"
.IX Header "OVERVIEW"
\&\fBrrdtool graph\fR needs data to work with, so you must use one or more
\&\fBdata definition\fR statements to collect this
data. You are not limited to one database, it's perfectly legal to
collect data from two or more databases (one per statement, though).
.PP
If you want to display averages, maxima, percentiles, etcetera
it is best to collect them now using the
\&\fBvariable definition\fR statement.
Currently this makes no difference, but in a future version
of RRDtool you may want to collect these values before consolidation.
.PP
The data fetched from the \fB\s-1RRA\s0\fR is then \fBconsolidated\fR so that
there is exactly one data point per pixel in the graph. If you do
not take care yourself, \fBRRDtool\fR will expand the range slightly
if necessary. Note, in that case the first and/or last pixel may very
well become unknown!
.PP
Sometimes data is not exactly in the format you would like to display
it. For instance, you might be collecting \fBbytes\fR per second, but
want to display \fBbits\fR per second. This is what the \fBdata
calculation\fR command is designed for. After
\&\fBconsolidating\fR the data, a copy is made and this copy is modified
using a rather powerful \fB\s-1RPN\s0\fR command set.
.PP
When you are done fetching and processing the data, it is time to
graph it (or print it). This ends the \fBrrdtool graph\fR sequence.
.PP
Use \fBgraphv\fR instead of \fBgraph\fR to get detailed information about the
graph geometry and data once it is drawn. See the bottom of the document for
more information.
.SH "OPTIONS"
.IX Header "OPTIONS"
.SS "\fIfilename\fP"
.IX Subsection "filename"
The name and path of the graph to generate. It is recommended to
end this in \f(CW\*(C`.png\*(C'\fR, \f(CW\*(C`.svg\*(C'\fR or \f(CW\*(C`.eps\*(C'\fR, but \fBRRDtool\fR does not enforce this.
.PP
\&\fIfilename\fR can be '\f(CW\*(C`\-\*(C'\fR' to send the image to \f(CW\*(C`stdout\*(C'\fR. In
this case, no other output is generated.
.SS "Time range"
.IX Subsection "Time range"
[\fB\-s\fR|\fB\-\-start\fR \fItime\fR]
[\fB\-e\fR|\fB\-\-end\fR \fItime\fR]
[\fB\-S\fR|\fB\-\-step\fR \fIseconds\fR]
.PP
The start and end of the time series you would like to display, and which
\&\fB\s-1RRA\s0\fR the data should come from. Defaults are: 1 day ago until
now, with the best possible resolution. \fBStart\fR and \fBend\fR can
be specified in several formats, see
AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0 and rrdgraph_examples.
By default, \fBrrdtool graph\fR calculates the width of one pixel in
the time domain and tries to get data from an \fB\s-1RRA\s0\fR with that
resolution. With the \fBstep\fR option you can alter this behavior.
If you want \fBrrdtool graph\fR to get data at a one-hour resolution
from the \fB\s-1RRD\s0\fR, set \fBstep\fR to 3'600. Note: a step smaller than
one pixel will silently be ignored.
.SS "Labels"
.IX Subsection "Labels"
[\fB\-t\fR|\fB\-\-title\fR \fIstring\fR]
[\fB\-v\fR|\fB\-\-vertical\-label\fR \fIstring\fR]
.PP
A horizontal string at the top of the graph and/or a vertically
placed string at the left hand side of the graph.
.SS "Size"
.IX Subsection "Size"
[\fB\-w\fR|\fB\-\-width\fR \fIpixels\fR]
[\fB\-h\fR|\fB\-\-height\fR \fIpixels\fR]
[\fB\-j\fR|\fB\-\-only\-graph\fR]
[\fB\-D\fR|\fB\-\-full\-size\-mode\fR]
.PP
By default, the width and height of the \fBcanvas\fR (the part with
the actual data and such). This defaults to 400 pixels by 100 pixels.
.PP
If you specify the \fB\-\-full\-size\-mode\fR option, the width and height
specify the final dimensions of the output image and the canvas
is automatically resized to fit.
.PP
If you specify the \fB\-\-only\-graph\fR option and set the height < 32
pixels 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.
.SS "Limits"
.IX Subsection "Limits"
[\fB\-u\fR|\fB\-\-upper\-limit\fR \fIvalue\fR]
[\fB\-l\fR|\fB\-\-lower\-limit\fR \fIvalue\fR]
[\fB\-r\fR|\fB\-\-rigid\fR]
.PP
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 behavior by
explicitly setting the limits. The displayed y\-axis will then range at
least from \fBlower-limit\fR to \fBupper-limit\fR. Autoscaling will still
permit those boundaries to be stretched unless the \fBrigid\fR option is
set.
.PP
[\fB\-A\fR|\fB\-\-alt\-autoscale\fR]
.PP
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 something
like \f(CW\*(C`260 + 0.001 * sin(x)\*(C'\fR. This option calculates the minimum and
maximum y\-axis from the actual minimum and maximum data values. Our example
would display slightly less than \f(CW\*(C`260\-0.001\*(C'\fR to slightly more than
\&\f(CW\*(C`260+0.001\*(C'\fR (this feature was contributed by Sasha Mikheev).
.PP
[\fB\-J\fR|\fB\-\-alt\-autoscale\-min\fR]
.PP
Where \f(CW\*(C`\-\-alt\-autoscale\*(C'\fR will modify both the absolute maximum \s-1AND\s0 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 \s-1WAN\s0 line uses compression,
and thus the throughput may be higher than the \s-1WAN\s0 line speed.
.PP
[\fB\-M\fR|\fB\-\-alt\-autoscale\-max\fR]
.PP
Where \f(CW\*(C`\-\-alt\-autoscale\*(C'\fR 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.
.PP
[\fB\-N\fR|\fB\-\-no\-gridfit\fR]
.PP
In order to avoid anti-aliasing blurring effects RRDtool snaps
points to device resolution pixels, this results in a crisper
appearance. If this is not to your liking, you can use this switch
to turn this behavior off.
.PP
Grid-fitting is turned off for \s-1PDF\s0, \s-1EPS\s0, \s-1SVG\s0 output by default.
.SS "X\-Axis"
.IX Subsection "X-Axis"
[\fB\-x\fR|\fB\-\-x\-grid\fR \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\fB:\fR\fI\s-1LST\s0\fR\fB:\fR\fI\s-1LPR\s0\fR\fB:\fR\fI\s-1LFM\s0\fR]
.PP
[\fB\-x\fR|\fB\-\-x\-grid\fR \fBnone\fR]
.PP
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 auto configuration
to get this right. You can specify the string \f(CW\*(C`none\*(C'\fR to suppress the grid
and labels altogether.
.PP
The grid is defined by specifying a certain amount of time in the \fI?TM\fR
positions. You can choose from \f(CW\*(C`SECOND\*(C'\fR, \f(CW\*(C`MINUTE\*(C'\fR, \f(CW\*(C`HOUR\*(C'\fR, \f(CW\*(C`DAY\*(C'\fR,
\&\f(CW\*(C`WEEK\*(C'\fR, \f(CW\*(C`MONTH\*(C'\fR or \f(CW\*(C`YEAR\*(C'\fR. Then you define how many of these should
pass between each line or label. This pair (\fI?TM:?ST\fR) needs to be
specified for the base grid (\fIG??\fR), the major grid (\fIM??\fR) and the
labels (\fIL??\fR). For the labels you also must define a precision
in \fI\s-1LPR\s0\fR and a \fIstrftime\fR format string in \fI\s-1LFM\s0\fR. \fI\s-1LPR\s0\fR 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).
.PP
.Vb 1
\& \-\-x\-grid MINUTE:10:HOUR:1:HOUR:4:0:%X
.Ve
.PP
This places grid lines every 10 minutes, major grid lines every hour,
and labels every 4 hours. The labels are placed under the major grid
lines as they specify exactly that time.
.PP
.Vb 1
\& \-\-x\-grid HOUR:8:DAY:1:DAY:1:86400:%A
.Ve
.PP
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.
.SS "Y\-Axis"
.IX Subsection "Y-Axis"
[\fB\-y\fR|\fB\-\-y\-grid\fR \fIgrid step\fR\fB:\fR\fIlabel factor\fR]
.PP
[\fB\-y\fR|\fB\-\-y\-grid\fR \fBnone\fR]
.PP
Y\-axis grid lines appear at each \fIgrid step\fR interval. Labels are
placed every \fIlabel factor\fR lines. You can specify \f(CW\*(C`\-y none\*(C'\fR to
suppress the grid and labels altogether. The default for this option is
to automatically select sensible values.
.PP
If you have set \-\-y\-grid to 'none' not only the labels get suppressed, 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.
.PP
[\fB\-Y\fR|\fB\-\-alt\-y\-grid\fR]
.PP
Place the Y grid dynamically based on the graph's Y range. The algorithm
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 Mikheev).
.PP
[\fB\-o\fR|\fB\-\-logarithmic\fR]
.PP
Logarithmic y\-axis scaling.
.PP
[\fB\-X\fR|\fB\-\-units\-exponent\fR \fIvalue\fR]
.PP
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 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, 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.
.PP
This option is very effective at confusing the heck out of the default
RRDtool autoscaling function and grid painter. If RRDtool detects that it is not
successful in labeling the graph under the given circumstances, it will switch
to the more robust \fB\-\-alt\-y\-grid\fR mode.
.PP
[\fB\-L\fR|\fB\-\-units\-length\fR \fIvalue\fR]
.PP
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
fiddling with the y\-axis labeling.
.PP
[\fB\-\-units=si\fR]
.PP
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, \s-1SI\s0 notation is used by default.
.SS "Right Y Axis"
.IX Subsection "Right Y Axis"
[\fB\-\-right\-axis\fR \fIscale\fR\fB:\fR\fIshift\fR]
[\fB\-\-right\-axis\-label\fR \fIlabel\fR]
.PP
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.
.PP
[\fB\-\-right\-axis\-format\fR \fIformat-string\fR]
.PP
By default the format of the axis labels gets determined automatically. If
you want to do this your self, use this option with the same \f(CW%lf\fR arguments
you know from the \s-1PRINT\s0 and \s-1GPRINT\s0 commands.
.SS "Legend"
.IX Subsection "Legend"
[\fB\-g\fR|\fB\-\-no\-legend\fR]
.PP
Suppress generation of the legend; only render the graph.
.PP
[\fB\-F\fR|\fB\-\-force\-rules\-legend\fR]
.PP
Force the generation of \s-1HRULE\s0 and \s-1VRULE\s0 legends even if those \s-1HRULE\s0 or
\&\s-1VRULE\s0 will not be drawn because out of graph boundaries (mimics
behavior of pre 1.0.42 versions).
.PP
[\fB\-\-legend\-position\fR=(north|south|west|east)]
.PP
Place the legend at the given side of the graph. The default is south.
In west or east position it is necessary to add line breaks manually.
.PP
[\fB\-\-legend\-direction\fR=(topdown|bottomup)]
.PP
Place the legend items in the given vertical order. The default is topdown.
Using bottomup the legend items appear in the same vertical order as a
stack of lines or areas.
.SS "Miscellaneous"
.IX Subsection "Miscellaneous"
[\fB\-z\fR|\fB\-\-lazy\fR]
.PP
Only generate the graph if the current graph is out of date or not existent.
Note, that all the calculations will happen regardless so that the output of
\&\s-1PRINT\s0 and graphv will be complete regardless. Note that the behavior of
lazy in this regard has seen several changes over time. The only thing you
can really rely on before RRDtool 1.3.7 is that lazy will not generate the
graph when it is already there and up to date, and also that it will output
the size of the graph.
.PP
[\fB\-\-daemon\fR \fIaddress\fR]
.PP
Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
to the server before reading the \s-1RRD\s0 files. This allows the graph to contain
fresh data even if the daemon is configured to cache values for a long time.
For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
.PP
.Vb 1
\& rrdtool graph [...] \-\-daemon unix:/var/run/rrdcached.sock [...]
.Ve
.PP
[\fB\-f\fR|\fB\-\-imginfo\fR \fIprintfstr\fR]
.PP
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 function 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:
.PP
.Vb 1
\& \-\-imginfo \*(Aq\*(Aq
.Ve
.PP
[\fB\-c\fR|\fB\-\-color\fR \fI\s-1COLORTAG\s0\fR#\fIrrggbb\fR[\fIaa\fR]]
.PP
Override the default colors for the standard elements of the graph. The
\&\fI\s-1COLORTAG\s0\fR is one of \f(CW\*(C`BACK\*(C'\fR background, \f(CW\*(C`CANVAS\*(C'\fR for the background of
the actual graph, \f(CW\*(C`SHADEA\*(C'\fR for the left and top border, \f(CW\*(C`SHADEB\*(C'\fR for the
right and bottom border, \f(CW\*(C`GRID\*(C'\fR, \f(CW\*(C`MGRID\*(C'\fR for the major grid, \f(CW\*(C`FONT\*(C'\fR for
the color of the font, \f(CW\*(C`AXIS\*(C'\fR for the axis of the graph, \f(CW\*(C`FRAME\*(C'\fR for the
line around the color spots, and finally \f(CW\*(C`ARROW\*(C'\fR 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, \s-1FF\s0 is maximum) of red, green
and blue. Optionally you may add another hexadecimal number specifying the
transparency (\s-1FF\s0 is solid). You may set this option several times to alter
multiple defaults.
.PP
A green arrow is made by: \f(CW\*(C`\-\-color ARROW#00FF00\*(C'\fR
.PP
[\fB\-\-grid\-dash\fR \fIon\fR\fB:\fR\fIoff\fR]
.PP
by default the grid is drawn in a 1 on, 1 off pattern. With this option you can set this yourself
.PP
.Vb 1
\& \-\-grid\-dash 1:3 for a dot grid
\&
\& \-\-grid\-dash 1:0 for uninterrupted grid lines
.Ve
.PP
[\fB\-\-border\fR \fIwidth\fR]]
.PP
Width in pixels for the 3d border drawn around the image. Default 2, 0
disables the border. See \f(CW\*(C`SHADEA\*(C'\fR and \f(CW\*(C`SHADEB\*(C'\fR above for setting the border
color.
.PP
[\fB\-\-dynamic\-labels\fR]
.PP
Pick the shape of the color marker next to the label according to the element drawn on the graph.
.PP
[\fB\-m\fR|\fB\-\-zoom\fR \fIfactor\fR]
.PP
Zoom the graphics by the given amount. The factor must be > 0
.PP
[\fB\-n\fR|\fB\-\-font\fR \fI\s-1FONTTAG\s0\fR\fB:\fR\fIsize\fR\fB:\fR[\fIfont\fR]]
.PP
This lets you customize which font to use for the various text elements on
the \s-1RRD\s0 graphs. \f(CW\*(C`DEFAULT\*(C'\fR sets the default value for all elements, \f(CW\*(C`TITLE\*(C'\fR
for the title, \f(CW\*(C`AXIS\*(C'\fR for the axis labels, \f(CW\*(C`UNIT\*(C'\fR for the vertical unit
label, \f(CW\*(C`LEGEND\*(C'\fR for the graph legend, \f(CW\*(C`WATERMARK\*(C'\fR for the watermark on the
edge of the graph.
.PP
Use Times for the title: \f(CW\*(C`\-\-font TITLE:13:Times\*(C'\fR
.PP
Note that you need to quote the argument to \fB\-\-font\fR if the font-name
contains whitespace:
\&\-\-font \*(L"TITLE:13:Some Font\*(R"
.PP
If you do not give a font string you can modify just the size of the default font:
\&\f(CW\*(C`\-\-font TITLE:13:\*(C'\fR.
.PP
If you specify the size 0 then you can modify just the font without touching
the size. This is especially useful for altering the default font without
resetting the default fontsizes: \f(CW\*(C`\-\-font DEFAULT:0:Courier\*(C'\fR.
.PP
RRDtool comes with a preset default font. You can set the environment
variable \f(CW\*(C`RRD_DEFAULT_FONT\*(C'\fR if you want to change this.
.PP
RRDtool uses Pango for its font handling. This means you can to use
the full Pango syntax when selecting your font:
.PP
The font name has the form "[\fIFAMILY-LIST\fR] [\fISTYLE-OPTIONS\fR] [\fI\s-1SIZE\s0\fR]",
where \fIFAMILY-LIST\fR is a comma separated list of families optionally
terminated by a comma, \fI\s-1STYLE_OPTIONS\s0\fR is a whitespace separated list of
words where each \s-1WORD\s0 describes one of style, variant, weight, stretch, or
gravity, and \fI\s-1SIZE\s0\fR is a decimal number (size in points) or optionally
followed by the unit modifier \*(L"px\*(R" for absolute size. Any one of the options
may be absent.
.PP
[\fB\-R\fR|\fB\-\-font\-render\-mode\fR {\fBnormal\fR,\fBlight\fR,\fBmono\fR}]
.PP
There are 3 font render modes:
.PP
\&\fBnormal\fR: Full Hinting and Anti-aliasing (default)
.PP
\&\fBlight\fR: Slight Hinting and Anti-aliasing
.PP
\&\fBmono\fR: Full Hinting and \s-1NO\s0 Anti-aliasing
.PP
[\fB\-B\fR|\fB\-\-font\-smoothing\-threshold\fR \fIsize\fR]
.PP
(this gets ignored in 1.3 for now!)
.PP
This specifies the largest font size which will be rendered
bitmapped, that is, without any font smoothing. By default,
no text is rendered bitmapped.
.PP
[\fB\-P\fR|\fB\-\-pango\-markup\fR]
.PP
All text in RRDtool is rendered using Pango. With the \fB\-\-pango\-markup\fR option, all
text will be processed by pango markup. This allows to embed some simple html
like markup tags using
.PP
.Vb 1
\& text
.Ve
.PP
Apart from the verbose syntax, there are also the following short tags available.
.PP
.Vb 9
\& b Bold
\& big Makes font relatively larger, equivalent to
\& i Italic
\& s Strikethrough
\& sub Subscript
\& sup Superscript
\& small Makes font relatively smaller, equivalent to
\& tt Monospace font
\& u Underline
.Ve
.PP
More details on .
.PP
[\fB\-G\fR|\fB\-\-graph\-render\-mode\fR {\fBnormal\fR,\fBmono\fR}]
.PP
There are 2 render modes:
.PP
\&\fBnormal\fR: Graphs are fully Anti-aliased (default)
.PP
\&\fBmono\fR: No Anti-aliasing
.PP
[\fB\-E\fR|\fB\-\-slope\-mode\fR]
.PP
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.
.PP
[\fB\-a\fR|\fB\-\-imgformat\fR \fB\s-1PNG\s0\fR|\fB\s-1SVG\s0\fR|\fB\s-1EPS\s0\fR|\fB\s-1PDF\s0\fR]
.PP
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,
Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats.
.PP
[\fB\-i\fR|\fB\-\-interlaced\fR]
.PP
(this gets ignored in 1.3 for now!)
.PP
If images are interlaced they become visible on browsers more quickly.
.PP
[\fB\-T\fR|\fB\-\-tabwidth\fR \fIvalue\fR]
.PP
By default the tab-width is 40 pixels, use this option to change it.
.PP
[\fB\-b\fR|\fB\-\-base\fR \fIvalue\fR]
.PP
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.
.PP
[\fB\-W\fR|\fB\-\-watermark\fR \fIstring\fR]
.PP
Adds the given string as a watermark, horizontally centered, at the bottom
of the graph.
.SS "Data and variables"
.IX Subsection "Data and variables"
\&\fB\s-1DEF:\s0\fR\fIvname\fR\fB=\fR\fIrrdfile\fR\fB:\fR\fIds-name\fR\fB:\fR\fI\s-1CF\s0\fR[\fB:step=\fR\fIstep\fR][\fB:start=\fR\fItime\fR][\fB:end=\fR\fItime\fR]
.PP
\&\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fI\s-1RPN\s0 expression\fR
.PP
\&\fB\s-1VDEF:\s0\fR\fIvname\fR\fB=\fR\fI\s-1RPN\s0 expression\fR
.PP
You need at least one \fB\s-1DEF\s0\fR statement to generate anything. The
other statements are useful but optional.
See rrdgraph_data and rrdgraph_rpn for the exact format.
.PP
\&\s-1NOTE:\s0 \fBGraph and print elements\fR
.PP
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.
.SS "graphv"
.IX Subsection "graphv"
Calling RRDtool with the graphv option will return information in the
RRDtool info format. On the command line this means that all output will be
in key=value format. When used from the Perl and Ruby bindings a hash
pointer will be returned from the call.
.PP
When the filename '\-' is given, the contents of the graph itself will also
be returned through this interface (hash key 'image'). On the command line
the output will look like this:
.PP
.Vb 10
\& print[0] = "0.020833"
\& print[1] = "0.0440833"
\& graph_left = 51
\& graph_top = 22
\& graph_width = 400
\& graph_height = 100
\& graph_start = 1232908800
\& graph_end = 1232914200
\& image_width = 481
\& image_height = 154
\& value_min = 0.0000000000e+00
\& value_max = 4.0000000000e\-02
\& image = BLOB_SIZE:8196
\& [... 8196 bytes of image data ...]
.Ve
.PP
There is more information returned than in the standard interface.
Especially the 'graph_*' keys are new. They help applications that want to
know what is where on the graph.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ graph\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdgraph gives an overview of how \fBrrdtool graph\fR works.
rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
rrdgraph_graph page describes all of the graph and print functions.
.PP
Make sure to read rrdgraph_examples for tips&tricks.
.SH "AUTHOR"
.IX Header "AUTHOR"
Program by Tobias Oetiker
.PP
This manual page by Alex van den Bogaerdt
with corrections and/or additions by several people
07070100047507000081a4000000000000000000000001529552350000413d0000011f00010018ffffffffffffffff0000002900000000root/usr/local/share/man/man1/rrdbuild.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDBUILD 1"
.TH RRDBUILD 1 "2010-07-05" "1.4.4" "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"
rrdbuild \- Instructions for building RRDtool
.SH "OVERVIEW"
.IX Header "OVERVIEW"
If you downloaded the source of RRDtool you have to compile it. This
document will give some information on how this is done.
.PP
RRDtool relies on services of third part libraries. Some of these libraries
may already be installed on your system. You have to compile copies of the other
ones before you can build RRDtool.
.PP
This document will tell you about all the necessary steps to get going.
.PP
These instructions assume you are using a \fBbash\fR shell. If you use csh/tcsh,
then you can either type \fIbash\fR to switch to bash for the compilation or if
you know what you are doing just replace the export bits with
setenv.
.PP
We further assume that your copies of \fBtar\fR and \fBmake\fR are actually \fB\s-1GNU\s0
tar\fR and \fB\s-1GNU\s0 make\fR respectively. It could be that they are installed as
\&\fBgtar\fR and \fBgmake\fR on your system.
.SH "OPTIMISTIC BUILD"
.IX Header "OPTIMISTIC BUILD"
Before you start to build RRDtool, you have to decide two things:
.IP "1." 4
In which directory you want to build the software.
.IP "2." 4
Where you want to install the software.
.PP
Once you have decided. Save the two locations into environment variables.
.PP
.Vb 2
\& BUILD_DIR=/tmp/rrdbuild
\& INSTALL_DIR=/opt/rrdtool\-1.4.4
.Ve
.PP
If your \fI/tmp\fR is mounted with the option noexec (\s-1RHEL\s0 seems todo that) you have to choose
a different directory!
.PP
Now make sure the \s-1BUILD_DIR\s0 exists and go there:
.PP
.Vb 2
\& mkdir \-p $BUILD_DIR
\& cd $BUILD_DIR
.Ve
.PP
Lets first assume you already have all the necessary libraries
pre-installed.
.PP
.Vb 4
\& wget http://oss.oetiker.ch/rrdtool/pub/rrdtool\-1.4.4.tar.gz
\& gunzip \-c rrdtool\-1.4.4.tar.gz | tar xf \-
\& cd rrdtool\-1.4.4
\& ./configure \-\-prefix=$INSTALL_DIR && make && make install
.Ve
.PP
Ok, this was very optimistic. This try will probably have ended with
\&\fBconfigure\fR complaining about several missing libraries.
.SH "INSTALLING DEPENDENCIES"
.IX Header "INSTALLING DEPENDENCIES"
If your \s-1OS\s0 lets you install additional packages from a software repository,
you may get away with installing the missing packages. When the packages are
installed, run configure again and try to compile again. Below you find some
hints on getting your \s-1OS\s0 ready for compiling RRDtool.
.PP
Additions to this list are welcome. In general RRDtool should work with the
latest versions of the libraries. The versions listed here are just what was
current when I tested this.
.SS "OpenSolaris 2008.05"
.IX Subsection "OpenSolaris 2008.05"
Just add a compiler and the gnome development package:
.PP
.Vb 2
\& pkg install sunstudioexpress
\& pkg install SUNWgnome\-common\-devel
.Ve
.PP
There is a problem with \fIcairo.pc\fR on OpenSolaris. It suggests that
xrender is required for compilation with cairo. This is not true and also
bad since OpenSolaris does not include an \fIxrender.pc\fR file. Use Perl to
fix this:
.PP
.Vb 1
\& perl \-i~ \-p \-e \*(Aqs/(Requires.*?)\es*xrender.*/$1/\*(Aq /usr/lib/pkgconfig/cairo.pc
.Ve
.PP
Make sure the RRDtool build system finds your new compiler
.PP
.Vb 1
\& export PATH=/opt/SunStudioExpress/bin
.Ve
.SS "Debian / Ubuntu"
.IX Subsection "Debian / Ubuntu"
Use apt-get to make sure you have all that is required. A number
of packages will get added through dependencies.
.PP
.Vb 1
\& apt\-get install libpango1.0\-dev libxml2\-dev
.Ve
.SS "Gentoo"
.IX Subsection "Gentoo"
In Gentoo installing RRDtool is really simple you just need to \fBemerge
rrdtool\fR. All dependencies will be handled automatically by the portage
system. The only thing you should care about are \s-1USE\s0 flags, which allow you
fine tune features RRDtool will be built with. Currently the following \s-1USE\s0
flags are available:
.PP
.Vb 7
\& doc \- install .html and .txt documentation
\& into /usr/share/doc/rrdtool\-1.x.xx/
\& perl \- build and install perl language bindings
\& python \- build and install python language bindings
\& ruby \- build and install ruby language bindings
\& tcl \- build and install tcl language bindings
\& rrdcgi \- build and install rrdcgi
.Ve
.PP
After you've decided which \s-1USE\s0 flags you need, set them either in
\&\fImake.conf\fR or \fI/etc/portage/package.use\fR and finally run:
.PP
.Vb 1
\& # emerge \-va rrdtool
.Ve
.PP
Take a look at Gentoo handbook for further details on how to manage \s-1USE\s0
flags: http://www.gentoo.org/doc/en/handbook/handbook\-x86.xml?part=2
.SH "BUILDING DEPENDENCIES"
.IX Header "BUILDING DEPENDENCIES"
But again this may have been too optimistic still, and you actually have to
compile your own copies of some of the required libraries. Things like
libpng and zlib are pretty standard so you will probably have them on your
system anyway. Freetype, Fontinst, Cairo, Pango may be installed, but it is
possible that they are pretty old and thus don't live up to our
expectations, so you may want to compile their latest versions.
.SS "General build tips for \s-1AIX\s0"
.IX Subsection "General build tips for AIX"
If you are working with \s-1AIX\s0, you may find the \fB\-\-disable\-shared\fR option
will cause things to break for you. In that case you may have to install the
shared libraries into the RRDtool \s-1PREFIX\s0 and work with \fB\-\-disable\-static\fR
instead.
.PP
Another hint to get RRDtool working on \s-1AIX\s0 is to use the \s-1IBM\s0 \s-1XL\s0 C Compiler:
.PP
.Vb 2
\& export CC=/usr/vac/bin/cc
\& export PERLCC=$CC
.Ve
.PP
(Better instructions for \s-1AIX\s0 welcome!)
.SS "Build Instructions"
.IX Subsection "Build Instructions"
Some libraries want to know where other libraries are. For this to work,
set the following environment variable
.PP
.Vb 2
\& export PKG_CONFIG_PATH=${INSTALL_DIR}/lib/pkgconfig
\& export PATH=$INSTALL_DIR/bin:$PATH
.Ve
.PP
The above relies on the presence of the \fIpkgconfig\fR program. Below you find instructions
on how to compile pkgconfig.
.PP
Since we are compiling libraries dynamically, they must know where to find
each other. This is done by setting an appropriate \s-1LDFLAGS\s0. Unfortunately,
the syntax again differs from system to system:
.IP "Solaris" 4
.IX Item "Solaris"
.Vb 1
\& export LDFLAGS=\-R${INSTALL_DIR}/lib
.Ve
.Sp
if you are using the Sun Studio/Forte compiler, you may also want to set
.Sp
.Vb 2
\& CFLAGS="\-xO3 \-xcode=pic13" (SPARC)
\& CFLAGS="\-xO3 \-Kpic" (x86)
.Ve
.IP "Linux" 4
.IX Item "Linux"
.Vb 1
\& export LDFLAGS="\-Wl,\-\-rpath \-Wl,${INSTALL_DIR}/lib"
.Ve
.IP "\s-1HPUX\s0" 4
.IX Item "HPUX"
.Vb 1
\& export LDFLAGS="+b${INSTALL_DIR}/lib"
.Ve
.IP "\s-1AIX\s0" 4
.IX Item "AIX"
.Vb 1
\& export LDFLAGS="\-Wl,\-blibpath:${INSTALL_DIR}/lib"
.Ve
.PP
If you have \s-1GNU\s0 make installed and it is not called 'make',
then do
.PP
.Vb 2
\& export MAKE=gmake
\& export GNUMAKE=gmake
.Ve
.PP
otherwise just do
.PP
.Vb 1
\& export MAKE=make
.Ve
.PP
\fIBuilding pkgconfig\fR
.IX Subsection "Building pkgconfig"
.PP
As mentioned above, without pkgconfig the whole build process will be lots
of pain and suffering, so make sure you have a copy on your system. If it is
not available natively, here is how to compile it.
.PP
.Vb 6
\& wget http://pkgconfig.freedesktop.org/releases/pkg\-config\-0.23.tar.gz
\& gunzip \-c pkg\-config\-0.23.tar.gz | tar xf \-
\& cd pkg\-config\-0.23
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC"
\& $MAKE
\& $MAKE install
.Ve
.PP
After installing pkgconfig in a custom directory, setting up the corresponding
environment variable will be helpful.
.PP
.Vb 1
\& export PKG_CONFIG=$INSTALL_DIR/bin/pkg\-config
.Ve
.PP
\fIBuilding zlib\fR
.IX Subsection "Building zlib"
.PP
Chances are very high that you already have that on your system ...
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/zlib\-1.2.3.tar.gz
\& gunzip \-c zlib\-1.2.3.tar.gz | tar xf \-
\& cd zlib\-1.2.3
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC" \-\-shared
\& $MAKE
\& $MAKE install
.Ve
.PP
\fIBuilding libpng\fR
.IX Subsection "Building libpng"
.PP
Libpng itself requires zlib to build, so we need to help a bit. If you
already have a copy of zlib on your system (which is very likely) you can
drop the settings of \s-1LDFLAGS\s0 and \s-1CPPFLAGS\s0. Note that the backslash (\e) at
the end of line 4 means that line 4 and line 5 are on one line.
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/libpng\-1.2.18.tar.gz
\& gunzip \-c libpng\-1.2.18.tar.gz | tar xf \-
\& cd libpng\-1.2.10
\& env CFLAGS="\-O3 \-fPIC" ./configure \-\-prefix=$INSTALL_DIR
\& $MAKE
\& $MAKE install
.Ve
.PP
\fIBuilding freetype\fR
.IX Subsection "Building freetype"
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/freetype\-2.3.5.tar.gz
\& gunzip \-c freetype\-2.3.5.tar.gz | tar xf \-
\& cd freetype\-2.3.5
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC"
\& $MAKE
\& $MAKE install
.Ve
.PP
If you run into problems building freetype on Solaris, you may want to try to
add the following at the start the configure line:
.PP
.Vb 1
\& env EGREP=egrep
.Ve
.PP
\fIBuilding LibXML2\fR
.IX Subsection "Building LibXML2"
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/libxml2\-2.6.32.tar.gz
\& gunzip \-c libxml2\-2.6.32.tar.gz | tar xf \-
\& cd libxml2\-2.6.32
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC"
\& $MAKE
\& $MAKE install
.Ve
.PP
\fIBuilding fontconfig\fR
.IX Subsection "Building fontconfig"
.PP
Note that fontconfig has a run time configuration file in INSTALL_DIR/etc you
may want to adjust that so that fontconfig finds the fonts on your system.
Run the fc-cache program to build the fontconfig cache after changing the
config file.
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/fontconfig\-2.4.2.tar.gz
\& gunzip \-c fontconfig\-2.4.2.tar.gz | tar xf \-
\& cd fontconfig\-2.4.2
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC" \-\-with\-freetype\-config=$INSTALL_DIR/bin/freetype\-config
\& $MAKE
\& $MAKE install
.Ve
.PP
\fIBuilding Pixman\fR
.IX Subsection "Building Pixman"
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/pixman\-0.10.0.tar.gz
\& gunzip \-c pixman\-0.10.0.tar.gz | tar xf \-
\& cd pixman\-0.10.0
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC"
\& $MAKE
\& $MAKE install
.Ve
.PP
\fIBuilding Cairo\fR
.IX Subsection "Building Cairo"
.PP
.Vb 11
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/cairo\-1.6.4.tar.gz
\& gunzip \-c cairo\-1.6.4.tar.gz | tar xf \-
\& cd cairo\-1.6.4
\& ./configure \-\-prefix=$INSTALL_DIR \e
\& \-\-enable\-xlib=no \e
\& \-\-enable\-xlib\-render=no \e
\& \-\-enable\-win32=no \e
\& CFLAGS="\-O3 \-fPIC"
\& $MAKE
\& $MAKE install
.Ve
.PP
When building on Solaris you may want todo
.PP
.Vb 5
\& ./configure \-\-prefix=$INSTALL_DIR \e
\& \-\-enable\-xlib=no \e
\& \-\-enable\-xlib\-render=no \e
\& \-\-enable\-win32=no \e
\& CFLAGS="\-O3 \-fPIC \-D_POSIX_PTHREAD_SEMANTICS"
.Ve
.PP
\fIBuilding Glib\fR
.IX Subsection "Building Glib"
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/glib\-2.15.4.tar.gz
\& gunzip \-c glib\-2.15.4.tar.gz | tar xf \-
\& cd glib\-2.15.4
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC"
\& $MAKE
\& $MAKE install
.Ve
.PP
\fIBuilding Pango\fR
.IX Subsection "Building Pango"
.PP
.Vb 7
\& cd $BUILD_DIR
\& wget http://oss.oetiker.ch/rrdtool/pub/libs/pango\-1.21.1.tar.bz2
\& bunzip2 \-c pango\-1.21.1.tar.bz2 | tar xf \-
\& cd pango\-1.21.1
\& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC" \-\-without\-x
\& $MAKE
\& $MAKE install
.Ve
.SS "Building rrdtool (second try)"
.IX Subsection "Building rrdtool (second try)"
Now all the dependent libraries are built and you can try again. This time
you tell configure where it should be looking for libraries and include
files. This is done via environment variables. Depending on the shell you
are running, the syntax for setting environment variables is different.
.PP
And finally try building again. We disable the python and tcl bindings
because it seems that a fair number of people have ill configured python and
tcl setups that would prevent RRDtool from building if they are included in
their current state.
.PP
.Vb 5
\& cd $BUILD_DIR/rrdtool\-1.4.4
\& ./configure \-\-prefix=$INSTALL_DIR \-\-disable\-tcl \-\-disable\-python
\& $MAKE clean
\& $MAKE
\& $MAKE install
.Ve
.PP
\&\s-1SOLARIS\s0 \s-1HINT:\s0 if you want to build the Perl module for the native Perl (the
one shipping with Solaris) you will need the Sun Forte compiler installed on
your box or you have to hand-tune bindings/perl\-shared/Makefile while
building!
.PP
Now go to \fI\f(CI$INSTALL_DIR\fI\fR\fB/share/rrdtool/examples/\fR and run them to see if
your build has been successful.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047515000081a400000000000000000000000152955235000018f10000011f00010018ffffffffffffffff0000002800000000root/usr/local/share/man/man1/rrdinfo.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDINFO 1"
.TH RRDINFO 1 "2009-04-20" "1.4.4" "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"
rrdinfo \- extract header information from an RRD
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBinfo\fR \fIfilename\fR
[\fB\-\-daemon\fR\ \fIaddress\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBinfo\fR function prints the header information from an \s-1RRD\s0 in
a parsing friendly format.
.PP
Check rrdcreate if you are uncertain about the meaning of the
individual keys.
.IP "\fIfilename\fR" 8
.IX Item "filename"
The name of the \fB\s-1RRD\s0\fR you want to examine.
.IP "\fB\-\-daemon\fR \fIaddress\fR" 8
.IX Item "--daemon address"
Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
to the server before reading the \s-1RRD\s0 files. This allows \fBrrdtool\fR to return
fresh data even if the daemon is configured to cache values for a long time.
For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
.Sp
.Vb 1
\& rrdtool info \-\-daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd
.Ve
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This is the output generated by running \fBinfo\fR on a simple \s-1RRD\s0 which
contains two data sources and one \s-1RRA\s0. Note that the number after the
\&\fIlast_update\fR keyword is in seconds since 1970. The string \fBNaN\fR
stands for \fI*UNKNOWN*\fR data. In the example it means that this \s-1RRD\s0
has neither minimum nor maximum values defined for either of its
data sources.
.PP
.Vb 10
\& filename = "random.rrd"
\& rrd_version = "0001"
\& step = 300
\& last_update = 955892996
\& header_size = 2872
\& ds[a].type = "GAUGE"
\& ds[a].minimal_heartbeat = 600
\& ds[a].min = NaN
\& ds[a].max = NaN
\& ds[a].last_ds = "UNKN"
\& ds[a].value = 2.1824421548e+04
\& ds[a].unknown_sec = 0
\& ds[b].type = "GAUGE"
\& ds[b].minimal_heartbeat = 600
\& ds[b].min = NaN
\& ds[b].max = NaN
\& ds[b].last_ds = "UNKN"
\& ds[b].value = 3.9620838224e+03
\& ds[b].unknown_sec = 0
\& rra[0].cf = "AVERAGE"
\& rra[0].pdp_per_row = 1
\& rra[0].cdp_prep[0].value = nan
\& rra[0].cdp_prep[0].unknown_datapoints = 0
\& rra[0].cdp_prep[1].value = nan
\& rra[0].cdp_prep[1].unknown_datapoints = 0
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ info\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047518000081a400000000000000000000000152955235000014b90000011f00010018ffffffffffffffff0000002a00000000root/usr/local/share/man/man1/rrdresize.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDRESIZE 1"
.TH RRDRESIZE 1 "2009-02-21" "1.4.4" "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"
rrdresize \- alters the size of an RRA and creates a new .rrd file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBresize\fR \fIfilename\fR \fIrra-num\fR \fB\s-1GROW\s0\fR\fI|\fR\fB\s-1SHRINK\s0\fR \fIrows\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBresize\fR function is used to modify the number of rows in
an \fB\s-1RRA\s0\fR.
.IP "\fIfilename\fR" 8
.IX Item "filename"
the name of the \fB\s-1RRD\s0\fR you want to alter.
.IP "\fIrra-num\fR" 8
.IX Item "rra-num"
the \fB\s-1RRA\s0\fR you want to alter. You can find the number using \fBrrdtool info\fR.
.IP "\fB\s-1GROW\s0\fR" 8
.IX Item "GROW"
used if you want to add extra rows to an \s-1RRA\s0. The extra rows will be inserted
as the rows that are oldest.
.IP "\fB\s-1SHRINK\s0\fR" 8
.IX Item "SHRINK"
used if you want to remove rows from an \s-1RRA\s0. The rows that will be removed
are the oldest rows.
.IP "\fIrows\fR" 8
.IX Item "rows"
the number of rows you want to add or remove.
.SH "NOTES"
.IX Header "NOTES"
The new .rrd file, with the modified RRAs, is written to the file
\&\fBresize.rrd\fR in the current directory. \fBThe original .rrd file is not
modified\fR.
.PP
It is possible to abuse this tool and get strange results
by first removing some rows and then reinserting the same amount (effectively
clearing them to be Unknown). You may thus end up with unknown data in one
\&\s-1RRA\s0 while at the same timestamp this data is available in another \s-1RRA\s0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alex van den Bogaerdt
0707010004750d000081a400000000000000000000000152955235000011dc0000011f00010018ffffffffffffffff0000002900000000root/usr/local/share/man/man1/rrdfirst.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDFIRST 1"
.TH RRDFIRST 1 "2008-03-15" "1.4.4" "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"
rrdfirst \- Return the date of the first data sample in an RRA within an RRD
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBfirst\fR \fIfilename\fR [\fI\-\-rraindex number\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBfirst\fR function returns the \s-1UNIX\s0 timestamp of the first data
sample entered into the specified \s-1RRA\s0 of the \s-1RRD\s0 file.
.IP "\fIfilename\fR" 8
.IX Item "filename"
The name of the \fB\s-1RRD\s0\fR that contains the data.
.IP "\fI\-\-rraindex number\fR" 8
.IX Item "--rraindex number"
The index number of the \fB\s-1RRA\s0\fR that is to be examined. If not specified, the
index defaults to zero. \fB\s-1RRA\s0\fR index numbers can be determined through
\&\fBrrdtool info\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Burton Strauss
07070100047509000081a40000000000000000000000015295523500002de40000011f00010018ffffffffffffffff0000002700000000root/usr/local/share/man/man1/rrdcgi.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDCGI 1"
.TH RRDCGI 1 "2008-12-22" "1.4.4" "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"
rrdcgi \- Create web pages containing RRD graphs based on templates
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`#!/path/to/\*(C'\fR\fBrrdcgi\fR [\fB\-\-filter\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBrrdcgi\fR is a sort of very limited script interpreter. Its purpose
is to run as a cgi-program and parse a web page template containing special
.Ve
.Sp
might give you the name of the remote user given you are using
some sort of access control on the directory.
.IP "\s-1RRD::GOODFOR\s0 \fIseconds\fR" 8
.IX Item "RRD::GOODFOR seconds"
Specify the number of seconds this page should remain valid. This will prompt
the rrdcgi to output a Last-Modified, an Expire and if the number of
seconds is \fInegative\fR a Refresh header.
.IP "\s-1RRD::INCLUDE\s0 \fIfilename\fR" 8
.IX Item "RRD::INCLUDE filename"
Include the contents of the specified file into the page returned from the cgi.
.IP "\s-1RRD::SETENV\s0 \fIvariable\fR \fIvalue\fR" 8
.IX Item "RRD::SETENV variable value"
If you want to present your graphs in another time zone than your own, you
could use
.Sp
.Vb 1
\&
.Ve
.Sp
to make sure everything is presented in Universal Time. Note that the
values permitted to \s-1TZ\s0 depend on your \s-1OS\s0.
.IP "\s-1RRD::SETVAR\s0 \fIvariable\fR \fIvalue\fR" 8
.IX Item "RRD::SETVAR variable value"
Analog to \s-1SETENV\s0 but for local variables.
.IP "\s-1RRD::GETVAR\s0 \fIvariable\fR" 8
.IX Item "RRD::GETVAR variable"
Analog to \s-1GETENV\s0 but for local variables.
.IP "\s-1RRD::TIME::LAST\s0 \fIrrd-file\fR \fIstrftime-format\fR" 8
.IX Item "RRD::TIME::LAST rrd-file strftime-format"
This gets replaced by the last modification time of the selected \s-1RRD\s0. The
time is \fIstrftime\fR\-formatted with the string specified in the second argument.
.IP "\s-1RRD::TIME::NOW\s0 \fIstrftime-format\fR" 8
.IX Item "RRD::TIME::NOW strftime-format"
This gets replaced by the current time of day. The time is
\&\fIstrftime\fR\-formatted with the string specified in the argument.
.Sp
Note that if you return : (colons) from your strftime format you may
have to escape them using \e if the time is to be used as an argument
to a \s-1GRAPH\s0 command.
.IP "\s-1RRD::TIME::STRFTIME\s0 \fISTART|END\fR \fIstart-spec\fR \fIend-spec\fR \fIstrftime-format\fR" 8
.IX Item "RRD::TIME::STRFTIME START|END start-spec end-spec strftime-format"
This gets replaced by a strftime-formatted time using the format
\&\fIstrftime-format\fR on either \fIstart-spec\fR or \fIend-spec\fR depending on
whether \fI\s-1START\s0\fR or \fI\s-1END\s0\fR is specified. Both \fIstart-spec\fR and \fIend-spec\fR
must be supplied as either could be relative to the other. This is intended
to allow pretty titles on graphs with times that are easier for non RRDtool
folks to figure out than \*(L"\-2weeks\*(R".
.Sp
Note that again, if you return : (colon) from your strftime format,
you may have to escape them using \e if the time is to be used as an
argument to a \s-1GRAPH\s0 command.
.IP "\s-1RRD::GRAPH\s0 \fIrrdgraph arguments\fR" 8
.IX Item "RRD::GRAPH rrdgraph arguments"
This tag creates the \s-1RRD\s0 graph defined by its argument and then is
replaced by an appropriate tag referring to the graph.
The \fB\-\-lazy\fR option in \s-1RRD\s0 graph can be used to make sure that graphs
are only regenerated when they are out of date. The arguments
to the \fB\s-1RRD::GRAPH\s0\fR tag work as described in the \fBrrdgraph\fR manual page.
.Sp
Use the \fB\-\-lazy\fR option in your \s-1RRD::GRAPH\s0 tags, to reduce the load
on your server. This option makes sure that graphs are only regenerated when
the old ones are out of date.
.Sp
If you do not specify your own \fB\-\-imginfo\fR format, the following will
be used:
.Sp
.Vb 1
\&
.Ve
.Sp
Note that \f(CW%s\fR stands for the filename part of the graph generated, all
directories given in the \s-1PNG\s0 file argument will get dropped.
.IP "\s-1RRD::PRINT\s0 \fInumber\fR" 8
.IX Item "RRD::PRINT number"
If the preceding \fB\s-1RRD::GRAPH\s0\fR tag contained and \fB\s-1PRINT\s0\fR arguments,
then you can access their output with this tag. The \fInumber\fR argument refers to the
number of the \fB\s-1PRINT\s0\fR argument. This first \fB\s-1PRINT\s0\fR has \fInumber\fR 0.
.IP "\s-1RRD::INTERNAL\s0 " 8
.IX Item "RRD::INTERNAL "
This tag gets replaced by an internal var. Currently these vars are known:
\&\s-1VERSION\s0, \s-1COMPILETIME\s0.
These vars represent the compiled-in values.
.SH "EXAMPLE 1"
.IX Header "EXAMPLE 1"
The example below creates a web pages with a single \s-1RRD\s0 graph.
.PP
.Vb 9
\& #!/usr/local/bin/rrdcgi
\&
\& RRDCGI Demo
\&
\&

RRDCGI Example Page

\&

\&
\&
\&

\&
\&
.Ve
.SH "EXAMPLE 2"
.IX Header "EXAMPLE 2"
This script is slightly more elaborate, it allows you to run it from
a form which sets \s-1RRD_NAME\s0. \s-1RRD_NAME\s0 is then used to select which \s-1RRD\s0
you want to use as source for your graph.
.PP
.Vb 10
\& #!/usr/local/bin/rrdcgi
\&
\& RRDCGI Demo
\&
\&

RRDCGI test Page

\& \*(Aq
\& \-\-lazy \-\-start \-1d \-\-end now
\& DEF:http_src=/.../rrds/test.rrd:http_src:AVERAGE
\& AREA:http_src#00ff00:http_src
\& >
\&
\&
.Ve
.PP
Note 1: Replace /.../ with the relevant directories
.PP
Note 2: The SRC=/.../pngs should be paths from the view of the
webserver/browser
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
0707010004751a000081a400000000000000000000000152955235000021050000011f00010018ffffffffffffffff0000002b00000000root/usr/local/share/man/man1/rrdthreads.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDTHREADS 1"
.TH RRDTHREADS 1 "2008-06-08" "1.4.4" "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"
rrdthreads \- Provisions for linking the RRD library to use in multi\-threaded programs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Using librrd in multi-threaded programs requires some extra
precautions, as the \s-1RRD\s0 library in its original form was not
thread-safe at all. This document describes requirements and pitfalls
on the way to use the multi-threaded version of librrd in your own
programs. It also gives hints for future \s-1RRD\s0 development to keep the
library thread-safe.
.PP
Currently only some \s-1RRD\s0 operations are implemented in a thread-safe
way. They all end in the usual "\f(CW\*(C`_r\*(C'\fR" suffix.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In order to use librrd in multi-threaded programs you must:
.IP "\(bu" 4
Link with \fIlibrrd_th\fR instead of \fIlibrrd\fR (use \f(CW\*(C`\-lrrd_th\*(C'\fR when
linking)
.IP "\(bu" 4
Use the "\f(CW\*(C`_r\*(C'\fR" functions instead of the normal API-functions
.IP "\(bu" 4
Do not use any at-style time specifications. Parsing of such time
specifications is terribly non-thread-safe.
.IP "\(bu" 4
Never use non *\f(CW\*(C`_r\*(C'\fR functions unless it is explicitly documented that
the function is tread-safe.
.IP "\(bu" 4
Every thread \s-1SHOULD\s0 call \f(CW\*(C`rrd_get_context()\*(C'\fR before its first call to
any \f(CW\*(C`librrd_th\*(C'\fR function in order to set up thread specific data. This
is not strictly required, but it is the only way to test if memory
allocation can be done by this function. Otherwise the program may die
with a \s-1SIGSEGV\s0 in a low-memory situation.
.IP "\(bu" 4
Always call \f(CW\*(C`rrd_error_clear()\*(C'\fR before any call to the
library. Otherwise the call might fail due to some earlier error.
.SS "\s-1NOTES\s0 \s-1FOR\s0 \s-1RRD\s0 \s-1CONTRIBUTORS\s0"
.IX Subsection "NOTES FOR RRD CONTRIBUTORS"
Some precautions must be followed when developing \s-1RRD\s0 from now on:
.IP "\(bu" 4
Only use thread-safe functions in library code. Many often used libc
functions aren't thread-safe. Take care in the following
situations or when using the following library functions:
.RS 4
.IP "\(bu" 4
Direct calls to \f(CW\*(C`strerror()\*(C'\fR must be avoided: use \f(CW\*(C`rrd_strerror()\*(C'\fR
instead, it provides a per-thread error message.
.IP "\(bu" 4
The \f(CW\*(C`getpw*\*(C'\fR, \f(CW\*(C`getgr*\*(C'\fR, \f(CW\*(C`gethost*\*(C'\fR function families (and some more
\&\f(CW\*(C`get*\*(C'\fR functions) are not thread-safe: use the *\f(CW\*(C`_r\*(C'\fR variants
.IP "\(bu" 4
Time functions: \f(CW\*(C`asctime\*(C'\fR, \f(CW\*(C`ctime\*(C'\fR, \f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR: use
*\f(CW\*(C`_r\*(C'\fR variants
.IP "\(bu" 4
\&\f(CW\*(C`strtok\*(C'\fR: use \f(CW\*(C`strtok_r\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`tmpnam\*(C'\fR: use \f(CW\*(C`tmpnam_r\*(C'\fR
.IP "\(bu" 4
Many others (lookup documentation)
.RE
.RS 4
.RE
.IP "\(bu" 4
A header file named \fIrrd_is_thread_safe.h\fR is provided
that works with the \s-1GNU\s0 C\-preprocessor to \*(L"poison\*(R" some of the most
common non-thread-safe functions using the \f(CW\*(C`#pragma GCC poison\*(C'\fR
directive. Just include this header in source files you want to keep
thread-safe.
.IP "\(bu" 4
Do not introduce global variables!
.Sp
If you really, really have to use a global variable you may add a new
field to the \f(CW\*(C`rrd_context\*(C'\fR structure and modify \fIrrd_error.c\fR,
\&\fIrrd_thread_safe.c\fR and \fIrrd_non_thread_safe.c\fR
.IP "\(bu" 4
Do not use \f(CW\*(C`getopt\*(C'\fR or \f(CW\*(C`getopt_long\*(C'\fR in *\f(CW\*(C`_r\*(C'\fR (neither directly nor
indirectly).
.Sp
\&\f(CW\*(C`getopt\*(C'\fR uses global variables and behaves badly in a multi-threaded
application when called concurrently. Instead provide a *_r function
taking all options as function parameters. You may provide argc and
**argv arguments for variable length argument lists. See
\&\f(CW\*(C`rrd_update_r\*(C'\fR as an example.
.IP "\(bu" 4
Do not use the \f(CW\*(C`rrd_parsetime\*(C'\fR function!
.Sp
It uses lots of global variables. You may use it in functions not designed
to be thread-safe, like in functions wrapping the \f(CW\*(C`_r\*(C'\fR version of some
operation (e.g., \f(CW\*(C`rrd_create\*(C'\fR, but not in \f(CW\*(C`rrd_create_r\*(C'\fR)
.SS "\s-1CURRENTLY\s0 \s-1IMPLEMENTED\s0 \s-1THREAD\s0 \s-1SAFE\s0 \s-1FUNCTIONS\s0"
.IX Subsection "CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS"
Currently there exist thread-safe variants of \f(CW\*(C`rrd_update\*(C'\fR,
\&\f(CW\*(C`rrd_create\*(C'\fR, \f(CW\*(C`rrd_dump\*(C'\fR, \f(CW\*(C`rrd_info\*(C'\fR, \f(CW\*(C`rrd_last\*(C'\fR, and \f(CW\*(C`rrd_fetch\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Peter Stamfest
07070100047516000081a400000000000000000000000152955235000014490000011f00010018ffffffffffffffff0000002800000000root/usr/local/share/man/man1/rrdlast.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDLAST 1"
.TH RRDLAST 1 "2008-09-25" "1.4.4" "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"
rrdlast \- Return the date of the last data sample in an RRD
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBlast\fR \fIfilename\fR
[\fB\-\-daemon\fR\ \fIaddress\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBlast\fR function returns the \s-1UNIX\s0 timestamp of the most recent
update of the \s-1RRD\s0.
.IP "\fIfilename\fR" 8
.IX Item "filename"
The name of the \fB\s-1RRD\s0\fR that contains the data.
.IP "\fB\-\-daemon\fR \fIaddress\fR" 8
.IX Item "--daemon address"
Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
to the server before reading the \s-1RRD\s0 files. This allows \fBrrdtool\fR to return
fresh data even if the daemon is configured to cache values for a long time.
For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
.Sp
.Vb 1
\& rrdtool last \-\-daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ last\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "AUTHOR"
.IX Header "AUTHOR"
Russ Wright
0707010004751c000081a400000000000000000000000152955235000030f60000011f00010018ffffffffffffffff0000002800000000root/usr/local/share/man/man1/rrdtune.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDTUNE 1"
.TH RRDTUNE 1 "2008-03-15" "1.4.4" "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"
rrdtune \- Modify some basic properties of a Round Robin Database
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBtune\fR \fIfilename\fR
[\fB\-\-heartbeat\fR|\fB\-h\fR\ \fIds-name\fR:\fIheartbeat\fR]
[\fB\-\-minimum\fR|\fB\-i\fR\ \fIds-name\fR:\fImin\fR]
[\fB\-\-maximum\fR|\fB\-a\fR\ \fIds-name\fR:\fImax\fR]
[\fB\-\-data\-source\-type\fR|\fB\-d\fR\ \fIds-name\fR:\fI\s-1DST\s0\fR]
[\fB\-\-data\-source\-rename\fR|\fB\-r\fR\ \fIold-name\fR:\fInew-name\fR]
[\fB\-\-deltapos\fR\ \fIscale-value\fR]
[\fB\-\-deltaneg\fR\ \fIscale-value\fR]
[\fB\-\-failure\-threshold\fR\ \fIfailure-threshold\fR]
[\fB\-\-window\-length\fR\ \fIwindow-length\fR]
[\fB\-\-alpha\fR\ \fIadaption-parameter\fR]
[\fB\-\-beta\fR\ \fIadaption-parameter\fR]
[\fB\-\-gamma\fR\ \fIadaption-parameter\fR]
[\fB\-\-gamma\-deviation\fR\ \fIadaption-parameter\fR]
[\fB\-\-smoothing\-window\fR\ \fIfraction-of-season\fR]
[\fB\-\-smoothing\-window\-deviation\fR\ \fIfraction-of-season\fR]
[\fB\-\-aberrant\-reset\fR\ \fIds-name\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The tune option allows you to alter some of the basic configuration
values stored in the header area of a Round Robin Database (\fB\s-1RRD\s0\fR).
.PP
One application of the \fBtune\fR function is to relax the
validation rules on an \fB\s-1RRD\s0\fR. This allows to fill a new \fB\s-1RRD\s0\fR with
data available in larger intervals than what you would normally want
to permit. Be very careful with tune operations for \s-1COMPUTE\s0 data sources.
Setting the \fImin\fR, \fImax\fR, and \fIheartbeat\fR for a \s-1COMPUTE\s0 data source
without changing the data source type to a non-COMPUTE \fB\s-1DST\s0\fR \s-1WILL\s0 corrupt
the data source header in the \fB\s-1RRD\s0\fR.
.PP
A second application of the \fBtune\fR function is to set or alter parameters
used by the specialized function \fBRRAs\fR for aberrant behavior detection.
.IP "\fIfilename\fR" 8
.IX Item "filename"
The name of the \fB\s-1RRD\s0\fR you want to tune.
.IP "\fB\-\-heartbeat\fR|\fB\-h\fR\ \fIds-name\fR:\fIheartbeat\fR" 8
.IX Item "--heartbeat|-hds-name:heartbeat"
modify the \fIheartbeat\fR of a data source. By setting this to a high
value the \s-1RRD\s0 will accept things like one value per day.
.IP "\fB\-\-minimum\fR|\fB\-i\fR\ \fIds-name\fR:\fImin\fR" 8
.IX Item "--minimum|-ids-name:min"
alter the minimum value acceptable as input from the data source.
Setting \fImin\fR to 'U' will disable this limit.
.IP "\fB\-\-maximum\fR|\fB\-a\fR\ \fIds-name\fR:\fImax\fR" 8
.IX Item "--maximum|-ads-name:max"
alter the maximum value acceptable as input from the data source.
Setting \fImax\fR to 'U' will disable this limit.
.IP "\fB\-\-data\-source\-type\fR|\fB\-d\fR\ \fIds-name\fR:\fI\s-1DST\s0\fR" 8
.IX Item "--data-source-type|-dds-name:DST"
alter the type \fB\s-1DST\s0\fR of a data source.
.IP "\fB\-\-data\-source\-rename\fR|\fB\-r\fR\ \fIold-name\fR:\fInew-name\fR" 8
.IX Item "--data-source-rename|-rold-name:new-name"
rename a data source.
.IP "\fB\-\-deltapos\fR\ \fIscale-value\fR" 8
.IX Item "--deltaposscale-value"
Alter the deviation scaling factor for the upper bound of the
confidence band used internally to calculate violations for the
\&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR. The default value is 2. Note that this parameter is
not related to graphing confidence bounds which must be specified as a
\&\s-1CDEF\s0 argument to generate a graph with confidence bounds. The graph
scale factor need not to agree with the value used internally by the
\&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR.
.IP "\fB\-\-deltaneg\fR\ \fIscale-value\fR" 8
.IX Item "--deltanegscale-value"
Alter the deviation scaling factor for the lower bound of the confidence band
used internally to calculate violations for the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. The default
value is 2. As with \fB\-\-deltapos\fR, this argument is unrelated to the scale
factor chosen when graphing confidence bounds.
.IP "\fB\-\-failure\-threshold\fR\ \fIfailure-threshold\fR" 8
.IX Item "--failure-thresholdfailure-threshold"
Alter the number of confidence bound violations that constitute a failure for
purposes of the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. This must be an integer less than or equal to
the window length of the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. This restriction is not verified by
the tune option, so one can reset failure-threshold and window-length
simultaneously. Setting this option will reset the count of violations to 0.
.IP "\fB\-\-window\-length\fR\ \fIwindow-length\fR" 8
.IX Item "--window-lengthwindow-length"
Alter the number of time points in the temporal window for determining
failures. This must be an integer greater than or equal to the window
length of the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR and less than or equal to 28. Setting
this option will reset the count of violations to 0.
.IP "\fB\-\-alpha\fR\ \fIadaption-parameter\fR" 8
.IX Item "--alphaadaption-parameter"
Alter the intercept adaptation parameter for the Holt-Winters
forecasting algorithm. This parameter must be between 0 and 1.
.IP "\fB\-\-beta\fR\ \fIadaption-parameter\fR" 8
.IX Item "--betaadaption-parameter"
Alter the slope adaptation parameter for the Holt-Winters forecasting
algorithm. This parameter must be between 0 and 1.
.IP "\fB\-\-gamma\fR\ \fIadaption-parameter\fR" 8
.IX Item "--gammaadaption-parameter"
Alter the seasonal coefficient adaptation parameter for the \s-1SEASONAL\s0
\&\fB\s-1RRA\s0\fR. This parameter must be between 0 and 1.
.IP "\fB\-\-gamma\-deviation\fR\ \fIadaption-parameter\fR" 8
.IX Item "--gamma-deviationadaption-parameter"
Alter the seasonal deviation adaptation parameter for the \s-1DEVSEASONAL\s0
\&\fB\s-1RRA\s0\fR. This parameter must be between 0 and 1.
.IP "\fB\-\-smoothing\-window\fR\ \fIfraction-of-season\fR" 8
.IX Item "--smoothing-windowfraction-of-season"
Alter the size of the smoothing window for the \s-1SEASONAL\s0 \fB\s-1RRA\s0\fR. This must
be between 0 and 1.
.IP "\fB\-\-smoothing\-window\-deviation\fR\ \fIfraction-of-season\fR" 8
.IX Item "--smoothing-window-deviationfraction-of-season"
Alter the size of the smoothing window for the \s-1DEVSEASONAL\s0 \fB\s-1RRA\s0\fR. This must
be between 0 and 1.
.IP "\fB\-\-aberrant\-reset\fR\ \fIds-name\fR" 8
.IX Item "--aberrant-resetds-name"
This option causes the aberrant behavior detection algorithm to reset
for the specified data source; that is, forget all it is has learnt so far.
Specifically, for the \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0 \fB\s-1RRA\s0\fR, it sets the intercept and
slope coefficients to unknown. For the \s-1SEASONAL\s0 \fB\s-1RRA\s0\fR, it sets all seasonal
coefficients to unknown. For the \s-1DEVSEASONAL\s0 \fB\s-1RRA\s0\fR, it sets all seasonal
deviation coefficients to unknown. For the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR, it erases the
violation history. Note that reset does not erase past predictions
(the values of the \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0 \fB\s-1RRA\s0\fR), predicted deviations (the
values of the \s-1DEVPREDICT\s0 \fB\s-1RRA\s0\fR), or failure history (the values of the
\&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR). This option will function even if not all the listed
\&\fBRRAs\fR are present.
.Sp
Due to the implementation of this option, there is an indirect impact on
other data sources in the \s-1RRD\s0. A smoothing algorithm is applied to
\&\s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 values on a periodic basis. During bootstrap
initialization this smoothing is deferred. For efficiency, the implementation
of smoothing is not data source specific. This means that utilizing
reset for one data source will delay running the smoothing algorithm
for all data sources in the file. This is unlikely to have serious
consequences, unless the data being collected for the non-reset data sources
is unusually volatile during the reinitialization period of the reset
data source.
.Sp
Use of this tuning option is advised when the behavior of the data source
time series changes in a drastic and permanent manner.
.SH "EXAMPLE 1"
.IX Header "EXAMPLE 1"
\&\f(CW\*(C`rrdtool tune data.rrd \-h in:100000 \-h out:100000 \-h through:100000\*(C'\fR
.PP
Set the minimum required heartbeat for data sources 'in', 'out'
and 'through' to 10'000 seconds which is a little over one day in data.rrd.
This would allow to feed old data from \s-1MRTG\-2\s0.0 right into
RRDtool without generating *UNKNOWN* entries.
.SH "EXAMPLE 2"
.IX Header "EXAMPLE 2"
\&\f(CW\*(C`rrdtool tune monitor.rrd \-\-window\-length 5 \-\-failure\-threshold 3\*(C'\fR
.PP
If the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR is implicitly created, the default
window-length is 9 and the default failure-threshold is 7. This
command now defines a failure as 3 or more violations in a temporal
window of 5 time points.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047508000081a400000000000000000000000152955235000077270000011f00010018ffffffffffffffff0000002a00000000root/usr/local/share/man/man1/rrdcached.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDCACHED 1"
.TH RRDCACHED 1 "2010-03-22" "1.4.4" "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"
rrdcached \- Data caching daemon for rrdtool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdcached\fR
[\fB\-P\fR\ \fIpermissions\fR]
[\fB\-l\fR\ \fIaddress\fR]
[\fB\-s\fR\ \fIgroup\fR]
[\fB\-w\fR\ \fItimeout\fR]
[\fB\-z\fR\ \fIdelay\fR]
[\fB\-f\fR\ \fItimeout\fR]
[\fB\-p\fR\ \fIpid_file\fR]
[\fB\-t\fR\ \fIwrite_threads\fR]
[\fB\-j\fR\ \fIjournal_dir\fR]
[\-F]
[\-g]
[\fB\-b\fR\ \fIbase_dir\fR\ [\fB\-B\fR]]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBrrdcached\fR is a daemon that receives updates to existing \s-1RRD\s0 files,
accumulates them and, if enough have been received or a defined time has
passed, writes the updates to the \s-1RRD\s0 file. A \fIflush\fR command may be used to
force writing of values to disk, so that graphing facilities and similar can
work with up-to-date data.
.PP
The daemon was written with big setups in mind. Those setups usually run into
\&\s-1IO\s0\ related problems sooner or later for reasons that are beyond the scope
of this document. Check the wiki at the RRDtool homepage for details. Also
check \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" below before using this daemon! A detailed
description of how the daemon operates can be found in the \*(L"\s-1HOW\s0 \s-1IT\s0 \s-1WORKS\s0\*(R"
section below.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-l\fR \fIaddress\fR" 4
.IX Item "-l address"
Tells the daemon to bind to \fIaddress\fR and accept incoming connections on that
socket. If \fIaddress\fR begins with \f(CW\*(C`unix:\*(C'\fR, everything following that prefix is
interpreted as the path to a \s-1UNIX\s0 domain socket. Otherwise the address or node
name are resolved using \f(CW\*(C`getaddrinfo()\*(C'\fR.
.Sp
For network sockets, a port may be specified by using the form
\&\f(CW\*(C`\f(CB[\f(CW\f(CIaddress\f(CW\f(CB]:\f(CW\f(CIport\f(CW\*(C'\fR. If the address is an IPv4 address or a fully
qualified domain name (i.\ e. the address contains at least one dot
(\f(CW\*(C`.\*(C'\fR)), the square brackets can be omitted, resulting in the (simpler)
\&\f(CW\*(C`\f(CIaddress\f(CW\f(CB:\f(CW\f(CIport\f(CW\*(C'\fR pattern. The default port is \fB42217/udp\fR. If you
specify a network socket, it is mandatory to read the
\&\*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" section.
.Sp
The following formats are accepted. Please note that the address of the \s-1UNIX\s0
domain socket \fBmust\fR start with a slash in the second case!
.Sp
.Vb 5
\& unix:
\& /
\&
\& []:
\& :
.Ve
.Sp
If the \fB\-l\fR option is not specified the default address,
\&\f(CW\*(C`unix:/tmp/rrdcached.sock\*(C'\fR, will be used.
.IP "\fB\-s\fR \fIgroup_name\fR|\fIgid\fR" 4
.IX Item "-s group_name|gid"
Set the group permissions of a \s-1UNIX\s0 domain socket. The option accepts either
a numeric group id or group name. That group will then have both read and write
permissions (the socket will have file permissions 0750) for the socket and,
therefore, is able to send commands to the daemon. This
may be useful in cases where you cannot easily run all \s-1RRD\s0 processes with the same
user privileges (e.g. graph generating \s-1CGI\s0 scripts that typically run in the
permission context of the web server).
.Sp
This option affects the \fIfollowing\fR \s-1UNIX\s0 socket addresses (the following
\&\fB\-l\fR options), i.e., you may specify different settings for different
sockets.
.Sp
The default is not to change ownership or permissions of the socket and, thus,
use the system default.
.IP "\fB\-m\fR \fImode\fR" 4
.IX Item "-m mode"
Set the file permissions of a \s-1UNIX\s0 domain socket. The option accepts an octal
number representing the bit pattern for the mode (see \fIchmod\fR\|(1) for
details).
.Sp
Please note that not all systems honor this setting. On Linux, read/write
permissions are required to connect to a \s-1UNIX\s0 socket. However, many
BSD-derived systems ignore permissions for \s-1UNIX\s0 sockets. See \fIunix\fR\|(7) for
details.
.Sp
This option affects the \fIfollowing\fR \s-1UNIX\s0 socket addresses (the following
\&\fB\-l\fR options), i.e., you may specify different settings for different
sockets.
.Sp
The default is not to change ownership or permissions of the socket and, thus,
use the system default.
.IP "\fB\-P\fR \fIcommand\fR[,\fIcommand\fR[,...]]" 4
.IX Item "-P command[,command[,...]]"
Specifies the commands accepted via a network socket. This allows
administrators of \fIRRDCacheD\fR to control the actions accepted from various
sources.
.Sp
The arguments given to the \fB\-P\fR option is a comma separated list of commands.
For example, to allow the \f(CW\*(C`FLUSH\*(C'\fR and \f(CW\*(C`PENDING\*(C'\fR commands one could specify:
.Sp
.Vb 1
\& rrdcached \-P FLUSH,PENDING $MORE_ARGUMENTS
.Ve
.Sp
The \fB\-P\fR option affects the \fIfollowing\fR socket addresses (the following \fB\-l\fR
options). In the following example, only the IPv4 network socket (address
\&\f(CW10.0.0.1\fR) will be restricted to the \f(CW\*(C`FLUSH\*(C'\fR and \f(CW\*(C`PENDING\*(C'\fR commands:
.Sp
.Vb 1
\& rrdcached \-l unix:/some/path \-P FLUSH,PENDING \-l 10.0.0.1
.Ve
.Sp
A complete list of available commands can be found in the section
\&\*(L"Valid Commands\*(R" below. There are two minor special exceptions:
.RS 4
.IP "\(bu" 4
The \f(CW\*(C`HELP\*(C'\fR and \f(CW\*(C`QUIT\*(C'\fR commands are always allowed.
.IP "\(bu" 4
If the \f(CW\*(C`BATCH\*(C'\fR command is accepted, the \fB.\fR\ command will automatically
be accepted, too.
.RE
.RS 4
.Sp
Please also read \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" below.
.RE
.IP "\fB\-w\fR \fItimeout\fR" 4
.IX Item "-w timeout"
Data is written to disk every \fItimeout\fR seconds. If this option is not
specified the default interval of 300\ seconds will be used.
.IP "\fB\-z\fR \fIdelay\fR" 4
.IX Item "-z delay"
If specified, rrdcached will delay writing of each \s-1RRD\s0 for a random number
of seconds in the range\ [0,\fIdelay\fR). This will avoid too many
writes being queued simultaneously. This value should be no greater than
the value specified in \fB\-w\fR. By default, there is no delay.
.IP "\fB\-f\fR \fItimeout\fR" 4
.IX Item "-f timeout"
Every \fItimeout\fR seconds the entire cache is searched for old values which are
written to disk. This only concerns files to which updates have stopped, so
setting this to a high value, such as 3600\ seconds, is acceptable in most
cases. This timeout defaults to 3600\ seconds.
.IP "\fB\-p\fR \fIfile\fR" 4
.IX Item "-p file"
Sets the name and location of the PID-file. If not specified, the default,
\&\f(CW\*(C`\f(CI$localststedir\f(CW/run/rrdcached.pid\*(C'\fR will be used.
.IP "\fB\-t\fR \fIwrite_threads\fR" 4
.IX Item "-t write_threads"
Specifies the number of threads used for writing \s-1RRD\s0 files. The default
is\ 4. Increasing this number will allow rrdcached to have more
simultaneous I/O requests into the kernel. This may allow the kernel to
re-order disk writes, resulting in better disk throughput.
.IP "\fB\-j\fR \fIdir\fR" 4
.IX Item "-j dir"
Write updates to a journal in \fIdir\fR. In the event of a program or system
crash, this will allow the daemon to write any updates that were pending
at the time of the crash.
.Sp
On startup, the daemon will check for journal files in this directory. If
found, all updates therein will be read into memory before the daemon
starts accepting new connections.
.Sp
The journal will be rotated with the same frequency as the flush timer
given by \fB\-f\fR.
.Sp
When journaling is enabled, the daemon will use a fast shutdown procedure.
Rather than flushing all files to disk, it will make sure the journal is
properly written and exit immediately. Although the \s-1RRD\s0 data files are
not fully up-to-date, no information is lost; all pending updates will be
replayed from the journal next time the daemon starts up.
.Sp
To disable fast shutdown, use the \fB\-F\fR option.
.IP "\fB\-F\fR" 4
.IX Item "-F"
\&\s-1ALWAYS\s0 flush all updates to the \s-1RRD\s0 data files when the daemon is shut
down, regardless of journal setting.
.IP "\fB\-g\fR" 4
.IX Item "-g"
Run in the foreground. The daemon will not \fIfork()\fR.
.IP "\fB\-b\fR \fIdir\fR" 4
.IX Item "-b dir"
The daemon will change into a specific directory at startup. All files passed
to the daemon, that are specified by a \fBrelative\fR path, will be interpreted
to be relative to this directory. If not given the default, \f(CW\*(C`/tmp\*(C'\fR, will be
used.
.Sp
.Vb 10
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& ! Command line ! File updated !
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& ! foo.rrd ! /tmp/foo.rrd !
\& ! foo/bar.rrd ! /tmp/foo/bar.rrd !
\& ! /var/lib/rrd/foo.rrd ! /var/lib/rrd/foo.rrd !
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& Paths given on the command line and paths actually
\& updated by the daemon, assuming the base directory
\& "/tmp".
.Ve
.Sp
\&\fB\s-1WARNING:\s0\fR The paths up to and including the base directory \fB\s-1MUST\s0 \s-1NOT\s0 \s-1BE\s0\fR
symbolic links. In other words, if the base directory is
specified as:
.Sp
.Vb 1
\& \-b /base/dir/somewhere
.Ve
.Sp
\&... then \fB\s-1NONE\s0\fR of the following should be symbolic links:
.Sp
.Vb 3
\& /base
\& /base/dir
\& /base/dir/somewhere
.Ve
.IP "\fB\-B\fR" 4
.IX Item "-B"
Only permit writes into the base directory specified in \fB\-b\fR (and any
sub-directories). This does \fB\s-1NOT\s0\fR detect symbolic links. Paths
containing \f(CW\*(C`../\*(C'\fR will also be blocked.
.SH "AFFECTED RRDTOOL COMMANDS"
.IX Header "AFFECTED RRDTOOL COMMANDS"
The following commands may be made aware of the \fBrrdcached\fR using the command
line argument \fB\-\-daemon\fR or the environment variable \fB\s-1RRDCACHED_ADDRESS\s0\fR:
.IP "\(bu" 4
dump
.IP "\(bu" 4
fetch
.IP "\(bu" 4
flush
.IP "\(bu" 4
graph
.IP "\(bu" 4
graphv
.IP "\(bu" 4
info
.IP "\(bu" 4
last
.IP "\(bu" 4
lastupdate
.IP "\(bu" 4
update
.IP "\(bu" 4
xport
.PP
The \fBupdate\fR command can send values to the daemon instead of writing them to
the disk itself. All other commands can send a \fB\s-1FLUSH\s0\fR command (see below) to
the daemon before accessing the files, so they work with up-to-date data even
if the cache timeout is large.
.SH "ERROR REPORTING"
.IX Header "ERROR REPORTING"
The daemon reports errors in one of two ways: During startup, error messages
are printed to \f(CW\*(C`STDERR\*(C'\fR. One of the steps when starting up is to fork to the
background and closing \f(CW\*(C`STDERR\*(C'\fR \- after this writing directly to the user is
no longer possible. Once this has happened, the daemon will send log messages
to the system logging daemon using \fIsyslog\fR\|(3). The facility used is
\&\f(CW\*(C`LOG_DAEMON\*(C'\fR.
.SH "HOW IT WORKS"
.IX Header "HOW IT WORKS"
When receiving an update, \fBrrdcached\fR does not write to disk but looks for an
entry for that file in its internal tree. If not found, an entry is created
including the current time (called \*(L"First\*(R" in the diagram below). This time is
\&\fBnot\fR the time specified on the command line but the time the operating system
considers to be \*(L"now\*(R". The value and time of the value (called \*(L"Time\*(R" in the
diagram below) are appended to the tree node.
.PP
When appending a value to a tree node, it is checked whether it's time to write
the values to disk. Values are written to disk if
\&\f(CW\*(C`now()\ \-\ First\ >=\ timeout\*(C'\fR, where \f(CW\*(C`timeout\*(C'\fR is the timeout specified
using the \fB\-w\fR option, see \*(L"\s-1OPTIONS\s0\*(R". If the values are \*(L"old enough\*(R" they
will be enqueued in the \*(L"update queue\*(R", i.\ e. they will be appended to
the linked list shown below. Because the tree nodes and the elements of the
linked list are the same data structures in memory, any update to a file that
has already been enqueued will be written with the next write to the \s-1RRD\s0 file,
too.
.PP
A separate \*(L"update thread\*(R" constantly dequeues the first element in the update
queue and writes all its values to the appropriate file. So as long as the
update queue is not empty files are written at the highest possible rate.
.PP
Since the timeout of files is checked only when new values are added to the
file, \*(L"dead\*(R" files, i.\ e. files that are not updated anymore, would never
be written to disk. Therefore, every now and then, controlled by the \fB\-f\fR
option, the entire tree is walked and all \*(L"old\*(R" values are enqueued. Since this
only affects \*(L"dead\*(R" files and walking the tree is relatively expensive, you
should set the \*(L"flush interval\*(R" to a reasonably high value. The default is
3600\ seconds (one hour).
.PP
The downside of caching values is that they won't show up in graphs generated
from the \s-1RRD\s0\ files. To get around this, the daemon provides the \*(L"flush
command\*(R" to flush specific files. This means that the file is inserted at the
\&\fBhead\fR of the update queue or moved there if it is already enqueued. The flush
command will return only after the file's pending updates have been written
to disk.
.PP
.Vb 10
\& +\-\-\-\-\-\-+ +\-\-\-\-\-\-+ +\-\-\-\-\-\-+
\& ! head ! ! root ! ! tail !
\& +\-\-\-+\-\-+ +\-\-\-+\-\-+ +\-\-\-+\-\-+
\& ! /\e !
\& ! / \e !
\& ! /\e /\e !
\& ! /\e/\e \e \`\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- ... \-\-\-\-\-\-\-\-, !
\& V / \`\-\-\-\-\-\-\-, ! V
\& +\-\-\-+\-\-\-\-+\-\-\-+ +\-\-\-\-\-\-+\-\-\-\-\-+ +\-\-\-+\-\-\-\-+\-\-\-+
\& ! File: foo ! ! File: bar ! ! File: qux !
\& ! First: 101 ! ! First: 119 ! ! First: 180 !
\& ! Next:&bar \-+\-\-\->! Next:&... \-+\-\-\-> ... \-\-\->! Next:NULL !
\& | Prev:NULL !\*(C'\fR (\*(L"line feed\*(R").
.PP
After the connection has been established, the client is expected to send a
\&\*(L"command\*(R". A command consists of the command keyword, possibly some arguments,
and a terminating newline character. For a list of commands, see
\&\*(L"Valid Commands\*(R" below.
.PP
Example:
.PP
.Vb 1
\& FLUSH /tmp/foo.rrd
.Ve
.PP
The daemon answers with a line consisting of a status code and a short status
message, separated by one or more space characters. A negative status code
signals an error, a positive status code or zero signal success. If the status
code is greater than zero, it indicates the number of lines that follow the
status line.
.PP
Examples:
.PP
.Vb 1
\& 0 Success
\&
\& 2 Two lines follow
\& This is the first line
\& And this is the second line
.Ve
.SS "Valid Commands"
.IX Subsection "Valid Commands"
The following commands are understood by the daemon:
.IP "\fB\s-1FLUSH\s0\fR \fIfilename\fR" 4
.IX Item "FLUSH filename"
Causes the daemon to put \fIfilename\fR to the \fBhead\fR of the update queue
(possibly moving it there if the node is already enqueued). The answer will be
sent \fBafter\fR the node has been dequeued.
.IP "\fB\s-1FLUSHALL\s0\fR" 4
.IX Item "FLUSHALL"
Causes the daemon to start flushing \s-1ALL\s0 pending values to disk. This
returns immediately, even though the writes may take a long time.
.IP "\fB\s-1PENDING\s0\fR \fIfilename\fR" 4
.IX Item "PENDING filename"
Shows any \*(L"pending\*(R" updates for a file, in order. The updates shown have
not yet been written to the underlying \s-1RRD\s0 file.
.IP "\fB\s-1FORGET\s0\fR \fIfilename\fR" 4
.IX Item "FORGET filename"
Removes \fIfilename\fR from the cache. Any pending updates \fB\s-1WILL\s0 \s-1BE\s0 \s-1LOST\s0\fR.
.IP "\fB\s-1QUEUE\s0\fR" 4
.IX Item "QUEUE"
Shows the files that are on the output queue. Returns zero or more lines
in the following format, where is the number of values
to be written for the :
.Sp
.Vb 1
\&
.Ve
.IP "\fB\s-1HELP\s0\fR [\fIcommand\fR]" 4
.IX Item "HELP [command]"
Returns a short usage message. If no command is given, or \fIcommand\fR is
\&\fB\s-1HELP\s0\fR, a list of commands supported by the daemon is returned. Otherwise a
short description, possibly containing a pointer to a manual page, is returned.
Obviously, this is meant for interactive usage and the format in which the
commands and usage summaries are returned is not well defined.
.IP "\fB\s-1STATS\s0\fR" 4
.IX Item "STATS"
Returns a list of metrics which can be used to measure the daemons performance
and check its status. For a description of the values returned, see
\&\*(L"Performance Values\*(R" below.
.Sp
The format in which the values are returned is similar to many other line based
protocols: Each value is printed on a separate line, each consisting of the
name of the value, a colon, one or more spaces and the actual value.
.Sp
Example:
.Sp
.Vb 10
\& 9 Statistics follow
\& QueueLength: 0
\& UpdatesReceived: 30
\& FlushesReceived: 2
\& UpdatesWritten: 13
\& DataSetsWritten: 390
\& TreeNodesNumber: 13
\& TreeDepth: 4
\& JournalBytes: 190
\& JournalRotate: 0
.Ve
.IP "\fB\s-1UPDATE\s0\fR \fIfilename\fR \fIvalues\fR [\fIvalues\fR ...]" 4
.IX Item "UPDATE filename values [values ...]"
Adds more data to a filename. This is \fBthe\fR operation the daemon was designed
for, so describing the mechanism again is unnecessary. Read \*(L"\s-1HOW\s0 \s-1IT\s0 \s-1WORKS\s0\*(R"
above for a detailed explanation.
.Sp
Note that rrdcached only accepts absolute timestamps in the update values.
Updates strings like \*(L"N:1:2:3\*(R" are automatically converted to absolute
time by the \s-1RRD\s0 client library before sending to rrdcached.
.IP "\fB\s-1WROTE\s0\fR \fIfilename\fR" 4
.IX Item "WROTE filename"
This command is written to the journal after a file is successfully
written out to disk. It is used during journal replay to determine which
updates have already been applied. It is \fIonly\fR valid in the journal; it
is not accepted from the other command channels.
.IP "\fB\s-1BATCH\s0\fR" 4
.IX Item "BATCH"
This command initiates the bulk load of multiple commands. This is
designed for installations with extremely high update rates, since it
permits more than one command to be issued per \fIread()\fR and \fIwrite()\fR.
.Sp
All commands are executed just as they would be if given individually,
except for output to the user. Messages indicating success are
suppressed, and error messages are delayed until the client is finished.
.Sp
Command processing is finished when the client sends a dot (\*(L".\*(R") on its
own line. After the client has finished, the server responds with an
error count and the list of error messages (if any). Each error messages
indicates the number of the command to which it corresponds, and the error
message itself. The first user command after \fB\s-1BATCH\s0\fR is command number one.
.Sp
.Vb 9
\& client: BATCH
\& server: 0 Go ahead. End with dot \*(Aq.\*(Aq on its own line.
\& client: UPDATE x.rrd 1223661439:1:2:3
.PP
Both \fBrrdcached\fR and this manual page have been written by Florian.
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
kevin brintnall
0707010004751b000081a400000000000000000000000152955235000043210000011f00010018ffffffffffffffff0000002800000000root/usr/local/share/man/man1/rrdtool.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDTOOL 1"
.TH RRDTOOL 1 "2009-10-14" "1.4.4" "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"
rrdtool \- Round Robin Database Tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fB\-\fR [workdir]| \fIfunction\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "\s-1OVERVIEW\s0"
.IX Subsection "OVERVIEW"
It is pretty easy to gather status information from all sorts of
things, ranging from the temperature in your office to the number of
octets which have passed through the \s-1FDDI\s0 interface of your
router. But it is not so trivial to store this data in an efficient and
systematic manner. This is where \fBRRDtool\fR comes in handy. It lets you
\&\fIlog and analyze\fR the data you gather from all kinds of data-sources
(\fB\s-1DS\s0\fR). The data analysis part of RRDtool is based on the ability to
quickly generate graphical representations of the data values
collected over a definable time period.
.PP
In this man page you will find general information on the design and
functionality of the Round Robin Database Tool (RRDtool). For a more
detailed description of how to use the individual functions of
\&\fBRRDtool\fR check the corresponding man page.
.PP
For an introduction to the usage of RRDtool make sure you consult the
rrdtutorial.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
While the man pages talk of command line switches you have to set in
order to make \fBRRDtool\fR work it is important to note that
\&\fBRRDtool\fR can be remotely controlled through a set of pipes. This
saves a considerable amount of startup time when you plan to make
\&\fBRRDtool\fR do a lot of things quickly. Check the section on Remote_Control
further down. There is also a number of language bindings
for RRDtool which allow you to use it directly from Perl, python, Tcl,
\&\s-1PHP\s0, etc.
.IP "\fBcreate\fR" 8
.IX Item "create"
Set up a new Round Robin Database (\s-1RRD\s0). Check rrdcreate.
.IP "\fBupdate\fR" 8
.IX Item "update"
Store new data values into an \s-1RRD\s0. Check rrdupdate.
.IP "\fBupdatev\fR" 8
.IX Item "updatev"
Operationally equivalent to \fBupdate\fR except for output. Check rrdupdate.
.IP "\fBgraph\fR" 8
.IX Item "graph"
Create a graph from data stored in one or several RRDs. Apart from
generating graphs, data can also be extracted to stdout. Check rrdgraph.
.IP "\fBdump\fR" 8
.IX Item "dump"
Dump the contents of an \s-1RRD\s0 in plain \s-1ASCII\s0. In connection with restore
you can use this to move an \s-1RRD\s0 from one computer architecture to
another. Check rrddump.
.IP "\fBrestore\fR" 8
.IX Item "restore"
Restore an \s-1RRD\s0 in \s-1XML\s0 format to a binary \s-1RRD\s0. Check rrdrestore
.IP "\fBfetch\fR" 8
.IX Item "fetch"
Get data for a certain time period from a \s-1RRD\s0. The graph function
uses fetch to retrieve its data from an \s-1RRD\s0. Check rrdfetch.
.IP "\fBtune\fR" 8
.IX Item "tune"
Alter setup of an \s-1RRD\s0. Check rrdtune.
.IP "\fBlast\fR" 8
.IX Item "last"
Find the last update time of an \s-1RRD\s0. Check rrdlast.
.IP "\fBinfo\fR" 8
.IX Item "info"
Get information about an \s-1RRD\s0. Check rrdinfo.
.IP "\fBrrdresize\fR" 8
.IX Item "rrdresize"
Change the size of individual RRAs. This is dangerous! Check rrdresize.
.IP "\fBxport\fR" 8
.IX Item "xport"
Export data retrieved from one or several RRDs. Check rrdxport.
.IP "\fBflushcached\fR" 8
.IX Item "flushcached"
Flush the values for a specific \s-1RRD\s0 file from memory. Check rrdflushcached.
.IP "\fBrrdcgi\fR" 8
.IX Item "rrdcgi"
This is a standalone tool for producing \s-1RRD\s0 graphs on the fly. Check
rrdcgi.
.SS "\s-1HOW\s0 \s-1DOES\s0 \s-1RRDTOOL\s0 \s-1WORK\s0?"
.IX Subsection "HOW DOES RRDTOOL WORK?"
.IP "Data Acquisition" 8
.IX Item "Data Acquisition"
When monitoring the state of a system, it is convenient to have the
data available at a constant time interval. Unfortunately, you may not
always be able to fetch data at exactly the time you want
to. Therefore \fBRRDtool\fR lets you update the log file at any time you
want. It will automatically interpolate the value of the data-source
(\fB\s-1DS\s0\fR) at the latest official time-slot (interval) and write this
interpolated value to the log. The original value you have supplied is
stored as well and is also taken into account when interpolating the
next log entry.
.IP "Consolidation" 8
.IX Item "Consolidation"
You may log data at a 1 minute interval, but you might also be
interested to know the development of the data over the last year. You
could do this by simply storing the data in 1 minute intervals for the
whole year. While this would take considerable disk space it would
also take a lot of time to analyze the data when you wanted to create
a graph covering the whole year. \fBRRDtool\fR offers a solution to this
problem through its data consolidation feature. When setting up an
Round Robin Database (\fB\s-1RRD\s0\fR), you can define at which interval this
consolidation should occur, and what consolidation function (\fB\s-1CF\s0\fR)
(average, minimum, maximum, total, last) should be used to build the
consolidated values (see rrdcreate). You can define any number of
different consolidation setups within one \fB\s-1RRD\s0\fR. They will all be
maintained on the fly when new data is loaded into the \fB\s-1RRD\s0\fR.
.IP "Round Robin Archives" 8
.IX Item "Round Robin Archives"
Data values of the same consolidation setup are stored into Round
Robin Archives (\fB\s-1RRA\s0\fR). This is a very efficient manner to store data
for a certain amount of time, while using a known and constant amount
of storage space.
.Sp
It works like this: If you want to store 1'000 values in 5 minute
interval, \fBRRDtool\fR will allocate space for 1'000 data values and a
header area. In the header it will store a pointer telling which slots
(value) in the storage area was last written to. New values are
written to the Round Robin Archive in, you guessed it, a round robin
manner. This automatically limits the history to the last 1'000 values
(in our example). Because you can define several \fB\s-1RRA\s0\fRs within a
single \fB\s-1RRD\s0\fR, you can setup another one, for storing 750 data values
at a 2 hour interval, for example, and thus keep a log for the last
two months at a lower resolution.
.Sp
The use of \fB\s-1RRA\s0\fRs guarantees that the \fB\s-1RRD\s0\fR does not grow over
time and that old data is automatically eliminated. By using the
consolidation feature, you can still keep data for a very long time,
while gradually reducing the resolution of the data along the time
axis.
.Sp
Using different consolidation functions (\fB\s-1CF\s0\fR) allows you to store
exactly the type of information that actually interests you: the maximum
one minute traffic on the \s-1LAN\s0, the minimum temperature of your wine cellar,
the total minutes of down time, etc.
.IP "Unknown Data" 8
.IX Item "Unknown Data"
As mentioned earlier, the \fB\s-1RRD\s0\fR stores data at a constant
interval. Sometimes it may happen that no new data is available when a
value has to be written to the \fB\s-1RRD\s0\fR. Data acquisition may not be
possible for one reason or other. With \fBRRDtool\fR you can handle these
situations by storing an \fI*UNKNOWN*\fR value into the database. The
value '\fI*UNKNOWN*\fR' is supported through all the functions of the
tool. When consolidating a data set, the amount of \fI*UNKNOWN*\fR data
values is accounted for and when a new consolidated value is ready to
be written to its Round Robin Archive (\fB\s-1RRA\s0\fR), a validity check is
performed to make sure that the percentage of unknown values in the
data point is above a configurable level. If not, an \fI*UNKNOWN*\fR value
will be written to the \fB\s-1RRA\s0\fR.
.IP "Graphing" 8
.IX Item "Graphing"
\&\fBRRDtool\fR allows you to generate reports in numerical and
graphical form based on the data stored in one or several
\&\fB\s-1RRD\s0\fRs. The graphing feature is fully configurable. Size, color and
contents of the graph can be defined freely. Check rrdgraph
for more information on this.
.IP "Aberrant Behavior Detection" 8
.IX Item "Aberrant Behavior Detection"
by Jake Brutlag
.Sp
\&\fBRRDtool\fR provides the building blocks for near real-time aberrant
behavior detection. These components include:
.RS 8
.IP "\(bu" 4
An algorithm for predicting the value of a time series one time step
into the future.
.IP "\(bu" 4
A measure of deviation between predicted and observed values.
.IP "\(bu" 4
A mechanism to decide if and when an observed value or sequence of
observed values is \fItoo deviant\fR from the predicted value(s).
.RE
.RS 8
.Sp
Here is a brief explanation of these components:
.Sp
The Holt-Winters time series forecasting algorithm is an on-line (or
incremental) algorithm that adaptively predicts future observations in
a time series. Its forecast is the sum of three components: a baseline
(or intercept), a linear trend over time (or slope), and a seasonal
coefficient (a periodic effect, such as a daily cycle). There is one
seasonal coefficient for each time point in the period (cycle). After
a value is observed, each of these components is updated via
exponential smoothing. This means that the algorithm \*(L"learns\*(R" from
past values and uses them to predict the future. The rate of
adaptation is governed by 3 parameters, alpha (intercept), beta
(slope), and gamma (seasonal). The prediction can also be viewed as a
smoothed value for the time series.
.Sp
The measure of deviation is a seasonal weighted absolute
deviation. The term \fIseasonal\fR means deviation is measured separately
for each time point in the seasonal cycle. As with Holt-Winters
forecasting, deviation is predicted using the measure computed from
past values (but only at that point in the seasonal cycle). After the
value is observed, the algorithm learns from the observed value via
exponential smoothing. Confidence bands for the observed time series
are generated by scaling the sequence of predicted deviation values
(we usually think of the sequence as a continuous line rather than a
set of discrete points).
.Sp
Aberrant behavior (a potential failure) is reported whenever the
number of times the observed value violates the confidence bands meets
or exceeds a specified threshold within a specified temporal window
(e.g. 5 violations during the past 45 minutes with a value observed
every 5 minutes).
.Sp
This functionality is embedded in a set of related \fBRRAs\fR. In
particular, a \s-1FAILURES\s0 \fB\s-1RRA\s0\fR logs potential failures. With these data
you could, for example, use a front-end application to \fBRRDtool\fR to
initiate real-time alerts.
.Sp
For a detailed description on how to set this up, see rrdcreate.
.RE
.SS "\s-1REMOTE\s0 \s-1CONTROL\s0"
.IX Subsection "REMOTE CONTROL"
When you start \fBRRDtool\fR with the command line option '\fB\-\fR' it waits
for input via standard input (\s-1STDIN\s0). With this feature you can
improve performance by attaching \fBRRDtool\fR to another process (\s-1MRTG\s0
is one example) through a set of pipes. Over these pipes \fBRRDtool\fR
accepts the same arguments as on the command line and some special
commands like \fBquit, cd, mkdir\fR and \fBls\fR. For detailed help on the
server commands type:
.PP
.Vb 1
\& rrdtool help cd|mkdir|pwd|ls|quit
.Ve
.PP
When a command is completed, RRDtool will print the string '\f(CW\*(C`OK\*(C'\fR',
followed by timing information of the form \fBu:\fR\fIusertime\fR
\&\fBs:\fR\fIsystemtime\fR. Both values are the running totals of seconds since
RRDtool was started. If an error occurs, a line of the form '\f(CW\*(C`ERROR:\*(C'\fR
\&\fIDescription of error\fR' will be printed instead. \fBRRDtool\fR will not abort,
unless something really serious happens. If
a \fBworkdir\fR is specified and the \s-1UID\s0 is 0, RRDtool will do a chroot to that
workdir. If the \s-1UID\s0 is not 0, RRDtool only changes the current directory to
\&\fBworkdir\fR.
.SS "\s-1RRD\s0 Server"
.IX Subsection "RRD Server"
If you want to create a RRD-Server, you must choose a \s-1TCP/IP\s0 Service
number and add them to \fI/etc/services\fR like this:
.PP
.Vb 1
\& rrdsrv 13900/tcp # RRD server
.Ve
.PP
Attention: the \s-1TCP\s0 port 13900 isn't officially registered for
rrdsrv. You can use any unused port in your services file, but the
server and the client system must use the same port, of course.
.PP
With this configuration you can add RRDtool as meta-server to
\&\fI/etc/inetd.conf\fR. For example:
.PP
.Vb 1
\& rrdsrv stream tcp nowait root /opt/rrd/bin/rrdtool rrdtool \- /var/rrd
.Ve
.PP
Don't forget to create the database directory /var/rrd and
reinitialize your inetd.
.PP
If all was setup correctly, you can access the server with Perl
sockets, tools like netcat, or in a quick interactive test by using
\&'telnet localhost rrdsrv'.
.PP
\&\fB\s-1NOTE:\s0\fR that there is no authentication with this feature! Do not setup
such a port unless you are sure what you are doing.
.SH "RRDCACHED, THE CACHING DAEMON"
.IX Header "RRDCACHED, THE CACHING DAEMON"
For very big setups, updating thousands of \s-1RRD\s0 files often becomes a serious \s-1IO\s0
problem. If you run into such problems, you might want to take a look at
rrdcached, a caching daemon for RRDtool which may help you lessen the
stress on your disks.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune, rrdlast, rrdxport,
rrdflushcached, rrdcached
.SH "BUGS"
.IX Header "BUGS"
Bugs? Features!
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
0707010004750b000081a400000000000000000000000152955235000019d40000011f00010018ffffffffffffffff0000002800000000root/usr/local/share/man/man1/rrddump.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDDUMP 1"
.TH RRDDUMP 1 "2009-10-14" "1.4.4" "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"
rrddump \- dump the contents of an RRD to XML format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBdump\fR \fIfilename.rrd\fR [\fIfilename.xml\fR]
[\fB\-\-header\fR|\fB\-h\fR\ {none,xsd,dtd}]
[\fB\-\-no\-header\fR]
[\fB\-\-daemon\fR\ \fIaddress\fR]
>\ \fIfilename.xml\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBdump\fR function writes the contents of an \fB\s-1RRD\s0\fR in human
readable (?) \s-1XML\s0 format to a file or to stdout. This format can
be read by rrdrestore. Together they allow you to transfer your
files from one computer architecture to another as well to
manipulate the contents of an \fB\s-1RRD\s0\fR file in a somewhat more
convenient manner.
.IP "\fIfilename.rrd\fR" 8
.IX Item "filename.rrd"
The name of the \fB\s-1RRD\s0\fR you want to dump.
.IP "\fIfilename.xml\fR" 8
.IX Item "filename.xml"
The (optional) filename that you want to write the \s-1XML\s0 output to.
If not specified, the \s-1XML\s0 will be printed to stdout.
.IP "\fB\-\-header\fR|\fB\-h\fR {none,xsd,dtd}" 8
.IX Item "--header|-h {none,xsd,dtd}"
By default RRDtool will add a dtd header to the xml file. Here
you can customize this to and xsd header or no header at all.
.IP "\fB\-\-no\-header\fR" 8
.IX Item "--no-header"
A shortcut for \-\-header=none.
.Sp
If you want to restore the dump with RRDtool 1.2 you should use the
\&\-\-no\-header option since 1.2 can not deal with xml headers.
.IP "\fB\-\-daemon\fR \fIaddress\fR" 8
.IX Item "--daemon address"
Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
to the server before reading the \s-1RRD\s0 files. This allows \fBrrdtool\fR to return
fresh data even if the daemon is configured to cache values for a long time.
For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
.Sp
.Vb 1
\& rrdtool dump \-\-daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To transfer an \s-1RRD\s0 between architectures, follow these steps:
.IP "1." 4
On the same system where the \s-1RRD\s0 was created, use \fBrrdtool\fR \fBdump\fR
to export the data to \s-1XML\s0 format.
.IP "2." 4
Transfer the \s-1XML\s0 dump to the target system.
.IP "3." 4
Run \fBrrdtool\fR \fBrestore\fR to create a new \s-1RRD\s0 from the \s-1XML\s0 dump. See
\&\fBrrdrestore\fR for details.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ dump\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047504000081a40000000000000000000000015295523500009afb0000011f00010018ffffffffffffffff0000002d00000000root/usr/local/share/man/man1/cdeftutorial.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "CDEFTUTORIAL 1"
.TH CDEFTUTORIAL 1 "2010-05-10" "1.4.4" "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"
cdeftutorial \- Alex van den Bogaerdt's CDEF tutorial
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Intention of this document: to provide some examples of the commonly
used parts of RRDtool's \s-1CDEF\s0 language.
.PP
If you think some important feature is not explained properly, and if
adding it to this document would benefit most users, please do ask me
to add it. I will then try to provide an answer in the next release
of this tutorial. No feedback equals no changes! Additions to
this document are also welcome. \*(-- Alex van den Bogaerdt
.SS "Why this tutorial?"
.IX Subsection "Why this tutorial?"
One of the powerful parts of RRDtool is its ability to do all sorts
of calculations on the data retrieved from its databases. However,
RRDtool's many options and syntax make it difficult for the average
user to understand. The manuals are good at explaining what these
options do; however they do not (and should not) explain in detail
why they are useful. As with my RRDtool tutorial: if you want a
simple document in simple language you should read this tutorial.
If you are happy with the official documentation, you may find this
document too simple or even boring. If you do choose to read this
tutorial, I also expect you to have read and fully understand my
other tutorial.
.SS "More reading"
.IX Subsection "More reading"
If you have difficulties with the way I try to explain it please read
Steve Rader's rpntutorial. It may help you understand how this all works.
.SH "What are CDEFs?"
.IX Header "What are CDEFs?"
When retrieving data from an \s-1RRD\s0, you are using a \*(L"\s-1DEF\s0\*(R" to work with
that data. Think of it as a variable that changes over time (where
time is the x\-axis). The value of this variable is what is found in
the database at that particular time and you can't do any
modifications on it. This is what CDEFs are for: they takes values
from DEFs and perform calculations on them.
.SH "Syntax"
.IX Header "Syntax"
.Vb 2
\& DEF:var_name_1=some.rrd:ds_name:CF
\& CDEF:var_name_2=RPN_expression
.Ve
.PP
You first define \*(L"var_name_1\*(R" to be data collected from data source
\&\*(L"ds_name\*(R" found in \s-1RRD\s0 \*(L"some.rrd\*(R" with consolidation function \*(L"\s-1CF\s0\*(R".
.PP
Assume the ifInOctets \s-1SNMP\s0 counter is saved in mrtg.rrd as the \s-1DS\s0 \*(L"in\*(R".
Then the following \s-1DEF\s0 defines a variable for the average of that
data source:
.PP
.Vb 1
\& DEF:inbytes=mrtg.rrd:in:AVERAGE
.Ve
.PP
Say you want to display bits per second (instead of bytes per second
as stored in the database.) You have to define a calculation
(hence \*(L"\s-1CDEF\s0\*(R") on variable \*(L"inbytes\*(R" and use that variable (inbits)
instead of the original:
.PP
.Vb 1
\& CDEF:inbits=inbytes,8,*
.Ve
.PP
This tells RRDtool to multiply inbytes by eight to get inbits. I'll
explain later how this works. In the graphing or printing functions,
you can now use inbits where you would use inbytes otherwise.
.PP
Note that the variable name used in the \s-1CDEF\s0 (inbits) must not be the
same as the variable named in the \s-1DEF\s0 (inbytes)!
.SH "RPN-expressions"
.IX Header "RPN-expressions"
\&\s-1RPN\s0 is short-hand for Reverse Polish Notation. It works as follows.
You put the variables or numbers on a stack. You also put operations
(things-to-do) on the stack and this stack is then processed. The result
will be placed on the stack. At the end, there should be exactly one
number left: the outcome of the series of operations. If there is not
exactly one number left, RRDtool will complain loudly.
.PP
Above multiplication by eight will look like:
.IP "1." 4
Start with an empty stack
.IP "2." 4
Put the content of variable inbytes on the stack
.IP "3." 4
Put the number eight on the stack
.IP "4." 4
Put the operation multiply on the stack
.IP "5." 4
Process the stack
.IP "6." 4
Retrieve the value from the stack and put it in variable inbits
.PP
We will now do an example with real numbers. Suppose the variable
inbytes would have value 10, the stack would be:
.IP "1." 4
||
.IP "2." 4
|10|
.IP "3." 4
|10|8|
.IP "4." 4
|10|8|*|
.IP "5." 4
|80|
.IP "6." 4
||
.PP
Processing the stack (step 5) will retrieve one value from the stack
(from the right at step 4). This is the operation multiply and this
takes two values off the stack as input. The result is put back on the
stack (the value 80 in this case). For multiplication the order doesn't
matter, but for other operations like subtraction and division it does.
Generally speaking you have the following order:
.PP
.Vb 1
\& y = A \- B \-\-> y=minus(A,B) \-\-> CDEF:y=A,B,\-
.Ve
.PP
This is not very intuitive (at least most people don't think so). For
the function f(A,B) you reverse the position of \*(L"f\*(R", but you do not
reverse the order of the variables.
.SH "Converting your wishes to RPN"
.IX Header "Converting your wishes to RPN"
First, get a clear picture of what you want to do. Break down the problem
in smaller portions until they cannot be split anymore. Then it is rather
simple to convert your ideas into \s-1RPN\s0.
.PP
Suppose you have several RRDs and would like to add up some counters in
them. These could be, for instance, the counters for every \s-1WAN\s0 link you
are monitoring.
.PP
You have:
.PP
.Vb 3
\& router1.rrd with link1in link2in
\& router2.rrd with link1in link2in
\& router3.rrd with link1in link2in
.Ve
.PP
Suppose you would like to add up all these counters, except for link2in
inside router2.rrd. You need to do:
.PP
(in this example, \*(L"router1.rrd:link1in\*(R" means the \s-1DS\s0 link1in inside the
\&\s-1RRD\s0 router1.rrd)
.PP
.Vb 7
\& router1.rrd:link1in
\& router1.rrd:link2in
\& router2.rrd:link1in
\& router3.rrd:link1in
\& router3.rrd:link2in
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +
\& (outcome of the sum)
.Ve
.PP
As a mathematical function, this could be written:
.PP
\&\f(CW\*(C`add(router1.rrd:link1in , router1.rrd:link2in , router2.rrd:link1in , router3.rrd:link1in , router3.rrd:link2.in)\*(C'\fR
.PP
With RRDtool and \s-1RPN\s0, first, define the inputs:
.PP
.Vb 5
\& DEF:a=router1.rrd:link1in:AVERAGE
\& DEF:b=router1.rrd:link2in:AVERAGE
\& DEF:c=router2.rrd:link1in:AVERAGE
\& DEF:d=router3.rrd:link1in:AVERAGE
\& DEF:e=router3.rrd:link2in:AVERAGE
.Ve
.PP
Now, the mathematical function becomes: \f(CW\*(C`add(a,b,c,d,e)\*(C'\fR
.PP
In \s-1RPN\s0, there's no operator that sums more than two values so you need
to do several additions. You add a and b, add c to the result, add d
to the result and add e to the result.
.PP
.Vb 5
\& push a: a stack contains the value of a
\& push b and add: b,+ stack contains the result of a+b
\& push c and add: c,+ stack contains the result of a+b+c
\& push d and add: d,+ stack contains the result of a+b+c+d
\& push e and add: e,+ stack contains the result of a+b+c+d+e
.Ve
.PP
What was calculated here would be written down as:
.PP
.Vb 1
\& ( ( ( (a+b) + c) + d) + e) >
.Ve
.PP
This is in \s-1RPN:\s0 \f(CW\*(C`CDEF:result=a,b,+,c,+,d,+,e,+\*(C'\fR
.PP
This is correct but it can be made more clear to humans. It does
not matter if you add a to b and then add c to the result or first
add b to c and then add a to the result. This makes it possible to
rewrite the \s-1RPN\s0 into \f(CW\*(C`CDEF:result=a,b,c,d,e,+,+,+,+\*(C'\fR which is
evaluated differently:
.PP
.Vb 10
\& push value of variable a on the stack: a
\& push value of variable b on the stack: a b
\& push value of variable c on the stack: a b c
\& push value of variable d on the stack: a b c d
\& push value of variable e on the stack: a b c d e
\& push operator + on the stack: a b c d e +
\& and process it: a b c P (where P == d+e)
\& push operator + on the stack: a b c P +
\& and process it: a b Q (where Q == c+P)
\& push operator + on the stack: a b Q +
\& and process it: a R (where R == b+Q)
\& push operator + on the stack: a R +
\& and process it: S (where S == a+R)
.Ve
.PP
As you can see the \s-1RPN\s0 expression \f(CW\*(C`a,b,c,d,e,+,+,+,+,+\*(C'\fR will evaluate in
\&\f(CW\*(C`((((d+e)+c)+b)+a)\*(C'\fR and it has the same outcome as \f(CW\*(C`a,b,+,c,+,d,+,e,+\*(C'\fR.
This is called the commutative law of addition,
but you may forget this right away, as long as you remember what it
means.
.PP
Now look at an expression that contains a multiplication:
.PP
First in normal math: \f(CW\*(C`let result = a+b*c\*(C'\fR. In this case you can't
choose the order yourself, you have to start with the multiplication
and then add a to it. You may alter the position of b and c, you must
not alter the position of a and b.
.PP
You have to take this in consideration when converting this expression
into \s-1RPN\s0. Read it as: \*(L"Add the outcome of b*c to a\*(R" and then it is
easy to write the \s-1RPN\s0 expression: \f(CW\*(C`result=a,b,c,*,+\*(C'\fR
Another expression that would return the same: \f(CW\*(C`result=b,c,*,a,+\*(C'\fR
.PP
In normal math, you may encounter something like \*(L"a*(b+c)\*(R" and this
can also be converted into \s-1RPN\s0. The parenthesis just tell you to first
add b and c, and then multiply a with the result. Again, now it is
easy to write it in \s-1RPN:\s0 \f(CW\*(C`result=a,b,c,+,*\*(C'\fR. Note that this is very
similar to one of the expressions in the previous paragraph, only the
multiplication and the addition changed places.
.PP
When you have problems with \s-1RPN\s0 or when RRDtool is complaining, it's
usually a good thing to write down the stack on a piece of paper
and see what happens. Have the manual ready and pretend to be RRDtool.
Just do all the math by hand to see what happens, I'm sure this will
solve most, if not all, problems you encounter.
.SH "Some special numbers"
.IX Header "Some special numbers"
.SS "The unknown value"
.IX Subsection "The unknown value"
Sometimes collecting your data will fail. This can be very common,
especially when querying over busy links. RRDtool can be configured
to allow for one (or even more) unknown value(s) and calculate the missing
update. You can, for instance, query your device every minute. This is
creating one so called \s-1PDP\s0 or primary data point per minute. If you
defined your \s-1RRD\s0 to contain an \s-1RRA\s0 that stores 5\-minute values, you need
five of those PDPs to create one \s-1CDP\s0 (consolidated data point).
These PDPs can become unknown in two cases:
.IP "1." 4
The updates are too far apart. This is tuned using the \*(L"heartbeat\*(R" setting.
.IP "2." 4
The update was set to unknown on purpose by inserting no value (using the
template option) or by using \*(L"U\*(R" as the value to insert.
.PP
When a \s-1CDP\s0 is calculated, another mechanism determines if this \s-1CDP\s0 is valid
or not. If there are too many PDPs unknown, the \s-1CDP\s0 is unknown as well.
This is determined by the xff factor. Please note that one unknown counter
update can result in two unknown PDPs! If you only allow for one unknown
\&\s-1PDP\s0 per \s-1CDP\s0, this makes the \s-1CDP\s0 go unknown!
.PP
Suppose the counter increments with one per second and you retrieve it
every minute:
.PP
.Vb 7
\& counter value resulting rate
\& 10\*(Aq000
\& 10\*(Aq060 1; (10\*(Aq060\-10\*(Aq000)/60 == 1
\& 10\*(Aq120 1; (10\*(Aq120\-10\*(Aq060)/60 == 1
\& unknown unknown; you don\*(Aqt know the last value
\& 10\*(Aq240 unknown; you don\*(Aqt know the previous value
\& 10\*(Aq300 1; (10\*(Aq300\-10\*(Aq240)/60 == 1
.Ve
.PP
If the \s-1CDP\s0 was to be calculated from the last five updates, it would get
two unknown PDPs and three known PDPs. If xff would have been set to 0.5
which by the way is a commonly used factor, the \s-1CDP\s0 would have a known
value of 1. If xff would have been set to 0.2 then the resulting \s-1CDP\s0
would be unknown.
.PP
You have to decide the proper values for heartbeat, number of PDPs per
\&\s-1CDP\s0 and the xff factor. As you can see from the previous text they define
the behavior of your \s-1RRA\s0.
.SS "Working with unknown data in your database"
.IX Subsection "Working with unknown data in your database"
As you have read in the previous chapter, entries in an \s-1RRA\s0 can be
set to the unknown value. If you do calculations with this type of
value, the result has to be unknown too. This means that an expression
such as \f(CW\*(C`result=a,b,+\*(C'\fR will be unknown if either a or b is unknown.
It would be wrong to just ignore the unknown value and return the value
of the other parameter. By doing so, you would assume \*(L"unknown\*(R" means \*(L"zero\*(R"
and this is not true.
.PP
There has been a case where somebody was collecting data for over a year.
A new piece of equipment was installed, a new \s-1RRD\s0 was created and the
scripts were changed to add a counter from the old database and a counter
from the new database. The result was disappointing, a large part of
the statistics seemed to have vanished mysteriously ...
They of course didn't, values from the old database (known values) were
added to values from the new database (unknown values) and the result was
unknown.
.PP
In this case, it is fairly reasonable to use a \s-1CDEF\s0 that alters unknown
data into zero. The counters of the device were unknown (after all, it
wasn't installed yet!) but you know that the data rate through the device
had to be zero (because of the same reason: it was not installed).
.PP
There are some examples below that make this change.
.SS "Infinity"
.IX Subsection "Infinity"
Infinite data is another form of a special number. It cannot be
graphed because by definition you would never reach the infinite
value. You can think of positive and negative infinity depending on
the position relative to zero.
.PP
RRDtool is capable of representing (\-not\- graphing!) infinity by stopping
at its current maximum (for positive infinity) or minimum (for negative
infinity) without knowing this maximum (minimum).
.PP
Infinity in RRDtool is mostly used to draw an \s-1AREA\s0 without knowing its
vertical dimensions. You can think of it as drawing an \s-1AREA\s0 with an
infinite height and displaying only the part that is visible in the
current graph. This is probably a good way to approximate infinity
and it sure allows for some neat tricks. See below for examples.
.SS "Working with unknown data and infinity"
.IX Subsection "Working with unknown data and infinity"
Sometimes you would like to discard unknown data and pretend it is zero
(or any other value for that matter) and sometimes you would like to
pretend that known data is unknown (to discard known-to-be-wrong data).
This is why CDEFs have support for unknown data. There are also examples
available that show unknown data by using infinity.
.SH "Some examples"
.IX Header "Some examples"
.SS "Example: using a recently created \s-1RRD\s0"
.IX Subsection "Example: using a recently created RRD"
You are keeping statistics on your router for over a year now. Recently
you installed an extra router and you would like to show the combined
throughput for these two devices.
.PP
If you just add up the counters from router.rrd and router2.rrd, you
will add known data (from router.rrd) to unknown data (from router2.rrd) for
the bigger part of your stats. You could solve this in a few ways:
.IP "\(bu" 4
While creating the new database, fill it with zeros from the start to now.
You have to make the database start at or before the least recent time in
the other database.
.IP "\(bu" 4
Alternatively, you could use \s-1CDEF\s0 and alter unknown data to zero.
.PP
Both methods have their pros and cons. The first method is troublesome and
if you want to do that you have to figure it out yourself. It is not
possible to create a database filled with zeros, you have to put them in
manually. Implementing the second method is described next:
.PP
What we want is: \*(L"if the value is unknown, replace it with zero\*(R". This
could be written in pseudo-code as: if (value is unknown) then (zero)
else (value). When reading the rrdgraph manual you notice the \*(L"\s-1UN\s0\*(R"
function that returns zero or one. You also notice the \*(L"\s-1IF\s0\*(R" function
that takes zero or one as input.
.PP
First look at the \*(L"\s-1IF\s0\*(R" function. It takes three values from the stack,
the first value is the decision point, the second value is returned to
the stack if the evaluation is \*(L"true\*(R" and if not, the third value is
returned to the stack. We want the \*(L"\s-1UN\s0\*(R" function to decide what happens
so we combine those two functions in one \s-1CDEF\s0.
.PP
Lets write down the two possible paths for the \*(L"\s-1IF\s0\*(R" function:
.PP
.Vb 2
\& if true return a
\& if false return b
.Ve
.PP
In \s-1RPN:\s0 \f(CW\*(C`result=x,a,b,IF\*(C'\fR where \*(L"x\*(R" is either true or false.
.PP
Now we have to fill in \*(L"x\*(R", this should be the \*(L"(value is unknown)\*(R" part
and this is in \s-1RPN:\s0 \f(CW\*(C`result=value,UN\*(C'\fR
.PP
We now combine them: \f(CW\*(C`result=value,UN,a,b,IF\*(C'\fR and when we fill in the
appropriate things for \*(L"a\*(R" and \*(L"b\*(R" we're finished:
.PP
\&\f(CW\*(C`CDEF:result=value,UN,0,value,IF\*(C'\fR
.PP
You may want to read Steve Rader's \s-1RPN\s0 guide if you have difficulties
with the way I explained this last example.
.PP
If you want to check this \s-1RPN\s0 expression, just mimic RRDtool behavior:
.PP
.Vb 4
\& For any known value, the expression evaluates as follows:
\& CDEF:result=value,UN,0,value,IF (value,UN) is not true so it becomes 0
\& CDEF:result=0,0,value,IF "IF" will return the 3rd value
\& CDEF:result=value The known value is returned
\&
\& For the unknown value, this happens:
\& CDEF:result=value,UN,0,value,IF (value,UN) is true so it becomes 1
\& CDEF:result=1,0,value,IF "IF" sees 1 and returns the 2nd value
\& CDEF:result=0 Zero is returned
.Ve
.PP
Of course, if you would like to see another value instead of zero, you
can use that other value.
.PP
Eventually, when all unknown data is removed from the \s-1RRD\s0, you may want
to remove this rule so that unknown data is properly displayed.
.SS "Example: better handling of unknown data, by using time"
.IX Subsection "Example: better handling of unknown data, by using time"
The above example has one drawback. If you do log unknown data in
your database after installing your new equipment, it will also be
translated into zero and therefore you won't see that there was a
problem. This is not good and what you really want to do is:
.IP "\(bu" 4
If there is unknown data, look at the time that this sample was taken.
.IP "\(bu" 4
If the unknown value is before time xxx, make it zero.
.IP "\(bu" 4
If it is after time xxx, leave it as unknown data.
.PP
This is doable: you can compare the time that the sample was taken
to some known time. Assuming you started to monitor your device on
Friday September 17, 1999, 00:35:57 \s-1MET\s0 \s-1DST\s0. Translate this time in seconds
since 1970\-01\-01 and it becomes 937'521'357. If you process unknown values
that were received after this time, you want to leave them unknown and
if they were \*(L"received\*(R" before this time, you want to translate them
into zero (so you can effectively ignore them while adding them to your
other routers counters).
.PP
Translating Friday September 17, 1999, 00:35:57 \s-1MET\s0 \s-1DST\s0 into 937'521'357 can
be done by, for instance, using gnu date:
.PP
.Vb 1
\& date \-d "19990917 00:35:57" +%s
.Ve
.PP
You could also dump the database and see where the data starts to be
known. There are several other ways of doing this, just pick one.
.PP
Now we have to create the magic that allows us to process unknown
values different depending on the time that the sample was taken.
This is a three step process:
.IP "1." 4
If the timestamp of the value is after 937'521'357, leave it as is.
.IP "2." 4
If the value is a known value, leave it as is.
.IP "3." 4
Change the unknown value into zero.
.PP
Lets look at part one:
.PP
.Vb 1
\& if (true) return the original value
.Ve
.PP
We rewrite this:
.PP
.Vb 2
\& if (true) return "a"
\& if (false) return "b"
.Ve
.PP
We need to calculate true or false from step 1. There is a function
available that returns the timestamp for the current sample. It is
called, how surprisingly, \*(L"\s-1TIME\s0\*(R". This time has to be compared to
a constant number, we need \*(L"\s-1GT\s0\*(R". The output of \*(L"\s-1GT\s0\*(R" is true or false
and this is good input to \*(L"\s-1IF\s0\*(R". We want \*(L"if (time > 937521357) then
(return a) else (return b)\*(R".
.PP
This process was already described thoroughly in the previous chapter
so lets do it quick:
.PP
.Vb 4
\& if (x) then a else b
\& where x represents "time>937521357"
\& where a represents the original value
\& where b represents the outcome of the previous example
\&
\& time>937521357 \-\-> TIME,937521357,GT
\&
\& if (x) then a else b \-\-> x,a,b,IF
\& substitute x \-\-> TIME,937521357,GT,a,b,IF
\& substitute a \-\-> TIME,937521357,GT,value,b,IF
\& substitute b \-\-> TIME,937521357,GT,value,value,UN,0,value,IF,IF
.Ve
.PP
We end up with:
\&\f(CW\*(C`CDEF:result=TIME,937521357,GT,value,value,UN,0,value,IF,IF\*(C'\fR
.PP
This looks very complex, however, as you can see, it was not too hard to
come up with.
.SS "Example: Pretending weird data isn't there"
.IX Subsection "Example: Pretending weird data isn't there"
Suppose you have a problem that shows up as huge spikes in your graph.
You know this happens and why, so you decide to work around the problem.
Perhaps you're using your network to do a backup at night and by doing
so you get almost 10mb/s while the rest of your network activity does
not produce numbers higher than 100kb/s.
.PP
There are two options:
.IP "1." 4
If the number exceeds 100kb/s it is wrong and you want it masked out
by changing it into unknown.
.IP "2." 4
You don't want the graph to show more than 100kb/s.
.PP
Pseudo code: if (number > 100) then unknown else number
or
Pseudo code: if (number > 100) then 100 else number.
.PP
The second \*(L"problem\*(R" may also be solved by using the rigid option of
RRDtool graph, however this has not the same result. In this example
you can end up with a graph that does autoscaling. Also, if you use
the numbers to display maxima they will be set to 100kb/s.
.PP
We use \*(L"\s-1IF\s0\*(R" and \*(L"\s-1GT\s0\*(R" again. \*(L"if (x) then (y) else (z)\*(R" is written
down as \*(L"CDEF:result=x,y,z,IF\*(R"; now fill in x, y and z.
For x you fill in \*(L"number greater than 100kb/s\*(R" becoming
\&\*(L"number,100000,GT\*(R" (kilo is 1'000 and b/s is what we measure!).
The \*(L"z\*(R" part is \*(L"number\*(R" in both cases and the \*(L"y\*(R" part is either
\&\*(L"\s-1UNKN\s0\*(R" for unknown or \*(L"100000\*(R" for 100kb/s.
.PP
The two \s-1CDEF\s0 expressions would be:
.PP
.Vb 2
\& CDEF:result=number,100000,GT,UNKN,number,IF
\& CDEF:result=number,100000,GT,100000,number,IF
.Ve
.SS "Example: working on a certain time span"
.IX Subsection "Example: working on a certain time span"
If you want a graph that spans a few weeks, but would only want to
see some routers' data for one week, you need to \*(L"hide\*(R" the rest of
the time frame. Don't ask me when this would be useful, it's just
here for the example :)
.PP
We need to compare the time stamp to a begin date and an end date.
Comparing isn't difficult:
.PP
.Vb 2
\& TIME,begintime,GE
\& TIME,endtime,LE
.Ve
.PP
These two parts of the \s-1CDEF\s0 produce either 0 for false or 1 for true.
We can now check if they are both 0 (or 1) using a few \s-1IF\s0 statements
but, as Wataru Satoh pointed out, we can use the \*(L"*\*(R" or \*(L"+\*(R" functions
as logical \s-1AND\s0 and logical \s-1OR\s0.
.PP
For \*(L"*\*(R", the result will be zero (false) if either one of the two
operators is zero. For \*(L"+\*(R", the result will only be false (0) when
two false (0) operators will be added. Warning: *any* number not
equal to 0 will be considered \*(L"true\*(R". This means that, for instance,
\&\*(L"\-1,1,+\*(R" (which should be \*(L"true or true\*(R") will become \s-1FALSE\s0 ...
In other words, use \*(L"+\*(R" only if you know for sure that you have positive
numbers (or zero) only.
.PP
Let's compile the complete \s-1CDEF:\s0
.PP
.Vb 2
\& DEF:ds0=router1.rrd:AVERAGE
\& CDEF:ds0modified=TIME,begintime,GT,TIME,endtime,LE,*,ds0,UNKN,IF
.Ve
.PP
This will return the value of ds0 if both comparisons return true. You
could also do it the other way around:
.PP
.Vb 2
\& DEF:ds0=router1.rrd:AVERAGE
\& CDEF:ds0modified=TIME,begintime,LT,TIME,endtime,GT,+,UNKN,ds0,IF
.Ve
.PP
This will return an \s-1UNKNOWN\s0 if either comparison returns true.
.SS "Example: You suspect to have problems and want to see unknown data."
.IX Subsection "Example: You suspect to have problems and want to see unknown data."
Suppose you add up the number of active users on several terminal servers.
If one of them doesn't give an answer (or an incorrect one) you get \*(L"NaN\*(R"
in the database (\*(L"Not a Number\*(R") and NaN is evaluated as Unknown.
.PP
In this case, you would like to be alerted to it and the sum of the
remaining values is of no value to you.
.PP
It would be something like:
.PP
.Vb 5
\& DEF:users1=location1.rrd:onlineTS1:LAST
\& DEF:users2=location1.rrd:onlineTS2:LAST
\& DEF:users3=location2.rrd:onlineTS1:LAST
\& DEF:users4=location2.rrd:onlineTS2:LAST
\& CDEF:allusers=users1,users2,users3,users4,+,+,+
.Ve
.PP
If you now plot allusers, unknown data in one of users1..users4 will
show up as a gap in your graph. You want to modify this to show a
bright red line, not a gap.
.PP
Define an extra \s-1CDEF\s0 that is unknown if all is okay and is infinite if
there is an unknown value:
.PP
.Vb 1
\& CDEF:wrongdata=allusers,UN,INF,UNKN,IF
.Ve
.PP
\&\*(L"allusers,UN\*(R" will evaluate to either true or false, it is the (x) part
of the \*(L"\s-1IF\s0\*(R" function and it checks if allusers is unknown.
The (y) part of the \*(L"\s-1IF\s0\*(R" function is set to \*(L"\s-1INF\s0\*(R" (which means infinity)
and the (z) part of the function returns \*(L"\s-1UNKN\s0\*(R".
.PP
The logic is: if (allusers == unknown) then return \s-1INF\s0 else return \s-1UNKN\s0.
.PP
You can now use \s-1AREA\s0 to display this \*(L"wrongdata\*(R" in bright red. If it
is unknown (because allusers is known) then the red \s-1AREA\s0 won't show up.
If the value is \s-1INF\s0 (because allusers is unknown) then the red \s-1AREA\s0 will
be filled in on the graph at that particular time.
.PP
.Vb 2
\& AREA:allusers#0000FF:combined user count
\& AREA:wrongdata#FF0000:unknown data
.Ve
.SS "Same example useful with STACKed data:"
.IX Subsection "Same example useful with STACKed data:"
If you use stack in the previous example (as I would do) then you don't
add up the values. Therefore, there is no relationship between the
four values and you don't get a single value to test.
Suppose users3 would be unknown at one point in time: users1 is plotted,
users2 is stacked on top of users1, users3 is unknown and therefore
nothing happens, users4 is stacked on top of users2.
Add the extra CDEFs anyway and use them to overlay the \*(L"normal\*(R" graph:
.PP
.Vb 11
\& DEF:users1=location1.rrd:onlineTS1:LAST
\& DEF:users2=location1.rrd:onlineTS2:LAST
\& DEF:users3=location2.rrd:onlineTS1:LAST
\& DEF:users4=location2.rrd:onlineTS2:LAST
\& CDEF:allusers=users1,users2,users3,users4,+,+,+
\& CDEF:wrongdata=allusers,UN,INF,UNKN,IF
\& AREA:users1#0000FF:users at ts1
\& STACK:users2#00FF00:users at ts2
\& STACK:users3#00FFFF:users at ts3
\& STACK:users4#FFFF00:users at ts4
\& AREA:wrongdata#FF0000:unknown data
.Ve
.PP
If there is unknown data in one of users1..users4, the \*(L"wrongdata\*(R" \s-1AREA\s0
will be drawn and because it starts at the X\-axis and has infinite height
it will effectively overwrite the STACKed parts.
.PP
You could combine the two \s-1CDEF\s0 lines into one (we don't use \*(L"allusers\*(R")
if you like. But there are good reasons for writing two \s-1CDEFS:\s0
.IP "\(bu" 4
It improves the readability of the script.
.IP "\(bu" 4
It can be used inside \s-1GPRINT\s0 to display the total number of users.
.PP
If you choose to combine them, you can substitute the \*(L"allusers\*(R" in the
second \s-1CDEF\s0 with the part after the equal sign from the first line:
.PP
.Vb 1
\& CDEF:wrongdata=users1,users2,users3,users4,+,+,+,UN,INF,UNKN,IF
.Ve
.PP
If you do so, you won't be able to use these next GPRINTs:
.PP
.Vb 5
\& COMMENT:"Total number of users seen"
\& GPRINT:allusers:MAX:"Maximum: %6.0lf"
\& GPRINT:allusers:MIN:"Minimum: %6.0lf"
\& GPRINT:allusers:AVERAGE:"Average: %6.0lf"
\& GPRINT:allusers:LAST:"Current: %6.0lf\en"
.Ve
.SH "The examples from the RRD graph manual page"
.IX Header "The examples from the RRD graph manual page"
.SS "Degrees Celsius vs. Degrees Fahrenheit"
.IX Subsection "Degrees Celsius vs. Degrees Fahrenheit"
To convert Celsius into Fahrenheit use the formula
F=9/5*C+32
.PP
.Vb 5
\& rrdtool graph demo.png \-\-title="Demo Graph" \e
\& DEF:cel=demo.rrd:exhaust:AVERAGE \e
\& CDEF:far=9,5,/,cel,*,32,+ \e
\& LINE2:cel#00a000:"D. Celsius" \e
\& LINE2:far#ff0000:"D. Fahrenheit\ec"
.Ve
.PP
This example gets the \s-1DS\s0 called \*(L"exhaust\*(R" from database \*(L"demo.rrd\*(R"
and puts the values in variable \*(L"cel\*(R". The \s-1CDEF\s0 used is evaluated
as follows:
.PP
.Vb 10
\& CDEF:far=9,5,/,cel,*,32,+
\& 1. push 9, push 5
\& 2. push function "divide" and process it
\& the stack now contains 9/5
\& 3. push variable "cel"
\& 4. push function "multiply" and process it
\& the stack now contains 9/5*cel
\& 5. push 32
\& 6. push function "plus" and process it
\& the stack contains now the temperature in Fahrenheit
.Ve
.SS "Changing unknown into zero"
.IX Subsection "Changing unknown into zero"
.Vb 9
\& rrdtool graph demo.png \-\-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
These two CDEFs are built from several functions. It helps to split
them when viewing what they do. Starting with the first \s-1CDEF\s0 we would
get:
.PP
.Vb 4
\& idat1,UN \-\-> a
\& 0 \-\-> b
\& idat1 \-\-> c
\& if (a) then (b) else (c)
.Ve
.PP
The result is therefore \*(L"0\*(R" if it is true that \*(L"idat1\*(R" equals \*(L"\s-1UN\s0\*(R".
If not, the original value of \*(L"idat1\*(R" is put back on the stack.
Lets call this answer \*(L"d\*(R". The process is repeated for the next
five items on the stack, it is done the same and will return answer
\&\*(L"h\*(R". The resulting stack is therefore \*(L"d,h\*(R".
The expression has been simplified to \*(L"d,h,+,8,*\*(R" and it will now be
easy to see that we add \*(L"d\*(R" and \*(L"h\*(R", and multiply the result with eight.
.PP
The end result is that we have added \*(L"idat1\*(R" and \*(L"idat2\*(R" and in the
process we effectively ignored unknown values. The result is multiplied
by eight, most likely to convert bytes/s to bits/s.
.SS "Infinity demo"
.IX Subsection "Infinity demo"
.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:whipeout#FF0000:Unknown
.Ve
.PP
This demo demonstrates two ways to use infinity. It is a bit tricky
to see what happens in the \*(L"background\*(R" \s-1CDEF\s0.
.PP
.Vb 1
\& "val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF"
.Ve
.PP
This \s-1RPN\s0 takes the value of \*(L"val4\*(R" as input and then immediately
removes it from the stack using \*(L"\s-1POP\s0\*(R". The stack is now empty but
as a side effect we now know the time that this sample was taken.
This time is put on the stack by the \*(L"\s-1TIME\s0\*(R" function.
.PP
\&\*(L"\s-1TIME\s0,7200,%\*(R" takes the modulo of time and 7'200 (which is two hours).
The resulting value on the stack will be a number in the range from
0 to 7199.
.PP
For people who don't know the modulo function: it is the remainder
after an integer division. If you divide 16 by 3, the answer would
be 5 and the remainder would be 1. So, \*(L"16,3,%\*(R" returns 1.
.PP
We have the result of \*(L"\s-1TIME\s0,7200,%\*(R" on the stack, lets call this
\&\*(L"a\*(R". The start of the \s-1RPN\s0 has become \*(L"a,3600,LE\*(R" and this checks
if \*(L"a\*(R" is less or equal than \*(L"3600\*(R". It is true half of the time.
We now have to process the rest of the \s-1RPN\s0 and this is only a simple
\&\*(L"\s-1IF\s0\*(R" function that returns either \*(L"\s-1INF\s0\*(R" or \*(L"\s-1UNKN\s0\*(R" depending on the
time. This is returned to variable \*(L"background\*(R".
.PP
The second \s-1CDEF\s0 has been discussed earlier in this document so we
won't do that here.
.PP
Now you can draw the different layers. Start with the background
that is either unknown (nothing to see) or infinite (the whole
positive part of the graph gets filled).
.PP
Next you draw the data on top of this background, it will overlay
the background. Suppose one of val1..val4 would be unknown, in that
case you end up with only three bars stacked on top of each other.
You don't want to see this because the data is only valid when all
four variables are valid. This is why you use the second \s-1CDEF\s0, it
will overlay the data with an \s-1AREA\s0 so the data cannot be seen anymore.
.PP
If your data can also have negative values you also need to overwrite
the other half of your graph. This can be done in a relatively simple
way: what you need is the \*(L"wipeout\*(R" variable and place a negative
sign before it: \*(L"CDEF:wipeout2=wipeout,\-1,*\*(R"
.SS "Filtering data"
.IX Subsection "Filtering data"
You may do some complex data filtering:
.PP
.Vb 1
\& MEDIAN FILTER: filters shot noise
\&
\& DEF:var=database.rrd:traffic:AVERAGE
\& CDEF:prev1=PREV(var)
\& CDEF:prev2=PREV(prev1)
\& CDEF:prev3=PREV(prev2)
\& CDEF:median=prev1,prev2,prev3,+,+,3,/
\& LINE3:median#000077:filtered
\& LINE1:prev2#007700:\*(Aqraw data\*(Aq
\&
\&
\& DERIVATE:
\&
\& DEF:var=database.rrd:traffic:AVERAGE
\& CDEF:prev1=PREV(var)
\& CDEF:time=var,POP,TIME
\& CDEF:prevtime=PREV(time)
\& CDEF:derivate=var,prev1,\-,time,prevtime,\-,/
\& LINE3:derivate#000077:derivate
\& LINE1:var#007700:\*(Aqraw data\*(Aq
.Ve
.SH "Out of ideas for now"
.IX Header "Out of ideas for now"
This document was created from questions asked by either myself or by
other people on the RRDtool mailing list. Please let me know if you
find errors in it or if you have trouble understanding it. If you
think there should be an addition, mail me:
.PP
Remember: \fBNo feedback equals no changes!\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The RRDtool manpages
.SH "AUTHOR"
.IX Header "AUTHOR"
Alex van den Bogaerdt
07070100047511000081a40000000000000000000000015295523500002d9f0000011f00010018ffffffffffffffff0000003200000000root/usr/local/share/man/man1/rrdgraph_examples.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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_EXAMPLES 1"
.TH RRDGRAPH_EXAMPLES 1 "2009-02-21" "1.4.4" "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_examples \- Examples for rrdtool graph
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool graph /home/httpd/html/test.png \-\-img\-format \s-1PNG\s0\fR
.PP
followed by any of the examples below
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
For your convenience some of the commands are explained here
by using detailed examples. They are not always cut-and-paste
ready because comments are intermixed with the examples.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Data with multiple resolutions"
.IX Subsection "Data with multiple resolutions"
.Vb 7
\& \-\-end now \-\-start end\-120000s \-\-width 400
\& DEF:ds0a=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
\& DEF:ds0b=/home/rrdtool/data/router1.rrd:ds0:AVERAGE:step=1800
\& DEF:ds0c=/home/rrdtool/data/router1.rrd:ds0:AVERAGE:step=7200
\& LINE1:ds0a#0000FF:"default resolution\el"
\& LINE1:ds0b#00CCFF:"resolution 1800 seconds per interval\el"
\& LINE1:ds0c#FF00FF:"resolution 7200 seconds per interval\el"
.Ve
.SS "Nicely formatted legend section"
.IX Subsection "Nicely formatted legend section"
.Vb 10
\& DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
\& DEF:ds1=/home/rrdtool/data/router1.rrd:ds1:AVERAGE
\& VDEF:ds0max=ds0,MAXIMUM
\& VDEF:ds0avg=ds0,AVERAGE
\& VDEF:ds0min=ds0,MINIMUM
\& VDEF:ds0pct=ds0,95,PERCENT
\& VDEF:ds1max=ds1,MAXIMUM
\& VDEF:ds1avg=ds1,AVERAGE
\& VDEF:ds1min=ds1,MINIMUM
\& VDEF:ds1pct=ds1,95,PERCENT
.Ve
.PP
Note: consolidation occurs here.
.PP
.Vb 2
\& CDEF:ds0bits=ds0,8,*
\& CDEF:ds1bits=ds1,8,*
.Ve
.PP
Note: 10 spaces to move text to the right
.PP
.Vb 1
\& COMMENT:" "
.Ve
.PP
Note: the column titles have to be as wide as the columns
.PP
.Vb 3
\& COMMENT:"Maximum "
\& COMMENT:"Average "
\& COMMENT:"Minimum "
\&
\& COMMENT:"95th percentile\el"
\& AREA:ds0bits#00C000:"Inbound "
\& GPRINT:ds0max:"%6.2lf %Sbps"
\& GPRINT:ds0avg:"%6.2lf %Sbps"
\& GPRINT:ds0min:"%6.2lf %Sbps"
\& GPRINT:ds0pct:"%6.2lf %Sbps\el"
\& LINE1:ds1bits#0000FF:"Outbound"
\& GPRINT:ds1max:"%6.2lf %Sbps"
\& GPRINT:ds1avg:"%6.2lf %Sbps"
\& GPRINT:ds1min:"%6.2lf %Sbps"
\& GPRINT:ds1pct:"%6.2lf %Sbps\el"
.Ve
.SS "Offsetting a line on the y\-axis"
.IX Subsection "Offsetting a line on the y-axis"
Depending on your needs you can do this in two ways:
.IP "\(bu" 4
Offset the data, then graph this
.Sp
.Vb 1
\& DEF:mydata=my.rrd:ds:AVERAGE
.Ve
.Sp
Note: this will also influence any other command that uses \*(L"data\*(R"
.Sp
.Vb 2
\& CDEF:data=mydata,100,+
\& LINE1:data#FF0000:"Data with offset"
.Ve
.IP "\(bu" 4
Graph the original data, with an offset
.Sp
.Vb 1
\& DEF:mydata=my.rrd:ds:AVERAGE
.Ve
.Sp
Note: no color in the first line so it is not visible
.Sp
.Vb 1
\& LINE1:100
.Ve
.Sp
Note: the second line gets stacked on top of the first one
.Sp
.Vb 1
\& LINE1:data#FF0000:"Data with offset":STACK
.Ve
.SS "Drawing dashed lines"
.IX Subsection "Drawing dashed lines"
Also works for \s-1HRULE\s0 and \s-1VRULE\s0
.IP "\(bu" 4
default style: \- \- \- \- \-
LINE1:data#FF0000:\*(L"dashed line\*(R":dashes
.IP "\(bu" 4
more fancy style with offset: \- \- \-\-\- \- \-\-\- \-
LINE1:data#FF0000:\*(L"another dashed line\*(R":dashes=15,5,5,10:dash\-offset=10
.SS "Time ranges"
.IX Subsection "Time ranges"
.Vb 6
\& Last four weeks: \-\-start end\-4w \-\-end 00:00
\& January 2001: \-\-start 20010101 \-\-end start+31d
\& January 2001: \-\-start 20010101 \-\-end 20010201
\& Last hour: \-\-start end\-1h
\& Last 24 hours:
\& Yesterday: \-\-end 00:00
.Ve
.SS "Viewing the current and previous week together"
.IX Subsection "Viewing the current and previous week together"
.Vb 3
\& \-\-end now \-\-start end\-1w
\& DEF:thisweek=router.rrd:ds0:AVERAGE
\& DEF:lastweek=router.rrd:ds0:AVERAGE:end=now\-1w:start=end\-1w
.Ve
.PP
Shift the data forward by one week (604800 seconds)
.PP
.Vb 4
\& SHIFT:lastweek:604800
\& [ more of the usual VDEF and CDEF stuff if you like ]
\& AREA:lastweek#0000FF:Last\e week
\& LINE1:thisweek#FF0000:This\e week
.Ve
.SS "Aberrant Behaviour Detection"
.IX Subsection "Aberrant Behaviour Detection"
If the specialized function \fBRRAs\fR exist for aberrant behavior detection, they
can be used to generate the graph of a time series with confidence bands and
failures.
.PP
.Vb 10
\& rrdtool graph example.png \e
\& DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \e
\& DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \e
\& DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \e
\& DEF:fail=monitor.rrd:ifOutOctets:FAILURES \e
\& TICK:fail#ffffa0:1.0:"Failures\e: Average bits out" \e
\& CDEF:scaledobs=obs,8,* \e
\& CDEF:upper=pred,dev,2,*,+ \e
\& CDEF:lower=pred,dev,2,*,\- \e
\& CDEF:scaledupper=upper,8,* \e
\& CDEF:scaledlower=lower,8,* \e
\& LINE2:scaledobs#0000ff:"Average bits out" \e
\& LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \e
\& LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out"
.Ve
.PP
This example generates a graph of the data series in blue (\s-1LINE2\s0 with the scaledobs
virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
data sources), and potential failures (i.e. potential aberrant aberrant behavior)
marked by vertical yellow lines (the fail data source).
.PP
The raw data comes from an \s-1AVERAGE\s0 \fB\s-1RRA\s0\fR, the finest resolution of the observed
time series (one consolidated data point per primary data point). The predicted
(or smoothed) values are stored in the \s-1HWPREDICT\s0 \fB\s-1RRA\s0\fR. The predicted deviations
(think standard deviation) values are stored in the \s-1DEVPREDICT\s0 \fB\s-1RRA\s0\fR. Finally,
the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR contains indicators, with 1 denoting a potential failure.
.PP
All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
The confidence bounds are computed by an offset of 2 deviations both above
and below the predicted values (the CDEFs upper and lower). Vertical lines
indicated potential failures are graphed via the \s-1TICK\s0 graph element, which
converts non-zero values in an \fB\s-1RRA\s0\fR into tick marks. Here an axis-fraction
argument of 1.0 means the tick marks span the entire y\-axis, and hence become
vertical lines on the graph.
.PP
The choice of 2 deviations (a scaling factor) matches the default used internally
by the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. If the internal value is changed (see rrdtune), this
graphing command should be changed to be consistent.
.PP
\fIA note on data reduction:\fR
.IX Subsection "A note on data reduction:"
.PP
The \fBrrdtool\fR \fIgraph\fR command is designed to plot data at a specified temporal
resolution, regardless of the actually resolution of the data in the \s-1RRD\s0 file.
This can present a problem for the specialized consolidation functions which
maintain a one-to-one mapping between primary data points and consolidated
data points. If a graph insists on viewing the contents of these \fBRRAs\fR on a
coarser temporal scale, the \fIgraph\fR command tries to do something intelligent,
but the confidence bands and failures no longer have the same meaning and may
be misleading.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdgraph gives an overview of how \fBrrdtool graph\fR works.
rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fBxDEF\fR statements.
rrdgraph_graph page describes all the graph and print functions.
.SH "AUTHOR"
.IX Header "AUTHOR"
Program by Tobias Oetiker
.PP
This manual page by Alex van den Bogaerdt
with corrections and/or additions by several people
0707010004751d000081a4000000000000000000000001529552350000e6830000011f00010018ffffffffffffffff0000002c00000000root/usr/local/share/man/man1/rrdtutorial.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDTUTORIAL 1"
.TH RRDTUTORIAL 1 "2009-10-15" "1.4.4" "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"
rrdtutorial \- Alex van den Bogaerdt's RRDtool tutorial
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
RRDtool is written by Tobias Oetiker with
contributions from many people all around the world. This document is
written by Alex van den Bogaerdt to help you
understand what RRDtool is and what it can do for you.
.PP
The documentation provided with RRDtool can be too technical for some
people. This tutorial is here to help you understand the basics of
RRDtool. It should prepare you to read the documentation yourself.
It also explains the general things about statistics with a focus on
networking.
.SH "TUTORIAL"
.IX Header "TUTORIAL"
.SS "Important"
.IX Subsection "Important"
Please don't skip ahead in this document! The first part of this
document explains the basics and may be boring. But if you don't
understand the basics, the examples will not be as meaningful to you.
.PP
Sometimes things change. This example used to provide numbers like
\&\*(L"0.04\*(R" in stead of \*(L"4.00000e\-02\*(R". Those are really the same numbers,
just written down differently. Don't be alarmed if a future version
of rrdtool displays a slightly different form of output. The examples
in this document are correct for version 1.2.0 of RRDtool.
.PP
Also, sometimes bugs do occur. They may also influence the outcome of
the examples. Example speed4.png was suffering from this (the handling
of unknown data in an if-statement was wrong). Normal data will be
just fine (a bug in rrdtool wouldn't last long) but special cases like
NaN, \s-1INF\s0 and so on may last a bit longer. Try another version if you
can, or just live with it.
.PP
I fixed the speed4.png example (and added a note). There may be other
examples which suffer from the same or a similar bug. Try to fix it
yourself, which is a great excercise. But please do not submit your
result as a fix to the source of this document. Discuss it on the
user's list, or write to me.
.SS "What is RRDtool?"
.IX Subsection "What is RRDtool?"
RRDtool refers to Round Robin Database tool.
Round robin is a technique that works with a fixed amount of data, and a
pointer to the current element. Think of a circle with some dots plotted
on the edge. These dots are the places where data can be stored. Draw an
arrow from the center of the circle to one of the dots; this is the pointer.
When the current data is read or written, the pointer moves to the next
element. As we are on a circle there is neither a beginning nor an end, you can
go on and on and on. After a while, all the available places will be used and
the process automatically reuses old locations. This way, the dataset
will not grow in size and therefore requires no maintenance.
RRDtool works with with Round Robin Databases (RRDs). It stores and retrieves
data from them.
.SS "What data can be put into an \s-1RRD\s0?"
.IX Subsection "What data can be put into an RRD?"
You name it, it will probably fit as long as it is some sort of
time-series data. This means you have to be able to measure some value
at several points in time and provide this information to RRDtool. If
you can do this, RRDtool will be able to store it. The values must be
numerical but don't have to be integers, as is the case with \s-1MRTG\s0 (the
next section will give more details on this more specialized application).
.PP
Many examples below talk about \s-1SNMP\s0 which is an acronym for Simple Network
Management Protocol. \*(L"Simple\*(R" refers to the protocol. It does not
mean it is simple to manage or monitor a network. After working your
way through this document, you should know enough to be able to
understand what people are talking about. For now, just realize that
\&\s-1SNMP\s0 can be used to query devices for the values of counters they keep. It
is the value from those counters that we want to store in the \s-1RRD\s0.
.SS "What can I do with this tool?"
.IX Subsection "What can I do with this tool?"
RRDtool originated from \s-1MRTG\s0 (Multi Router Traffic Grapher). \s-1MRTG\s0
started as a tiny little script for graphing the use of a university's
connection to the Internet. \s-1MRTG\s0 was later (ab\-)used as a tool for
graphing other data sources including temperature, speed, voltage,
number of printouts and the like.
.PP
Most likely you will start to use RRDtool to store and process data
collected via \s-1SNMP\s0. The data will most likely be bytes (or bits)
transferred from and to a network or a computer. But it can also be
used to display tidal waves, solar radiation, power consumption,
number of visitors at an exhibition, noise levels near an airport,
temperature on your favorite holiday location, temperature in the
fridge and whatever your imagination can come up with.
.PP
You only need a sensor to measure the data and be able to feed the
numbers into RRDtool. RRDtool then lets you create a database, store
data in it, retrieve that data and create graphs in \s-1PNG\s0 format for
display on a web browser. Those \s-1PNG\s0 images are dependent on the data
you collected and could be, for instance, an overview of the average
network usage, or the peaks that occurred.
.SS "What if I still have problems after reading this document?"
.IX Subsection "What if I still have problems after reading this document?"
First of all: read it again! You may have missed something.
If you are unable to compile the sources and you have a fairly common
\&\s-1OS\s0, it will probably not be the fault of RRDtool. There may be pre-compiled
versions around on the Internet. If they come from trusted sources, get
one of those.
.PP
If on the other hand the program works but does not give you the
expected results, it will be a problem with configuring it. Review
your configuration and compare it with the examples that follow.
.PP
There is a mailing list and an archive of it. Read the list for a few
weeks and search the archive. It is considered rude to just ask
a question without searching the archives: your problem may already have been
solved for somebody else! This is true for most, if not all, mailing lists
and not only for this particular one. Look in the documentation that
came with RRDtool for the location and usage of the list.
.PP
I suggest you take a moment to subscribe to the mailing list right now
by sending an email to with a
subject of \*(L"subscribe\*(R". If you ever want to leave this list, just write
an email to the same address but now with a subject of \*(L"unsubscribe\*(R".
.SS "How will you help me?"
.IX Subsection "How will you help me?"
By giving you some detailed descriptions with detailed examples.
I assume that following the instructions in the order presented
will give you enough knowledge of RRDtool to experiment for yourself.
If it doesn't work the first time, don't give up. Reread the stuff that
you did understand, you may have missed something.
.PP
By following the examples you get some hands-on experience and, even
more important, some background information of how it works.
.PP
You will need to know something about hexadecimal numbers. If you don't
then start with reading bin_dec_hex before you continue here.
.SS "Your first Round Robin Database"
.IX Subsection "Your first Round Robin Database"
In my opinion the best way to learn something is to actually do it.
Why not start right now? We will create a database, put some values
in it and extract this data again. Your output should be the same
as the output that is included in this document.
.PP
We will start with some easy stuff and compare a car with a router,
or compare kilometers (miles if you wish) with bits and bytes. It's
all the same: some number over some time.
.PP
Assume we have a device that transfers bytes to and from the Internet.
This device keeps a counter that starts at zero when it is turned on,
increasing with every byte that is transferred. This counter will probably have
a maximum value. If this value is reached and an extra byte is counted,
the counter starts over at zero. This is the same as many counters
in the world such as the mileage counter in a car.
.PP
Most discussions about networking talk about bits per second so lets
get used to that right away. Assume a byte is eight bits and start to
think in bits not bytes. The counter, however, still counts bytes!
In the \s-1SNMP\s0 world most of the counters are 32 bits. That means they are
counting from 0 to 4294967295. We will use these values in the examples.
The device, when asked, returns the current value of the counter. We
know the time that has passes since we last asked so we now know how
many bytes have been transferred ***on average*** per second. This is
not very hard to calculate. First in words, then in calculations:
.IP "1." 3
Take the current counter, subtract the previous value from it.
.IP "2." 3
Do the same with the current time and the previous time (in seconds).
.IP "3." 3
Divide the outcome of (1) by the outcome of (2), the result is
the amount of bytes per second. Multiply by eight to get the
number of bits per second (bps).
.PP
.Vb 1
\& bps = (counter_now \- counter_before) / (time_now \- time_before) * 8
.Ve
.PP
For some people it may help to translate this to an automobile example.
Do not try this example, and if you do, don't blame me for the results!
.PP
People who are not used to think in kilometers per hour can translate
most into miles per hour by dividing km by 1.6 (close enough).
I will use the following abbreviations:
.PP
.Vb 6
\& m: meter
\& km: kilometer (= 1000 meters).
\& h: hour
\& s: second
\& km/h: kilometers per hour
\& m/s: meters per second
.Ve
.PP
You are driving a car. At 12:05 you read the counter in the dashboard
and it tells you that the car has moved 12345 km until that moment.
At 12:10 you look again, it reads 12357 km. This means you have
traveled 12 km in five minutes. A scientist would translate that
into meters per second and this makes a nice comparison toward the
problem of (bytes per five minutes) versus (bits per second).
.PP
We traveled 12 kilometers which is 12000 meters. We did that in five
minutes or 300 seconds. Our speed is 12000m / 300s or 40 m/s.
.PP
We could also calculate the speed in km/h: 12 times 5 minutes
is an hour, so we have to multiply 12 km by 12 to get 144 km/h.
For our native English speaking friends: that's 90 mph so don't
try this example at home or where I live :)
.PP
Remember: these numbers are averages only. There is no way to figure out
from the numbers, if you drove at a constant speed. There is an example
later on in this tutorial that explains this.
.PP
I hope you understand that there is no difference in calculating m/s or
bps; only the way we collect the data is different. Even the k from kilo
is the same as in networking terms k also means 1000.
.PP
We will now create a database where we can keep all these interesting
numbers. The method used to start the program may differ slightly from
\&\s-1OS\s0 to \s-1OS\s0, but I assume you can figure it out if it works different on
your's. Make sure you do not overwrite any file on your system when
executing the following command and type the whole line as one long
line (I had to split it for readability)
and skip all of the '\e' characters.
.PP
.Vb 5
\& rrdtool create test.rrd \e
\& \-\-start 920804400 \e
\& DS:speed:COUNTER:600:U:U \e
\& RRA:AVERAGE:0.5:1:24 \e
\& RRA:AVERAGE:0.5:6:10
.Ve
.PP
(So enter: \f(CW\*(C`rrdtool create test.rrd \-\-start 920804400 DS ...\*(C'\fR)
.SS "What has been created?"
.IX Subsection "What has been created?"
We created the round robin database called test (test.rrd) which starts at
noon the day I started writing this document, 7th of March, 1999 (this date
translates to 920804400 seconds as explained below). Our database holds
one data source (\s-1DS\s0) named \*(L"speed\*(R" that represents a counter. This counter
is read every five minutes (this is the default therefore you don't have to
put \f(CW\*(C`\-\-step=300\*(C'\fR). In the same database two round robin archives (RRAs)
are kept, one averages the data every time it is read (e.g., there's nothing
to average) and keeps 24 samples (24 times 5 minutes is 2 hours). The other
averages 6 values (half hour) and contains 10 such averages (e.g. 5 hours).
.PP
RRDtool works with special time stamps coming from the \s-1UNIX\s0 world.
This time stamp is the number of seconds that passed since January
1st 1970 \s-1UTC\s0. The time stamp value is translated into local time and
it will therefore look different for different time zones.
.PP
Chances are that you are not in the same part of the world as I am.
This means your time zone is different. In all examples where I talk
about time, the hours may be wrong for you. This has little effect on
the results of the examples, just correct the hours while reading.
As an example: where I will see \*(L"12:05\*(R" the \s-1UK\s0 folks will see \*(L"11:05\*(R".
.PP
We now have to fill our database with some numbers. We'll pretend to
have read the following numbers:
.PP
.Vb 10
\& 12:05 12345 km
\& 12:10 12357 km
\& 12:15 12363 km
\& 12:20 12363 km
\& 12:25 12363 km
\& 12:30 12373 km
\& 12:35 12383 km
\& 12:40 12393 km
\& 12:45 12399 km
\& 12:50 12405 km
\& 12:55 12411 km
\& 13:00 12415 km
\& 13:05 12420 km
\& 13:10 12422 km
\& 13:15 12423 km
.Ve
.PP
We fill the database as follows:
.PP
.Vb 5
\& rrdtool update test.rrd 920804700:12345 920805000:12357 920805300:12363
\& rrdtool update test.rrd 920805600:12363 920805900:12363 920806200:12373
\& rrdtool update test.rrd 920806500:12383 920806800:12393 920807100:12399
\& rrdtool update test.rrd 920807400:12405 920807700:12411 920808000:12415
\& rrdtool update test.rrd 920808300:12420 920808600:12422 920808900:12423
.Ve
.PP
This reads: update our test database with the following numbers
.PP
.Vb 2
\& time 920804700, value 12345
\& time 920805000, value 12357
.Ve
.PP
etcetera.
.PP
As you can see, it is possible to feed more than one value into the
database in one command. I had to stop at three for readability but
the real maximum per line is \s-1OS\s0 dependent.
.PP
We can now retrieve the data from our database using \*(L"rrdtool fetch\*(R":
.PP
.Vb 1
\& rrdtool fetch test.rrd AVERAGE \-\-start 920804400 \-\-end 920809200
.Ve
.PP
It should return the following output:
.PP
.Vb 1
\& speed
\&
\& 920804700: nan
\& 920805000: 4.0000000000e\-02
\& 920805300: 2.0000000000e\-02
\& 920805600: 0.0000000000e+00
\& 920805900: 0.0000000000e+00
\& 920806200: 3.3333333333e\-02
\& 920806500: 3.3333333333e\-02
\& 920806800: 3.3333333333e\-02
\& 920807100: 2.0000000000e\-02
\& 920807400: 2.0000000000e\-02
\& 920807700: 2.0000000000e\-02
\& 920808000: 1.3333333333e\-02
\& 920808300: 1.6666666667e\-02
\& 920808600: 6.6666666667e\-03
\& 920808900: 3.3333333333e\-03
\& 920809200: nan
.Ve
.PP
If it doesn't, something may be wrong. Perhaps your \s-1OS\s0 will print
\&\*(L"NaN\*(R" in a different form. \*(L"NaN\*(R" stands for \*(L"Not A Number\*(R". If your \s-1OS\s0
writes \*(L"U\*(R" or \*(L"\s-1UNKN\s0\*(R" or something similar that's okay. If something
else is wrong, it will probably be due to an error you made (assuming
that my tutorial is correct of course :\-). In that case: delete the
database and try again.
.PP
The meaning of the above output will become clear below.
.SS "Time to create some graphics"
.IX Subsection "Time to create some graphics"
Try the following command:
.PP
.Vb 4
\& rrdtool graph speed.png \e
\& \-\-start 920804400 \-\-end 920808000 \e
\& DEF:myspeed=test.rrd:speed:AVERAGE \e
\& LINE2:myspeed#FF0000
.Ve
.PP
This will create speed.png which starts at 12:00 and ends at 13:00.
There is a definition of a variable called myspeed, using the data from \s-1RRA\s0
\&\*(L"speed\*(R" out of database \*(L"test.rrd\*(R". The line drawn is 2 pixels high
and represents the variable myspeed. The color is red (specified by
its rgb-representation, see below).
.PP
You'll notice that the start of the graph is not at 12:00 but at 12:05.
This is because we have insufficient data to tell the average before
that time. This will only happen when you miss some samples, this will
not happen a lot, hopefully.
.PP
If this has worked: congratulations! If not, check what went wrong.
.PP
The colors are built up from red, green and blue. For each of the
components, you specify how much to use in hexadecimal where 00 means
not included and \s-1FF\s0 means fully included.
The \*(L"color\*(R" white is a mixture of red, green and blue: \s-1FFFFFF\s0
The \*(L"color\*(R" black is all colors off: 000000
.PP
.Vb 5
\& red #FF0000
\& green #00FF00
\& blue #0000FF
\& magenta #FF00FF (mixed red with blue)
\& gray #555555 (one third of all components)
.Ve
.PP
Additionally you can (with a recent RRDtool) add an alpha channel
(transparency). The default will be \*(L"\s-1FF\s0\*(R" which means non-transparent.
.PP
The \s-1PNG\s0 you just created can be displayed using your favorite image
viewer. Web browsers will display the \s-1PNG\s0 via the \s-1URL\s0
\&\*(L"file:///the/path/to/speed.png\*(R"
.SS "Graphics with some math"
.IX Subsection "Graphics with some math"
When looking at the image, you notice that the horizontal axis is labeled
12:10, 12:20, 12:30, 12:40 and 12:50. Sometimes a label doesn't fit (12:00
and 13:00 would be likely candidates) so they are skipped.
.PP
The vertical axis displays the range we entered. We provided
kilometers and when divided by 300 seconds, we get very small
numbers. To be exact, the first value was 12 (12357\-12345) and divided
by 300 this makes 0.04, which is displayed by RRDtool as \*(L"40 m\*(R"
meaning \*(L"40/1000\*(R". The \*(L"m\*(R" (milli) has nothing to do with meters (also m),
kilometers or millimeters! RRDtool doesn't know about the physical
units of our data, it just works with dimensionless numbers.
.PP
If we had measured our distances in meters, this would have been
(12357000\-12345000)/300 = 12000/300 = 40.
.PP
As most people have a better feel for numbers in this range, we'll
correct that. We could recreate our database and store the correct
data, but there is a better way: we do some calculations while creating
the png file!
.PP
.Vb 6
\& rrdtool graph speed2.png \e
\& \-\-start 920804400 \-\-end 920808000 \e
\& \-\-vertical\-label m/s \e
\& DEF:myspeed=test.rrd:speed:AVERAGE \e
\& CDEF:realspeed=myspeed,1000,\e* \e
\& LINE2:realspeed#FF0000
.Ve
.PP
Note: I need to escape the multiplication operator * with a backslash.
If I don't, the operating system may interpret it and use it for file
name expansion. You could also place the line within quotation marks
like so:
.PP
.Vb 1
\& "CDEF:realspeed=myspeed,1000,*" \e
.Ve
.PP
It boils down to: it is RRDtool which should see *, not your shell.
And it is your shell interpreting \e, not RRDtool. You may need to
adjust examples accordingly if you happen to use an operating
system or shell which behaves differently.
.PP
After viewing this \s-1PNG\s0, you notice the \*(L"m\*(R" (milli) has
disappeared. This it what the correct result would be. Also, a label
has been added to the image. Apart from the things mentioned above,
the \s-1PNG\s0 should look the same.
.PP
The calculations are specified in the \s-1CDEF\s0 part above and are in
Reverse Polish Notation (\*(L"\s-1RPN\s0\*(R"). What we requested RRDtool to do is:
\&\*(L"take the data source myspeed and the number 1000; multiply
those\*(R". Don't bother with \s-1RPN\s0 yet, it will be explained later on in
more detail. Also, you may want to read my tutorial on CDEFs and Steve
Rader's tutorial on \s-1RPN\s0. But first finish this tutorial.
.PP
Hang on! If we can multiply values with 1000, it should also be possible
to display kilometers per hour from the same data!
.PP
To change a value that is measured in meters per second:
.PP
.Vb 3
\& Calculate meters per hour: value * 3600
\& Calculate kilometers per hour: value / 1000
\& Together this makes: value * (3600/1000) or value * 3.6
.Ve
.PP
In our example database we made a mistake and we need to compensate for
this by multiplying with 1000. Applying that correction:
.PP
.Vb 1
\& value * 3.6 * 1000 == value * 3600
.Ve
.PP
Now let's create this \s-1PNG\s0, and add some more magic ...
.PP
.Vb 10
\& rrdtool graph speed3.png \e
\& \-\-start 920804400 \-\-end 920808000 \e
\& \-\-vertical\-label km/h \e
\& DEF:myspeed=test.rrd:speed:AVERAGE \e
\& "CDEF:kmh=myspeed,3600,*" \e
\& CDEF:fast=kmh,100,GT,kmh,0,IF \e
\& CDEF:good=kmh,100,GT,0,kmh,IF \e
\& HRULE:100#0000FF:"Maximum allowed" \e
\& AREA:good#00FF00:"Good speed" \e
\& AREA:fast#FF0000:"Too fast"
.Ve
.PP
Note: here we use another means to escape the * operator by enclosing
the whole string in double quotes.
.PP
This graph looks much better. Speed is shown in km/h and there is even
an extra line with the maximum allowed speed (on the road I travel
on). I also changed the colors used to display speed and changed it
from a line into an area.
.PP
The calculations are more complex now. For speed measurements within
the speed limit they are:
.PP
.Vb 2
\& Check if kmh is greater than 100 ( kmh,100 ) GT
\& If so, return 0, else kmh ((( kmh,100 ) GT ), 0, kmh) IF
.Ve
.PP
For values above the speed limit:
.PP
.Vb 2
\& Check if kmh is greater than 100 ( kmh,100 ) GT
\& If so, return kmh, else return 0 ((( kmh,100) GT ), kmh, 0) IF
.Ve
.SS "Graphics Magic"
.IX Subsection "Graphics Magic"
I like to believe there are virtually no limits to how RRDtool graph
can manipulate data. I will not explain how it works, but look at the
following \s-1PNG:\s0
.PP
.Vb 10
\& rrdtool graph speed4.png \e
\& \-\-start 920804400 \-\-end 920808000 \e
\& \-\-vertical\-label km/h \e
\& DEF:myspeed=test.rrd:speed:AVERAGE \e
\& CDEF:nonans=myspeed,UN,0,myspeed,IF \e
\& CDEF:kmh=nonans,3600,* \e
\& CDEF:fast=kmh,100,GT,100,0,IF \e
\& CDEF:over=kmh,100,GT,kmh,100,\-,0,IF \e
\& CDEF:good=kmh,100,GT,0,kmh,IF \e
\& HRULE:100#0000FF:"Maximum allowed" \e
\& AREA:good#00FF00:"Good speed" \e
\& AREA:fast#550000:"Too fast" \e
\& STACK:over#FF0000:"Over speed"
.Ve
.PP
Remember the note in the beginning? I had to remove unknown data from
this example. The 'nonans' \s-1CDEF\s0 is new, and the 6th line (which used to
be the 5th line) used to read 'CDEF:kmh=myspeed,3600,*'
.PP
Let's create a quick and dirty \s-1HTML\s0 page to view the three PNGs:
.PP
.Vb 7
\& Speed
\&
\&
\&
\&
\&
\&
.Ve
.PP
Name the file \*(L"speed.html\*(R" or similar, and look at it in your web browser.
.PP
Now, all you have to do is measure the values regularly and update the
database. When you want to view the data, recreate the PNGs and make
sure to refresh them in your browser. (Note: just clicking reload may
not be enough, especially when proxies are involved. Try shift-reload
or ctrl\-F5).
.SS "Updates in Reality"
.IX Subsection "Updates in Reality"
We've already used the \f(CW\*(C`update\*(C'\fR command: it took one or more
parameters in the form of \*(L":\*(R". You'll be glad to know
that you can specify the current time by filling in a \*(L"N\*(R" as the time.
Or you could use the \*(L"time\*(R" function in Perl (the shortest example in
this tutorial):
.PP
.Vb 1
\& perl \-e \*(Aqprint time, "\en" \*(Aq
.Ve
.PP
How to run a program on regular intervals is \s-1OS\s0 specific. But here is
an example in pseudo code:
.PP
.Vb 2
\& \- Get the value and put it in variable "$speed"
\& \- rrdtool update speed.rrd N:$speed
.Ve
.PP
(do not try this with our test database, we'll use it in further examples)
.PP
This is all. Run the above script every five minutes. When you need to know
what the graphs look like, run the examples above. You could put them
in a script as well. After running that script, view the page
index.html we created above.
.SS "Some words on \s-1SNMP\s0"
.IX Subsection "Some words on SNMP"
I can imagine very few people that will be able to get real data from
their car every five minutes. All other people will have to settle for
some other kind of counter. You could measure the number of pages
printed by a printer, for example, the cups of coffee made by the
coffee machine, a device that counts the electricity used,
whatever. Any incrementing counter can be monitored and graphed using
the stuff you learned so far. Later on we will also be able to monitor
other types of values like temperature.
.PP
Many people interested in RRDtool will use the counter that keeps track
of octets (bytes) transferred by a network device. So let's do just
that next. We will start with a description of how to collect data.
.PP
Some people will make a remark that there are tools which can do this data
collection for you. They are right! However, I feel it is important that
you understand they are not necessary. When you have to determine why
things went wrong you need to know how they work.
.PP
One tool used in the example has been talked about very briefly in the
beginning of this document, it is called \s-1SNMP\s0. It is a way of talking
to networked equipment. The tool I use below is called \*(L"snmpget\*(R" and
this is how it works:
.PP
.Vb 1
\& snmpget device password OID
.Ve
.PP
or
.PP
.Vb 1
\& snmpget \-v[version] \-c[password] device OID
.Ve
.PP
For device you substitute the name, or the \s-1IP\s0 address, of your device.
For password you use the \*(L"community read string\*(R" as it is called in the
\&\s-1SNMP\s0 world. For some devices the default of \*(L"public\*(R" might work, however
this can be disabled, altered or protected for privacy and security
reasons. Read the documentation that comes with your device or program.
.PP
Then there is this parameter, called \s-1OID\s0, which means \*(L"object identifier\*(R".
.PP
When you start to learn about \s-1SNMP\s0 it looks very confusing. It isn't
all that difficult when you look at the Management Information Base
(\*(L"\s-1MIB\s0\*(R"). It is an upside-down tree that describes data, with a single node
as the root and from there a number of branches. These branches end
up in another node, they branch out, etc. All the branches have a name
and they form the path that we follow all the way down. The branches
that we follow are named: iso, org, dod, internet, mgmt and mib\-2.
These names can also be written down as numbers and are 1 3 6 1 2 1.
.PP
.Vb 1
\& iso.org.dod.internet.mgmt.mib\-2 (1.3.6.1.2.1)
.Ve
.PP
There is a lot of confusion about the leading dot that some programs
use. There is *no* leading dot in an \s-1OID\s0. However, some programs
can use the above part of OIDs as a default. To indicate the difference
between abbreviated OIDs and full OIDs they need a leading dot when
you specify the complete \s-1OID\s0. Often those programs will leave out
the default portion when returning the data to you. To make things
worse, they have several default prefixes ...
.PP
Ok, lets continue to the start of our \s-1OID:\s0 we had 1.3.6.1.2.1
From there, we are especially interested in the branch \*(L"interfaces\*(R"
which has number 2 (e.g., 1.3.6.1.2.1.2 or 1.3.6.1.2.1.interfaces).
.PP
First, we have to get some \s-1SNMP\s0 program. First look if there is a
pre-compiled package available for your \s-1OS\s0. This is the preferred way.
If not, you will have to get the sources yourself and compile those.
The Internet is full of sources, programs etc. Find information using
a search engine or whatever you prefer.
.PP
Assume you got the program. First try to collect some data that is
available on most systems. Remember: there is a short name for the
part of the tree that interests us most in the world we live in!
.PP
I will give an example which can be used on Fedora Core 3. If it
doesn't work for you, work your way through the manual of snmp and
adapt the example to make it work.
.PP
.Vb 1
\& snmpget \-v2c \-c public myrouter system.sysDescr.0
.Ve
.PP
The device should answer with a description of itself, perhaps an
empty one. Until you got a valid answer from a device, perhaps using a
different \*(L"password\*(R", or a different device, there is no point in
continuing.
.PP
.Vb 1
\& snmpget \-v2c \-c public myrouter interfaces.ifNumber.0
.Ve
.PP
Hopefully you get a number as a result, the number of interfaces.
If so, you can carry on and try a different program called \*(L"snmpwalk\*(R".
.PP
.Vb 1
\& snmpwalk \-v2c \-c public myrouter interfaces.ifTable.ifEntry.ifDescr
.Ve
.PP
If it returns with a list of interfaces, you're almost there.
Here's an example:
[user@host /home/alex]$ snmpwalk \-v2c \-c public cisco 2.2.1.2
.PP
.Vb 5
\& interfaces.ifTable.ifEntry.ifDescr.1 = "BRI0: B\-Channel 1"
\& interfaces.ifTable.ifEntry.ifDescr.2 = "BRI0: B\-Channel 2"
\& interfaces.ifTable.ifEntry.ifDescr.3 = "BRI0" Hex: 42 52 49 30
\& interfaces.ifTable.ifEntry.ifDescr.4 = "Ethernet0"
\& interfaces.ifTable.ifEntry.ifDescr.5 = "Loopback0"
.Ve
.PP
On this cisco equipment, I would like to monitor the \*(L"Ethernet0\*(R"
interface and from the above output I see that it is number four. I try:
.PP
.Vb 1
\& [user@host /home/alex]$ snmpget \-v2c \-c public cisco 2.2.1.10.4 2.2.1.16.4
\&
\& interfaces.ifTable.ifEntry.ifInOctets.4 = 2290729126
\& interfaces.ifTable.ifEntry.ifOutOctets.4 = 1256486519
.Ve
.PP
So now I have two OIDs to monitor and they are (in full, this time):
.PP
.Vb 1
\& 1.3.6.1.2.1.2.2.1.10
.Ve
.PP
and
.PP
.Vb 1
\& 1.3.6.1.2.1.2.2.1.16
.Ve
.PP
both with an interface number of 4.
.PP
Don't get fooled, this wasn't my first try. It took some time for me too
to understand what all these numbers mean. It does help a lot when they
get translated into descriptive text... At least, when people are talking
about MIBs and OIDs you know what it's all about.
Do not forget the interface number (0 if it is not interface dependent)
and try snmpwalk if you don't get an answer from snmpget.
.PP
If you understand the above section and get numbers from your device, continue
on with this tutorial. If not, then go back and re-read this part.
.SS "A Real World Example"
.IX Subsection "A Real World Example"
Let the fun begin. First, create a new database. It contains data from
two counters, called input and output. The data is put into archives
that average it. They take 1, 6, 24 or 288 samples at a time.
They also go into archives that keep the maximum numbers. This will be
explained later on. The time in-between samples is 300 seconds, a good
starting point, which is the same as five minutes.
.PP
.Vb 4
\& 1 sample "averaged" stays 1 period of 5 minutes
\& 6 samples averaged become one average on 30 minutes
\& 24 samples averaged become one average on 2 hours
\& 288 samples averaged become one average on 1 day
.Ve
.PP
Lets try to be compatible with \s-1MRTG\s0 which stores about the following
amount of data:
.PP
.Vb 4
\& 600 5\-minute samples: 2 days and 2 hours
\& 600 30\-minute samples: 12.5 days
\& 600 2\-hour samples: 50 days
\& 732 1\-day samples: 732 days
.Ve
.PP
These ranges are appended, so the total amount of data stored in the
database is approximately 797 days. RRDtool stores the data
differently, it doesn't start the \*(L"weekly\*(R" archive where the \*(L"daily\*(R"
archive stopped. For both archives the most recent data will be near
\&\*(L"now\*(R" and therefore we will need to keep more data than \s-1MRTG\s0 does!
.PP
We will need:
.PP
.Vb 4
\& 600 samples of 5 minutes (2 days and 2 hours)
\& 700 samples of 30 minutes (2 days and 2 hours, plus 12.5 days)
\& 775 samples of 2 hours (above + 50 days)
\& 797 samples of 1 day (above + 732 days, rounded up to 797)
\&
\& rrdtool create myrouter.rrd \e
\& DS:input:COUNTER:600:U:U \e
\& DS:output:COUNTER:600:U:U \e
\& RRA:AVERAGE:0.5:1:600 \e
\& RRA:AVERAGE:0.5:6:700 \e
\& RRA:AVERAGE:0.5:24:775 \e
\& RRA:AVERAGE:0.5:288:797 \e
\& RRA:MAX:0.5:1:600 \e
\& RRA:MAX:0.5:6:700 \e
\& RRA:MAX:0.5:24:775 \e
\& RRA:MAX:0.5:288:797
.Ve
.PP
Next thing to do is to collect data and store it. Here is an example.
It is written partially in pseudo code, you will have to find out what
to do exactly on your \s-1OS\s0 to make it work.
.PP
.Vb 8
\& while not the end of the universe
\& do
\& get result of
\& snmpget router community 2.2.1.10.4
\& into variable $in
\& get result of
\& snmpget router community 2.2.1.16.4
\& into variable $out
\&
\& rrdtool update myrouter.rrd N:$in:$out
\&
\& wait for 5 minutes
\& done
.Ve
.PP
Then, after collecting data for a day, try to create an image using:
.PP
.Vb 5
\& rrdtool graph myrouter\-day.png \-\-start \-86400 \e
\& DEF:inoctets=myrouter.rrd:input:AVERAGE \e
\& DEF:outoctets=myrouter.rrd:output:AVERAGE \e
\& AREA:inoctets#00FF00:"In traffic" \e
\& LINE1:outoctets#0000FF:"Out traffic"
.Ve
.PP
This should produce a picture with one day worth of traffic.
One day is 24 hours of 60 minutes of 60 seconds: 24*60*60=86400, we
start at now minus 86400 seconds. We define (with DEFs) inoctets and
outoctets as the average values from the database myrouter.rrd and draw
an area for the \*(L"in\*(R" traffic and a line for the \*(L"out\*(R" traffic.
.PP
View the image and keep logging data for a few more days.
If you like, you could try the examples from the test database and
see if you can get various options and calculations to work.
.PP
Suggestion: Display in bytes per second and in bits per second. Make
the Ethernet graphics go red if they are over four megabits per
second.
.SS "Consolidation Functions"
.IX Subsection "Consolidation Functions"
A few paragraphs back I mentioned the possibility of keeping
the maximum values instead of the average values. Let's go
into this a bit more.
.PP
Recall all the stuff about the speed of the car. Suppose we drove at 144
km/h during 5 minutes and then were stopped by the police for 25 minutes.
At the end of the lecture we would take our laptop and create and view the
image taken from the database. If we look at the second \s-1RRA\s0 we did
create, we would have the average from 6 samples. The samples measured
would be 144+0+0+0+0+0=144, divided by 30 minutes, corrected for the
error by 1000, translated into km/h, with a result of 24 km/h.
I would still get a ticket but not for speeding anymore :)
.PP
Obviously, in this case we shouldn't look at the averages. In some
cases they are handy. If you want to know how many km you had traveled,
the averaged picture would be the right one to look at. On the other hand, for
the speed that we traveled at, the maximum numbers seen is much more
interesting. Later we will see more types.
.PP
It is the same for data. If you want to know the amount, look at the
averages. If you want to know the rate, look at the maximum.
Over time, they will grow apart more and more. In the last database
we have created, there are two archives that keep data per day. The
archive that keeps averages will show low numbers, the archive that
shows maxima will have higher numbers.
.PP
For my car this would translate in averages per day of 96/24=4 km/h
(as I travel about 94 kilometers on a day) during working days, and
maxima of 120 km/h (my top speed that I reach every day).
.PP
Big difference. Do not look at the second graph to estimate the
distances that I travel and do not look at the first graph to
estimate my speed. This will work if the samples are close together,
as they are in five minutes, but not if you average.
.PP
On some days, I go for a long ride. If I go across Europe and travel
for 12 hours, the first graph will rise to about 60 km/h. The second
one will show 180 km/h. This means that I traveled a distance of 60
km/h times 24 h = 1440 km. I did this with a higher speed and a
maximum around 180 km/h. However, it probably doesn't mean that I
traveled for 8 hours at a constant speed of 180 km/h!
.PP
This is a real example: go with the flow through Germany (fast!) and stop
a few times for gas and coffee. Drive slowly through Austria and the
Netherlands. Be careful in the mountains and villages. If you would
look at the graphs created from the five-minute averages you would
get a totally different picture. You would see the same values on the
average and maximum graphs (provided I measured every 300 seconds).
You would be able to see when I stopped, when I was in top gear, when
I drove over fast highways etc. The granularity of the data is much
higher, so you can see more. However, this takes 12 samples per hour,
or 288 values per day, so it would be a lot of data over a longer
period of time. Therefore we average it, eventually to one value per
day. From this one value, we cannot see much detail, of course.
.PP
Make sure you understand the last few paragraphs. There is no value
in only a line and a few axis, you need to know what they mean and
interpret the data in an appropriate way. This is true for all data.
.PP
The biggest mistake you can make is to use the collected data for
something that it is not suitable for. You would be better off if
you didn't have the graph at all.
.SS "Let's review what you now should know"
.IX Subsection "Let's review what you now should know"
You know how to create a database and can put data in it. You can get
the numbers out again by creating an image, do math on the data from
the database and view the result instead of the raw data. You know
about the difference between averages and maximum, and when to use
which (or at least you should have an idea).
.PP
RRDtool can do more than what we have learned up to now. Before you
continue with the rest of this doc, I recommend that you reread from
the start and try some modifications on the examples. Make sure you
fully understand everything. It will be worth the effort and helps
you not only with the rest of this tutorial, but also in your day to day
monitoring long after you read this introduction.
.SS "Data Source Types"
.IX Subsection "Data Source Types"
All right, you feel like continuing. Welcome back and get ready
for an increased speed in the examples and explanations.
.PP
You know that in order to view a counter over time, you have to
take two numbers and divide the difference of them between the
time lapsed. This makes sense for the examples I gave you but there
are other possibilities. For instance, I'm able to retrieve the
temperature from my router in three places namely the inlet, the
so called hot-spot and the exhaust. These values are not counters.
If I take the difference of the two samples and divide that by
300 seconds I would be asking for the temperature change per second.
Hopefully this is zero! If not, the computer room is probably on fire :)
.PP
So, what can we do? We can tell RRDtool to store the values we measure
directly as they are (this is not entirely true but close enough). The
graphs we make will look much better, they will show a rather constant
value. I know when the router is busy (it
works \-> it uses more electricity \-> it generates more heat \-> the
temperature rises). I know when the doors are left open (the room is
air conditioned) \-> the warm air from the rest of the building flows into the
computer room \-> the inlet temperature rises). Etc. The data type we
use when creating the database before was counter, we now have a
different data type and thus a different name for it. It is called
\&\s-1GAUGE\s0. There are more such data types:
.PP
.Vb 4
\& \- COUNTER we already know this one
\& \- GAUGE we just learned this one
\& \- DERIVE
\& \- ABSOLUTE
.Ve
.PP
The two additional types are \s-1DERIVE\s0 and \s-1ABSOLUTE\s0. Absolute can be used like
counter with one difference: RRDtool assumes the counter is reset when
it's read. That is: its delta is known without calculation by RRDtool
whereas RRDtool needs to calculate it for the counter type.
Example: our first example (12345, 12357, 12363, 12363) would read:
unknown, 12, 6, 0. The rest of the calculations stay the same.
The other one, derive, is like counter. Unlike counter, it can also
decrease so it can have a negative delta. Again, the rest of the
calculations stay the same.
.PP
Let's try them all:
.PP
.Vb 10
\& rrdtool create all.rrd \-\-start 978300900 \e
\& DS:a:COUNTER:600:U:U \e
\& DS:b:GAUGE:600:U:U \e
\& DS:c:DERIVE:600:U:U \e
\& DS:d:ABSOLUTE:600:U:U \e
\& RRA:AVERAGE:0.5:1:10
\& rrdtool update all.rrd \e
\& 978301200:300:1:600:300 \e
\& 978301500:600:3:1200:600 \e
\& 978301800:900:5:1800:900 \e
\& 978302100:1200:3:2400:1200 \e
\& 978302400:1500:1:2400:1500 \e
\& 978302700:1800:2:1800:1800 \e
\& 978303000:2100:4:0:2100 \e
\& 978303300:2400:6:600:2400 \e
\& 978303600:2700:4:600:2700 \e
\& 978303900:3000:2:1200:3000
\& rrdtool graph all1.png \-s 978300600 \-e 978304200 \-h 400 \e
\& DEF:linea=all.rrd:a:AVERAGE LINE3:linea#FF0000:"Line A" \e
\& DEF:lineb=all.rrd:b:AVERAGE LINE3:lineb#00FF00:"Line B" \e
\& DEF:linec=all.rrd:c:AVERAGE LINE3:linec#0000FF:"Line C" \e
\& DEF:lined=all.rrd:d:AVERAGE LINE3:lined#000000:"Line D"
.Ve
.SS "RRDtool under the Microscope"
.IX Subsection "RRDtool under the Microscope"
.IP "\(bu" 2
Line A is a \s-1COUNTER\s0 type, so it should continuously increment and RRDtool
must calculate the differences. Also, RRDtool needs to divide the
difference by the amount of time lapsed. This should end up as a
straight line at 1 (the deltas are 300, the time is 300).
.IP "\(bu" 2
Line B is of type \s-1GAUGE\s0. These are \*(L"real\*(R" values so they should match
what we put in: a sort of a wave.
.IP "\(bu" 2
Line C is of type \s-1DERIVE\s0. It should be a counter that can decrease. It does
so between 2400 and 0, with 1800 in-between.
.IP "\(bu" 2
Line D is of type \s-1ABSOLUTE\s0. This is like counter but it works on
values without calculating the difference. The numbers are the same
and as you can see (hopefully) this has a different result.
.PP
This translates in the following values, starting at 23:10 and ending
at 00:10 the next day (where \*(L"u\*(R" means unknown/unplotted):
.PP
.Vb 4
\& \- Line A: u u 1 1 1 1 1 1 1 1 1 u
\& \- Line B: u 1 3 5 3 1 2 4 6 4 2 u
\& \- Line C: u u 2 2 2 0 \-2 \-6 2 0 2 u
\& \- Line D: u 1 2 3 4 5 6 7 8 9 10 u
.Ve
.PP
If your \s-1PNG\s0 shows all this, you know you have entered the data correctly,
the RRDtool executable is working properly, your viewer doesn't fool you,
and you successfully entered the year 2000 :)
.PP
You could try the same example four times, each time with only one of
the lines.
.PP
Let's go over the data again:
.IP "\(bu" 2
Line A: 300,600,900 and so on. The counter delta is a constant 300 and
so is the time delta. A number divided by itself is always 1 (except
when dividing by zero which is undefined/illegal).
.Sp
Why is it that the first point is unknown? We do know what we put into
the database, right? True, But we didn't have a value to calculate the delta
from, so we don't know where we started. It would be wrong to assume we
started at zero so we don't!
.IP "\(bu" 2
Line B: There is nothing to calculate. The numbers are as they are.
.IP "\(bu" 2
Line C: Again, the start-out value is unknown. The same story is holds
as for line A. In this case the deltas are not constant, therefore the line
is not either. If we would put the same numbers in the database as we did for
line A, we would have gotten the same line. Unlike type counter,
this type can decrease and I hope to show you later on why
this makes a difference.
.IP "\(bu" 2
Line D: Here the device calculates the deltas. Therefore we \s-1DO\s0 know the
first delta and it is plotted. We had the same input as with line A, but
the meaning of this input is different and thus the line is different.
In this case the deltas increase each time with 300. The time delta
stays at a constant 300 and therefore the division of the two gives
increasing values.
.SS "Counter Wraps"
.IX Subsection "Counter Wraps"
There are a few more basics to show. Some important options are still to
be covered and we haven't look at counter wraps yet. First the counter wrap:
In our car we notice that the counter shows 999987. We travel 20 km and
the counter should go to 1000007. Unfortunately, there are only six digits
on our counter so it really shows 000007. If we would plot that on a type
\&\s-1DERIVE\s0, it would mean that the counter was set back 999980 km. It wasn't,
and there has to be some protection for this. This protection is only
available for type \s-1COUNTER\s0 which should be used for this kind of counter
anyways. How does it work? Type counter should never decrease and
therefore RRDtool must assume it wrapped if it does decrease!
If the delta is negative, this can be compensated for by adding the
maximum value of the counter + 1. For our car this would be:
.PP
.Vb 1
\& Delta = 7 \- 999987 = \-999980 (instead of 1000007\-999987=20)
\&
\& Real delta = \-999980 + 999999 + 1 = 20
.Ve
.PP
At the time of writing this document, RRDtool knows of counters that
are either 32 bits or 64 bits of size. These counters can handle the
following different values:
.PP
.Vb 2
\& \- 32 bits: 0 .. 4294967295
\& \- 64 bits: 0 .. 18446744073709551615
.Ve
.PP
If these numbers look strange to you, you can view them in
their hexadecimal form:
.PP
.Vb 2
\& \- 32 bits: 0 .. FFFFFFFF
\& \- 64 bits: 0 .. FFFFFFFFFFFFFFFF
.Ve
.PP
RRDtool handles both counters the same. If an overflow occurs and
the delta would be negative, RRDtool first adds the maximum of a small
counter + 1 to the delta. If the delta is still negative, it had to be
the large counter that wrapped. Add the maximum possible value of the
large counter + 1 and subtract the erroneously added small value.
.PP
There is a risk in this: suppose the large counter wrapped while adding
a huge delta, it could happen, theoretically, that adding the smaller value
would make the delta positive. In this unlikely case the results would
not be correct. The increase should be nearly as high as the maximum
counter value for that to happen, so chances are you would have several
other problems as well and this particular problem would not even be
worth thinking about. Even though, I did include an example, so you
can judge for yourself.
.PP
The next section gives you some numerical examples for counter-wraps.
Try to do the calculations yourself or just believe me if your calculator
can't handle the numbers :)
.PP
Correction numbers:
.PP
.Vb 3
\& \- 32 bits: (4294967295 + 1) = 4294967296
\& \- 64 bits: (18446744073709551615 + 1)
\& \- correction1 = 18446744069414584320
\&
\& Before: 4294967200
\& Increase: 100
\& Should become: 4294967300
\& But really is: 4
\& Delta: \-4294967196
\& Correction1: \-4294967196 + 4294967296 = 100
\&
\& Before: 18446744073709551000
\& Increase: 800
\& Should become: 18446744073709551800
\& But really is: 184
\& Delta: \-18446744073709550816
\& Correction1: \-18446744073709550816
\& + 4294967296 = \-18446744069414583520
\& Correction2: \-18446744069414583520
\& + 18446744069414584320 = 800
\&
\& Before: 18446744073709551615 ( maximum value )
\& Increase: 18446744069414584320 ( absurd increase, minimum for
\& Should become: 36893488143124135935 this example to work )
\& But really is: 18446744069414584319
\& Delta: \-4294967296
\& Correction1: \-4294967296 + 4294967296 = 0
\& (not negative \-> no correction2)
\&
\& Before: 18446744073709551615 ( maximum value )
\& Increase: 18446744069414584319 ( one less increase )
\& Should become: 36893488143124135934
\& But really is: 18446744069414584318
\& Delta: \-4294967297
\& Correction1: \-4294967297 + 4294967296 = \-1
\& Correction2: \-1 + 18446744069414584320 = 18446744069414584319
.Ve
.PP
As you can see from the last two examples, you need strange numbers
for RRDtool to fail (provided it's bug free of course), so this should
not happen. However, \s-1SNMP\s0 or whatever method you choose to collect the
data, might also report wrong numbers occasionally. We can't prevent all
errors, but there are some things we can do. The RRDtool \*(L"create\*(R" command
takes two special parameters for this. They define
the minimum and maximum allowed values. Until now, we used \*(L"U\*(R", meaning
\&\*(L"unknown\*(R". If you provide values for one or both of them and if RRDtool
receives data points that are outside these limits, it will ignore those
values. For a thermometer in degrees Celsius, the absolute minimum is
just under \-273. For my router, I can assume this minimum is much higher
so I would set it to 10, where as the maximum temperature I would
set to 80. Any higher and the device would be out of order.
.PP
For the speed of my car, I would never expect negative numbers and
also I would not expect a speed higher than 230. Anything else,
and there must have been an error. Remember: the opposite is not true,
if the numbers pass this check, it doesn't mean that they are
correct. Always judge the graph with a healthy dose of suspicion if it
seems weird to you.
.SS "Data Resampling"
.IX Subsection "Data Resampling"
One important feature of RRDtool has not been explained yet: it is
virtually impossible to collect data and feed it into RRDtool on exact
intervals. RRDtool therefore interpolates the data, so they are stored
on exact intervals. If you do not know what this means or how it
works, then here's the help you seek:
.PP
Suppose a counter increases by exactly one for every second. You want
to measure it in 300 seconds intervals. You should retrieve values
that are exactly 300 apart. However, due to various circumstances you
are a few seconds late and the interval is 303. The delta will also be
303 in that case. Obviously, RRDtool should not put 303 in the database
and make you believe that the counter increased by 303 in 300 seconds.
This is where RRDtool interpolates: it alters the 303 value as if it
would have been stored earlier and it will be 300 in 300 seconds.
Next time you are at exactly the right time. This means that the current
interval is 297 seconds and also the counter increased by 297. Again,
RRDtool interpolates and stores 300 as it should be.
.PP
.Vb 1
\& in the RRD in reality
\&
\& time+000: 0 delta="U" time+000: 0 delta="U"
\& time+300: 300 delta=300 time+300: 300 delta=300
\& time+600: 600 delta=300 time+603: 603 delta=303
\& time+900: 900 delta=300 time+900: 900 delta=297
.Ve
.PP
Let's create two identical databases. I've chosen the time range 920805000
to 920805900 as this goes very well with the example numbers.
.PP
.Vb 4
\& rrdtool create seconds1.rrd \e
\& \-\-start 920804700 \e
\& DS:seconds:COUNTER:600:U:U \e
\& RRA:AVERAGE:0.5:1:24
.Ve
.PP
Make a copy
.PP
.Vb 3
\& for Unix: cp seconds1.rrd seconds2.rrd
\& for Dos: copy seconds1.rrd seconds2.rrd
\& for vms: how would I know :)
.Ve
.PP
Put in some data
.PP
.Vb 4
\& rrdtool update seconds1.rrd \e
\& 920805000:000 920805300:300 920805600:600 920805900:900
\& rrdtool update seconds2.rrd \e
\& 920805000:000 920805300:300 920805603:603 920805900:900
.Ve
.PP
Create output
.PP
.Vb 10
\& rrdtool graph seconds1.png \e
\& \-\-start 920804700 \-\-end 920806200 \e
\& \-\-height 200 \e
\& \-\-upper\-limit 1.05 \-\-lower\-limit 0.95 \-\-rigid \e
\& DEF:seconds=seconds1.rrd:seconds:AVERAGE \e
\& CDEF:unknown=seconds,UN \e
\& LINE2:seconds#0000FF \e
\& AREA:unknown#FF0000
\& rrdtool graph seconds2.png \e
\& \-\-start 920804700 \-\-end 920806200 \e
\& \-\-height 200 \e
\& \-\-upper\-limit 1.05 \-\-lower\-limit 0.95 \-\-rigid \e
\& DEF:seconds=seconds2.rrd:seconds:AVERAGE \e
\& CDEF:unknown=seconds,UN \e
\& LINE2:seconds#0000FF \e
\& AREA:unknown#FF0000
.Ve
.PP
View both images together (add them to your index.html file)
and compare. Both graphs should show the same, despite the
input being different.
.SH "WRAPUP"
.IX Header "WRAPUP"
It's time now to wrap up this tutorial. We covered all the basics for
you to be able to work with RRDtool and to read the additional
documentation available. There is plenty more to discover about
RRDtool and you will find more and more uses for this package. You can
easily create graphs using just the examples provided and using only
RRDtool. You can also use one of the front ends to RRDtool that are
available.
.SH "MAILINGLIST"
.IX Header "MAILINGLIST"
Remember to subscribe to the RRDtool mailing list. Even if you are not
answering to mails that come by, it helps both you and the rest of the
users. A lot of the stuff that I know about \s-1MRTG\s0 (and therefore about
RRDtool) I've learned while just reading the list without posting to
it. I did not need to ask the basic questions as they are answered in
the \s-1FAQ\s0 (read it!) and in various mails by other users. With
thousands of users all over the world, there will always be people who
ask questions that you can answer because you read this and other
documentation and they didn't.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The RRDtool manpages
.SH "AUTHOR"
.IX Header "AUTHOR"
I hope you enjoyed the examples and their descriptions. If you do, help
other people by pointing them to this document when they are asking
basic questions. They will not only get their answers, but at the same
time learn a whole lot more.
.PP
Alex van den Bogaerdt
0707010004750c000081a40000000000000000000000015295523500003e320000011f00010018ffffffffffffffff0000002900000000root/usr/local/share/man/man1/rrdfetch.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDFETCH 1"
.TH RRDFETCH 1 "2008-09-25" "1.4.4" "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"
rrdfetch \- Fetch data from an RRD.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBfetch\fR \fIfilename\fR \fI\s-1CF\s0\fR
[\fB\-\-resolution\fR|\fB\-r\fR\ \fIresolution\fR]
[\fB\-\-start\fR|\fB\-s\fR\ \fIstart\fR]
[\fB\-\-end\fR|\fB\-e\fR\ \fIend\fR]
[\fB\-\-daemon\fR\ \fIaddress\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBfetch\fR function is normally used internally by the graph
function to get data from \fB\s-1RRD\s0\fRs. \fBfetch\fR will analyze the \fB\s-1RRD\s0\fR
and try to retrieve the data in the resolution requested.
The data fetched is printed to stdout. \fI*UNKNOWN*\fR data is often
represented by the string \*(L"NaN\*(R" depending on your \s-1OS\s0's printf
function.
.IP "\fIfilename\fR" 8
.IX Item "filename"
the name of the \fB\s-1RRD\s0\fR you want to fetch the data from.
.IP "\fI\s-1CF\s0\fR" 8
.IX Item "CF"
the consolidation function that is applied to the data you
want to fetch (\s-1AVERAGE\s0,MIN,MAX,LAST)
.IP "\fB\-\-resolution\fR|\fB\-r\fR \fIresolution\fR (default is the highest resolution)" 8
.IX Item "--resolution|-r resolution (default is the highest resolution)"
the interval you want the values to have (seconds per
value). \fBrrdfetch\fR will try to match your request, but it will return
data even if no absolute match is possible. \fB\s-1NB\s0.\fR See note below.
.IP "\fB\-\-start\fR|\fB\-s\fR \fIstart\fR (default end\-1day)" 8
.IX Item "--start|-s start (default end-1day)"
start of the time series. A 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 fetched. See also AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0
section for a detailed explanation on ways to specify the start time.
.IP "\fB\-\-end\fR|\fB\-e\fR \fIend\fR (default now)" 8
.IX Item "--end|-e end (default now)"
the end of the time series in seconds since epoch. See also AT-STYLE
\&\s-1TIME\s0 \s-1SPECIFICATION\s0 section for a detailed explanation of how to
specify the end time.
.IP "\fB\-\-daemon\fR \fIaddress\fR" 8
.IX Item "--daemon address"
Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
to the server before reading the \s-1RRD\s0 files. This allows \fBrrdtool\fR to return
fresh data even if the daemon is configured to cache values for a long time.
For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
.Sp
.Vb 1
\& rrdtool fetch \-\-daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd AVERAGE
.Ve
.SS "\s-1RESOLUTION\s0 \s-1INTERVAL\s0"
.IX Subsection "RESOLUTION INTERVAL"
In order to get RRDtool to fetch anything other than the finest resolution \s-1RRA\s0
\&\fBboth\fR the start and end time must be specified on boundaries that are
multiples of the desired resolution. Consider the following example:
.PP
.Vb 7
\& rrdtool create subdata.rrd \-s 10 DS:ds0:GAUGE:300:0:U \e
\& RRA:AVERAGE:0.5:30:3600 \e
\& RRA:AVERAGE:0.5:90:1200 \e
\& RRA:AVERAGE:0.5:360:1200 \e
\& RRA:MAX:0.5:360:1200 \e
\& RRA:AVERAGE:0.5:8640:600 \e
\& RRA:MAX:0.5:8640:600
.Ve
.PP
This \s-1RRD\s0 collects data every 10 seconds and stores its averages over 5
minutes, 15 minutes, 1 hour, and 1 day, as well as the maxima for 1 hour
and 1 day.
.PP
Consider now that you want to fetch the 15 minute average data for the
last hour. You might try
.PP
.Vb 1
\& rrdtool fetch subdata.rrd AVERAGE \-r 900 \-s \-1h
.Ve
.PP
However, this will almost always result in a time series that is
\&\fB\s-1NOT\s0\fR in the 15 minute \s-1RRA\s0. Therefore, the highest resolution \s-1RRA\s0,
i.e. 5 minute averages, will be chosen which in this case is not
what you want.
.PP
Hence, make sure that
.IP "1." 3
both start and end time are a multiple of 900
.IP "2." 3
both start and end time are within the desired \s-1RRA\s0
.PP
So, if time now is called \*(L"t\*(R", do
.PP
.Vb 3
\& end time == int(t/900)*900,
\& start time == end time \- 1hour,
\& resolution == 900.
.Ve
.PP
Using the bash shell, this could look be:
.PP
.Vb 4
\& TIME=$(date +%s)
\& RRDRES=900
\& rrdtool fetch subdata.rrd AVERAGE \-r $RRDRES \e
\& \-e $(($TIME/$RRDRES*$RRDRES)) \-s e\-1h
.Ve
.PP
Or in Perl:
.PP
.Vb 3
\& perl \-e \*(Aq$ctime = time; $rrdres = 900; \e
\& system "rrdtool fetch subdata.rrd AVERAGE \e
\& \-r $rrdres \-e @{[int($ctime/$rrdres)*$rrdres]} \-s e\-1h"\*(Aq
.Ve
.SS "AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0"
.IX Subsection "AT-STYLE TIME SPECIFICATION"
Apart from the traditional \fISeconds since epoch\fR, RRDtool does also
understand at-style time specification. The specification is called
\&\*(L"at-style\*(R" after the Unix command \fIat\fR\|(1) that has moderately complex
ways to specify time to run your job at a certain date and time. The
at-style specification consists of two parts: the \fB\s-1TIME\s0 \s-1REFERENCE\s0\fR
specification and the \fB\s-1TIME\s0 \s-1OFFSET\s0\fR specification.
.SS "\s-1TIME\s0 \s-1REFERENCE\s0 \s-1SPECIFICATION\s0"
.IX Subsection "TIME REFERENCE SPECIFICATION"
The time reference specification is used, well, to establish a reference
moment in time (to which the time offset is then applied to). When present,
it should come first, when omitted, it defaults to \fBnow\fR. On its own part,
time reference consists of a \fItime-of-day\fR reference (which should come
first, if present) and a \fIday\fR reference.
.PP
The \fItime-of-day\fR can be specified as \fB\s-1HH:MM\s0\fR, \fB\s-1HH\s0.MM\fR,
or just \fB\s-1HH\s0\fR. You can suffix it with \fBam\fR or \fBpm\fR or use
24\-hours clock. Some special times of day are understood as well,
including \fBmidnight\fR (00:00), \fBnoon\fR (12:00) and British
\&\fBteatime\fR (16:00).
.PP
The \fIday\fR can be specified as \fImonth-name\fR \fIday-of-the-month\fR and
optional a 2\- or 4\-digit \fIyear\fR number (e.g. March 8 1999). Alternatively,
you can use \fIday-of-week-name\fR (e.g. Monday), or one of the words:
\&\fByesterday\fR, \fBtoday\fR, \fBtomorrow\fR. You can also specify the \fIday\fR as a
full date in several numerical formats, including \fBMM/DD/[\s-1YY\s0]YY\fR,
\&\fB\s-1DD\s0.MM.[\s-1YY\s0]YY\fR, or \fB\s-1YYYYMMDD\s0\fR.
.PP
\&\fI\s-1NOTE1\s0\fR: this is different from the original \fIat\fR\|(1) behavior, where a
single-number date is interpreted as MMDD[\s-1YY\s0]YY.
.PP
\&\fI\s-1NOTE2\s0\fR: if you specify the \fIday\fR in this way, the \fItime-of-day\fR is
\&\s-1REQUIRED\s0 as well.
.PP
Finally, you can use the words \fBnow\fR, \fBstart\fR, or \fBend\fR as your time
reference. \fBNow\fR refers to the current moment (and is also the default
time reference). \fBStart\fR (\fBend\fR) can be used to specify a time
relative to the start (end) time for those tools that use these
categories (\fBrrdfetch\fR, rrdgraph).
.PP
Month and day of the week names can be used in their naturally
abbreviated form (e.g., Dec for December, Sun for Sunday, etc.). The
words \fBnow\fR, \fBstart\fR, \fBend\fR can be abbreviated as \fBn\fR, \fBs\fR, \fBe\fR.
.SS "\s-1TIME\s0 \s-1OFFSET\s0 \s-1SPECIFICATION\s0"
.IX Subsection "TIME OFFSET SPECIFICATION"
The time offset specification is used to add/subtract certain time
intervals to/from the time reference moment. It consists of a \fIsign\fR
(\fB+\fR\ or\ \fB\-\fR) and an \fIamount\fR. The following time units can be
used to specify the \fIamount\fR: \fByears\fR, \fBmonths\fR, \fBweeks\fR, \fBdays\fR,
\&\fBhours\fR, \fBminutes\fR, or \fBseconds\fR. These units can be used in
singular or plural form, and abbreviated naturally or to a single
letter (e.g. +3days, \-1wk, \-3y). Several time units can be combined
(e.g., \-5mon1w2d) or concatenated (e.g., \-5h45min = \-5h\-45min =
\&\-6h+15min = \-7h+1h30m\-15min, etc.)
.PP
\&\fI\s-1NOTE3\s0\fR: If you specify time offset in days, weeks, months, or years,
you will end with the time offset that may vary depending on your time
reference, because all those time units have no single well defined
time interval value (1\ year contains either 365 or 366 days, 1\ month
is 28 to 31 days long, and even 1\ day may be not equal to 24 hours
twice a year, when DST-related clock adjustments take place).
To cope with this, when you use days, weeks, months, or years
as your time offset units your time reference date is adjusted
accordingly without too much further effort to ensure anything
about it (in the hope that \fImktime\fR\|(3) will take care of this later).
This may lead to some surprising (or even invalid!) results,
e.g. 'May\ 31\ \-1month' = 'Apr\ 31' (meaningless) = 'May\ 1'
(after \fImktime\fR\|(3) normalization); in the \s-1EET\s0 timezone
\&'3:30am Mar 29 1999 \-1 day' yields '3:30am Mar 28 1999' (Sunday)
which is an invalid time/date combination (because of 3am \-> 4am \s-1DST\s0
forward clock adjustment, see the below example).
.PP
In contrast, hours, minutes, and seconds are well defined time
intervals, and these are guaranteed to always produce time offsets
exactly as specified (e.g. for \s-1EET\s0 timezone, '8:00\ Mar\ 27\ 1999\ +2\ days' = '8:00\ Mar\ 29\ 1999', but since there is 1\-hour \s-1DST\s0 forward
clock adjustment that occurs around 3:00\ Mar\ 28\ 1999, the actual
time interval between 8:00\ Mar\ 27\ 1999 and 8:00\ Mar\ 29\ 1999
equals 47 hours; on the other hand, '8:00\ Mar\ 27\ 1999\ +48\ hours' =
\&'9:00\ Mar\ 29\ 1999', as expected)
.PP
\&\fI\s-1NOTE4\s0\fR: The single-letter abbreviation for both \fBmonths\fR and \fBminutes\fR
is \fBm\fR. To disambiguate them, the parser tries to read your mind\ :)
by applying the following two heuristics:
.IP "1." 3
If \fBm\fR is used in context of (i.e. right after the) years,
months, weeks, or days it is assumed to mean \fBmonths\fR, while
in the context of hours, minutes, and seconds it means minutes.
(e.g., in \-1y6m or +3w1m \fBm\fR is interpreted as \fBmonths\fR, while in
\&\-3h20m or +5s2m \fBm\fR the parser decides for \fBminutes\fR).
.IP "2." 3
Out of context (i.e. right after the \fB+\fR or \fB\-\fR sign) the
meaning of \fBm\fR is guessed from the number it directly follows.
Currently, if the number's absolute value is below 25 it is assumed
that \fBm\fR means \fBmonths\fR, otherwise it is treated as \fBminutes\fR.
(e.g., \-25m == \-25 minutes, while +24m == +24 months)
.PP
\&\fIFinal \s-1NOTES\s0\fR: Time specification is case-insensitive.
Whitespace can be inserted freely or omitted altogether.
There are, however, cases when whitespace is required
(e.g., 'midnight\ Thu'). In this case you should either quote the
whole phrase to prevent it from being taken apart by your shell or use
\&'_' (underscore) or ',' (comma) which also count as whitespace
(e.g., midnight_Thu or midnight,Thu).
.SS "\s-1TIME\s0 \s-1SPECIFICATION\s0 \s-1EXAMPLES\s0"
.IX Subsection "TIME SPECIFICATION EXAMPLES"
\&\fIOct 12\fR \*(-- October 12 this year
.PP
\&\fI\-1month\fR or \fI\-1m\fR \*(-- current time of day, only a month before
(may yield surprises, see \s-1NOTE3\s0 above).
.PP
\&\fInoon yesterday \-3hours\fR \*(-- yesterday morning; can also be specified
as \fI9am\-1day\fR.
.PP
\&\fI23:59 31.12.1999\fR \*(-- 1 minute to the year 2000.
.PP
\&\fI12/31/99 11:59pm\fR \*(-- 1 minute to the year 2000 for imperialists.
.PP
\&\fI12am 01/01/01\fR \*(-- start of the new millennium
.PP
\&\fIend\-3weeks\fR or \fIe\-3w\fR \*(-- 3 weeks before end time
(may be used as start time specification).
.PP
\&\fIstart+6hours\fR or \fIs+6h\fR \*(-- 6 hours after start time
(may be used as end time specification).
.PP
\&\fI931225537\fR \*(-- 18:45 July 5th, 1999
(yes, seconds since 1970 are valid as well).
.PP
\&\fI19970703 12:45\fR \*(-- 12:45 July 3th, 1997
(my favorite, and its even got an \s-1ISO\s0 number (8601)).
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables may be used to change the behavior of
\&\f(CW\*(C`rrdtool\ fetch\*(C'\fR:
.IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
.IX Item "RRDCACHED_ADDRESS"
If this environment variable is set it will have the same effect as specifying
the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
line argument takes precedence.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047514000081a40000000000000000000000015295523500004e9d0000011f00010018ffffffffffffffff0000002d00000000root/usr/local/share/man/man1/rrdgraph_rpn.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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_RPN 1"
.TH RRDGRAPH_RPN 1 "2009-10-14" "1.4.4" "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_rpn \- About RPN Math in rrdtool graph
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fI\s-1RPN\s0 expression\fR:=\fIvname\fR|\fIoperator\fR|\fIvalue\fR[,\fI\s-1RPN\s0 expression\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you have ever used a traditional \s-1HP\s0 calculator you already know
\&\fB\s-1RPN\s0\fR (Reverse Polish Notation).
The idea behind \fB\s-1RPN\s0\fR is that you have a stack and push
your data onto this stack. Whenever you execute an operation, it
takes as many elements from the stack as needed. Pushing is done
implicitly, so whenever you specify a number or a variable, it gets
pushed onto the stack automatically.
.PP
At the end of the calculation there should be one and only one value left on
the stack. This is the outcome of the function and this is what is put into
the \fIvname\fR. For \fB\s-1CDEF\s0\fR instructions, the stack is processed for each
data point on the graph. \fB\s-1VDEF\s0\fR instructions work on an entire data set in
one run. Note, that currently \fB\s-1VDEF\s0\fR instructions only support a limited
list of functions.
.PP
Example: \f(CW\*(C`VDEF:maximum=mydata,MAXIMUM\*(C'\fR
.PP
This will set variable \*(L"maximum\*(R" which you now can use in the rest
of your \s-1RRD\s0 script.
.PP
Example: \f(CW\*(C`CDEF:mydatabits=mydata,8,*\*(C'\fR
.PP
This means: push variable \fImydata\fR, push the number 8, execute
the operator \fI*\fR. The operator needs two elements and uses those
to return one value. This value is then stored in \fImydatabits\fR.
As you may have guessed, this instruction means nothing more than
\&\fImydatabits = mydata * 8\fR. The real power of \fB\s-1RPN\s0\fR lies in the
fact that it is always clear in which order to process the input.
For expressions like \f(CW\*(C`a = b + 3 * 5\*(C'\fR you need to multiply 3 with
5 first before you add \fIb\fR to get \fIa\fR. However, with parentheses
you could change this order: \f(CW\*(C`a = (b + 3) * 5\*(C'\fR. In \fB\s-1RPN\s0\fR, you
would do \f(CW\*(C`a = b, 3, +, 5, *\*(C'\fR without the need for parentheses.
.SH "OPERATORS"
.IX Header "OPERATORS"
.IP "Boolean operators" 4
.IX Item "Boolean operators"
\&\fB\s-1LT\s0, \s-1LE\s0, \s-1GT\s0, \s-1GE\s0, \s-1EQ\s0, \s-1NE\s0\fR
.Sp
Pop two elements from the stack, compare them for the selected condition
and return 1 for true or 0 for false. Comparing an \fIunknown\fR or an
\&\fIinfinite\fR value will always result in 0 (false).
.Sp
\&\fB\s-1UN\s0, \s-1ISINF\s0\fR
.Sp
Pop one element from the stack, compare this to \fIunknown\fR respectively
to \fIpositive or negative infinity\fR. Returns 1 for true or 0 for false.
.Sp
\&\fB\s-1IF\s0\fR
.Sp
Pops three elements from the stack. If the element popped last is 0
(false), the value popped first is pushed back onto the stack,
otherwise the value popped second is pushed back. This does, indeed,
mean that any value other than 0 is considered to be true.
.Sp
Example: \f(CW\*(C`A,B,C,IF\*(C'\fR should be read as \f(CW\*(C`if (A) then (B) else (C)\*(C'\fR
.Sp
.IP "Comparing values" 4
.IX Item "Comparing values"
\&\fB\s-1MIN\s0, \s-1MAX\s0\fR
.Sp
Pops two elements from the stack and returns the smaller or larger,
respectively. Note that \fIinfinite\fR is larger than anything else.
If one of the input numbers is \fIunknown\fR then the result of the operation will be
\&\fIunknown\fR too.
.Sp
\&\fB\s-1LIMIT\s0\fR
.Sp
Pops two elements from the stack and uses them to define a range.
Then it pops another element and if it falls inside the range, it
is pushed back. If not, an \fIunknown\fR is pushed.
.Sp
The range defined includes the two boundaries (so: a number equal
to one of the boundaries will be pushed back). If any of the three
numbers involved is either \fIunknown\fR or \fIinfinite\fR this function
will always return an \fIunknown\fR
.Sp
Example: \f(CW\*(C`CDEF:a=alpha,0,100,LIMIT\*(C'\fR will return \fIunknown\fR if
alpha is lower than 0 or if it is higher than 100.
.Sp
.IP "Arithmetics" 4
.IX Item "Arithmetics"
\&\fB+, \-, *, /, %\fR
.Sp
Add, subtract, multiply, divide, modulo
.Sp
\&\fB\s-1ADDNAN\s0\fR
.Sp
NAN-safe addition. If one parameter is \s-1NAN/UNKNOWN\s0 it'll be treated as
zero. If both parameters are \s-1NAN/UNKNOWN\s0, \s-1NAN/UNKNOWN\s0 will be returned.
.Sp
\&\fB\s-1SIN\s0, \s-1COS\s0, \s-1LOG\s0, \s-1EXP\s0, \s-1SQRT\s0\fR
.Sp
Sine and cosine (input in radians), log and exp (natural logarithm),
square root.
.Sp
\&\fB\s-1ATAN\s0\fR
.Sp
Arctangent (output in radians).
.Sp
\&\fB\s-1ATAN2\s0\fR
.Sp
Arctangent of y,x components (output in radians).
This pops one element from the stack, the x (cosine) component, and then
a second, which is the y (sine) component.
It then pushes the arctangent of their ratio, resolving the ambiguity between
quadrants.
.Sp
Example: \f(CW\*(C`CDEF:angle=Y,X,ATAN2,RAD2DEG\*(C'\fR will convert \f(CW\*(C`X,Y\*(C'\fR
components into an angle in degrees.
.Sp
\&\fB\s-1FLOOR\s0, \s-1CEIL\s0\fR
.Sp
Round down or up to the nearest integer.
.Sp
\&\fB\s-1DEG2RAD\s0, \s-1RAD2DEG\s0\fR
.Sp
Convert angle in degrees to radians, or radians to degrees.
.Sp
\&\fB\s-1ABS\s0\fR
.Sp
Take the absolute value.
.IP "Set Operations" 4
.IX Item "Set Operations"
\&\fB\s-1SORT\s0, \s-1REV\s0\fR
.Sp
Pop one element from the stack. This is the \fIcount\fR of items to be sorted
(or reversed). The top \fIcount\fR of the remaining elements are then sorted
(or reversed) in place on the stack.
.Sp
Example: \f(CW\*(C`CDEF:x=v1,v2,v3,v4,v5,v6,6,SORT,POP,5,REV,POP,+,+,+,4,/\*(C'\fR will
compute the average of the values v1 to v6 after removing the smallest and
largest.
.Sp
\&\fB\s-1AVG\s0\fR
.Sp
Pop one element (\fIcount\fR) from the stack. Now pop \fIcount\fR elements and build the
average, ignoring all \s-1UNKNOWN\s0 values in the process.
.Sp
Example: \f(CW\*(C`CDEF:x=a,b,c,d,4,AVG\*(C'\fR
.Sp
\&\fB\s-1TREND\s0, \s-1TRENDNAN\s0\fR
.Sp
Create a \*(L"sliding window\*(R" average of another data series.
.Sp
Usage:
CDEF:smoothed=x,1800,TREND
.Sp
This will create a half-hour (1800 second) sliding window average of x. The
average is essentially computed as shown here:
.Sp
.Vb 8
\& +\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\->
\& now
\& delay t0
\&
\& delay t1
\&
\& delay t2
\&
\&
\&
\& Value at sample (t0) will be the average between (t0\-delay) and (t0)
\& Value at sample (t1) will be the average between (t1\-delay) and (t1)
\& Value at sample (t2) will be the average between (t2\-delay) and (t2)
.Ve
.Sp
\&\s-1TRENDNAN\s0 is \- in contrast to \s-1TREND\s0 \- NAN-safe. If you use \s-1TREND\s0 and one
source value is \s-1NAN\s0 the complete sliding window is affected. The \s-1TRENDNAN\s0
operation ignores all NAN-values in a sliding window and computes the
average of the remaining values.
.Sp
\&\fB\s-1PREDICT\s0, \s-1PREDICTSIGMA\s0\fR
.Sp
Create a \*(L"sliding window\*(R" average/sigma of another data series, that also
shifts the data series by given amounts of of time as well
.Sp
Usage \- explicit stating shifts:
CDEF:predict=,...,,n,,x,PREDICT
CDEF:sigma=,...,,n,,x,PREDICTSIGMA
.Sp
Usage \- shifts defined as a base shift and a number of time this is applied
CDEF:predict=,\-n,,x,PREDICT
CDEF:sigma=,\-n,,x,PREDICTSIGMA
.Sp
Example:
CDEF:predict=172800,86400,2,1800,x,PREDICT
.Sp
This will create a half-hour (1800 second) sliding window average/sigma of x, that
average is essentially computed as shown here:
.Sp
.Vb 10
\& +\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\->
\& now
\& shift 1 t0
\&
\& window
\&
\& shift 2
\&
\& window
\&
\& shift 1 t1
\&
\& window
\&
\& shift 2
\&
\& window
\&
\&
\& Value at sample (t0) will be the average between (t0\-shift1\-window) and (t0\-shift1)
\& and between (t0\-shift2\-window) and (t0\-shift2)
\& Value at sample (t1) will be the average between (t1\-shift1\-window) and (t1\-shift1)
\& and between (t1\-shift2\-window) and (t1\-shift2)
.Ve
.Sp
The function is by design NAN-safe.
This also allows for extrapolation into the future (say a few days)
\&\- you may need to define the data series whit the optional start= parameter, so that
the source data series has enough data to provide prediction also at the beginning of a graph...
.Sp
Here an example, that will create a 10 day graph that also shows the
prediction 3 days into the future with its uncertainty value (as defined by avg+\-4*sigma)
This also shows if the prediction is exceeded at a certain point.
.Sp
rrdtool graph image.png \-\-imgformat=PNG \e
\-\-start=\-7days \-\-end=+3days \-\-width=1000 \-\-height=200 \-\-alt\-autoscale\-max \e
DEF:value=value.rrd:value:AVERAGE:start=\-14days \e
LINE1:value#ff0000:value \e
CDEF:predict=86400,\-7,1800,value,PREDICT \e
CDEF:sigma=86400,\-7,1800,value,PREDICTSIGMA \e
CDEF:upper=predict,sigma,3,*,+ \e
CDEF:lower=predict,sigma,3,*,\- \e
LINE1:predict#00ff00:prediction \e
LINE1:upper#0000ff:upper\e certainty\e limit \e
LINE1:lower#0000ff:lower\e certainty\e limit \e
CDEF:exceeds=value,UN,0,value,lower,upper,LIMIT,UN,IF \e
TICK:exceeds#aa000080:1
.Sp
Note: Experience has shown that a factor between 3 and 5 to scale sigma is a good
discriminator to detect abnormal behavior. This obviously depends also on the type
of data and how \*(L"noisy\*(R" the data series is.
.Sp
This prediction can only be used for short term extrapolations \- say a few days into the future\-
.IP "Special values" 4
.IX Item "Special values"
\&\fB\s-1UNKN\s0\fR
.Sp
Pushes an unknown value on the stack
.Sp
\&\fB\s-1INF\s0, \s-1NEGINF\s0\fR
.Sp
Pushes a positive or negative infinite value on the stack. When
such a value is graphed, it appears at the top or bottom of the
graph, no matter what the actual value on the y\-axis is.
.Sp
\&\fB\s-1PREV\s0\fR
.Sp
Pushes an \fIunknown\fR value if this is the first value of a data
set or otherwise the result of this \fB\s-1CDEF\s0\fR at the previous time
step. This allows you to do calculations across the data. This
function cannot be used in \fB\s-1VDEF\s0\fR instructions.
.Sp
\&\fB\s-1PREV\s0(vname)\fR
.Sp
Pushes an \fIunknown\fR value if this is the first value of a data
set or otherwise the result of the vname variable at the previous time
step. This allows you to do calculations across the data. This
function cannot be used in \fB\s-1VDEF\s0\fR instructions.
.Sp
\&\fB\s-1COUNT\s0\fR
.Sp
Pushes the number 1 if this is the first value of the data set, the
number 2 if it is the second, and so on. This special value allows
you to make calculations based on the position of the value within
the data set. This function cannot be used in \fB\s-1VDEF\s0\fR instructions.
.IP "Time" 4
.IX Item "Time"
Time inside RRDtool is measured in seconds since the epoch. The
epoch is defined to be \f(CW\*(C`Thu\ Jan\ \ 1\ 00:00:00\ UTC\ 1970\*(C'\fR.
.Sp
\&\fB\s-1NOW\s0\fR
.Sp
Pushes the current time on the stack.
.Sp
\&\fB\s-1TIME\s0\fR
.Sp
Pushes the time the currently processed value was taken at onto the stack.
.Sp
\&\fB\s-1LTIME\s0\fR
.Sp
Takes the time as defined by \fB\s-1TIME\s0\fR, applies the time zone offset
valid at that time including daylight saving time if your \s-1OS\s0 supports
it, and pushes the result on the stack. There is an elaborate example
in the examples section below on how to use this.
.IP "Processing the stack directly" 4
.IX Item "Processing the stack directly"
\&\fB\s-1DUP\s0, \s-1POP\s0, \s-1EXC\s0\fR
.Sp
Duplicate the top element, remove the top element, exchange the two
top elements.
.Sp
.SH "VARIABLES"
.IX Header "VARIABLES"
These operators work only on \fB\s-1VDEF\s0\fR statements. Note that currently \s-1ONLY\s0 these work for \fB\s-1VDEF\s0\fR.
.IP "\s-1MAXIMUM\s0, \s-1MINIMUM\s0, \s-1AVERAGE\s0" 4
.IX Item "MAXIMUM, MINIMUM, AVERAGE"
Return the corresponding value, \s-1MAXIMUM\s0 and \s-1MINIMUM\s0 also return
the first occurrence of that value in the time component.
.Sp
Example: \f(CW\*(C`VDEF:avg=mydata,AVERAGE\*(C'\fR
.IP "\s-1STDEV\s0" 4
.IX Item "STDEV"
Returns the standard deviation of the values.
.Sp
Example: \f(CW\*(C`VDEF:stdev=mydata,STDEV\*(C'\fR
.IP "\s-1LAST\s0, \s-1FIRST\s0" 4
.IX Item "LAST, FIRST"
Return the last/first value including its time. The time for
\&\s-1FIRST\s0 is actually the start of the corresponding interval, whereas
\&\s-1LAST\s0 returns the end of the corresponding interval.
.Sp
Example: \f(CW\*(C`VDEF:first=mydata,FIRST\*(C'\fR
.IP "\s-1TOTAL\s0" 4
.IX Item "TOTAL"
Returns the rate from each defined time slot multiplied with the
step size. This can, for instance, return total bytes transferred
when you have logged bytes per second. The time component returns
the number of seconds.
.Sp
Example: \f(CW\*(C`VDEF:total=mydata,TOTAL\*(C'\fR
.IP "\s-1PERCENT\s0, \s-1PERCENTNAN\s0" 4
.IX Item "PERCENT, PERCENTNAN"
This should follow a \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR \fIvname\fR. The \fIvname\fR is popped,
another number is popped which is a certain percentage (0..100). The
data set is then sorted and the value returned is chosen such that
\&\fIpercentage\fR percent of the values is lower or equal than the result.
For \s-1PERCENTNAN\s0 \fIUnknown\fR values are ignored, but for \s-1PERCENT\s0
\&\fIUnknown\fR values are considered lower than any finite number for this
purpose so if this operator returns an \fIunknown\fR you have quite a lot
of them in your data. \fBInf\fRinite numbers are lesser, or more, than the
finite numbers and are always more than the \fIUnknown\fR numbers.
(NaN < \-INF < finite values < \s-1INF\s0)
.Sp
Example: \f(CW\*(C`VDEF:perc95=mydata,95,PERCENT\*(C'\fR
\f(CW\*(C`VDEF:percnan95=mydata,95,PERCENTNAN\*(C'\fR
.IP "\s-1LSLSLOPE\s0, \s-1LSLINT\s0, \s-1LSLCORREL\s0" 4
.IX Item "LSLSLOPE, LSLINT, LSLCORREL"
Return the parameters for a \fBL\fReast \fBS\fRquares \fBL\fRine \fI(y = mx +b)\fR
which approximate the provided dataset. \s-1LSLSLOPE\s0 is the slope \fI(m)\fR of
the line related to the \s-1COUNT\s0 position of the data. \s-1LSLINT\s0 is the
y\-intercept \fI(b)\fR, which happens also to be the first data point on the
graph. \s-1LSLCORREL\s0 is the Correlation Coefficient (also know as Pearson's
Product Moment Correlation Coefficient). It will range from 0 to +/\-1
and represents the quality of fit for the approximation.
.Sp
Example: \f(CW\*(C`VDEF:slope=mydata,LSLSLOPE\*(C'\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdgraph gives an overview of how \fBrrdtool graph\fR works.
rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
rrdgraph_graph page describes all of the graph and print functions.
.PP
Make sure to read rrdgraph_examples for tips&tricks.
.SH "AUTHOR"
.IX Header "AUTHOR"
Program by Tobias Oetiker
.PP
This manual page by Alex van den Bogaerdt
with corrections and/or additions by several people
07070100047513000081a40000000000000000000000015295523500002ad30000011f00010018ffffffffffffffff0000003000000000root/usr/local/share/man/man1/rrdgraph_libdbi.1 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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_LIBDBI 1"
.TH RRDGRAPH_LIBDBI 1 "2009-10-14" "1.4.4" "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_libdbi \- fetching data for graphing in rrdtool graph via libdbi
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
= \fBsql///=/...[/rrdminstepsize=][/rrdfillmissing=]//

"
.Vb 1
\& defines the table from which to fetch the resultset.
\&
\& If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a "+"
\&
\& hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
.Ve
.IP "\fB\fR" 8
.IX Item ""
.Vb 2
\& defines the column of EtableE which contains the unix\-timestamp
\& \- if this is a DATETIME field in the database, then prefix with leading \*(Aq*\*(Aq
\&
\& hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
.Ve
.IP "\fB\fR" 8
.IX Item ""
.Vb 1
\& defines the column of EtableE which contains the value column, which should be graphed
\&
\& hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
.Ve
.IP "\fB/derive\fR" 8
.IX Item "/derive"
.Vb 1
\& defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources)
.Ve
.IP "\fB/\fR" 8
.IX Item "/"
.Vb 1
\& defines one (ore more) where clauses that are joined with AND to filter the entries in the table
\&
\& hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
.Ve
.PP
the returned value column-names, which can be used as ds-names, are:
.IP "\fBmin\fR, \fBavg\fR, \fBmax\fR, \fBcount\fR and \fBsigma\fR" 8
.IX Item "min, avg, max, count and sigma"
.Vb 3
\& are returned to be used as ds\-names in your DS definition.
\& The reason for using this is that if the consolidation function is used for min/avg and max, then the engine is used several times.
\& And this results in the same SQL Statements used several times
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here an example of a table in a MySQL database:
.PP
.Vb 5
\& DB connect information
\& dbhost=127.0.0.1
\& user=rrd
\& password=secret
\& database=rrd
\&
\& here the table:
\& CREATE TABLE RRDValue (
\& RRDKeyID bigint(20) NOT NULL,
\& UnixTimeStamp int(11) NOT NULL,
\& value double default NOT NULL,
\& PRIMARY KEY (RRDKeyID,UnixTimeStamp)
\& );
.Ve
.PP
and the RRDKeyID we want to graph for is: 1141942900757789274
.PP
The pseudo rrd-filename to access this is:
\&\*(L"sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=secret//RRDValue/UnixTimeStamp/value/RRDKeyID=1141464142203608274\*(R"
.PP
To illustrate this here a command to create a graph that contains the actual values.
.PP
.Vb 10
\& DS_BASE="sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=passwd//RRDValue/UnixTimeStamp/value/RRDKeyID=1141942900757789274"
\& rrdtool graph test.png \-\-imgformat=PNG \-\-start=\-1day \-\-end=+3hours \-\-width=1000 \-\-height=600 \e
\& "DEF:min=$DS_BASE:min:AVERAGE" \e
\& "LINE1:min#FF0000:value" \e
\& "DEF:avg=$DS_BASE:avg:AVERAGE" \e
\& "LINE1:avg#00FF00:average" \e
\& "DEF:max=$DS_BASE:max:AVERAGE" \e
\& "LINE1:max#FF0000:max" \e
\& "DEF:sigma=$DS_BASE:sigma:AVERAGE" \e
\& "CDEF:upper=avg,4,sigma,*,+" \e
\& "LINE1:upper#0000FF:+4 sigma" \e
\& "CDEF:lower=avg,4,sigma,*,\-" \e
\& "LINE1:lower#0000FF:\-4 sigma"
.Ve
.SH "NOTES"
.IX Header "NOTES"
* Naturally you can also use any other kind of driver that libdbi supports \- e.g postgres, ...
.PP
* From the way the data source is joined, it should also be possible to do joins over different tables
(separate tables with \*(L",\*(R" in table and add in the \s-1WHERE\s0 Clauses the table equal joins.
This has not been tested!!!)
.PP
* It should also be relatively simple to add to the database using the same data source string.
This has not been implemented...
.PP
* The aggregation functions are ignored and several data columns are used instead
to avoid querying the same \s-1SQL\s0 several times when minimum, average and maximum are needed for graphing...
.PP
* for \s-1DB\s0 efficiency you should think of having 2 tables, one containing historic values and the other containing the latest data.
This second table should be kept small to allow for the least ammount of blocking \s-1SQL\s0 statements.
Whith mysql you can even use myisam table-type for the first and InnoDB for the second.
This is especially interresting as with tables with +100M rows myisam is much smaller then InnoDB.
.PP
* To debug the \s-1SQL\s0 statements set the environment variable \s-1RRDDEBUGSQL\s0 and the actual \s-1SQL\s0 statements and the timing is printed to stderr.
.SH "BUGS"
.IX Header "BUGS"
* at least on Linux please make sure that the libdbi driver is explicitly linked against libdbi.so.0
check via ldd /usr/lib/dbd/libmysql.so, that there is a line with libdbi.so.0.
otherwise at least the perl module RRDs will fail because the dynamic linker can not find some symbols from libdbi.so.
(this only happens when the libdbi driver is actually used the first time!)
This is \s-1KNOWN\s0 to be the case with \s-1RHEL4\s0 and \s-1FC4\s0 and \s-1FC5\s0! (But actually this is a bug with libdbi make files!)
.PP
* at least version 0.8.1 of libdbiexhibits a bug with \s-1BINARY\s0 fields
(shorttext,text,mediumtext,longtext and possibly also \s-1BINARY\s0 and \s-1BLOB\s0 fields),
that can result in coredumps of rrdtool.
The tool will tell you on stderr if this occures, so that you know what may be the reason.
If you are not experiencing these coredumps, then set the environment variable \s-1RRD_NO_LIBDBI_BUG_WARNING\s0,
and then the message will not get shown.
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Sperl
0707010004750a000081a40000000000000000000000015295523500007e860000011f00010018ffffffffffffffff0000002a00000000root/usr/local/share/man/man1/rrdcreate.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDCREATE 1"
.TH RRDCREATE 1 "2010-03-08" "1.4.4" "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"
rrdcreate \- Set up a new Round Robin Database
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdtool\fR \fBcreate\fR \fIfilename\fR
[\fB\-\-start\fR|\fB\-b\fR\ \fIstart\ time\fR]
[\fB\-\-step\fR|\fB\-s\fR\ \fIstep\fR]
[\fB\-\-no\-overwrite\fR]
[\fB\s-1DS:\s0\fR\fIds-name\fR\fB:\fR\fI\s-1DST\s0\fR\fB:\fR\fIdst\ arguments\fR]
[\fB\s-1RRA:\s0\fR\fI\s-1CF\s0\fR\fB:\fR\fIcf\ arguments\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The create function of RRDtool lets you set up new Round Robin
Database (\fB\s-1RRD\s0\fR) files. The file is created at its final, full size
and filled with \fI*UNKNOWN*\fR data.
.SS "\fIfilename\fP"
.IX Subsection "filename"
The name of the \fB\s-1RRD\s0\fR you want to create. \fB\s-1RRD\s0\fR files should end
with the extension \fI.rrd\fR. However, \fBRRDtool\fR will accept any
filename.
.SS "\fB\-\-start\fP|\fB\-b\fP \fIstart time\fP (default: now \- 10s)"
.IX Subsection "--start|-b start time (default: now - 10s)"
Specifies the time in seconds since 1970\-01\-01 \s-1UTC\s0 when the first
value should be added to the \fB\s-1RRD\s0\fR. \fBRRDtool\fR will not accept
any data timed before or at the time specified.
.PP
See also AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0 section in the
\&\fIrrdfetch\fR documentation for other ways to specify time.
.SS "\fB\-\-step\fP|\fB\-s\fP \fIstep\fP (default: 300 seconds)"
.IX Subsection "--step|-s step (default: 300 seconds)"
Specifies the base interval in seconds with which data will be fed
into the \fB\s-1RRD\s0\fR.
.SS "\fB\-\-no\-overwrite\fP"
.IX Subsection "--no-overwrite"
Do not clobber an existing file of the same name.
.SS "\fB\s-1DS:\s0\fP\fIds-name\fP\fB:\fP\fI\s-1DST\s0\fP\fB:\fP\fIdst arguments\fP"
.IX Subsection "DS:ds-name:DST:dst arguments"
A single \fB\s-1RRD\s0\fR can accept input from several data sources (\fB\s-1DS\s0\fR),
for example incoming and outgoing traffic on a specific communication
line. With the \fB\s-1DS\s0\fR configuration option you must define some basic
properties of each data source you want to store in the \fB\s-1RRD\s0\fR.
.PP
\&\fIds-name\fR is the name you will use to reference this particular data
source from an \fB\s-1RRD\s0\fR. A \fIds-name\fR must be 1 to 19 characters long in
the characters [a\-zA\-Z0\-9_].
.PP
\&\fI\s-1DST\s0\fR defines the Data Source Type. The remaining arguments of a
data source entry depend on the data source type. For \s-1GAUGE\s0, \s-1COUNTER\s0,
\&\s-1DERIVE\s0, and \s-1ABSOLUTE\s0 the format for a data source entry is:
.PP
\&\fB\s-1DS:\s0\fR\fIds-name\fR\fB:\fR\fI\s-1GAUGE\s0 | \s-1COUNTER\s0 | \s-1DERIVE\s0 | \s-1ABSOLUTE\s0\fR\fB:\fR\fIheartbeat\fR\fB:\fR\fImin\fR\fB:\fR\fImax\fR
.PP
For \s-1COMPUTE\s0 data sources, the format is:
.PP
\&\fB\s-1DS:\s0\fR\fIds-name\fR\fB:\fR\fI\s-1COMPUTE\s0\fR\fB:\fR\fIrpn-expression\fR
.PP
In order to decide which data source type to use, review the
definitions that follow. Also consult the section on \*(L"\s-1HOW\s0 \s-1TO\s0 \s-1MEASURE\s0\*(R"
for further insight.
.IP "\fB\s-1GAUGE\s0\fR" 4
.IX Item "GAUGE"
is for things like temperatures or number of people in a room or the
value of a RedHat share.
.IP "\fB\s-1COUNTER\s0\fR" 4
.IX Item "COUNTER"
is for continuous incrementing counters like the ifInOctets counter in
a router. The \fB\s-1COUNTER\s0\fR data source assumes that the counter never
decreases, except when a counter overflows. The update function takes
the overflow into account. The counter is stored as a per-second
rate. When the counter overflows, RRDtool checks if the overflow
happened at the 32bit or 64bit border and acts accordingly by adding
an appropriate value to the result.
.IP "\fB\s-1DERIVE\s0\fR" 4
.IX Item "DERIVE"
will store the derivative of the line going from the last to the
current value of the data source. This can be useful for gauges, for
example, to measure the rate of people entering or leaving a
room. Internally, derive works exactly like \s-1COUNTER\s0 but without
overflow checks. So if your counter does not reset at 32 or 64 bit you
might want to use \s-1DERIVE\s0 and combine it with a \s-1MIN\s0 value of 0.
.Sp
\&\fB\s-1NOTE\s0 on \s-1COUNTER\s0 vs \s-1DERIVE\s0\fR
.Sp
by Don Baarda
.Sp
If you cannot tolerate ever mistaking the occasional counter reset for a
legitimate counter wrap, and would prefer \*(L"Unknowns\*(R" for all legitimate
counter wraps and resets, always use \s-1DERIVE\s0 with min=0. Otherwise, using
\&\s-1COUNTER\s0 with a suitable max will return correct values for all legitimate
counter wraps, mark some counter resets as \*(L"Unknown\*(R", but can mistake some
counter resets for a legitimate counter wrap.
.Sp
For a 5 minute step and 32\-bit counter, the probability of mistaking a
counter reset for a legitimate wrap is arguably about 0.8% per 1Mbps of
maximum bandwidth. Note that this equates to 80% for 100Mbps interfaces, so
for high bandwidth interfaces and a 32bit counter, \s-1DERIVE\s0 with min=0 is
probably preferable. If you are using a 64bit counter, just about any max
setting will eliminate the possibility of mistaking a reset for a counter
wrap.
.IP "\fB\s-1ABSOLUTE\s0\fR" 4
.IX Item "ABSOLUTE"
is for counters which get reset upon reading. This is used for fast counters
which tend to overflow. So instead of reading them normally you reset them
after every read to make sure you have a maximum time available before the
next overflow. Another usage is for things you count like number of messages
since the last update.
.IP "\fB\s-1COMPUTE\s0\fR" 4
.IX Item "COMPUTE"
is for storing the result of a formula applied to other data sources
in the \fB\s-1RRD\s0\fR. This data source is not supplied a value on update, but
rather its Primary Data Points (PDPs) are computed from the PDPs of
the data sources according to the rpn-expression that defines the
formula. Consolidation functions are then applied normally to the PDPs
of the \s-1COMPUTE\s0 data source (that is the rpn-expression is only applied
to generate PDPs). In database software, such data sets are referred
to as \*(L"virtual\*(R" or \*(L"computed\*(R" columns.
.PP
\&\fIheartbeat\fR defines the maximum number of seconds that may pass
between two updates of this data source before the value of the
data source is assumed to be \fI*UNKNOWN*\fR.
.PP
\&\fImin\fR and \fImax\fR define the expected range values for data supplied by a
data source. If \fImin\fR and/or \fImax\fR any value outside the defined range
will be regarded as \fI*UNKNOWN*\fR. If you do not know or care about min and
max, set them to U for unknown. Note that min and max always refer to the
processed values of the \s-1DS\s0. For a traffic\-\fB\s-1COUNTER\s0\fR type \s-1DS\s0 this would be
the maximum and minimum data-rate expected from the device.
.PP
\&\fIIf information on minimal/maximal expected values is available,
always set the min and/or max properties. This will help RRDtool in
doing a simple sanity check on the data supplied when running update.\fR
.PP
\&\fIrpn-expression\fR defines the formula used to compute the PDPs of a
\&\s-1COMPUTE\s0 data source from other data sources in the same . It is
similar to defining a \fB\s-1CDEF\s0\fR argument for the graph command. Please
refer to that manual page for a list and description of \s-1RPN\s0 operations
supported. For \s-1COMPUTE\s0 data sources, the following \s-1RPN\s0 operations are
not supported: \s-1COUNT\s0, \s-1PREV\s0, \s-1TIME\s0, and \s-1LTIME\s0. In addition, in defining
the \s-1RPN\s0 expression, the \s-1COMPUTE\s0 data source may only refer to the
names of data source listed previously in the create command. This is
similar to the restriction that \fB\s-1CDEF\s0\fRs must refer only to \fB\s-1DEF\s0\fRs
and \fB\s-1CDEF\s0\fRs previously defined in the same graph command.
.SS "\fB\s-1RRA:\s0\fP\fI\s-1CF\s0\fP\fB:\fP\fIcf arguments\fP"
.IX Subsection "RRA:CF:cf arguments"
The purpose of an \fB\s-1RRD\s0\fR is to store data in the round robin archives
(\fB\s-1RRA\s0\fR). An archive consists of a number of data values or statistics for
each of the defined data-sources (\fB\s-1DS\s0\fR) and is defined with an \fB\s-1RRA\s0\fR line.
.PP
When data is entered into an \fB\s-1RRD\s0\fR, it is first fit into time slots
of the length defined with the \fB\-s\fR option, thus becoming a \fIprimary
data point\fR.
.PP
The data is also processed with the consolidation function (\fI\s-1CF\s0\fR) of
the archive. There are several consolidation functions that
consolidate primary data points via an aggregate function: \fB\s-1AVERAGE\s0\fR,
\&\fB\s-1MIN\s0\fR, \fB\s-1MAX\s0\fR, \fB\s-1LAST\s0\fR.
.IP "\s-1AVERAGE\s0" 4
.IX Item "AVERAGE"
the average of the data points is stored.
.IP "\s-1MIN\s0" 4
.IX Item "MIN"
the smallest of the data points is stored.
.IP "\s-1MAX\s0" 4
.IX Item "MAX"
the largest of the data points is stored.
.IP "\s-1LAST\s0" 4
.IX Item "LAST"
the last data points is used.
.PP
Note that data aggregation inevitably leads to loss of precision and
information. The trick is to pick the aggregate function such that the
\&\fIinteresting\fR properties of your data is kept across the aggregation
process.
.PP
The format of \fB\s-1RRA\s0\fR line for these
consolidation functions is:
.PP
\&\fB\s-1RRA:\s0\fR\fI\s-1AVERAGE\s0 | \s-1MIN\s0 | \s-1MAX\s0 | \s-1LAST\s0\fR\fB:\fR\fIxff\fR\fB:\fR\fIsteps\fR\fB:\fR\fIrows\fR
.PP
\&\fIxff\fR The xfiles factor defines what part of a consolidation interval may
be made up from \fI*UNKNOWN*\fR data while the consolidated value is still
regarded as known. It is given as the ratio of allowed \fI*UNKNOWN*\fR PDPs
to the number of PDPs in the interval. Thus, it ranges from 0 to 1 (exclusive).
.PP
\&\fIsteps\fR defines how many of these \fIprimary data points\fR are used to build
a \fIconsolidated data point\fR which then goes into the archive.
.PP
\&\fIrows\fR defines how many generations of data values are kept in an \fB\s-1RRA\s0\fR.
Obviously, this has to be greater than zero.
.SH "Aberrant Behavior Detection with Holt-Winters Forecasting"
.IX Header "Aberrant Behavior Detection with Holt-Winters Forecasting"
In addition to the aggregate functions, there are a set of specialized
functions that enable \fBRRDtool\fR to provide data smoothing (via the
Holt-Winters forecasting algorithm), confidence bands, and the
flagging aberrant behavior in the data source time series:
.IP "\(bu" 4
\&\fB\s-1RRA:\s0\fR\fI\s-1HWPREDICT\s0\fR\fB:\fR\fIrows\fR\fB:\fR\fIalpha\fR\fB:\fR\fIbeta\fR\fB:\fR\fIseasonal period\fR[\fB:\fR\fIrra-num\fR]
.IP "\(bu" 4
\&\fB\s-1RRA:\s0\fR\fI\s-1MHWPREDICT\s0\fR\fB:\fR\fIrows\fR\fB:\fR\fIalpha\fR\fB:\fR\fIbeta\fR\fB:\fR\fIseasonal period\fR[\fB:\fR\fIrra-num\fR]
.IP "\(bu" 4
\&\fB\s-1RRA:\s0\fR\fI\s-1SEASONAL\s0\fR\fB:\fR\fIseasonal period\fR\fB:\fR\fIgamma\fR\fB:\fR\fIrra-num\fR[\fB:smoothing\-window=\fR\fIfraction\fR]
.IP "\(bu" 4
\&\fB\s-1RRA:\s0\fR\fI\s-1DEVSEASONAL\s0\fR\fB:\fR\fIseasonal period\fR\fB:\fR\fIgamma\fR\fB:\fR\fIrra-num\fR[\fB:smoothing\-window=\fR\fIfraction\fR]
.IP "\(bu" 4
\&\fB\s-1RRA:\s0\fR\fI\s-1DEVPREDICT\s0\fR\fB:\fR\fIrows\fR\fB:\fR\fIrra-num\fR
.IP "\(bu" 4
\&\fB\s-1RRA:\s0\fR\fI\s-1FAILURES\s0\fR\fB:\fR\fIrows\fR\fB:\fR\fIthreshold\fR\fB:\fR\fIwindow length\fR\fB:\fR\fIrra-num\fR
.PP
These \fBRRAs\fR differ from the true consolidation functions in several ways.
First, each of the \fB\s-1RRA\s0\fRs is updated once for every primary data point.
Second, these \fBRRAs\fR are interdependent. To generate real-time confidence
bounds, a matched set of \s-1SEASONAL\s0, \s-1DEVSEASONAL\s0, \s-1DEVPREDICT\s0, and either
\&\s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0 must exist. Generating smoothed values of the primary
data points requires a \s-1SEASONAL\s0 \fB\s-1RRA\s0\fR and either an \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0
\&\fB\s-1RRA\s0\fR. Aberrant behavior detection requires \s-1FAILURES\s0, \s-1DEVSEASONAL\s0, \s-1SEASONAL\s0,
and either \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0.
.PP
The predicted, or smoothed, values are stored in the \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0
\&\fB\s-1RRA\s0\fR. \s-1HWPREDICT\s0 and \s-1MHWPREDICT\s0 are actually two variations on the
Holt-Winters method. They are interchangeable. Both attempt to decompose data
into three components: a baseline, a trend, and a seasonal coefficient.
\&\s-1HWPREDICT\s0 adds its seasonal coefficient to the baseline to form a prediction, whereas
\&\s-1MHWPREDICT\s0 multiplies its seasonal coefficient by the baseline to form a
prediction. The difference is noticeable when the baseline changes
significantly in the course of a season; \s-1HWPREDICT\s0 will predict the seasonality
to stay constant as the baseline changes, but \s-1MHWPREDICT\s0 will predict the
seasonality to grow or shrink in proportion to the baseline. The proper choice
of method depends on the thing being modeled. For simplicity, the rest of this
discussion will refer to \s-1HWPREDICT\s0, but \s-1MHWPREDICT\s0 may be substituted in its
place.
.PP
The predicted deviations are stored in \s-1DEVPREDICT\s0 (think a standard deviation
which can be scaled to yield a confidence band). The \s-1FAILURES\s0 \fB\s-1RRA\s0\fR stores
binary indicators. A 1 marks the indexed observation as failure; that is, the
number of confidence bounds violations in the preceding window of observations
met or exceeded a specified threshold. An example of using these \fBRRAs\fR to graph
confidence bounds and failures appears in rrdgraph.
.PP
The \s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 \fBRRAs\fR store the seasonal coefficients for the
Holt-Winters forecasting algorithm and the seasonal deviations, respectively.
There is one entry per observation time point in the seasonal cycle. For
example, if primary data points are generated every five minutes and the
seasonal cycle is 1 day, both \s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 will have 288 rows.
.PP
In order to simplify the creation for the novice user, in addition to
supporting explicit creation of the \s-1HWPREDICT\s0, \s-1SEASONAL\s0, \s-1DEVPREDICT\s0,
\&\s-1DEVSEASONAL\s0, and \s-1FAILURES\s0 \fBRRAs\fR, the \fBRRDtool\fR create command supports
implicit creation of the other four when \s-1HWPREDICT\s0 is specified alone and
the final argument \fIrra-num\fR is omitted.
.PP
\&\fIrows\fR specifies the length of the \fB\s-1RRA\s0\fR prior to wrap around. Remember
that there is a one-to-one correspondence between primary data points and
entries in these RRAs. For the \s-1HWPREDICT\s0 \s-1CF\s0, \fIrows\fR should be larger than
the \fIseasonal period\fR. If the \s-1DEVPREDICT\s0 \fB\s-1RRA\s0\fR is implicitly created, the
default number of rows is the same as the \s-1HWPREDICT\s0 \fIrows\fR argument. If the
\&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR is implicitly created, \fIrows\fR will be set to the \fIseasonal
period\fR argument of the \s-1HWPREDICT\s0 \fB\s-1RRA\s0\fR. Of course, the \fBRRDtool\fR
\&\fIresize\fR command is available if these defaults are not sufficient and the
creator wishes to avoid explicit creations of the other specialized function
\&\fBRRAs\fR.
.PP
\&\fIseasonal period\fR specifies the number of primary data points in a seasonal
cycle. If \s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 are implicitly created, this argument for
those \fBRRAs\fR is set automatically to the value specified by \s-1HWPREDICT\s0. If
they are explicitly created, the creator should verify that all three
\&\fIseasonal period\fR arguments agree.
.PP
\&\fIalpha\fR is the adaption parameter of the intercept (or baseline)
coefficient in the Holt-Winters forecasting algorithm. See rrdtool for a
description of this algorithm. \fIalpha\fR must lie between 0 and 1. A value
closer to 1 means that more recent observations carry greater weight in
predicting the baseline component of the forecast. A value closer to 0 means
that past history carries greater weight in predicting the baseline
component.
.PP
\&\fIbeta\fR is the adaption parameter of the slope (or linear trend) coefficient
in the Holt-Winters forecasting algorithm. \fIbeta\fR must lie between 0 and 1
and plays the same role as \fIalpha\fR with respect to the predicted linear
trend.
.PP
\&\fIgamma\fR is the adaption parameter of the seasonal coefficients in the
Holt-Winters forecasting algorithm (\s-1HWPREDICT\s0) or the adaption parameter in
the exponential smoothing update of the seasonal deviations. It must lie
between 0 and 1. If the \s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 \fBRRAs\fR are created
implicitly, they will both have the same value for \fIgamma\fR: the value
specified for the \s-1HWPREDICT\s0 \fIalpha\fR argument. Note that because there is
one seasonal coefficient (or deviation) for each time point during the
seasonal cycle, the adaptation rate is much slower than the baseline. Each
seasonal coefficient is only updated (or adapts) when the observed value
occurs at the offset in the seasonal cycle corresponding to that
coefficient.
.PP
If \s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 \fBRRAs\fR are created explicitly, \fIgamma\fR need not
be the same for both. Note that \fIgamma\fR can also be changed via the
\&\fBRRDtool\fR \fItune\fR command.
.PP
\&\fIsmoothing-window\fR specifies the fraction of a season that should be
averaged around each point. By default, the value of \fIsmoothing-window\fR is
0.05, which means each value in \s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 will be occasionally
replaced by averaging it with its (\fIseasonal period\fR*0.05) nearest neighbors.
Setting \fIsmoothing-window\fR to zero will disable the running-average smoother
altogether.
.PP
\&\fIrra-num\fR provides the links between related \fBRRAs\fR. If \s-1HWPREDICT\s0 is
specified alone and the other \fBRRAs\fR are created implicitly, then
there is no need to worry about this argument. If \fBRRAs\fR are created
explicitly, then carefully pay attention to this argument. For each
\&\fB\s-1RRA\s0\fR which includes this argument, there is a dependency between
that \fB\s-1RRA\s0\fR and another \fB\s-1RRA\s0\fR. The \fIrra-num\fR argument is the 1\-based
index in the order of \fB\s-1RRA\s0\fR creation (that is, the order they appear
in the \fIcreate\fR command). The dependent \fB\s-1RRA\s0\fR for each \fB\s-1RRA\s0\fR
requiring the \fIrra-num\fR argument is listed here:
.IP "\(bu" 4
\&\s-1HWPREDICT\s0 \fIrra-num\fR is the index of the \s-1SEASONAL\s0 \fB\s-1RRA\s0\fR.
.IP "\(bu" 4
\&\s-1SEASONAL\s0 \fIrra-num\fR is the index of the \s-1HWPREDICT\s0 \fB\s-1RRA\s0\fR.
.IP "\(bu" 4
\&\s-1DEVPREDICT\s0 \fIrra-num\fR is the index of the \s-1DEVSEASONAL\s0 \fB\s-1RRA\s0\fR.
.IP "\(bu" 4
\&\s-1DEVSEASONAL\s0 \fIrra-num\fR is the index of the \s-1HWPREDICT\s0 \fB\s-1RRA\s0\fR.
.IP "\(bu" 4
\&\s-1FAILURES\s0 \fIrra-num\fR is the index of the \s-1DEVSEASONAL\s0 \fB\s-1RRA\s0\fR.
.PP
\&\fIthreshold\fR is the minimum number of violations (observed values outside
the confidence bounds) within a window that constitutes a failure. If the
\&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR is implicitly created, the default value is 7.
.PP
\&\fIwindow length\fR is the number of time points in the window. Specify an
integer greater than or equal to the threshold and less than or equal to 28.
The time interval this window represents depends on the interval between
primary data points. If the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR is implicitly created, the
default value is 9.
.SH "The HEARTBEAT and the STEP"
.IX Header "The HEARTBEAT and the STEP"
Here is an explanation by Don Baarda on the inner workings of RRDtool.
It may help you to sort out why all this *UNKNOWN* data is popping
up in your databases:
.PP
RRDtool gets fed samples/updates at arbitrary times. From these it builds Primary
Data Points (PDPs) on every \*(L"step\*(R" interval. The PDPs are
then accumulated into the RRAs.
.PP
The \*(L"heartbeat\*(R" defines the maximum acceptable interval between
samples/updates. If the interval between samples is less than \*(L"heartbeat\*(R",
then an average rate is calculated and applied for that interval. If
the interval between samples is longer than \*(L"heartbeat\*(R", then that
entire interval is considered \*(L"unknown\*(R". Note that there are other
things that can make a sample interval \*(L"unknown\*(R", such as the rate
exceeding limits, or a sample that was explicitly marked as unknown.
.PP
The known rates during a \s-1PDP\s0's \*(L"step\*(R" interval are used to calculate
an average rate for that \s-1PDP\s0. If the total \*(L"unknown\*(R" time accounts for
more than \fBhalf\fR the \*(L"step\*(R", the entire \s-1PDP\s0 is marked
as \*(L"unknown\*(R". This means that a mixture of known and \*(L"unknown\*(R" sample
times in a single \s-1PDP\s0 \*(L"step\*(R" may or may not add up to enough \*(L"known\*(R"
time to warrant a known \s-1PDP\s0.
.PP
The \*(L"heartbeat\*(R" can be short (unusual) or long (typical) relative to
the \*(L"step\*(R" interval between PDPs. A short \*(L"heartbeat\*(R" means you
require multiple samples per \s-1PDP\s0, and if you don't get them mark the
\&\s-1PDP\s0 unknown. A long heartbeat can span multiple \*(L"steps\*(R", which means
it is acceptable to have multiple PDPs calculated from a single
sample. An extreme example of this might be a \*(L"step\*(R" of 5 minutes and a
\&\*(L"heartbeat\*(R" of one day, in which case a single sample every day will
result in all the PDPs for that entire day period being set to the
same average rate. \fI\-\- Don Baarda \fR
.PP
.Vb 10
\& time|
\& axis|
\& begin_\|_|00|
\& |01|
\& u|02|\-\-\-\-* sample1, restart "hb"\-timer
\& u|03| /
\& u|04| /
\& u|05| /
\& u|06|/ "hbt" expired
\& u|07|
\& |08|\-\-\-\-* sample2, restart "hb"
\& |09| /
\& |10| /
\& u|11|\-\-\-\-* sample3, restart "hb"
\& u|12| /
\& u|13| /
\& step1_u|14| /
\& u|15|/ "swt" expired
\& u|16|
\& |17|\-\-\-\-* sample4, restart "hb", create "pdp" for step1 =
\& |18| / = unknown due to 10 "u" labled secs > 0.5 * step
\& |19| /
\& |20| /
\& |21|\-\-\-\-* sample5, restart "hb"
\& |22| /
\& |23| /
\& |24|\-\-\-\-* sample6, restart "hb"
\& |25| /
\& |26| /
\& |27|\-\-\-\-* sample7, restart "hb"
\& step2_\|_|28| /
\& |22| /
\& |23|\-\-\-\-* sample8, restart "hb", create "pdp" for step1, create "cdp"
\& |24| /
\& |25| /
.Ve
.PP
graphics by \fIvladimir.lavrov@desy.de\fR.
.SH "HOW TO MEASURE"
.IX Header "HOW TO MEASURE"
Here are a few hints on how to measure:
.IP "Temperature" 4
.IX Item "Temperature"
Usually you have some type of meter you can read to get the temperature.
The temperature is not really connected with a time. The only connection is
that the temperature reading happened at a certain time. You can use the
\&\fB\s-1GAUGE\s0\fR data source type for this. RRDtool will then record your reading
together with the time.
.IP "Mail Messages" 4
.IX Item "Mail Messages"
Assume you have a method to count the number of messages transported by
your mail server in a certain amount of time, giving you data like '5
messages in the last 65 seconds'. If you look at the count of 5 like an
\&\fB\s-1ABSOLUTE\s0\fR data type you can simply update the \s-1RRD\s0 with the number 5 and the
end time of your monitoring period. RRDtool will then record the number of
messages per second. If at some later stage you want to know the number of
messages transported in a day, you can get the average messages per second
from RRDtool for the day in question and multiply this number with the
number of seconds in a day. Because all math is run with Doubles, the
precision should be acceptable.
.IP "It's always a Rate" 4
.IX Item "It's always a Rate"
RRDtool stores rates in amount/second for \s-1COUNTER\s0, \s-1DERIVE\s0 and \s-1ABSOLUTE\s0
data. When you plot the data, you will get on the y axis
amount/second which you might be tempted to convert to an absolute
amount by multiplying by the delta-time between the points. RRDtool
plots continuous data, and as such is not appropriate for plotting
absolute amounts as for example \*(L"total bytes\*(R" sent and received in a
router. What you probably want is plot rates that you can scale to
bytes/hour, for example, or plot absolute amounts with another tool
that draws bar-plots, where the delta-time is clear on the plot for
each point (such that when you read the graph you see for example \s-1GB\s0
on the y axis, days on the x axis and one bar for each day).
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 6
\& rrdtool create temperature.rrd \-\-step 300 \e
\& DS:temp:GAUGE:600:\-273:5000 \e
\& RRA:AVERAGE:0.5:1:1200 \e
\& RRA:MIN:0.5:12:2400 \e
\& RRA:MAX:0.5:12:2400 \e
\& RRA:AVERAGE:0.5:12:2400
.Ve
.PP
This sets up an \fB\s-1RRD\s0\fR called \fItemperature.rrd\fR which accepts one
temperature value every 300 seconds. If no new data is supplied for
more than 600 seconds, the temperature becomes \fI*UNKNOWN*\fR. The
minimum acceptable value is \-273 and the maximum is 5'000.
.PP
A few archive areas are also defined. The first stores the
temperatures supplied for 100 hours (1'200 * 300 seconds = 100
hours). The second \s-1RRA\s0 stores the minimum temperature recorded over
every hour (12 * 300 seconds = 1 hour), for 100 days (2'400 hours). The
third and the fourth \s-1RRA\s0's do the same for the maximum and
average temperature, respectively.
.SH "EXAMPLE 2"
.IX Header "EXAMPLE 2"
.Vb 4
\& rrdtool create monitor.rrd \-\-step 300 \e
\& DS:ifOutOctets:COUNTER:1800:0:4294967295 \e
\& RRA:AVERAGE:0.5:1:2016 \e
\& RRA:HWPREDICT:1440:0.1:0.0035:288
.Ve
.PP
This example is a monitor of a router interface. The first \fB\s-1RRA\s0\fR tracks the
traffic flow in octets; the second \fB\s-1RRA\s0\fR generates the specialized
functions \fBRRAs\fR for aberrant behavior detection. Note that the \fIrra-num\fR
argument of \s-1HWPREDICT\s0 is missing, so the other \fBRRAs\fR will implicitly be
created with default parameter values. In this example, the forecasting
algorithm baseline adapts quickly; in fact the most recent one hour of
observations (each at 5 minute intervals) accounts for 75% of the baseline
prediction. The linear trend forecast adapts much more slowly. Observations
made during the last day (at 288 observations per day) account for only
65% of the predicted linear trend. Note: these computations rely on an
exponential smoothing formula described in the \s-1LISA\s0 2000 paper.
.PP
The seasonal cycle is one day (288 data points at 300 second intervals), and
the seasonal adaption parameter will be set to 0.1. The \s-1RRD\s0 file will store 5
days (1'440 data points) of forecasts and deviation predictions before wrap
around. The file will store 1 day (a seasonal cycle) of 0\-1 indicators in
the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR.
.PP
The same \s-1RRD\s0 file and \fBRRAs\fR are created with the following command,
which explicitly creates all specialized function \fBRRAs\fR.
.PP
.Vb 8
\& rrdtool create monitor.rrd \-\-step 300 \e
\& DS:ifOutOctets:COUNTER:1800:0:4294967295 \e
\& RRA:AVERAGE:0.5:1:2016 \e
\& RRA:HWPREDICT:1440:0.1:0.0035:288:3 \e
\& RRA:SEASONAL:288:0.1:2 \e
\& RRA:DEVPREDICT:1440:5 \e
\& RRA:DEVSEASONAL:288:0.1:2 \e
\& RRA:FAILURES:288:7:9:5
.Ve
.PP
Of course, explicit creation need not replicate implicit create, a
number of arguments could be changed.
.SH "EXAMPLE 3"
.IX Header "EXAMPLE 3"
.Vb 5
\& rrdtool create proxy.rrd \-\-step 300 \e
\& DS:Total:DERIVE:1800:0:U \e
\& DS:Duration:DERIVE:1800:0:U \e
\& DS:AvgReqDur:COMPUTE:Duration,Requests,0,EQ,1,Requests,IF,/ \e
\& RRA:AVERAGE:0.5:1:2016
.Ve
.PP
This example is monitoring the average request duration during each 300 sec
interval for requests processed by a web proxy during the interval.
In this case, the proxy exposes two counters, the number of requests
processed since boot and the total cumulative duration of all processed
requests. Clearly these counters both have some rollover point, but using the
\&\s-1DERIVE\s0 data source also handles the reset that occurs when the web proxy is
stopped and restarted.
.PP
In the \fB\s-1RRD\s0\fR, the first data source stores the requests per second rate
during the interval. The second data source stores the total duration of all
requests processed during the interval divided by 300. The \s-1COMPUTE\s0 data source
divides each \s-1PDP\s0 of the AccumDuration by the corresponding \s-1PDP\s0 of
TotalRequests and stores the average request duration. The remainder of the
\&\s-1RPN\s0 expression handles the divide by zero case.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047505000081a40000000000000000000000015295523500002d790000011f00010018ffffffffffffffff0000002c00000000root/usr/local/share/man/man1/rpntutorial.1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RPNTUTORIAL 1"
.TH RPNTUTORIAL 1 "2009-12-08" "1.4.4" "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"
rpntutorial \- Reading RRDtool RPN Expressions by Steve Rader
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This tutorial should help you get to grips with RRDtool \s-1RPN\s0 expressions
as seen in \s-1CDEF\s0 arguments of RRDtool graph.
.SH "Reading Comparison Operators"
.IX Header "Reading Comparison Operators"
The \s-1LT\s0, \s-1LE\s0, \s-1GT\s0, \s-1GE\s0 and \s-1EQ\s0 \s-1RPN\s0 logic operators are not as tricky as
they appear. These operators act on the two values on the stack
preceding them (to the left). Read these two values on the stack
from left to right inserting the operator in the middle. If the
resulting statement is true, then replace the three values from the
stack with \*(L"1\*(R". If the statement if false, replace the three values
with \*(L"0\*(R".
.PP
For example, think about \*(L"2,1,GT\*(R". This \s-1RPN\s0 expression could be
read as \*(L"is two greater than one?\*(R" The answer to that question is
\&\*(L"true\*(R". So the three values should be replaced with \*(L"1\*(R". Thus the
\&\s-1RPN\s0 expression 2,1,GT evaluates to 1.
.PP
Now consider \*(L"2,1,LE\*(R". This \s-1RPN\s0 expression could be read as \*(L"is
two less than or equal to one?\*(R". The natural response is \*(L"no\*(R"
and thus the \s-1RPN\s0 expression 2,1,LE evaluates to 0.
.SH "Reading the IF Operator"
.IX Header "Reading the IF Operator"
The \s-1IF\s0 \s-1RPN\s0 logic operator can be straightforward also. The key
to reading \s-1IF\s0 operators is to understand that the condition part
of the traditional \*(L"if X than Y else Z\*(R" notation has *already*
been evaluated. So the \s-1IF\s0 operator acts on only one value on the
stack: the third value to the left of the \s-1IF\s0 value. The second
value to the left of the \s-1IF\s0 corresponds to the true (\*(L"Y\*(R") branch.
And the first value to the left of the \s-1IF\s0 corresponds to the false
(\*(L"Z\*(R") branch. Read the \s-1RPN\s0 expression \*(L"X,Y,Z,IF\*(R" from left to
right like so: \*(L"if X then Y else Z\*(R".
.PP
For example, consider \*(L"1,10,100,IF\*(R". It looks bizarre to me.
But when I read \*(L"if 1 then 10 else 100\*(R" it's crystal clear: 1 is true
so the answer is 10. Note that only zero is false; all other values
are true. \*(L"2,20,200,IF\*(R" (\*(L"if 2 then 20 else 200\*(R") evaluates to 20.
And \*(L"0,1,2,IF\*(R" ("if 0 then 1 else 2) evaluates to 2.
.PP
Notice that none of the above examples really simulate the whole
\&\*(L"if X then Y else Z\*(R" statement. This is because computer programmers
read this statement as \*(L"if Some Condition then Y else Z\*(R". So it's
important to be able to read \s-1IF\s0 operators along with the \s-1LT\s0, \s-1LE\s0,
\&\s-1GT\s0, \s-1GE\s0 and \s-1EQ\s0 operators.
.SH "Some Examples"
.IX Header "Some Examples"
While compound expressions can look overly complex, they can be
considered elegantly simple. To quickly comprehend \s-1RPN\s0 expressions,
you must know the algorithm for evaluating \s-1RPN\s0 expressions:
iterate searches from the left to the right looking for an operator.
When it's found, apply that operator by popping the operator and some
number of values (and by definition, not operators) off the stack.
.PP
For example, the stack \*(L"1,2,3,+,+\*(R" gets \*(L"2,3,+\*(R" evaluated (as \*(L"2+3\*(R")
during the first iteration and is replaced by 5. This results in
the stack \*(L"1,5,+\*(R". Finally, \*(L"1,5,+\*(R" is evaluated resulting in the
answer 6. For convenience, it's useful to write this set of
operations as:
.PP
.Vb 3
\& 1) 1,2,3,+,+ eval is 2,3,+ = 5 result is 1,5,+
\& 2) 1,5,+ eval is 1,5,+ = 6 result is 6
\& 3) 6
.Ve
.PP
Let's use that notation to conveniently solve some complex \s-1RPN\s0 expressions
with multiple logic operators:
.PP
.Vb 1
\& 1) 20,10,GT,10,20,IF eval is 20,10,GT = 1 result is 1,10,20,IF
.Ve
.PP
read the eval as pop \*(L"20 is greater than 10\*(R" so push 1
.PP
.Vb 1
\& 2) 1,10,20,IF eval is 1,10,20,IF = 10 result is 10
.Ve
.PP
read pop \*(L"if 1 then 10 else 20\*(R" so push 10. Only 10 is left so
10 is the answer.
.PP
Let's read a complex \s-1RPN\s0 expression that also has the traditional
multiplication operator:
.PP
.Vb 4
\& 1) 128,8,*,7000,GT,7000,128,8,*,IF eval 128,8,* result is 1024
\& 2) 1024 ,7000,GT,7000,128,8,*,IF eval 1024,7000,GT result is 0
\& 3) 0, 7000,128,8,*,IF eval 128,8,* result is 1024
\& 4) 0, 7000,1024, IF result is 1024
.Ve
.PP
Now let's go back to the first example of multiple logic operators,
but replace the value 20 with the variable \*(L"input\*(R":
.PP
.Vb 1
\& 1) input,10,GT,10,input,IF eval is input,10,GT ( lets call this A )
.Ve
.PP
Read eval as \*(L"if input > 10 then true\*(R" and replace \*(L"input,10,GT\*(R"
with \*(L"A\*(R":
.PP
.Vb 1
\& 2) A,10,input,IF eval is A,10,input,IF
.Ve
.PP
read \*(L"if A then 10 else input\*(R". Now replace A with it's verbose
description again and\*(--voila!\-\-you have an easily readable description
of the expression:
.PP
.Vb 1
\& if input > 10 then 10 else input
.Ve
.PP
Finally, let's go back to the first most complex example and replace
the value 128 with \*(L"input\*(R":
.PP
.Vb 1
\& 1) input,8,*,7000,GT,7000,input,8,*,IF eval input,8,* result is A
.Ve
.PP
where A is \*(L"input * 8\*(R"
.PP
.Vb 1
\& 2) A,7000,GT,7000,input,8,*,IF eval is A,7000,GT result is B
.Ve
.PP
where B is \*(L"if ((input * 8) > 7000) then true\*(R"
.PP
.Vb 1
\& 3) B,7000,input,8,*,IF eval is input,8,* result is C
.Ve
.PP
where C is \*(L"input * 8\*(R"
.PP
.Vb 1
\& 4) B,7000,C,IF
.Ve
.PP
At last we have a readable decoding of the complex \s-1RPN\s0 expression with
a variable:
.PP
.Vb 1
\& if ((input * 8) > 7000) then 7000 else (input * 8)
.Ve
.SH "Exercises"
.IX Header "Exercises"
Exercise 1:
.PP
Compute \*(L"3,2,*,1,+ and \*(R"3,2,1,+,*" by hand. Rewrite them in
traditional notation. Explain why they have different answers.
.PP
Answer 1:
.PP
.Vb 3
\& 3*2+1 = 7 and 3*(2+1) = 9. These expressions have
\& different answers because the altering of the plus and
\& times operators alter the order of their evaluation.
.Ve
.PP
Exercise 2:
.PP
One may be tempted to shorten the expression
.PP
.Vb 1
\& input,8,*,56000,GT,56000,input,*,8,IF
.Ve
.PP
by removing the redundant use of \*(L"input,8,*\*(R" like so:
.PP
.Vb 1
\& input,56000,GT,56000,input,IF,8,*
.Ve
.PP
Use traditional notation to show these expressions are not the same.
Write an expression that's equivalent to the first expression, but
uses the \s-1LE\s0 and \s-1DIV\s0 operators.
.PP
Answer 2:
.PP
.Vb 2
\& if (input <= 56000/8 ) { input*8 } else { 56000 }
\& input,56000,8,DIV,LT,input,8,*,56000,IF
.Ve
.PP
Exercise 3:
.PP
Briefly explain why traditional mathematic notation requires the
use of parentheses. Explain why \s-1RPN\s0 notation does not require
the use of parentheses.
.PP
Answer 3:
.PP
.Vb 6
\& Traditional mathematic expressions are evaluated by
\& doing multiplication and division first, then addition and
\& subtraction. Parentheses are used to force the evaluation of
\& addition before multiplication (etc). RPN does not require
\& parentheses because the ordering of objects on the stack
\& can force the evaluation of addition before multiplication.
.Ve
.PP
Exercise 4:
.PP
Explain why it was desirable for the RRDtool developers to implement
\&\s-1RPN\s0 notation instead of traditional mathematical notation.
.PP
Answer 4:
.PP
.Vb 5
\& The algorithm that implements traditional mathematical
\& notation is more complex then algorithm used for RPN.
\& So implementing RPN allowed Tobias Oetiker to write less
\& code! (The code is also less complex and therefore less
\& likely to have bugs.)
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Steve Rader
07070100047520000041ed0000000000000000000000025295527a000000000000011f00010018ffffffffffffffff0000001e00000000root/usr/local/share/man/man3 07070100047521000081a40000000000000000000000015295521c00001e540000011f00010018ffffffffffffffff0000002500000000root/usr/local/share/man/man3/RRDp.3 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDp 3"
.TH RRDp 3 "2010-07-06" "perl v5.12.3" "User Contributed Perl Documentation"
.\" 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"
RRDp \- Attach RRDtool from within a perl script via a set of pipes;
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use \fBRRDp\fR
.PP
\&\fBRRDp::start\fR \fIpath to RRDtool executable\fR
.PP
\&\fBRRDp::cmd\fR \fIrrdtool commandline\fR
.PP
\&\f(CW$answer\fR = \fBRRD::read\fR
.PP
\&\f(CW$status\fR = \fBRRD::end\fR
.PP
\&\fB\f(CB$RRDp::user\fB\fR, \fB\f(CB$RRDp::sys\fB\fR, \fB\f(CB$RRDp::real\fB\fR, \fB\f(CB$RRDp::error_mode\fB\fR, \fB\f(CB$RRDp::error\fB\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can safely communicate with the RRDtool.
.PP
After every \fBRRDp::cmd\fR you have to issue an \fBRRDp::read\fR command to get
\&\fBRRDtool\fRs answer to your command. The answer is returned as a pointer,
in order to speed things up. If the last command did not return any
data, \fBRRDp::read\fR will return an undefined variable.
.PP
If you import the \s-1PERFORMANCE\s0 variables into your namespace,
you can access RRDtool's internal performance measurements.
.IP "use \fBRRDp\fR" 8
.IX Item "use RRDp"
Load the RRDp::pipe module.
.IP "\fBRRDp::start\fR \fIpath to RRDtool executable\fR" 8
.IX Item "RRDp::start path to RRDtool executable"
start RRDtool. The argument must be the path to the RRDtool executable
.IP "\fBRRDp::cmd\fR \fIrrdtool commandline\fR" 8
.IX Item "RRDp::cmd rrdtool commandline"
pass commands on to RRDtool. Check the RRDtool documentation for
more info on the RRDtool commands.
.Sp
\&\fBNote\fR: Due to design limitations, \fBRRDp::cmd\fR does not support the
\&\f(CW\*(C`graph \-\*(C'\fR command \- use \f(CW\*(C`graphv \-\*(C'\fR instead.
.ie n .IP "$answer = \fBRRDp::read\fR" 8
.el .IP "\f(CW$answer\fR = \fBRRDp::read\fR" 8
.IX Item "$answer = RRDp::read"
read RRDtool's response to your command. Note that the \f(CW$answer\fR variable will
only contain a pointer to the returned data. The reason for this is, that
RRDtool can potentially return quite excessive amounts of data
and we don't want to copy this around in memory. So when you want to
access the contents of \f(CW$answer\fR you have to use $$answer which dereferences
the variable.
.ie n .IP "$status = \fBRRDp::end\fR" 8
.el .IP "\f(CW$status\fR = \fBRRDp::end\fR" 8
.IX Item "$status = RRDp::end"
terminates RRDtool and returns RRDtool's status ...
.ie n .IP "\fB\fB$RRDp::user\fB\fR, \fB\fB$RRDp::sys\fB\fR, \fB\fB$RRDp::real\fB\fR" 8
.el .IP "\fB\f(CB$RRDp::user\fB\fR, \fB\f(CB$RRDp::sys\fB\fR, \fB\f(CB$RRDp::real\fB\fR" 8
.IX Item "$RRDp::user, $RRDp::sys, $RRDp::real"
these variables will contain totals of the user time, system time and
real time as seen by RRDtool. User time is the time RRDtool is
running, System time is the time spend in system calls and real time
is the total time RRDtool has been running.
.Sp
The difference between user + system and real is the time spent
waiting for things like the hard disk and new input from the Perl
script.
.ie n .IP "\fB\fB$RRDp::error_mode\fB\fR and \fB\fB$RRDp::error\fB\fR" 8
.el .IP "\fB\f(CB$RRDp::error_mode\fB\fR and \fB\f(CB$RRDp::error\fB\fR" 8
.IX Item "$RRDp::error_mode and $RRDp::error"
If you set the variable \f(CW$RRDp::error_mode\fR to the value 'catch' before you run RRDp::read a potential
\&\s-1ERROR\s0 message will not cause the program to abort but will be returned in this variable. If no error
occurs the variable will be empty.
.Sp
.Vb 3
\& $RRDp::error_mode = \*(Aqcatch\*(Aq;
\& RRDp::cmd qw(info file.rrd);
\& print $RRDp::error if $RRDp::error;
.Ve
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 8
\& use RRDp;
\& RRDp::start "/usr/local/bin/rrdtool";
\& RRDp::cmd qw(create demo.rrd \-\-step 100
\& DS:in:GAUGE:100:U:U
\& RRA:AVERAGE:0.5:1:10);
\& $answer = RRDp::read;
\& print $$answer;
\& ($usertime,$systemtime,$realtime) = ($RRDp::user,$RRDp::sys,$RRDp::real);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information on how to use RRDtool, check the manpages.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
07070100047523000081a4000000000000000000000001529552340000242f0000011f00010018ffffffffffffffff0000002700000000root/usr/local/share/man/man3/librrd.3 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "librrd 3"
.TH librrd 3 "2009-11-15" "1.4.4" "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"
librrd \- RRD library functions
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBlibrrd\fR contains most of the functionality in \fBRRDTool\fR. The command
line utilities and language bindings are often just wrappers around the
code contained in \fBlibrrd\fR.
.PP
This manual page documents the \fBlibrrd\fR \s-1API\s0.
.PP
\&\fB\s-1NOTE:\s0\fR This document is a work in progress, and should be considered
incomplete as long as this warning persists. For more information about
the \fBlibrrd\fR functions, always consult the source code.
.SH "CORE FUNCTIONS"
.IX Header "CORE FUNCTIONS"
.IP "\fBrrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)\fR" 4
.IX Item "rrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)"
In some situations it is necessary to get the output of \f(CW\*(C`rrd_dump\*(C'\fR without
writing it to a file or the standard output. In such cases an application
can ask \fBrrd_dump_cb_r\fR to call an user-defined function each time there
is output to be stored somewhere. This can be used, to e.g. directly feed
an \s-1XML\s0 parser with the dumped output or transfer the resulting string
in memory.
.Sp
The arguments for \fBrrd_dump_cb_r\fR are the same as for \fBrrd_dump_opt_r\fR
except that the output filename parameter is replaced by the user-defined
callback function and an additional parameter for the callback function
that is passed untouched, i.e. to store information about the callback state
needed for the user-defined callback to function properly.
.Sp
Recent versions of \fBrrd_dump_opt_r\fR internally use this callback mechanism
to write their output to the file provided by the user.
.Sp
.Vb 7
\& size_t rrd_dump_opt_cb_fileout(
\& const void *data,
\& size_t len,
\& void *user)
\& {
\& return fwrite(data, 1, len, (FILE *)user);
\& }
.Ve
.Sp
The associated call for \fBrrd_dump_cb_r\fR looks like
.Sp
.Vb 2
\& res = rrd_dump_cb_r(filename, opt_header,
\& rrd_dump_opt_cb_fileout, (void *)out_file);
.Ve
.Sp
where the last parameter specifies the file handle \fBrrd_dump_opt_cb_fileout\fR
should write to. There's no specific condition for the callback to detect
when it is called for the first time, nor for the last time. If you require
this for initialization and cleanup you should do those tasks before and
after calling \fBrrd_dump_cr_r\fR respectively.
.SH "UTILITY FUNCTIONS"
.IX Header "UTILITY FUNCTIONS"
.IP "\fB\f(BIrrd_random()\fB\fR" 4
.IX Item "rrd_random()"
Generates random numbers just like \fIrandom()\fR. This further ensures that
the random number generator is seeded exactly once per process.
.IP "\fBrrd_add_ptr(void ***dest, size_t *dest_size, void *src)\fR" 4
.IX Item "rrd_add_ptr(void ***dest, size_t *dest_size, void *src)"
Dynamically resize the array pointed to by \f(CW\*(C`dest\*(C'\fR. \f(CW\*(C`dest_size\*(C'\fR is a
pointer to the current size of \f(CW\*(C`dest\*(C'\fR. Upon successful \fIrealloc()\fR, the
\&\f(CW\*(C`dest_size\*(C'\fR is incremented by 1 and the \f(CW\*(C`src\*(C'\fR pointer is stored at the
end of the new \f(CW\*(C`dest\*(C'\fR. Returns 1 on success, 0 on failure.
.Sp
.Vb 5
\& type **arr = NULL;
\& type *elem = "whatever";
\& size_t arr_size = 0;
\& if (!rrd_add_ptr(&arr, &arr_size, elem))
\& handle_failure();
.Ve
.IP "\fBrrd_add_strdup(char ***dest, size_t *dest_size, char *src)\fR" 4
.IX Item "rrd_add_strdup(char ***dest, size_t *dest_size, char *src)"
Like \f(CW\*(C`rrd_add_ptr\*(C'\fR, except adds a \f(CW\*(C`strdup\*(C'\fR of the source string.
.Sp
.Vb 5
\& char **arr = NULL;
\& size_t arr_size = NULL;
\& char *str = "example text";
\& if (!rrd_add_strdup(&arr, &arr_size, str))
\& handle_failure();
.Ve
.IP "\fBrrd_free_ptrs(void ***src, size_t *cnt)\fR" 4
.IX Item "rrd_free_ptrs(void ***src, size_t *cnt)"
Free an array of pointers allocated by \f(CW\*(C`rrd_add_ptr\*(C'\fR or
\&\f(CW\*(C`rrd_add_strdup\*(C'\fR. Also frees the array pointer itself. On return, the
source pointer will be \s-1NULL\s0 and the count will be zero.
.Sp
.Vb 3
\& /* created as above */
\& rrd_free_ptrs(&arr, &arr_size);
\& /* here, arr == NULL && arr_size == 0 */
.Ve
.IP "\fBrrd_mkdir_p(const char *pathname, mode_t mode)\fR" 4
.IX Item "rrd_mkdir_p(const char *pathname, mode_t mode)"
Create the directory named \f(CW\*(C`pathname\*(C'\fR including all of its parent
directories (similar to \f(CW\*(C`mkdir \-p\*(C'\fR on the command line \- see \fImkdir\fR\|(1) for
more information). The argument \f(CW\*(C`mode\*(C'\fR specifies the permissions to use. It
is modified by the process's \f(CW\*(C`umask\*(C'\fR. See \fImkdir\fR\|(2) for more details.
.Sp
The function returns 0 on success, a negative value else. In case of an error,
\&\f(CW\*(C`errno\*(C'\fR is set accordingly. Aside from the errors documented in \fImkdir\fR\|(2),
the function may fail with the following errors:
.RS 4
.IP "\fB\s-1EINVAL\s0\fR" 4
.IX Item "EINVAL"
\&\f(CW\*(C`pathname\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR or the empty string.
.IP "\fB\s-1ENOMEM\s0\fR" 4
.IX Item "ENOMEM"
Insufficient memory was available.
.IP "\fBany error returned by \f(BIstat\fB\|(2)\fR" 4
.IX Item "any error returned by stat"
.RE
.RS 4
.Sp
In contrast to \fImkdir\fR\|(2), the function does \fBnot\fR fail if \f(CW\*(C`pathname\*(C'\fR
already exists and is a directory.
.RE
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\s-1RRD\s0 Contributors
07070100047522000081a40000000000000000000000015295522f0000210d0000011f00010018ffffffffffffffff0000002500000000root/usr/local/share/man/man3/RRDs.3 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "RRDs 3"
.TH RRDs 3 "2010-07-06" "perl v5.12.3" "User Contributed Perl Documentation"
.\" 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"
RRDs \- Access RRDtool as a shared module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\& use RRDs;
\& RRDs::error
\& RRDs::last ...
\& RRDs::info ...
\& RRDs::create ...
\& RRDs::update ...
\& RRDs::updatev ...
\& RRDs::graph ...
\& RRDs::fetch ...
\& RRDs::tune ...
\& RRDs::times(start, end)
\& RRDs::dump ...
\& RRDs::restore ...
\& RRDs::flushcached ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Calling Sequence"
.IX Subsection "Calling Sequence"
This module accesses RRDtool functionality directly from within Perl. The
arguments to the functions listed in the \s-1SYNOPSIS\s0 are explained in the regular
RRDtool documentation. The command line call
.PP
.Vb 1
\& rrdtool update mydemo.rrd \-\-template in:out N:12:13
.Ve
.PP
gets turned into
.PP
.Vb 1
\& RRDs::update ("mydemo.rrd", "\-\-template", "in:out", "N:12:13");
.Ve
.PP
Note that
.PP
.Vb 1
\& \-\-template=in:out
.Ve
.PP
is also valid.
.PP
The RRDs::times function takes two parameters: a \*(L"start\*(R" and \*(L"end\*(R" time.
These should be specified in the \fBAT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0\fR format
used by RRDtool. See the \fBrrdfetch\fR documentation for a detailed
explanation on how to specify time.
.SS "Error Handling"
.IX Subsection "Error Handling"
The \s-1RRD\s0 functions will not abort your program even when they can not make
sense out of the arguments you fed them.
.PP
The function RRDs::error should be called to get the error status
after each function call. If RRDs::error does not return anything
then the previous function has completed its task successfully.
.PP
.Vb 4
\& use RRDs;
\& RRDs::update ("mydemo.rrd","N:12:13");
\& my $ERR=RRDs::error;
\& die "ERROR while updating mydemo.rrd: $ERR\en" if $ERR;
.Ve
.SS "Return Values"
.IX Subsection "Return Values"
The functions RRDs::last, RRDs::graph, RRDs::info, RRDs::fetch and RRDs::times
return their findings.
.PP
\&\fBRRDs::last\fR returns a single \s-1INTEGER\s0 representing the last update time.
.PP
.Vb 1
\& $lastupdate = RRDs::last ...
.Ve
.PP
\&\fBRRDs::graph\fR returns an \s-1ARRAY\s0 containing the x\-size and y\-size of the
created image and a pointer to an array with the results of the \s-1PRINT\s0 arguments.
.PP
.Vb 3
\& ($result_arr,$xsize,$ysize) = RRDs::graph ...
\& print "Imagesize: ${xsize}x${ysize}\en";
\& print "Averages: ", (join ", ", @$averages);
.Ve
.PP
\&\fBRRDs::info\fR returns a pointer to a hash. The keys of the hash
represent the property names of the \s-1RRD\s0 and the values of the hash are
the values of the properties.
.PP
.Vb 4
\& $hash = RRDs::info "example.rrd";
\& foreach my $key (keys %$hash){
\& print "$key = $$hash{$key}\en";
\& }
.Ve
.PP
\&\fBRRDs::graphv\fR takes the same parameters as \fBRRDs::graph\fR but it returns a
pointer to hash. The hash returned contains meta information about the
graph. Like its size as well as the position of the graph area on the image.
When calling with and empty filename than the contents of the graph will be
returned in the hash as well (key 'image').
.PP
\&\fBRRDs::updatev\fR also returns a pointer to hash. The keys of the hash
are concatenated strings of a timestamp, \s-1RRA\s0 index, and data source name for
each consolidated data point (\s-1CDP\s0) written to disk as a result of the
current update call. The hash values are \s-1CDP\s0 values.
.PP
\&\fBRRDs::fetch\fR is the most complex of
the pack regarding return values. There are 4 values. Two normal
integers, a pointer to an array and a pointer to a array of pointers.
.PP
.Vb 10
\& my ($start,$step,$names,$data) = RRDs::fetch ...
\& print "Start: ", scalar localtime($start), " ($start)\en";
\& print "Step size: $step seconds\en";
\& print "DS names: ", join (", ", @$names)."\en";
\& print "Data points: ", $#$data + 1, "\en";
\& print "Data:\en";
\& for my $line (@$data) {
\& print " ", scalar localtime($start), " ($start) ";
\& $start += $step;
\& for my $val (@$line) {
\& printf "%12.1f ", $val;
\& }
\& print "\en";
\& }
.Ve
.PP
\&\fBRRDs::times\fR returns two integers which are the number of seconds since
epoch (1970\-01\-01) for the supplied \*(L"start\*(R" and \*(L"end\*(R" arguments, respectively.
.PP
See the examples directory for more ways to use this extension.
.SH "NOTE"
.IX Header "NOTE"
If you are manipulating the \s-1TZ\s0 variable you should also call the \s-1POSIX\s0
function \fItzset\fR\|(3) to initialize all internal state of the library for properly
operating in the timezone of your choice.
.PP
.Vb 3
\& use POSIX qw(tzset);
\& $ENV{TZ} = \*(AqCET\*(Aq;
\& POSIX::tzset();
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker
070701000474a2000041ed0000000000000000000000035295527a000000000000011f00010018ffffffffffffffff0000001900000000root/usr/local/share/doc 070701000474a3000041ed0000000000000000000000045295527a000000000000011f00010018ffffffffffffffff0000002700000000root/usr/local/share/doc/rrdtool-1.4.4 070701000474c5000041ed0000000000000000000000025295527a000000000000011f00010018ffffffffffffffff0000002b00000000root/usr/local/share/doc/rrdtool-1.4.4/txt 070701000474d4000081a400000000000000000000000152955234000022480000011f00010018ffffffffffffffff0000003600000000root/usr/local/share/doc/rrdtool-1.4.4/txt/rrdcgi.txt RRDCGI(1) rrdtool RRDCGI(1)
NNAAMMEE
rrdcgi - Create web pages containing RRD graphs based on templates
SSYYNNOOPPSSIISS
"#!/path/to/"rrrrddccggii [----ffiilltteerr]
DDEESSCCRRIIPPTTIIOONN
rrrrddccggii is a sort of very limited script interpreter. Its purpose is to
run as a cgi-program and parse a web page template containing special