X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Frrd-beginners.1;h=c62764b969b65cbdeb130232600569984f85483a;hb=c397a78525a287fbb64551ebd8834d1c2407e01d;hp=9a2772a1c5f265ec675aa63b837c17b6c2e0dc02;hpb=ecfac614b914cef110a81ac665997a9b186da500;p=pkg-rrdtool.git diff --git a/doc/rrd-beginners.1 b/doc/rrd-beginners.1 index 9a2772a..c62764b 100644 --- a/doc/rrd-beginners.1 +++ b/doc/rrd-beginners.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.05) .\" .\" 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,11 @@ .\" ======================================================================== .\" .IX Title "RRD-BEGINNERS 1" -.TH RRD-BEGINNERS 1 "2007-11-20" "1.2.26" "rrdtool" +.TH RRD-BEGINNERS 1 "2009-10-14" "1.4.2" "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" rrd\-beginners \- RRDtool Beginners' Guide .SH "SYNOPSIS" @@ -143,7 +142,7 @@ databases. With help of an example, it explains the structure of RRDtool database. This is followed by an overview of the \*(L"graph\*(R" feature of RRDtool. At the end, it has sample scripts that illustrate the usage/wrapping of RRDtool within Shell or Perl scripts. -.Sh "What makes RRDtool so special?" +.SS "What makes RRDtool so special?" .IX Subsection "What makes RRDtool so special?" RRDtool is \s-1GNU\s0 licensed software developed by Tobias Oetiker, a system manager at the Swiss Federal Institute of Technology. Though it is a @@ -181,7 +180,7 @@ various operations on \s-1RRD\s0 databases. This command set can be accessed from the command line, as well as from Shell or Perl scripts. The scripts act as wrappers for accessing data stored in RRDtool databases. -.Sh "Understanding by an example" +.SS "Understanding by an example" .IX Subsection "Understanding by an example" The structure of an \s-1RRD\s0 database is different than other linear databases. Other databases define tables with columns, and many other parameters. These @@ -231,7 +230,7 @@ every step interval, a new value of \s-1DS\s0 is supplied to update the database This value is also called Primary Data Point \fB(\s-1PDP\s0)\fR. In our example mentioned above, a new \s-1PDP\s0 is generated every 300 seconds. .PP -Note, that if you do \s-1NOT\s0 supply new datapoints exactly every 300 seconds, +Note, that if you do \s-1NOT\s0 supply new data points exactly every 300 seconds, this is not a problem, RRDtool will interpolate the data accordingly. .PP \&\fB\s-1DST\s0\fR (Data Source Type) defines the type of the \s-1DS\s0. It can be @@ -241,7 +240,7 @@ the value is always increasing (the difference between the current and the previous value is greater than 0). Traffic counters on a router are an ideal candidate for using \s-1COUNTER\s0 as \s-1DST\s0. \s-1DERIVE\s0 is the same as \&\s-1COUNTER\s0, but it allows negative values as well. If you want to see the -rate of \fIchange\fR in free diskspace on your server, then you might +rate of \fIchange\fR in free disk space on your server, then you might want to use the \s-1DERIVE\s0 data type. \s-1ABSOLUTE\s0 also saves the rate of change, but it assumes that the previous value is set to 0. The difference between the current and the previous value is always equal @@ -307,7 +306,7 @@ individual \s-1RRA\s0 will save data for all the DSs in the database. For example, if a database has 3 DSs and daily, weekly, monthly, and yearly RRAs are declared, then each \s-1RRA\s0 will hold data from all 3 data sources. -.Sh "Graphical Magic" +.SS "Graphical Magic" .IX Subsection "Graphical Magic" Another important feature of RRDtool is its ability to create graphs. The \*(L"graph\*(R" command uses the \*(L"fetch\*(R" command internally to @@ -343,7 +342,7 @@ plotted in the order they are defined in the graph command. Therefore care must be taken to define \s-1STACK\s0 only after defining \s-1AREA/LINE\s0. It is also possible to put formatted comments within the graph. Detailed instructions can be found in the graph manual. -.Sh "Wrapping RRDtool within Shell/Perl script" +.SS "Wrapping RRDtool within Shell/Perl script" .IX Subsection "Wrapping RRDtool within Shell/Perl script" After understanding RRDtool it is now a time to actually use RRDtool in scripts. Tasks involved in network management are data collection, @@ -355,20 +354,20 @@ generation is done using Perl scripts. These scripts are shown below: \fIShell script (collects data, updates database)\fR .IX Subsection "Shell script (collects data, updates database)" .PP -.Vb 14 +.Vb 10 \& #!/bin/sh \& a=0 \& while [ "$a" == 0 ]; do \& snmpwalk \-c public 192.168.1.250 hrSWRunPerfMem > snmp_reply -\& total_mem=`awk 'BEGIN {tot_mem=0} +\& total_mem=\`awk \*(AqBEGIN {tot_mem=0} \& { if ($NF == "KBytes") \& {tot_mem=tot_mem+$(NF\-1)} \& } -\& END {print tot_mem}' snmp_reply` +\& END {print tot_mem}\*(Aq snmp_reply\` \& # I can use N as a replacement for the current time \& rrdtool update target.rrd N:$total_mem \& # sleep until the next 300 seconds are full -\& perl \-e 'sleep 300 \- time % 300' +\& perl \-e \*(Aqsleep 300 \- time % 300\*(Aq \& done # end of while loop .Ve .PP @@ -379,18 +378,14 @@ generation is done using Perl scripts. These scripts are shown below: \& #!/usr/bin/perl \-w \& # This script fetches data from target.rrd, creates a graph of memory \& # consumption on the target (Dual P3 Processor 1 GHz, 656 MB RAM) -.Ve -.PP -.Vb 6 +\& \& # call the RRD perl module \& use lib qw( /usr/local/rrdtool\-1.0.41/lib/perl ../lib/perl ); \& use RRDs; \& my $cur_time = time(); # set current time \& my $end_time = $cur_time \- 86400; # set end time to 24 hours ago \& my $start_time = $end_time \- 2592000; # set start 30 days in the past -.Ve -.PP -.Vb 58 +\& \& # fetch average values from the RRD database between start and end time \& my ($start,$step,$ds_names,$data) = \& RRDs::fetch("target.rrd", "AVERAGE", @@ -422,26 +417,26 @@ generation is done using Perl scripts. These scripts are shown below: \& # calculate the average of the array \& my $tot_mem_ave = $tot_mem_sum/($count); \& # create the graph -\& RRDs::graph ("/images/mem_$count.png", \e -\& "\-\-title= Memory Usage", \e -\& "\-\-vertical\-label=Memory Consumption (MB)", \e -\& "\-\-start=$start_time", \e -\& "\-\-end=$end_time", \e -\& "\-\-color=BACK#CCCCCC", \e -\& "\-\-color=CANVAS#CCFFFF", \e -\& "\-\-color=SHADEB#9999CC", \e -\& "\-\-height=125", \e -\& "\-\-upper\-limit=656", \e -\& "\-\-lower\-limit=0", \e -\& "\-\-rigid", \e -\& "\-\-base=1024", \e -\& "DEF:tot_mem=target.rrd:mem:AVERAGE", \e -\& "CDEF:tot_mem_cor=tot_mem,0,671744,LIMIT,UN,0,tot_mem,IF,1024,/",\e -\& "CDEF:machine_mem=tot_mem,656,+,tot_mem,\-",\e -\& "COMMENT:Memory Consumption between $start_time",\e -\& "COMMENT: and $end_time ",\e -\& "HRULE:656#000000:Maximum Available Memory \- 656 MB",\e -\& "AREA:machine_mem#CCFFFF:Memory Unused", \e +\& RRDs::graph ("/images/mem_$count.png", +\& "\-\-title= Memory Usage", +\& "\-\-vertical\-label=Memory Consumption (MB)", +\& "\-\-start=$start_time", +\& "\-\-end=$end_time", +\& "\-\-color=BACK#CCCCCC", +\& "\-\-color=CANVAS#CCFFFF", +\& "\-\-color=SHADEB#9999CC", +\& "\-\-height=125", +\& "\-\-upper\-limit=656", +\& "\-\-lower\-limit=0", +\& "\-\-rigid", +\& "\-\-base=1024", +\& "DEF:tot_mem=target.rrd:mem:AVERAGE", +\& "CDEF:tot_mem_cor=tot_mem,0,671744,LIMIT,UN,0,tot_mem,IF,1024,/", +\& "CDEF:machine_mem=tot_mem,656,+,tot_mem,\-", +\& "COMMENT:Memory Consumption between $start_time", +\& "COMMENT: and $end_time ", +\& "HRULE:656#000000:Maximum Available Memory \- 656 MB", +\& "AREA:machine_mem#CCFFFF:Memory Unused", \& "AREA:tot_mem_cor#6699CC:Total memory consumed in MB"); \& my $err=RRDs::error; \& if ($err) {print "problem generating the graph: $err\en";}