@@ -77,7 +85,7 @@ networking.
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.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.
@@ -117,7 +125,7 @@ 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 MRTG (the next section will give more details on this more specialized application).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 @@ -163,8 +171,8 @@ and not only for this particular one. Look in the documentation that came with RRDtool for the location and usage of the list.
I suggest you take a moment to subscribe to the mailing list right now by sending an email to <rrd-users-request@lists.oetiker.ch> 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''.
+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".
Take the current counter, subtract the previous value from it.
+Do the same with the current time and the previous time (in seconds).
+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). -
bps = (counter_now - counter_before) / (time_now - time_before) * 8
For some people it may help to translate this to an automobile example. @@ -266,7 +275,7 @@ and skip all of the '\' characters.
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 --step=300). 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
@@ -280,7 +289,7 @@ it will therefore look different for different time zones.
We now have to fill our database with some numbers. We'll pretend to have read the following numbers:
@@ -314,7 +323,7 @@ have read the following numbers: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.
-We can now retrieve the data from our database using ``rrdtool fetch'':
+We can now retrieve the data from our database using "rrdtool fetch":
rrdtool fetch test.rrd AVERAGE --start 920804400 --end 920809200It should return the following output:
@@ -338,8 +347,8 @@ the real maximum per line is OS dependent. 920808900: 3.3333333333e-03 920809200: nan
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.
@@ -355,7 +364,7 @@ database and try again. LINE2:myspeed#FF0000This 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).
You'll notice that the start of the graph is not at 12:00 but at 12:05. @@ -366,8 +375,8 @@ not happen a lot, hopefully.
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
+The "color" white is a mixture of red, green and blue: FFFFFF +The "color" black is all colors off: 000000
red #FF0000
green #00FF00
@@ -375,10 +384,10 @@ The ``color'' black is all colors off: 000000
magenta #FF00FF (mixed red with blue)
gray #555555 (one third of all components)
Additionally you can (with a recent RRDtool) add an alpha channel -(transparency). The default will be ``FF'' which means non-transparent.
+(transparency). The default will be "FF" which means non-transparent.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''
+"file:///the/path/to/speed.png"
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.
If we had measured our distances in meters, this would have been @@ -415,14 +424,14 @@ like so:
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. -After viewing this PNG, you notice the ``m'' (milli) has +
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.
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.
Hang on! If we can multiply values with 1000, it should also be possible @@ -495,7 +504,7 @@ be the 5th line) used to read 'CDEF:kmh=myspeed,3600,*'
<BR> <IMG src="speed4.png" alt="Traveled too fast?"> </BODY></HTML> -Name the file ``speed.html'' or similar, and look at it in your web browser.
+Name the file "speed.html" or similar, and look at it in your web browser.
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 @@ -505,9 +514,9 @@ or ctrl-F5).
We've already used the update 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):
perl -e 'print time, "\n" '
@@ -541,7 +550,7 @@ you understand they are not necessary. When you have to determine why
things went wrong you need to know how they work.
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:
snmpget device password OID
@@ -549,14 +558,14 @@ this is how it works:
snmpget -v[version] -c[password] device OID
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.
-Then there is this parameter, called OID, which means ``object identifier''.
+Then there is this parameter, called OID, which means "object identifier".
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 @@ -572,7 +581,7 @@ you specify the complete OID. Often those programs will leave out the default portion when returning the data to you. To make things worse, they have several default prefixes ...
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).
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. @@ -589,12 +598,12 @@ adapt the example to make it work.
snmpget -v2c -c public myrouter system.sysDescr.0The 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.
snmpget -v2c -c public myrouter interfaces.ifNumber.0
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''.
+If so, you can carry on and try a different program called "snmpwalk".
snmpwalk -v2c -c public myrouter interfaces.ifTable.ifEntry.ifDescr
If it returns with a list of interfaces, you're almost there. @@ -606,7 +615,7 @@ Here's an example: interfaces.ifTable.ifEntry.ifDescr.3 = "BRI0" Hex: 42 52 49 30 interfaces.ifTable.ifEntry.ifDescr.4 = "Ethernet0" interfaces.ifTable.ifEntry.ifDescr.5 = "Loopback0" -
On this cisco equipment, I would like to monitor the ``Ethernet0'' +
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:
[user@host /home/alex]$ snmpget -v2c -c public cisco 2.2.1.10.4 2.2.1.16.4
@@ -651,9 +660,9 @@ amount of data:
732 1-day samples: 732 days
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!
+"now" and therefore we will need to keep more data than MRTG does!We will need:
600 samples of 5 minutes (2 days and 2 hours) @@ -700,7 +709,7 @@ to do exactly on your OS to make it work. 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. +an area for the "in" traffic and a line for the "out" traffic.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.
@@ -844,27 +853,28 @@ calculations stay the same.RRDtool under the Microscope
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). -
-Line B is of type GAUGE. These are "real" values so they should match +what we put in: a sort of a wave.
+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.
+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. -
This translates in the following values, starting at 23:10 and ending -at 00:10 the next day (where ``u'' means unknown/unplotted):
+at 00:10 the next day (where "u" means unknown/unplotted):- 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 @@ -877,34 +887,35 @@ and you successfully entered the year 2000 :) the lines.Let's go over the data again:
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).
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!
- -Line B: There is nothing to calculate. The numbers are as they are.
+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. -
-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. -