X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Frrdtutorial.1;h=43889acee2f5216b583011bca034d231ebb37422;hb=645054bac6187b0e83fd4125fd59e4feda216b64;hp=00998d8e6739c4d091cca9fbba716c4c79a012d4;hpb=1559397b94b4af3de73cfa23c04be31d8bee53e7;p=pkg-rrdtool.git diff --git a/doc/rrdtutorial.1 b/doc/rrdtutorial.1 index 00998d8..43889ac 100644 --- a/doc/rrdtutorial.1 +++ b/doc/rrdtutorial.1 @@ -1,15 +1,7 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" 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 @@ -48,22 +40,25 @@ . 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. @@ -129,7 +124,12 @@ .\" ======================================================================== .\" .IX Title "RRDTUTORIAL 1" -.TH RRDTUTORIAL 1 "2009-02-21" "1.3.7" "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" .IX Header "DESCRIPTION" @@ -145,7 +145,7 @@ It also explains the general things about statistics with a focus on 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 @@ -169,7 +169,7 @@ examples which suffer from the same or a similar bug. Try to fix it 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 @@ -183,7 +183,7 @@ 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 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 @@ -199,7 +199,7 @@ way through this document, you should know enough to be able to 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 @@ -221,7 +221,7 @@ data in it, retrieve that data and create graphs in \s-1PNG\s0 format for 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 @@ -244,7 +244,7 @@ I suggest you take a moment to subscribe to the mailing list right now by sending an email to 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 @@ -257,7 +257,7 @@ more important, some background information of how it works. .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 @@ -353,7 +353,7 @@ and skip all of the '\e' characters. .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 @@ -379,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 @@ -430,9 +430,7 @@ It should return the following output: .PP .Vb 1 \& speed -.Ve -.PP -.Vb 16 +\& \& 920804700: nan \& 920805000: 4.0000000000e\-02 \& 920805300: 2.0000000000e\-02 @@ -456,10 +454,10 @@ If it doesn't, something may be wrong. Perhaps your \s-1OS\s0 will print 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 @@ -474,7 +472,7 @@ 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 \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 @@ -498,12 +496,12 @@ The \*(L"color\*(R" black is all colors off: 000000 .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 @@ -615,13 +613,13 @@ For values above the speed limit: \& 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 @@ -660,7 +658,7 @@ 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 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"