diff --git a/doc/rrd-beginners.1 b/doc/rrd-beginners.1
index a06c0ddf27c195e696b1e28c4150b5e299bf9583..3f8a41fa45abcaeec45839176d306c0d1d8cb4af 100644 (file)
--- a/doc/rrd-beginners.1
+++ b/doc/rrd-beginners.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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
. 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.
.\" ========================================================================
.\"
.IX Title "RRD-BEGINNERS 1"
-.TH RRD-BEGINNERS 1 "2008-03-15" "1.3.7" "rrdtool"
+.TH RRD-BEGINNERS 1 "2009-10-14" "1.4.7" "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"
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
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
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
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
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,
\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 \(aqBEGIN {tot_mem=0}
+\& total_mem=\`awk \*(AqBEGIN {tot_mem=0}
\& { if ($NF == "KBytes")
\& {tot_mem=tot_mem+$(NF\-1)}
\& }
-\& END {print tot_mem}\(aq 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 \(aqsleep 300 \- time % 300\(aq
+\& perl \-e \*(Aqsleep 300 \- time % 300\*(Aq
\& done # end of while loop
.Ve
.PP
\& #!/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",
\& # 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";}