X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdtutorial.pod;h=eaf7af6c1601fa79d01b1283aed5268db80eda86;hb=aa23f7de260fd48e1924d89a8907cf511b66d264;hp=0ad0f74e37444bc4b3cdb42dbfe6d84de268bfa1;hpb=5837606887a6d81e8b1f7588525cb1c8783fb62b;p=rrdtool.git diff --git a/doc/rrdtutorial.pod b/doc/rrdtutorial.pod index 0ad0f74..eaf7af6 100644 --- a/doc/rrdtutorial.pod +++ b/doc/rrdtutorial.pod @@ -38,11 +38,11 @@ When the current data is read or written, the pointer moves to the next element. As we are on a circle there is no beginning nor an end, you can go on and on. After a while, all the available places will be used and the process automatically reuses old locations. This way, the database -will not grow in size and therefore requires no mainenance. +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. -=head2 What data can be put into an RDD ? +=head2 What data can be put into an RRD ? You name it, it will probably fit. You should be able to measure some value at several points in time and provide this information to RRDtool. If you @@ -67,7 +67,7 @@ the like. Most likely you will start to use the 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. RRDtool lets you create a database, store data in it, retrieve that data -and create graphs in GIF format for display on a web browser. Those GIF +and create graphs in PNG format for display on a web browser. Those PNG 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. It can also be used to display tidal waves, solar radiation, power @@ -80,7 +80,7 @@ measure the data and be able to feed the numbers to RRDtool. 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 -OS, it will probably not be the fault of RRDtool. There may be precompiled +OS, 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. If on the other hand the program works but does not give you the @@ -177,7 +177,7 @@ You're 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 towards the +into meters per second and this makes a nice comparison toward the problem of (bytes per five minutes) versus (bits per second). We traveled 12 kilometers which is 12000 meters. We did that in five @@ -220,9 +220,9 @@ which starts at noon the day I started (7th of march, 1999) writing this document. It holds one data source (DS) named "speed" that gets built from a counter. This counter is read every five minutes (default) In the same database two round robin archives (RRAs) are kept, one -averages the data every time it is read (eg there's nothing to average) +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 of such averages (eg 5 hours) +6 values (half hour) and contains 10 of such averages (e.g., 5 hours) The remaining options will be discussed later on. RRDtool works with special time stamps coming from the UNIX world. @@ -280,31 +280,36 @@ We can now retrieve the data from our database using "rrdtool fetch": It should return the following output: - speed - - 920804700: NaN - 920805000: 0.04 - 920805300: 0.02 - 920805600: 0.00 - 920805900: 0.00 - 920806200: 0.03 - 920806500: 0.03 - 920806800: 0.03 - 920807100: 0.02 - 920807400: 0.02 - 920807700: 0.02 - 920808000: 0.01 - 920808300: 0.02 - 920808600: 0.01 - 920808900: 0.00 - 920809200: NaN + 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 If it doesn't, something may be wrong. Perhaps your OS will print "NaN" in a different form. It represents "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. +database and try again. Sometimes things change. This example used +to provide numbers like "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 What this output represents will become clear in the rest of the tutorial. @@ -312,12 +317,12 @@ What this output represents will become clear in the rest of the tutorial. Try the following command: - rrdtool graph speed.gif \ + rrdtool graph speed.png \ --start 920804400 --end 920808000 \ DEF:myspeed=test.rrd:speed:AVERAGE \ LINE2:myspeed#FF0000 -This will create speed.gif which starts at 12:00 and ends at 13:00. +This will create speed.png which starts at 12:00 and ends at 13:00. There is a definition of variable myspeed, it is the data from RRA "speed" out of database "test.rrd". The line drawn is 2 pixels high, and comes from variable myspeed. The color is red. @@ -341,15 +346,18 @@ The "color" black is all colors off: 000000 magenta #FF00FF (mixed red with blue) gray #555555 (one third of all components) -The GIF you just created can be displayed using your favorite image -viewer. Web browsers will display the GIF via the URL -"file://the/path/to/speed.gif" +Additionally you can add an alpha channel (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" =head2 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. The two remaining times (12:00 and -13:00) would not be displayed nicely so they are skipped. +12:10, 12:20, 12:30, 12:40 and 12:50. Sometimes a label doesn't fit (12:00 +and 13:00 would be candidates) so they are skipped. 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, @@ -362,18 +370,18 @@ have been (12357000-12345000)/300 = 12000/300 = 40. Let's correct that. We could recreate our database and store the correct data but there is a better way: do some calculations while creating the -gif file ! +png file ! - rrdtool graph speed2.gif \ + rrdtool graph speed2.png \ --start 920804400 --end 920808000 \ --vertical-label m/s \ DEF:myspeed=test.rrd:speed:AVERAGE \ - CDEF:realspeed=myspeed,1000,* \ + CDEF:realspeed=myspeed,1000,\* \ LINE2:realspeed#FF0000 -After viewing this GIF, you notice the "m" has disappeared. This it what +After viewing this PNG, you notice the "m" 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 GIF should be the same. +Apart from the things mentioned above, the PNG should be the same. The calculations are in the CDEF part and are in Reverse Polish Notation ("RPN"). What it says is: "take the data source myspeed and the number @@ -393,9 +401,9 @@ In our example database we made a mistake and we need to compensate for this by multiplying with 1000. Applying that correction: -*- value * 3.6 *1000 == value * 3600 -Now let's create this GIF, and add some more magic ... +Now let's create this PNG, and add some more magic ... - rrdtool graph speed3.gif \ + rrdtool graph speed3.png \ --start 920804400 --end 920808000 \ --vertical-label km/h \ DEF:myspeed=test.rrd:speed:AVERAGE \ @@ -424,9 +432,9 @@ For the other speed: 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 GIF: +following PNG: - rrdtool graph speed4.gif \ + rrdtool graph speed4.png \ --start 920804400 --end 920808000 \ --vertical-label km/h \ DEF:myspeed=test.rrd:speed:AVERAGE \ @@ -439,23 +447,23 @@ following GIF: AREA:fast#550000:"Too fast" \ STACK:over#FF0000:"Over speed" -Let's create a quick and dirty HTML page to view three GIFs: +Let's create a quick and dirty HTML page to view three PNGs: