![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdtutorial.1 b/doc/rrdtutorial.1
index 5ace3cefed85c4e8c0bf25682e35c6c437ea2be2..43889acee2f5216b583011bca034d231ebb37422 100644 (file)
--- a/doc/rrdtutorial.1
+++ b/doc/rrdtutorial.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.\" 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. | will give a
-.\" real vertical bar. \*(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-|\(bv\*(Tr
+.\" 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 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 (.Sh), items (.Ip), and index
+.\" 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.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.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.
.\" ========================================================================
.\"
.IX Title "RRDTUTORIAL 1"
-.TH RRDTUTORIAL 1 "2009-04-09" "1.3.99909060808" "rrdtool"
+.TH RRDTUTORIAL 1 "2009-06-01" "1.3.999" "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"
networking.
.SH "TUTORIAL"
.IX Header "TUTORIAL"
-.Sh "Important"
+.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
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.
-.Sh "What is RRDtool?"
+.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
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.
-.Sh "What data can be put into an \s-1RRD\s0?"
+.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
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.
-.Sh "What can I do with this tool?"
+.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
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.
-.Sh "What if I still have problems after reading this document?"
+.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
by sending an email to <rrd\-users\-request@lists.oetiker.ch> 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".
-.Sh "How will you help me?"
+.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
.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.
-.Sh "Your first Round Robin Database"
+.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
.Ve
.PP
(So enter: \f(CW\*(C`rrdtool create test.rrd \-\-start 920804400 DS ...\*(C'\fR)
-.Sh "What has been created?"
+.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
@@ -380,7 +379,7 @@ As an example: where I will see \*(L"12:05\*(R" the \s-1UK\s0 folks will see \*(
We now have to fill our database with some numbers. We'll pretend to
have read the following numbers:
.PP
-.Vb 15
+.Vb 10
\& 12:05 12345 km
\& 12:10 12357 km
\& 12:15 12363 km
.PP
.Vb 1
\& speed
-.Ve
-.PP
-.Vb 16
+\&
\& 920804700: nan
\& 920805000: 4.0000000000e\-02
\& 920805300: 2.0000000000e\-02
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.
+database and try again.
.PP
The meaning of the above output will become clear below.
-.Sh "Time to create some graphics"
+.SS "Time to create some graphics"
.IX Subsection "Time to create some graphics"
Try the following command:
.PP
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).
+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
.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.
+(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"
-.Sh "Graphics with some math"
+.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
\& Check if kmh is greater than 100 ( kmh,100 ) GT
\& If so, return kmh, else return 0 ((( kmh,100) GT ), kmh, 0) IF
.Ve
-.Sh "Graphics Magic"
+.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 13
+.Vb 10
\& rrdtool graph speed4.png \e
\& \-\-start 920804400 \-\-end 920808000 \e
\& \-\-vertical\-label km/h \e
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).
-.Sh "Updates in Reality"
+.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"<time>:<value>\*(R". You'll be glad to know
this tutorial):
.PP
.Vb 1
-\& perl \-e 'print time, "\en" '
+\& perl \-e \*(Aqprint time, "\en" \*(Aq
.Ve
.PP
How to run a program on regular intervals is \s-1OS\s0 specific. But here is
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.
-.Sh "Some words on \s-1SNMP\s0"
+.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
.PP
.Vb 1
\& [user@host /home/alex]$ snmpget \-v2c \-c public cisco 2.2.1.10.4 2.2.1.16.4
-.Ve
-.PP
-.Vb 2
+\&
\& interfaces.ifTable.ifEntry.ifInOctets.4 = 2290729126
\& interfaces.ifTable.ifEntry.ifOutOctets.4 = 1256486519
.Ve
.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.
-.Sh "A Real World Example"
+.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
\& 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)
-.Ve
-.PP
-.Vb 11
+\&
\& rrdtool create myrouter.rrd \e
\& DS:input:COUNTER:600:U:U \e
\& DS:output:COUNTER:600:U:U \e
\& get result of
\& snmpget router community 2.2.1.16.4
\& into variable $out
-.Ve
-.PP
-.Vb 1
+\&
\& rrdtool update myrouter.rrd N:$in:$out
-.Ve
-.PP
-.Vb 2
+\&
\& wait for 5 minutes
\& done
.Ve
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.
-.Sh "Consolidation Functions"
+.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
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.
-.Sh "Let's review what you now should know"
+.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
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.
-.Sh "Data Source Types"
+.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
Let's try them all:
.PP
-.Vb 22
+.Vb 10
\& rrdtool create all.rrd \-\-start 978300900 \e
\& DS:a:COUNTER:600:U:U \e
\& DS:b:GAUGE:600:U:U \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
-.Sh "RRDtool under the Microscope"
+.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
@@ -1098,7 +1087,7 @@ Line B is of type \s-1GAUGE\s0. These are \*(L"real\*(R" values so they should m
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.
+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
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.
-.Sh "Counter Wraps"
+.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:
.PP
.Vb 1
\& Delta = 7 \- 999987 = \-999980 (instead of 1000007\-999987=20)
-.Ve
-.PP
-.Vb 1
+\&
\& Real delta = \-999980 + 999999 + 1 = 20
.Ve
.PP
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.
+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
\& \- 32 bits: (4294967295 + 1) = 4294967296
\& \- 64 bits: (18446744073709551615 + 1)
\& \- correction1 = 18446744069414584320
-.Ve
-.PP
-.Vb 6
+\&
\& Before: 4294967200
\& Increase: 100
\& Should become: 4294967300
\& But really is: 4
\& Delta: \-4294967196
\& Correction1: \-4294967196 + 4294967296 = 100
-.Ve
-.PP
-.Vb 9
+\&
\& Before: 18446744073709551000
\& Increase: 800
\& Should become: 18446744073709551800
\& + 4294967296 = \-18446744069414583520
\& Correction2: \-18446744069414583520
\& + 18446744069414584320 = 800
-.Ve
-.PP
-.Vb 7
+\&
\& Before: 18446744073709551615 ( maximum value )
\& Increase: 18446744069414584320 ( absurd increase, minimum for
\& Should become: 36893488143124135935 this example to work )
\& Delta: \-4294967296
\& Correction1: \-4294967296 + 4294967296 = 0
\& (not negative \-> no correction2)
-.Ve
-.PP
-.Vb 7
+\&
\& Before: 18446744073709551615 ( maximum value )
\& Increase: 18446744069414584319 ( one less increase )
\& Should become: 36893488143124135934
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.
-.Sh "Data Resampling"
+.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
.PP
.Vb 1
\& in the RRD in reality
-.Ve
-.PP
-.Vb 4
+\&
\& 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
.PP
Create output
.PP
-.Vb 16
+.Vb 10
\& rrdtool graph seconds1.png \e
\& \-\-start 920804700 \-\-end 920806200 \e
\& \-\-height 200 \e