![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdtutorial.html b/doc/rrdtutorial.html
index fc73b900e5fb7d17686c978ccd28018bea406ce9..47497800f4adc656b88dbe985188a5cf581f238c 100644 (file)
--- a/doc/rrdtutorial.html
+++ b/doc/rrdtutorial.html
<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="#name">NAME</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#tutorial">TUTORIAL</a></li>
<ul>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
+
-->
+
+
+</div>
<!-- INDEX END -->
+<p>
+</p>
+<hr />
+<h1><a name="name">NAME</a></h1>
<p>rrdtutorial - Alex van den Bogaerdt's RRDtool tutorial</p>
<p>
</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>
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
+RRDtool works with Round Robin Databases (RRDs). It stores and retrieves
data from them.</p>
<p>
</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
number of printouts and the like.</p>
<p>Most likely you will start to use RRDtool to store and process data
collected via SNMP. The data will most likely be bytes (or bits)
-transfered from and to a network or a computer. But it can also be
+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 you imagination can come up with.</p>
+fridge and whatever your imagination can come up with.</p>
<p>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 PNG format for
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>
all the same: some number over some time.</p>
<p>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 transfered. This counter will probably have
+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.</p>
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 transfered ***on average*** per second. This is
+many bytes have been transferred ***on average*** per second. This is
not very hard to calculate. First in words, then in calculations:</p>
<ol>
<li>
<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>
920808300: 1.6666666667e-02
920808600: 6.6666666667e-03
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
-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>
+ 920809200: nan
+ 920809500: nan</pre>
+<p>Note that you might get more rows than you expect. The reason for this is
+that you ask for a time range that ends on 920809200. The number that is
+written behind 920809200: in the list above covers the time range from
+920808900 to 920809200, EXCLUDING 920809200. Hence to be on the sure side,
+you receive the entry from 920809200 to 920809500 as well since it INCLUDES
+920809200. You may also see "NaN" instead of "nan" this is OS dependent.
+"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>
<p>The meaning of the above output will become clear below.</p>
<p>
</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>
the stuff you learned so far. Later on we will also be able to monitor
other types of values like temperature.</p>
<p>Many people interested in RRDtool will use the counter that keeps track
-of octets (bytes) transfered by a network device. So let's do just
+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.</p>
<p>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
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>
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
+<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>
</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
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