tutorial/htwchur/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{HTW RRDtool Tutorial}
  17 \date{Monday, January 14th, 2008}
  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 Ask me!
  43 \end{itemize}
  44
  45 \section{Creating an RRD}
  46 \ex{Data Source Types}
  47
  48 RRDtool stores and graphs data you feed it. In order to do so
  49 properly you must provide some information about the nature of the
  50 data. RRDtool knows several different types of Data Sources (DS).
  51
  52 \begin{work}
  53   Read the RRDcreate manual page to identify the data source types
  54   and write down some examples for each type.
  55 \end{work}
  56
  57 \ex{Data Consolidation Methods}
  58
  59 Once you have passed data on to RRDtool it gets stored in a data
  60 storage array (Round Robin Archive). Each RRD can contain several
  61 RRAs, working at different resolutions and using different data
  62 consolidation methods.
  63
  64 \begin{work}
  65   Find the different Data Consolidation methods currently supported in
  66   RRDtool. This information can be found in the RRD create manual
  67   page.
  68 \end{work}
  69
  70 \ex{Data Validation}
  71
  72 Storing invalid data can often be more of a problem than not storing
  73 anything at all. In order to help you ensure that only valid data gets
  74 into your Round Robin Database, RRDtool allows you to
  75 describe some properties of the data you intend to store. This allows
  76 RRDtool to throw out invalid input before it even enters the database.
  77
  78 \begin{work}
  79 Identify the parameters to setup these safeguards. This information
  80 can be found in the RRD create manual page.\end{work}
  81
  82 \ex{Database Setup}
  83
  84 Having solved the exercises up this point you are now ready to setup a
  85 Round Robin Database. Use the command line tool\\
  86 \cmd{rrdtool} to work your magic.
  87
  88 \begin{work}
  89   Create an RRD which accepts input from two COUNTER
  90   data sources. The data sources provide new data every 300 seconds on
  91   average. Allow for a maximal update interval of 600 seconds. The
  92   input from both data-sources will always be between zero and 35
  93   million.
  94
  95   The RRD should store the data for 24 hours at 5 minute resolution
  96   and for a month at one hour resolution. For the one hour resolution
  97   you want to keep both the average and the 5 minute maximum data.
  98 \end{work}
  99
 100 \ex{Coupling of Data Values}
 101
 102 All values stored in a single RRD must be updated synchronously. Also,
 103 it is not trivial to add new data-sources to an existing RRD or remove
 104 old ones. In most cases it is sensible to create a new RRD for each
 105 data source unless you know that they are tightly coupled.
 106
 107 \begin{work}
 108   Think of some data sources which are tightly coupled in the sense that
 109   they should be stored into the same RRD and of some which should NOT be
 110   stored in the same RRD.
 111 \end{work}
 112
 113 \section{RRD Update}
 114 \ex{The RRD Perl Interface}
 115
 116 The fastest way to interact with an RRD is to write a perl script
 117 which uses the RRD shared module interface. You can find documentation
 118 on this in the RRDs manual page. In order to access it, you must
 119 add
 120
 121 \cmd{use RRDs;}
 122
 123 to the very beginning of your script.
 124
 125 \begin{work}
 126 Convert the command line for creating the RRD from the last exercise
 127 in the previous section into a perl script.
 128 \end{work}
 129
 130 \ex{The Error Messages in Perl}
 131 The RRDs commands do not complain when you call them with invalid
 132 arguments. Normally they just get ignored. To catch errors you must
 133 actively look for them. This is done with the \cmd{RRDs::error}
 134 function.
 135
 136 \begin{work}
 137 Add error checking to your perl script and test it by providing the
 138 create command with invalid parameters.
 139 \end{work}
 140
 141 \ex{Feeding Data into an RRD}
 142 In \cmd{/proc/net/dev} you can find some counters regarding the
 143 network traffic of your workstation. This file will contain new data each time you read it.
 144
 145 \begin{work}
 146   Use the data from this file to populate the RRD created in the previous
 147   exercise. Don't forget to add error checking to the update routine. Make
 148   sure you 'fake' the update time by stepping 5 minutes ahead everytime you
 149   update.
 150 \end{work}
 151
 152 \section{Creating graphs}
 153
 154 \ex{Line Graphs}
 155 Harvesting data and storing in RRDs alone won't help you get a
 156 promotion. What really interests people is getting graphs produced from
 157 this data.
 158
 159 \begin{work}
 160 Use the RRDs::graph function to create a graph representing the data
 161 stored in your RRD. To start, use only \cmd{DEF:...} and \cmd{LINE1:...}
 162 and \cmd{--end now+2day} parameters and have RRDtool
 163 auto-configure the rest.
 164 \end{work}
 165
 166 \ex{GPRINT Exercise}
 167 A RRD graph can also show numerical data.
 168
 169 \begin{work}
 170   Use the \cmd{GPRINT} argument to show the maximum 5 minute values of
 171   both data sources below the graph.
 172 \end{work}
 173
 174 \ex{A Stack Graph}
 175 Lets assume the data in the RRD represents traffic seen on two
 176 different web servers which share the load of a busy web site.
 177
 178 \begin{work}
 179   Use the \cmd{AREA:} and \cmd{STACK:} function to place the data from
 180   the first and second data-source on top of each other. This will
 181   show the traffic produced by each server on its own as well as the
 182   total traffic occurring on your web site.
 183 \end{work}
 184
 185 \ex{Using RPN Math}
 186
 187 The network traffic in /proc/net/snmp is in octets passed over the
 188 interface. Most people though will expect to see traffic data reported in
 189 bits instead of octets.
 190
 191 \begin{work}
 192 Use the \cmd{CDEF:} function to multiply your data by 8
 193 before graphing it. This has been discussed in the RRDtool
 194 presentation.
 195 \end{work}
 196
 197 \section{Graphing On The Fly}
 198 \ex{Simple RRDcgi Use}
 199
 200 The most time consuming operation in RRDtool is creating the graphs.
 201 So when setting up a complex monitor you want to avoid generating
 202 graphs when ever you can. One approach to this problem is to generate
 203 graphs on-the-fly. The \cmd{rrdcgi} tool helps you do this with a very
 204 simple script interpreter. Check the corresponding manual page.
 205
 206 Find \cmd{rrdcgi} in \cmd{/usr/bin} \ldots
 207
 208 \begin{work}
 209   Write a \cmd{rrdcgi} input file which generates the stacked graph
 210   you did in the last example. Check the effect of the \texttt{--lazy}
 211   option. You can test your input file by putting it into
 212   \cmd{httpd/htdocs/xyz.cgi} and then calling\\
 213   \cmd{http://paspels.tlab.ch/\ti{}rrd???/xyz.cgi}
 214 \end{work}
 215
 216 \ex{Interactive RRDcgi}
 217 The second example on the \cmd{rrdcgi} manual page shows how to access
 218 \cmd{FORM} parameters.
 219
 220 \begin{work}
 221 Use this to give the user of your page the
 222 option to select whether to generate a graph for the last day (\cmd{--start
 223 end-24h}) or for the last week (\cmd{--start end-7d}).
 224 \end{work}
 225
 226 \section{Mixed Features}
 227 \ex{Dump and Restore} An RRD is stored in native binary format. When
 228 you want to transport an RRD from one hardware/OS combination to
 229 another one you must use RRDtool dump and restore. (rrdtool 1.4 is going to change that).
 230
 231 \begin{work}
 232 Use \cmd{dump} to convert your RRD into XML format and have a look at
 233 it. You should be able recognize several of the elements of the
 234 RRD. Dumping an RRD can also be useful when you are debugging.
 235 \end{work}
 236
 237 \ex{Alter RRD Parameters}
 238 Some parameters of an existing RRD can be changed quite easily using
 239 the tune command.
 240
 241 \begin{work}
 242 Use the tune command to change the name of the two data sources in
 243 your RRD. Use dump to very that the changes were successful.
 244 \end{work}
 245
 246
 247 \ex{Examine an RRD}
 248
 249 If you are writing a frontend to RRDtool it might be necessary to
 250 find out about the configuration of an existing rrd file. The rrdinfo
 251 function helps you with this.
 252
 253 \begin{work}
 254   Use \texttt{RRDs::info} to fetch config data from an existing rrd
 255   and convert it into command line which you could supply to rrdtool
 256   create.
 257 \end{work}
 258
 259
 260 \end{document}
 261
 262
 263
 264