tutorial/opennms2013/rrd-exercises.tex

   1 \documentclass[a4paper,12pt]{article}
   2 \usepackage{lmodern}
   3 \usepackage[colorlinks]{hyperref}
   4 \newenvironment{work}{\textsf{\tiny EXERCISE}\nopagebreak\\[0.3ex]\begin{tabular}{|c|}
   5  \hline
   6  \begin{minipage}{0.965\linewidth}%
   7  \setlength{\parskip}{1.6ex plus 0.6ex minus 0.4ex}%
   8  \rule{0pt}{2.8ex}\ignorespaces}
   9 {\rule[-1.8ex]{0pt}{0pt}\end{minipage}\\
  10  \hline
  11  \end{tabular}}
  12 \newcommand{\ex}[1]{\subsection{#1}}
  13 \newcommand{\cmd}[1]{\texttt{\mbox{#1}}}
  14 \setlength{\parskip}{1.6ex plus 0.8ex minus 0.4ex}
  15 \setlength{\parindent}{0pt}
  16 \addtolength{\textheight}{5ex}
  17 \title{RRDtool Tutorial}
  18 \date{Wednesday, March 13th, 2013}
  19 \author{Tobias Oetiker $<$tobi@oetiker.ch$>$}
  20 \newcommand\bs{\char '134}   %  a \ character for the \tt font
  21 \newcommand\lb{\char '173}   %  a { character for the \tt font
  22 \newcommand\rb{\char '175}   %  a } character for the \tt font
  23 \newcommand\ti{$\sim$}   %  a ~ character for the \tt font
  24
  25 \begin{document}
  26 \maketitle
  27
  28 The objective of this tutorial session is to help you get comfortable using
  29 RRDtool to write your own monitoring applications.
  30
  31 In order to do some of the exercises you will need information which
  32 you do not have yet. There are three main sources from where you can
  33 acquire this information.
  34
  35 \begin{itemize}
  36 \item The \href{http://oss.oetiker.ch/rrdtool}{rrdtool web site}.
  37 \item Or read the rrdtool unix manual pages.
  38 \item Ask me!
  39 \end{itemize}
  40
  41 As you can see, there are no solutions printed on this sheet. I would
  42 propose though, that you your sollutions to me. I will then put them together
  43 mail them back to everyone who sent in their work.
  44
  45
  46 \newpage
  47 \section{Creating an RRD}
  48 \ex{Data Source Types}
  49
  50 RRDtool stores and graphs numerical data. In order to do so
  51 properly you must provide some information about the nature of the
  52 data. RRDtool knows several different types of Data Sources (DS).
  53
  54 \begin{work}
  55   Read the rrdcreate manual page to identify the data source types
  56   and write down some examples for each type.
  57 \end{work}
  58
  59 \ex{Data Consolidation Methods}
  60
  61 Once you have passed data on to RRDtool it gets stored in a data
  62 storage array (Round Robin Archive). Each RRD can contain several
  63 RRAs, working at different resolutions and using different data
  64 consolidation methods.
  65
  66 \begin{work}
  67   Find the different Data Consolidation methods currently supported in
  68   RRDtool. This information can be found in the RRD create manual
  69   page.
  70 \end{work}
  71
  72 \ex{Data Validation}
  73
  74 Storing invalid data can often be more of a problem than not storing
  75 anything at all. In order to help you ensure that only valid data gets
  76 into your Round Robin Database, RRDtool allows you to
  77 describe some properties of the data you intend to store. This allows
  78 RRDtool to throw out invalid input before it even enters the database.
  79
  80 \begin{work}
  81 Identify the parameters to setup these safeguards. This information
  82 can be found in the rrdcreate manual page.\end{work}
  83
  84 \ex{Database Setup}
  85
  86 Having solved the exercises up this point you are now ready to setup a
  87 Round Robin Database. Use the command line tool\\
  88 \cmd{rrdtool} to work your magic.
  89
  90 \begin{work}
  91   Create an RRD which accepts input from two COUNTER
  92   data sources. The data sources provide new data every 300 seconds on
  93   average. Allow for a maximal update interval of 600 seconds. The
  94   input from both data-sources will always be between zero and 35
  95   million.
  96
  97   The RRD should store the data for 24 hours at 5 minute resolution
  98   and for a month at one hour resolution. For the one hour resolution
  99   you want to keep both the average and the 5 minute maximum data.
 100
 101 \end{work}
 102
 103 Use \cmd{rrdtool info database.rrd} to see the structure of the rrd file you
 104 just created.
 105
 106 \ex{Coupling of Data Values}
 107
 108 All values stored in a single RRD must be updated synchronously. Also,
 109 it is not trivial to add new data-sources to an existing RRD or remove
 110 old ones. In most cases it is sensible to create a new RRD for each
 111 data source unless you know that they are tightly coupled.
 112
 113 \begin{work}
 114   Think of some data sources which are tightly coupled in the sense that
 115   they should be stored into the same RRD and of some which should NOT be
 116   stored in the same RRD.
 117 \end{work}
 118
 119 \newpage
 120 \section{RRD Update}
 121 \ex{The RRD Perl Interface}
 122
 123 The recommended way to interact with an RRD is to use some scripting
 124 language and an rrdtool language bindings. There are language bindings for
 125 perl, python, ruby, tcl, lua and many other languages available.
 126
 127 \begin{work}
 128 Convert the command line for creating the RRD from the last exercise
 129 in the previous section into a perl script.
 130 \end{work}
 131
 132 \ex{The Error Messages in Perl}
 133 The RRDs commands do not complain when you call them with invalid
 134 arguments. Normally they just get ignored. To catch errors you must
 135 actively look for them. This is done with the \cmd{RRDs::error}
 136 function. The behaviour of other bindings may differ.
 137
 138 \begin{work}
 139 Add error checking to your script and test it by providing the
 140 create command with invalid parameters.
 141 \end{work}
 142
 143 \newpage
 144 \ex{Feeding Data into an RRD}
 145 In \cmd{/proc/net/snmp} you can find some counters regarding the
 146 traffic of your workstation. This pseudo file contains new data each time you read it.
 147
 148 \begin{work}
 149   Use the data from this file to populate the RRD created in the previous
 150   exercise. Don't forget to add error checking to the update routine. Make
 151   sure you 'fake' the update time by stepping 5 minutes ahead everytime you
 152   update.
 153 \end{work}
 154
 155 Use \cmd{rrdtool dump file.rrd} what data is stored in the rrd file.
 156
 157 \ex{Data Re-Sampling}
 158
 159 RRDtool re-samples any data you feed it to the base interval you set for the
 160 database. This means, unless your data arrives exactly at the end of each
 161 interval, your original data will not be preserved. People NOT understanding
 162 how this works is one of the main toppics on the rrdtool mailinglist.
 163
 164 \begin{work}
 165 Get a grip on data resampling by creating a new rrd file and feeding it some
 166 test data to see how it handles the different cases.
 167 \end{work}
 168
 169 \newpage
 170 \section{Creating graphs}
 171
 172 Harvesting data and storing in RRDs alone won't help you get a
 173 promotion. What really interests people is getting graphs produced from
 174 this data.
 175
 176 \ex{Line Graphs}
 177
 178
 179 \begin{work}
 180 Use the graph function to create a graph representing the data
 181 stored in your RRD. To start, use only \cmd{DEF:...} and \cmd{LINE1:...}
 182 and \cmd{--end now+2day} parameters and have RRDtool
 183 auto-configure the rest.
 184 \end{work}
 185
 186 \ex{GPRINT Exercise}
 187 A RRD graph can also show numerical data.
 188
 189 \begin{work}
 190   Use the \cmd{GPRINT} argument to show the maximum 5 minute values of
 191   both data sources below the graph.
 192 \end{work}
 193
 194 \ex{A Stack Graph}
 195 Lets assume the data in the RRD represents traffic seen on two
 196 different web servers which share the load of a busy web site.
 197
 198 \begin{work}
 199   Use the \cmd{AREA:} and \cmd{:STACK} function to place the data from
 200   the first and second data-source on top of each other. This will
 201   show the traffic produced by each server on its own as well as the
 202   total traffic occurring on your web site.
 203 \end{work}
 204
 205 \ex{Using RPN Math}
 206
 207 The network traffic in /proc/net/snmp is in octets passed over the
 208 interface. Most people though will expect to see traffic data reported in
 209 bits instead of octets.
 210
 211 \begin{work}
 212 Use the \cmd{CDEF:} function to multiply your data by 8
 213 before graphing it.
 214 \end{work}
 215
 216 and while you are at it:
 217
 218 \begin{work}
 219 Create  conditional \cmd{CDEF}s to change the color of a line depending on the current value.
 220 before graphing it.
 221 \end{work}
 222
 223 \begin{work}
 224 Add two horizontal lines to the chart. One at the maximum value and the other at th $95\%$. Use the \cmd{VDEF} function for this.
 225 \ex{Smoothing}
 226
 227 Over the years, the number of functions supported by rrdtools RPN engine has
 228 grown considerably. Trending and smoothing functions have been incorporated.
 229
 230 \begin{work}
 231 For data that fluctuates widely, it may help to plot a moving average instead as this will make slow changes more obvious.
 232 Sample your the network traffic at 1 second interval and create a graph overlaying the original data with a 1 minute moving average.
 233 \end{work}
 234
 235 \ex{Data Selection}
 236
 237 You used the \cmd{DEF:} function to pull in data from an rrd file for graphing. The command supports several named parameters to better
 238 control the data that is read and to massage it to fit your needs.
 239
 240 \begin{work}
 241 Draw a chart where you overlay the current data with data from a previous interval for comparison.
 242 \end{work}
 243
 244 and while you are at it.
 245
 246 \begin{work}
 247 Instruct DEF to resample your input data at a lower resolution than the original data, to cause a staircase effect.
 248 \end{work}
 249
 250 \newpage
 251 \section{Advanced Exercises}
 252 \ex{Alter RRD Parameters}
 253 Some parameters of an existing RRD can be changed quite easily using
 254 the update command.
 255
 256 \begin{work}
 257 Use the update command to change the name of the two data sources in
 258 your RRD. Use dump to very that the changes were successful.
 259 \end{work}
 260
 261 \ex{Web Charting}
 262
 263 With browsers improving their abilities, rrdtools native charting abilities
 264 are not so important anymore. One might wish to draw his charts in the
 265 browser, using the \href{http://d3js.org/}{D3.js} library for example.
 266
 267 \begin{work}
 268 Use the \cmd{xport} function to extract chart data from an rrd file and create a chart using the d3 library.
 269 \end{work}
 270
 271 \ex{Examine an RRD}
 272
 273 If you are writing a frontend to RRDtool it might be necessary to
 274 find out about the configuration of an existing rrd file. The rrdinfo
 275 function helps you with this.
 276
 277 \begin{work}
 278   Use \texttt{info command} to fetch config data from an existing rrd
 279   and convert it into command line which you could supply to rrdtool
 280   create.
 281 \end{work}
 282
 283
 284 \end{document}
 285
 286
 287
 288