![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdtutorial.html b/doc/rrdtutorial.html
index 4eda356ae9847c7ca648963508dbc120b2ef6b9f..105c758d757e14d939edf14584d9ef716b4a47fc 100644 (file)
--- a/doc/rrdtutorial.html
+++ b/doc/rrdtutorial.html
+<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>rrdtutorial</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
-<p><a name="__index__"></a></p>
+
<!-- INDEX BEGIN -->
+<div name="index">
+<p><a name="__index__"></a></p>
<!--
<ul>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
+
-->
+
+
+</div>
<!-- INDEX END -->
<p>
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.</p>
<p>Sometimes things change. This example used to provide numbers like
-``0.04'' in stead of ``4.00000e-02''. Those are really the same numbers,
+"0.04" in stead of "4.00000e-02". 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.</p>
numerical but don't have to be integers, as is the case with MRTG (the
next section will give more details on this more specialized application).</p>
<p>Many examples below talk about SNMP which is an acronym for Simple Network
-Management Protocol. ``Simple'' refers to the protocol. It does not
+Management Protocol. "Simple" 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
came with RRDtool for the location and usage of the list.</p>
<p>I suggest you take a moment to subscribe to the mailing list right now
by sending an email to <<a href="mailto:rrd-users-request@lists.oetiker.ch">rrd-users-request@lists.oetiker.ch</a>> with a
-subject of ``subscribe''. If you ever want to leave this list, just write
-an email to the same address but now with a subject of ``unsubscribe''.</p>
+subject of "subscribe". If you ever want to leave this list, just write
+an email to the same address but now with a subject of "unsubscribe".</p>
<p>
</p>
<h2><a name="how_will_you_help_me">How will you help me?</a></h2>
many bytes have been transfered ***on average*** per second. This is
not very hard to calculate. First in words, then in calculations:</p>
<ol>
-<li></li>
-Take the current counter, subtract the previous value from it.
-<p></p>
-<li></li>
-Do the same with the current time and the previous time (in seconds).
-<p></p>
-<li></li>
-Divide the outcome of (1) by the outcome of (2), the result is
+<li>
+<p>Take the current counter, subtract the previous value from it.</p>
+</li>
+<li>
+<p>Do the same with the current time and the previous time (in seconds).</p>
+</li>
+<li>
+<p>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).
-<p></p></ol>
+number of bits per second (bps).</p>
+</li>
+</ol>
<pre>
bps = (counter_now - counter_before) / (time_now - time_before) * 8</pre>
<p>For some people it may help to translate this to an automobile example.
<p>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 (DS) named ``speed'' that represents a counter. This counter
+one data source (DS) named "speed" that represents a counter. This counter
is read every five minutes (this is the default therefore you don't have to
put <code>--step=300</code>). 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
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 ``12:05'' the UK folks will see ``11:05''.</p>
+As an example: where I will see "12:05" the UK folks will see "11:05".</p>
<p>We now have to fill our database with some numbers. We'll pretend to
have read the following numbers:</p>
<pre>
<p>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 OS dependent.</p>
-<p>We can now retrieve the data from our database using ``rrdtool fetch'':</p>
+<p>We can now retrieve the data from our database using "rrdtool fetch":</p>
<pre>
rrdtool fetch test.rrd AVERAGE --start 920804400 --end 920809200</pre>
<p>It should return the following output:</p>
920808900: 3.3333333333e-03
920809200: nan</pre>
<p>If it doesn't, something may be wrong. Perhaps your OS will print
-``NaN'' in a different form. ``NaN'' stands for ``Not A Number''. If your OS
-writes ``U'' or ``UNKN'' or something similar that's okay. If something
+"NaN" in a different form. "NaN" stands for "Not A Number". If your OS
+writes "U" or "UNKN" 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.</p>
LINE2:myspeed#FF0000</pre>
<p>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 RRA
-``speed'' out of database ``test.rrd''. The line drawn is 2 pixels high
+"speed" out of database "test.rrd". The line drawn is 2 pixels high
and represents the variable myspeed. The color is red (specified by
its rgb-representation, see below).</p>
<p>You'll notice that the start of the graph is not at 12:00 but at 12:05.
<p>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 FF means fully included.
-The ``color'' white is a mixture of red, green and blue: FFFFFF
-The ``color'' black is all colors off: 000000</p>
+The "color" white is a mixture of red, green and blue: FFFFFF
+The "color" black is all colors off: 000000</p>
<pre>
red #FF0000
green #00FF00
magenta #FF00FF (mixed red with blue)
gray #555555 (one third of all components)</pre>
<p>Additionally you can (with a recent RRDtool) add an alpha channel
-(transparency). The default will be ``FF'' which means non-transparent.</p>
+(transparency). The default will be "FF" which means non-transparent.</p>
<p>The PNG you just created can be displayed using your favorite image
viewer. Web browsers will display the PNG via the URL
-``file:///the/path/to/speed.png''</p>
+"file:///the/path/to/speed.png"</p>
<p>
</p>
<h2><a name="graphics_with_some_math">Graphics with some math</a></h2>
<p>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 ``40 m''
-meaning ``40/1000''. The ``m'' (milli) has nothing to do with meters (also m),
+by 300 this makes 0.04, which is displayed by RRDtool as "40 m"
+meaning "40/1000". The "m" (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.</p>
<p>If we had measured our distances in meters, this would have been
And it is your shell interpreting \, not RRDtool. You may need to
adjust examples accordingly if you happen to use an operating
system or shell which behaves differently.</p>
-<p>After viewing this PNG, you notice the ``m'' (milli) has
+<p>After viewing this PNG, you notice the "m" (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 PNG should look the same.</p>
<p>The calculations are specified in the CDEF part above and are in
-Reverse Polish Notation (``RPN''). What we requested RRDtool to do is:
-``take the data source myspeed and the number 1000; multiply
-those''. Don't bother with RPN yet, it will be explained later on in
+Reverse Polish Notation ("RPN"). What we requested RRDtool to do is:
+"take the data source myspeed and the number 1000; multiply
+those". Don't bother with RPN 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 RPN. But first finish this tutorial.</p>
<p>Hang on! If we can multiply values with 1000, it should also be possible
<BR>
<IMG src="speed4.png" alt="Traveled too fast?">
</BODY></HTML></pre>
-<p>Name the file ``speed.html'' or similar, and look at it in your web browser.</p>
+<p>Name the file "speed.html" or similar, and look at it in your web browser.</p>
<p>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
</p>
<h2><a name="updates_in_reality">Updates in Reality</a></h2>
<p>We've already used the <code>update</code> command: it took one or more
-parameters in the form of ``<time>:<value>''. You'll be glad to know
-that you can specify the current time by filling in a ``N'' as the time.
-Or you could use the ``time'' function in Perl (the shortest example in
+parameters in the form of "<time>:<value>". You'll be glad to know
+that you can specify the current time by filling in a "N" as the time.
+Or you could use the "time" function in Perl (the shortest example in
this tutorial):</p>
<pre>
perl -e 'print time, "\n" '</pre>
things went wrong you need to know how they work.</p>
<p>One tool used in the example has been talked about very briefly in the
beginning of this document, it is called SNMP. It is a way of talking
-to networked equipment. The tool I use below is called ``snmpget'' and
+to networked equipment. The tool I use below is called "snmpget" and
this is how it works:</p>
<pre>
snmpget device password OID</pre>
<pre>
snmpget -v[version] -c[password] device OID</pre>
<p>For device you substitute the name, or the IP address, of your device.
-For password you use the ``community read string'' as it is called in the
-SNMP world. For some devices the default of ``public'' might work, however
+For password you use the "community read string" as it is called in the
+SNMP world. For some devices the default of "public" 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.</p>
-<p>Then there is this parameter, called OID, which means ``object identifier''.</p>
+<p>Then there is this parameter, called OID, which means "object identifier".</p>
<p>When you start to learn about SNMP it looks very confusing. It isn't
all that difficult when you look at the Management Information Base
-(``MIB''). It is an upside-down tree that describes data, with a single node
+("MIB"). 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
the default portion when returning the data to you. To make things
worse, they have several default prefixes ...</p>
<p>Ok, lets continue to the start of our OID: we had 1.3.6.1.2.1
-From there, we are especially interested in the branch ``interfaces''
+From there, we are especially interested in the branch "interfaces"
which has number 2 (e.g., 1.3.6.1.2.1.2 or 1.3.6.1.2.1.interfaces).</p>
<p>First, we have to get some SNMP program. First look if there is a
pre-compiled package available for your OS. This is the preferred way.
snmpget -v2c -c public myrouter system.sysDescr.0</pre>
<p>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 ``password'', or a different device, there is no point in
+different "password", or a different device, there is no point in
continuing.</p>
<pre>
snmpget -v2c -c public myrouter interfaces.ifNumber.0</pre>
<p>Hopefully you get a number as a result, the number of interfaces.
-If so, you can carry on and try a different program called ``snmpwalk''.</p>
+If so, you can carry on and try a different program called "snmpwalk".</p>
<pre>
snmpwalk -v2c -c public myrouter interfaces.ifTable.ifEntry.ifDescr</pre>
<p>If it returns with a list of interfaces, you're almost there.
interfaces.ifTable.ifEntry.ifDescr.3 = "BRI0" Hex: 42 52 49 30
interfaces.ifTable.ifEntry.ifDescr.4 = "Ethernet0"
interfaces.ifTable.ifEntry.ifDescr.5 = "Loopback0"</pre>
-<p>On this cisco equipment, I would like to monitor the ``Ethernet0''
+<p>On this cisco equipment, I would like to monitor the "Ethernet0"
interface and from the above output I see that it is number four. I try:</p>
<pre>
[user@host /home/alex]$ snmpget -v2c -c public cisco 2.2.1.10.4 2.2.1.16.4</pre>
732 1-day samples: 732 days</pre>
<p>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 ``weekly'' archive where the ``daily''
+differently, it doesn't start the "weekly" archive where the "daily"
archive stopped. For both archives the most recent data will be near
-``now'' and therefore we will need to keep more data than MRTG does!</p>
+"now" and therefore we will need to keep more data than MRTG does!</p>
<p>We will need:</p>
<pre>
600 samples of 5 minutes (2 days and 2 hours)
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 ``in'' traffic and a line for the ``out'' traffic.</p>
+an area for the "in" traffic and a line for the "out" traffic.</p>
<p>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.</p>
</p>
<h2><a name="rrdtool_under_the_microscope">RRDtool under the Microscope</a></h2>
<ul>
-<li></li>
-Line A is a COUNTER type, so it should continuously increment and RRDtool
+<li>
+<p>Line A is a COUNTER 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).
-<p></p>
-<li></li>
-Line B is of type GAUGE. These are ``real'' values so they should match
-what we put in: a sort of a wave.
-<p></p>
-<li></li>
-Line C is of type DERIVE. It should be a counter that can decrease. It does
-so between 2400 and 0, with 1800 in-between.
-<p></p>
-<li></li>
-Line D is of type ABSOLUTE. This is like counter but it works on
+straight line at 1 (the deltas are 300, the time is 300).</p>
+</li>
+<li>
+<p>Line B is of type GAUGE. These are "real" values so they should match
+what we put in: a sort of a wave.</p>
+</li>
+<li>
+<p>Line C is of type DERIVE. It should be a counter that can decrease. It does
+so between 2400 and 0, with 1800 in-between.</p>
+</li>
+<li>
+<p>Line D is of type ABSOLUTE. 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.
-<p></p></ul>
+and as you can see (hopefully) this has a different result.</p>
+</li>
+</ul>
<p>This translates in the following values, starting at 23:10 and ending
-at 00:10 the next day (where ``u'' means unknown/unplotted):</p>
+at 00:10 the next day (where "u" means unknown/unplotted):</p>
<pre>
- 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
the lines.</p>
<p>Let's go over the data again:</p>
<ul>
-<li></li>
-Line A: 300,600,900 and so on. The counter delta is a constant 300 and
+<li>
+<p>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).
+when dividing by zero which is undefined/illegal).</p>
<p>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!</p>
-<p></p>
-<li></li>
-Line B: There is nothing to calculate. The numbers are as they are.
-<p></p>
-<li></li>
-Line C: Again, the start-out value is unknown. The same story is holds
+</li>
+<li>
+<p>Line B: There is nothing to calculate. The numbers are as they are.</p>
+</li>
+<li>
+<p>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.
-<p></p>
-<li></li>
-Line D: Here the device calculates the deltas. Therefore we DO know the
+this makes a difference.</p>
+</li>
+<li>
+<p>Line D: Here the device calculates the deltas. Therefore we DO 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.
-<p></p></ul>
+increasing values.</p>
+</li>
+</ul>
<p>
</p>
<h2><a name="counter_wraps">Counter Wraps</a></h2>
for RRDtool to fail (provided it's bug free of course), so this should
not happen. However, SNMP 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 ``create'' command
+errors, but there are some things we can do. The RRDtool "create" command
takes two special parameters for this. They define
-the minimum and maximum allowed values. Until now, we used ``U'', meaning
-``unknown''. If you provide values for one or both of them and if RRDtool
+the minimum and maximum allowed values. Until now, we used "U", meaning
+"unknown". 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