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 not found in this document.
  32 There are sever main sources from where you can
  33 acquire this information readily.
  34
  35 \begin{itemize}
  36 \item Me (at least today).
  37 \item The \href{http://oss.oetiker.ch/rrdtool}{rrdtool web site}.
  38 \item The rrdtool source on \url{github.com/oetiker/rrdtool-1.x}.
  39 \end{itemize}
  40
  41 Playing with RRDtool works best when you have some sample data to play with.
  42 You can find some on \url{github.com/oetiker/rrdtool-1.x/t/data}.
  43
  44 \newpage
  45 \section{Creating an RRD}
  46 \ex{Data Source Types}
  47
  48 RRDtool stores and graphs numerical data. 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 rrdcreate 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
  99 \end{work}
 100
 101 Use \cmd{rrdtool info database.rrd} to see the structure of the rrd file you
 102 just created.
 103
 104 \ex{Coupling of Data Values}
 105
 106 All values stored in a single RRD must be updated synchronously. Also,
 107 it is not trivial to add new data-sources to an existing RRD or remove
 108 old ones. In most cases it is sensible to create a new RRD for each
 109 data source unless you know that they are tightly coupled.
 110
 111 \begin{work}
 112   Think of some data sources which are tightly coupled in the sense that
 113   they should be stored into the same RRD and of some which should NOT be
 114   stored in the same RRD.
 115 \end{work}
 116
 117 \newpage
 118 \section{RRD Update}
 119 \ex{The RRD Perl Interface}
 120
 121 The recommended way to interact with an RRD is to use some scripting
 122 language and an rrdtool language bindings. There are language bindings for
 123 perl, python, ruby, tcl, lua and many other languages available.
 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. The behaviour of other bindings may differ.
 135
 136 \begin{work}
 137 Add error checking to your script and test it by providing the
 138 create command with invalid parameters.
 139 \end{work}
 140
 141 \newpage
 142 \ex{Feeding Data into an RRD}
 143 In \cmd{/proc/net/snmp} you can find some counters regarding the
 144 traffic of your workstation. This pseudo file contains new data each time you read it.
 145
 146 \begin{work}
 147   Use the data from this file to populate the RRD created in the previous
 148   exercise. Don't forget to add error checking to the update routine. Make
 149   sure you 'fake' the update time by stepping 5 minutes ahead every time you
 150   update.
 151 \end{work}
 152
 153 Use \cmd{rrdtool dump file.rrd} what data is stored in the rrd file.
 154
 155 \ex{Data Re-Sampling}
 156
 157 RRDtool re-samples any data you feed it to the base interval you set for the
 158 database. This means, unless your data arrives exactly at the end of each
 159 interval, your original data will not be preserved. People NOT understanding
 160 how this works is one of the main topics on the rrdtool mailing list.
 161
 162 \begin{work}
 163 Get a grip on data re-sampling by creating a new rrd file and feeding it some
 164 test data to see how it handles the different cases.
 165 \end{work}
 166
 167 \newpage
 168 \section{Creating graphs}
 169
 170 Harvesting data and storing in RRDs alone won't help you get a
 171 promotion. What really interests people is getting graphs produced from
 172 this data.
 173
 174 \ex{Line Graphs}
 175
 176
 177 \begin{work}
 178 Use the graph function to create a graph representing the data
 179 stored in your RRD. To start, use only \cmd{DEF:...} and \cmd{LINE1:...}
 180 and \cmd{--end now+2day} parameters and have RRDtool
 181 auto-configure the rest.
 182 \end{work}
 183
 184 \ex{GPRINT Exercise}
 185 A RRD graph can also show numerical data.
 186
 187 \begin{work}
 188   Use the \cmd{GPRINT} argument to show the maximum 5 minute values of
 189   both data sources below the graph.
 190 \end{work}
 191
 192 \ex{A Stack Graph}
 193 Lets assume the data in the RRD represents traffic seen on two
 194 different web servers which share the load of a busy web site.
 195
 196 \begin{work}
 197   Use the \cmd{AREA:} function and \cmd{:STACK} option to place the data from
 198   the first and second data-source on top of each other. This will
 199   show the traffic produced by each server on its own as well as the
 200   total traffic occurring on your web site.
 201 \end{work}
 202
 203 \ex{Using RPN Math}
 204
 205 The network traffic in /proc/net/snmp is in octets passed over the
 206 interface. Most people though will expect to see traffic data reported in
 207 bits instead of octets.
 208
 209 \begin{work}
 210 Use the \cmd{CDEF:} function to multiply your data by 8
 211 before graphing it.
 212 \end{work}
 213
 214 and while you are at it:
 215
 216 \begin{work}
 217 Create  conditional \cmd{CDEF}s to change the color of a line depending on the current value.
 218 before graphing it.
 219 \end{work}
 220
 221 \begin{work}
 222 Add two horizontal lines to the chart. One at the maximum value and the other at the $95\%$. Use the \cmd{VDEF} function for this.
 223 \end{work}
 224
 225
 226 \ex{Smoothing}
 227
 228 Over the years, the number of functions supported by rrdtools RPN engine has
 229 grown considerably. Trending and smoothing functions have been incorporated.
 230
 231 \begin{work}
 232 For data that fluctuates widely, it may help to plot a moving average instead as this will make slow changes more obvious.
 233 Sample your the network traffic at 1 second interval and create a graph overlaying the original data with a 1 minute moving average.
 234 \end{work}
 235
 236 \ex{Data Selection}
 237
 238 You used the \cmd{DEF:} function to pull in data from an rrd file for graphing. The command supports several named parameters to better
 239 control the data that is read and to massage it to fit your needs.
 240
 241 \begin{work}
 242 Draw a chart where you overlay the current data with data from a previous interval for comparison.
 243 \end{work}
 244
 245 and while you are at it.
 246
 247 \begin{work}
 248 Instruct DEF to re-sample your input data at a lower resolution than the original data, to cause a staircase effect.
 249 \end{work}
 250
 251 \newpage
 252 \section{Advanced Exercises}
 253 \ex{Compiling RRDtool Master}
 254
 255 RRDtool is developed in the open. When hunting down bugs or to test the latest features, it is helpful to be able to compile a copy yourself.
 256
 257 \begin{work}
 258 Clone the rrdtool github repo, checkout the master branch run autogen and compile your own copy of the latest rrdtool version.
 259 \end{work}
 260
 261 \ex{Alter RRD Parameters}
 262 Some parameters of an existing RRD can be changed quite easily using
 263 the update command.
 264
 265 \begin{work}
 266 Use the update command to change the name of the two data sources in
 267 your RRD. Use dump to very that the changes were successful.
 268 \end{work}
 269
 270 \ex{Web Charting}
 271
 272 With browsers improving their abilities, rrdtools native charting abilities
 273 are not so important anymore. One might wish to draw his charts in the
 274 browser, using the \href{http://d3js.org/}{D3.js} library or one of the charting libraries based on it like Rickshaw or Nvd3.
 275
 276 \begin{work}
 277 Use the \cmd{xport} function to extract chart data from an rrd file and create a chart using the d3 library.
 278 \end{work}
 279
 280 \ex{Examine an RRD}
 281
 282 If you are writing a front end to RRDtool it might be necessary to
 283 find out about the configuration of an existing rrd file. The rrdinfo
 284 function helps you with this.
 285
 286 \begin{work}
 287   Use \texttt{info command} to fetch config data from an existing rrd
 288   and convert it into command line which you could supply to rrdtool
 289   create.
 290 \end{work}
 291
 292
 293 \end{document}
 294
 295
 296
 297