make perlbuild more portable
[rrdtool.git] / doc / rrd-beginners.pod
1 =head1 NAME
2
3 rrd-beginners - RRDtool Beginners' Guide
4
5 =head1 SYNOPSIS
6
7 Helping new RRDtool users to understand the basics of RRDtool
8
9 =head1 DESCRIPTION
10
11 This manual is an attempt to assist beginners in understanding the concepts
12 of RRDtool. It sheds a light on differences between RRDtool and other
13 databases. With help of an example, it explains the structure of RRDtool
14 database. This is followed by an overview of the "graph" feature of RRDtool.
15 At the end, it has sample scripts that illustrate the
16 usage/wrapping of RRDtool within Shell or Perl scripts.
17
18 =head2 What makes RRDtool so special?
19
20 RRDtool is GNU licensed software developed by Tobias Oetiker, a system
21 manager at the Swiss Federal Institute of Technology. Though it is a
22 database, there are distinct differences between RRDtool databases and other
23 databases as listed below:
24
25 =over
26
27 =item *
28
29 RRDtool stores data; that makes it a back-end tool. The RRDtool command set
30 allows the creation of graphs; that makes it a front-end tool as well. Other
31 databases just store data and can not create graphs.
32
33 =item *
34
35 In case of linear databases, new data gets appended at the bottom of
36 the database table. Thus its size keeps on increasing, whereas the size of
37 an RRDtool database is determined at creation time. Imagine an RRDtool
38 database as the perimeter of a circle. Data is added along the
39 perimeter. When new data reaches the starting point, it overwrites
40 existing data. This way, the size of an RRDtool database always
41 remains constant. The name "Round Robin" stems from this behavior.
42
43 =item *
44
45 Other databases store the values as supplied. RRDtool can be configured to
46 calculate the rate of change from the previous to the current value and
47 store this information instead.
48
49 =item *
50
51 Other databases get updated when values are supplied. The RRDtool database
52 is structured in such a way that it needs data at predefined time
53 intervals. If it does not get a new value during the interval, it stores an
54 UNKNOWN value for that interval. So, when using the RRDtool database, it is
55 imperative to use scripts that run at regular intervals to ensure a constant
56 data flow to update the RRDtool database.
57
58 =back
59
60 RRDtool is designed to store time series of data. With every data
61 update, an associated time stamp is stored. Time is always expressed
62 in seconds passed since epoch (01-01-1970). RRDtool can be installed
63 on Unix as well as Windows. It comes with a command set to carry out
64 various operations on RRD databases. This command set can be accessed
65 from the command line, as well as from Shell or Perl scripts. The
66 scripts act as wrappers for accessing data stored in RRDtool
67 databases.
68
69 =head2 Understanding by an example
70
71 The structure of an RRD database is different than other linear databases.
72 Other databases define tables with columns, and many other parameters. These
73 definitions sometimes are very complex, especially in large databases.
74 RRDtool databases are primarily used for monitoring purposes and
75 hence are very simple in structure. The parameters
76 that need to be defined are variables that hold values and archives of those
77 values. Being time sensitive, a couple of time related parameters are also
78 defined. Because of its structure, the definition of an RRDtool database also
79 includes a provision to specify specific actions to take in the absence of
80 update values. Data Source (DS), heartbeat, Date Source Type (DST), Round
81 Robin Archive (RRA), and Consolidation Function (CF) are some of the
82 terminologies related to RRDtool databases.
83
84 The structure of a database and the terminology associated with it can be
85 best explained with an example.
86
87  rrdtool create target.rrd \
88          --start 1023654125 \
89          --step 300 \
90          DS:mem:GAUGE:600:0:671744 \
91          RRA:AVERAGE:0.5:12:24 \
92          RRA:AVERAGE:0.5:288:31
93
94 This example creates a database named F<target.rrd>. Start time
95 (1'023'654'125) is specified in total number of seconds since epoch
96 (time in seconds since 01-01-1970). While updating the database, the
97 update time is also specified.  This update time MUST be large (later)
98 then start time and MUST be in seconds since epoch.
99
100 The step of 300 seconds indicates that database expects new values every
101 300 seconds. The wrapper script should be scheduled to run every B<step>
102 seconds so that it updates the database every B<step> seconds.
103
104 DS (Data Source) is the actual variable which relates to the parameter on
105 the device that is monitored. Its syntax is
106
107  DS:variable_name:DST:heartbeat:min:max
108
109 B<DS> is a key word. C<variable_name> is a name under which the parameter is
110 saved in the database. There can be as many DSs in a database as needed. After
111 every step interval, a new value of DS is supplied to update the database.
112 This value is also called Primary Data Point B<(PDP)>. In our example
113 mentioned above, a new PDP is generated every 300 seconds.
114
115 Note, that if you do NOT supply new datapoints exactly every 300 seconds,
116 this is not a problem, RRDtool will interpolate the data accordingly.
117
118 B<DST> (Data Source Type) defines the type of the DS. It can be
119 COUNTER, DERIVE, ABSOLUTE, GAUGE. A DS declared as COUNTER will save
120 the rate of change of the value over a step period. This assumes that
121 the value is always increasing (the difference between the current and
122 the previous value is greater than 0). Traffic counters on a router
123 are an ideal candidate for using COUNTER as DST. DERIVE is the same as
124 COUNTER, but it allows negative values as well. If you want to see the
125 rate of I<change> in free diskspace on your server, then you might
126 want to use the DERIVE data type. ABSOLUTE also saves the rate of
127 change, but it assumes that the previous value is set to 0. The
128 difference between the current and the previous value is always equal
129 to the current value. Thus it just stores the current value divided by
130 the step interval (300 seconds in our example). GAUGE does not save
131 the rate of change. It saves the actual value itself. There are no
132 divisions or calculations. Memory consumption in a server is a typical
133 example of gauge. The difference between the different types DSTs can be
134 explained better with the following example:
135
136  Values       = 300, 600, 900, 1200
137  Step         = 300 seconds
138  COUNTER DS   =    1,  1,   1,    1
139  DERIVE DS    =    1,  1,   1,    1
140  ABSOLUTE DS  =    1,  2,   3,    4
141  GAUGE DS     = 300, 600, 900, 1200
142
143 The next parameter is B<heartbeat>. In our example, heartbeat is 600
144 seconds. If the database does not get a new PDP within 300 seconds, it
145 will wait for another 300 seconds (total 600 seconds).  If it doesn't
146 receive any PDP within 600 seconds, it will save an UNKNOWN value into
147 the database. This UNKNOWN value is a special feature of RRDtool - it
148 is much better than to assume a missing value was 0 (zero) or any
149 other number which might also be a valid data value.  For example, the
150 traffic flow counter on a router keeps increasing. Lets say, a value
151 is missed for an interval and 0 is stored instead of UNKNOWN. Now when
152 the next value becomes available, it will calculate the difference
153 between the current value and the previous value (0) which is not
154 correct. So, inserting the value UNKNOWN makes much more sense here.
155
156 The next two parameters are the minimum and maximum value,
157 respectively. If the variable to be stored has predictable maximum and
158 minimum values, this should be specified here. Any update value
159 falling out of this range will be stored as UNKNOWN.
160
161 The next line declares a round robin archive (RRA). The syntax for
162 declaring an RRA is
163
164  RRA:CF:xff:step:rows
165
166 RRA is the keyword to declare RRAs. The consolidation function (CF)
167 can be AVERAGE, MINIMUM, MAXIMUM, and LAST. The concept of the
168 consolidated data point (CDP) comes into the picture here. A CDP is
169 CFed (averaged, maximum/minimum value or last value) from I<step>
170 number of PDPs. This RRA will hold I<rows> CDPs.
171
172 Lets have a look at the example above. For the first RRA, 12 (steps)
173 PDPs (DS variables) are AVERAGEed (CF) to form one CDP. 24 (rows) of
174 theses CDPs are archived. Each PDP occurs at 300 seconds. 12 PDPs
175 represent 12 times 300 seconds which is 1 hour. It means 1 CDP (which
176 is equal to 12 PDPs) represents data worth 1 hour. 24 such CDPs
177 represent 1 day (1 hour times 24 CDPs). This means, this RRA is an
178 archive for one day. After 24 CDPs, CDP number 25 will replace the 1st
179 CDP. The second RRA saves 31 CDPs; each CPD represents an AVERAGE
180 value for a day (288 PDPs, each covering 300 seconds = 24
181 hours). Therefore this RRA is an archive for one month. A single
182 database can have many RRAs. If there are multiple DSs, each
183 individual RRA will save data for all the DSs in the database. For
184 example, if a database has 3 DSs and daily, weekly, monthly, and
185 yearly RRAs are declared, then each RRA will hold data from all 3 data
186 sources.
187
188 =head2 Graphical Magic
189
190 Another important feature of RRDtool is its ability to create
191 graphs. The "graph" command uses the "fetch" command internally to
192 retrieve values from the database. With the retrieved values it draws
193 graphs as defined by the parameters supplied on the command line. A
194 single graph can show different DS (Data Sources) from a database. It
195 is also possible to show the values from more than one database in a
196 single graph. Often, it is necessary to perform some math on the
197 values retrieved from the database before plotting them. For example,
198 in SNMP replies, memory consumption values are usually specified in
199 KBytes and traffic flow on interfaces is specified in Bytes. Graphs
200 for these values will be more meaningful if values are represented in
201 MBytes and mbps. The RRDtool graph command allows to define such
202 conversions. Apart from mathematical calculations, it is also possible
203 to perform logical operations such as greater than, less than, and
204 if/then/else. If a database contains more than one RRA archive, then a
205 question may arise - how does RRDtool decide which RRA archive to use
206 for retrieving the values? RRDtool looks at several things when making
207 its choice. First it makes sure that the RRA covers as much of the
208 graphing time frame as possible. Second it looks at the resolution of
209 the RRA compared to the resolution of the graph. It tries to find one
210 which has the same or higher better resolution. With the "-r" option
211 you can force RRDtool to assume a different resolution than the one
212 calculated from the pixel width of the graph.
213
214 Values of different variables can be presented in 5 different shapes
215 in a graph - AREA, LINE1, LINE2, LINE3, and STACK. AREA is represented
216 by a solid colored area with values as the boundary of this
217 area. LINE1/2/3 (increasing width) are just plain lines representing
218 the values. STACK is also an area but it is "stack"ed on top AREA or
219 LINE1/2/3. Another important thing to note is that variables are
220 plotted in the order they are defined in the graph command. Therefore
221 care must be taken to define STACK only after defining AREA/LINE. It
222 is also possible to put formatted comments within the graph.  Detailed
223 instructions can be found in the graph manual.
224
225 =head2 Wrapping RRDtool within Shell/Perl script
226
227 After understanding RRDtool it is now a time to actually use RRDtool
228 in scripts. Tasks involved in network management are data collection,
229 data storage, and data retrieval. In the following example, the
230 previously created target.rrd database is used. Data collection and
231 data storage is done using Shell scripts. Data retrieval and report
232 generation is done using Perl scripts. These scripts are shown below:
233
234 =head3 Shell script (collects data, updates database)
235
236  #!/bin/sh
237  a=0
238  while [ "$a" == 0 ]; do
239  snmpwalk -c public 192.168.1.250 hrSWRunPerfMem > snmp_reply
240      total_mem=`awk 'BEGIN {tot_mem=0}
241                            { if ($NF == "KBytes")
242                              {tot_mem=tot_mem+$(NF-1)}
243                            }
244                      END {print tot_mem}' snmp_reply`
245      # I can use N as a replacement for the current time
246      rrdtool update target.rrd N:$total_mem
247      # sleep until the next 300 seconds are full
248      perl -e 'sleep 300 - time % 300'
249  done # end of while loop
250
251 =head3 Perl script (retrieves data from database and generates graphs and statistics)
252
253  #!/usr/bin/perl -w
254  # This script fetches data from target.rrd, creates a graph of memory
255  # consumption on the target (Dual P3 Processor 1 GHz, 656 MB RAM)
256
257  # call the RRD perl module
258  use lib qw( /usr/local/rrdtool-1.0.41/lib/perl ../lib/perl );
259  use RRDs;
260  my $cur_time = time();                # set current time
261  my $end_time = $cur_time - 86400;     # set end time to 24 hours ago
262  my $start_time = $end_time - 2592000; # set start 30 days in the past
263
264  # fetch average values from the RRD database between start and end time
265  my ($start,$step,$ds_names,$data) =
266      RRDs::fetch("target.rrd", "AVERAGE",
267                  "-r", "600", "-s", "$start_time", "-e", "$end_time");
268  # save fetched values in a 2-dimensional array
269  my $rows = 0;
270  my $columns = 0;
271  my $time_variable = $start;
272  foreach $line (@$data) {
273    $vals[$rows][$columns] = $time_variable;
274    $time_variable = $time_variable + $step;
275    foreach $val (@$line) {
276            $vals[$rows][++$columns] = $val;}
277    $rows++;
278    $columns = 0;
279  }
280  my $tot_time = 0;
281  my $count = 0;
282  # save the values from the 2-dimensional into a 1-dimensional array
283  for $i ( 0 .. $#vals ) {
284      $tot_mem[$count] = $vals[$i][1];
285      $count++;
286  }
287  my $tot_mem_sum = 0;
288  # calculate the total of all values
289  for $i ( 0 .. ($count-1) ) {
290      $tot_mem_sum = $tot_mem_sum + $tot_mem[$i];
291  }
292  # calculate the average of the array
293  my $tot_mem_ave = $tot_mem_sum/($count);
294  # create the graph
295  RRDs::graph ("/images/mem_$count.png",   \
296              "--title= Memory Usage",    \
297              "--vertical-label=Memory Consumption (MB)", \
298              "--start=$start_time",      \
299              "--end=$end_time",          \
300              "--color=BACK#CCCCCC",      \
301              "--color=CANVAS#CCFFFF",    \
302              "--color=SHADEB#9999CC",    \
303              "--height=125",             \
304              "--upper-limit=656",        \
305              "--lower-limit=0",          \
306              "--rigid",                  \
307              "--base=1024",              \
308              "DEF:tot_mem=target.rrd:mem:AVERAGE", \
309              "CDEF:tot_mem_cor=tot_mem,0,671744,LIMIT,UN,0,tot_mem,IF,1024,/",\
310              "CDEF:machine_mem=tot_mem,656,+,tot_mem,-",\
311              "COMMENT:Memory Consumption between $start_time",\
312              "COMMENT:    and $end_time                     ",\
313              "HRULE:656#000000:Maximum Available Memory - 656 MB",\
314              "AREA:machine_mem#CCFFFF:Memory Unused",   \
315              "AREA:tot_mem_cor#6699CC:Total memory consumed in MB");
316  my $err=RRDs::error;
317  if ($err) {print "problem generating the graph: $err\n";}
318  # print the output
319  print "Average memory consumption is ";
320  printf "%5.2f",$tot_mem_ave/1024;
321  print " MB. Graphical representation can be found at /images/mem_$count.png.";
322
323 =head1 AUTHOR
324
325 Ketan Patel E<lt>k2pattu@yahoo.comE<gt>
326