tutorial/emanics/rrd-exercises.tex

   1 \documentclass[a4paper,12pt]{article}
   2 \usepackage{times}
   3 \newenvironment{work}{\textsf{\tiny EXERCISE}\nopagebreak\\[0.3ex]\begin{tabular}{|c|}
   4  \hline
   5  \begin{minipage}{0.965\linewidth}%
   6  \setlength{\parskip}{1.6ex plus 0.6ex minus 0.4ex}%
   7  \rule{0pt}{2.8ex}\ignorespaces}
   8 {\rule[-1.8ex]{0pt}{0pt}\end{minipage}\\
   9  \hline
  10  \end{tabular}}
  11 \newcommand{\ex}[1]{\subsection{#1}}
  12 \newcommand{\cmd}[1]{\texttt{\mbox{#1}}}
  13 \setlength{\parskip}{1.6ex plus 0.8ex minus 0.4ex}
  14 \setlength{\parindent}{0pt}
  15 \addtolength{\textheight}{5ex}
  16 \title{EMANICS RRDtool Tutorial}
  17 \date{Wednesday, July 11th, 2007}
  18 \author{Tobias Oetiker $<$tobi@oetiker.ch$>$}
  19 \newcommand\bs{\char '134}   %  a \ character for the \tt font
  20 \newcommand\lb{\char '173}   %  a { character for the \tt font
  21 \newcommand\rb{\char '175}   %  a } character for the \tt font
  22 \newcommand\ti{$\sim$}   %  a ~ character for the \tt font
  23
  24 \begin{document}
  25 \maketitle
  26
  27 The objective of this tutorial session is to help you get comfortable using
  28 RRDtool to write your own monitoring applications.
  29
  30 In order to do some of the exercises you will need information which
  31 you do not have yet. There are three main sources from where you can
  32 acquire this information.
  33
  34 As you can see, there are no solutions printed on this sheet. I would
  35 propose though, that you write your solutions into a file and mail
  36 this to me. I will then put together the solutions and mail it back
  37 to everyone who sent in their work.
  38
  39 \begin{itemize}
  40 \item Read the RRDtool Manual on the web site or the unix manual
  41   pages.\\ \cmd{http://oss.oetiker.ch/rrdtool}
  42 \item On the computers you can find rrdtool in \cmd{/usr/local/rrdtool-1.2.23}
  43   To use it, update your path accordingly:\\
  44 \cmd{RH=/usr/local/rrdtool-1.2.23; export PATH=\$RH/bin:\$PATH}
  45 \item Ask me!
  46 \end{itemize}
  47
  48 \newpage
  49 \section{Creating an RRD}
  50 \ex{Data Source Types}
  51
  52 RRDtool stores and graphs data you feed it. In order to do so
  53 properly you must provide some information about the nature of the
  54 data. RRDtool knows several different types of Data Sources (DS).
  55
  56 \begin{work}
  57   Read the RRDcreate manual page to identify the data source types
  58   and write down some examples for each type.
  59 \end{work}
  60
  61 \ex{Data Consolidation Methods}
  62
  63 Once you have passed data on to RRDtool it gets stored in a data
  64 storage array (Round Robin Archive). Each RRD can contain several
  65 RRAs, working at different resolutions and using different data
  66 consolidation methods.
  67
  68 \begin{work}
  69   Find the different Data Consolidation methods currently supported in
  70   RRDtool. This information can be found in the RRD create manual
  71   page.
  72 \end{work}
  73
  74 \ex{Data Validation}
  75
  76 Storing invalid data can often be more of a problem than not storing
  77 anything at all. In order to help you ensure that only valid data gets
  78 into your Round Robin Database, RRDtool allows you to
  79 describe some properties of the data you intend to store. This allows
  80 RRDtool to throw out invalid input before it even enters the database.
  81
  82 \begin{work}
  83 Identify the parameters to setup these safeguards. This information
  84 can be found in the RRD create manual page.\end{work}
  85
  86 \ex{Database Setup}
  87
  88 Having solved the exercises up this point you are now ready to setup a
  89 Round Robin Database. Use the command line tool\\
  90 \cmd{rrdtool} to work your magic.
  91
  92 \begin{work}
  93   Create an RRD which accepts input from two COUNTER
  94   data sources. The data sources provide new data every 300 seconds on
  95   average. Allow for a maximal update interval of 600 seconds. The
  96   input from both data-sources will always be between zero and 35
  97   million.
  98
  99   The RRD should store the data for 24 hours at 5 minute resolution
 100   and for a month at one hour resolution. For the one hour resolution
 101   you want to keep both the average and the 5 minute maximum data.
 102
 103 \end{work}
 104
 105 Use \cmd{rrdtool info database.rrd} to see the structure of the rrd file you
 106 just created.
 107
 108 \ex{Coupling of Data Values}
 109
 110 All values stored in a single RRD must be updated synchronously. Also,
 111 it is not trivial to add new data-sources to an existing RRD or remove
 112 old ones. In most cases it is sensible to create a new RRD for each
 113 data source unless you know that they are tightly coupled.
 114
 115 \begin{work}
 116   Think of some data sources which are tightly coupled in the sense that
 117   they should be stored into the same RRD and of some which should NOT be
 118   stored in the same RRD. (see /home/oetiker/solutions/ds.txt for some ideas)
 119 \end{work}
 120
 121 \newpage
 122 \section{RRD Update}
 123 \ex{The RRD Perl Interface}
 124
 125 The fastest way to interact with an RRD is to write a perl script
 126 which uses the RRD shared module interface. You can find documentation
 127 on this in the RRDs manual page. On \cmd{cider.caida.org} the perl module is
 128 stored in\\ \cmd{\$RH/lib/perl}. In order to access it, you must
 129 add
 130
 131 \cmd{use lib \$ENV\{RH\}.'/lib/perl';}\\
 132 \cmd{use RRDs;}
 133
 134 to the very beginning of your script.
 135
 136 \begin{work}
 137 Convert the command line for creating the RRD from the last exercise
 138 in the previous section into a perl script.
 139 \end{work}
 140
 141 \ex{The Error Messages in Perl}
 142 The RRDs commands do not complain when you call them with invalid
 143 arguments. Normally they just get ignored. To catch errors you must
 144 actively look for them. This is done with the \cmd{RRDs::error}
 145 function.
 146
 147 \begin{work}
 148 Add error checking to your perl script and test it by providing the
 149 create command with invalid parameters.
 150 \end{work}
 151
 152 \newpage
 153 \ex{Feeding Data into an RRD}
 154 In \cmd{/proc/net/snmp} you can find some counters about regarding the
 155 traffic of your workstation. This file will contain new data each time you read it.
 156
 157 \begin{work}
 158   Use the data from this file to populate the RRD created in the previous
 159   exercise. Don't forget to add error checking to the update routine. Make
 160   sure you 'fake' the update time by stepping 5 minutes ahead everytime you
 161   update.
 162 \end{work}
 163
 164 Use \cmd{rrdtool dump file.rrd} what data is stored in the rrd file.
 165 \section{Creating graphs}
 166
 167 \ex{Line Graphs}
 168 Harvesting data and storing in RRDs alone won't help you get a
 169 promotion. What really interests people is getting graphs produced from
 170 this data.
 171
 172 \begin{work}
 173 Use the RRDs::graph function to create a graph representing the data
 174 stored in your RRD. To start, use only \cmd{DEF:...} and \cmd{LINE1:...}
 175 and \cmd{--end now+2day} parameters and have RRDtool
 176 auto-configure the rest.
 177 \end{work}
 178
 179 \ex{GPRINT Exercise}
 180 A RRD graph can also show numerical data.
 181
 182 \begin{work}
 183   Use the \cmd{GPRINT} argument to show the maximum 5 minute values of
 184   both data sources below the graph.
 185 \end{work}
 186
 187 \ex{A Stack Graph}
 188 Lets assume the data in the RRD represents traffic seen on two
 189 different web servers which share the load of a busy web site.
 190
 191 \begin{work}
 192   Use the \cmd{AREA:} and \cmd{STACK:} function to place the data from
 193   the first and second data-source on top of each other. This will
 194   show the traffic produced by each server on its own as well as the
 195   total traffic occurring on your web site.
 196 \end{work}
 197
 198 \ex{Using RPN Math}
 199
 200 The network traffic in /proc/net/snmp is in octets passed over the
 201 interface. Most people though will expect to see traffic data reported in
 202 bits instead of octets.
 203
 204 \begin{work}
 205 Use the \cmd{CDEF:} function to multiply your data by 8
 206 before graphing it. This has been discussed in the RRDtool
 207 presentation.
 208 \end{work}
 209
 210 \newpage
 211 \section{Graphing On The Fly}
 212 \ex{Simple RRDcgi Use}
 213
 214 The most time consuming operation in RRDtool is creating the graphs.
 215 So when setting up a complex monitor you want to avoid generating
 216 graphs when ever you can. One approach to this problem is to generate
 217 graphs on-the-fly. The \cmd{rrdcgi} tool helps you do this with a very
 218 simple script interpreter. Check the corresponding manual page.
 219
 220 Find \cmd{rrdcgi} in \cmd{\$RH/bin} \ldots
 221
 222 \begin{work}
 223   Write a \cmd{rrdcgi} input file which generates the stacked graph
 224   you did in the last example. Check the effect of the \texttt{--lazy}
 225   option. You can test your input file by putting it into
 226   \cmd{public\_html/xyz.cgi} and then calling\\
 227   \cmd{http://www\ldots/\ti rrd??/xyz.cgi}
 228 \end{work}
 229
 230 \ex{Interactive RRDcgi}
 231 The second example on the \cmd{rrdcgi} manual page shows how to access
 232 \cmd{FORM} parameters.
 233
 234 \begin{work}
 235 Use this to give the user of your page the
 236 option to select whether to generate a graph for the last day (\cmd{--start
 237 end-24h}) or for the last week (\cmd{--start end-7d}).
 238 \end{work}
 239 \newpage
 240 \section{Mixed Features}
 241 \ex{Dump and Restore} An RRD is stored in native binary format. When
 242 you want to transport an RRD from one hardware/OS combination to
 243 another one you must use RRDtool dump and restore. (rrdtool 1.4 is going to change that).
 244
 245 \begin{work}
 246 Use \cmd{dump} to convert your RRD into XML format and have a look at
 247 it. You should be able recognize several of the elements of the
 248 RRD. Dumping an RRD can also be useful when you are debugging.
 249 \end{work}
 250
 251 \ex{Alter RRD Parameters}
 252 Some parameters of an existing RRD can be changed quite easily using
 253 the update command.
 254
 255 \begin{work}
 256 Use the update command to change the name of the two data sources in
 257 your RRD. Use dump to very that the changes were successful.
 258 \end{work}
 259
 260
 261 \ex{Examine an RRD}
 262
 263 If you are writing a frontend to RRDtool it might be necessary to
 264 find out about the configuration of an existing rrd file. The rrdinfo
 265 function helps you with this.
 266
 267 \begin{work}
 268   Use \texttt{RRDs::info} to fetch config data from an existing rrd
 269   and convert it into command line which you could supply to rrdtool
 270   create.
 271 \end{work}
 272
 273 \ex{Graph ntop}
 274
 275 Ntop can store its traffic data into rrdtool files..
 276
 277 \begin{work}
 278   Investigate the ntop rrd format and create your own graphs based on the information you gathered.
 279 \end{work}
 280
 281 \end{document}
 282
 283
 284
 285