doc/rrdtool.pod

   1 =head1 NAME
   2
   3 rrdtool - round robin database tool
   4
   5 =for html <div align="right"><a href="rrdtool.pdf">PDF</a> version.</div>
   6
   7 =head1 SYNOPSIS
   8
   9 B<rrdtool> B<-> [workdir]| I<function>
  10
  11 =head1 DESCRIPTION
  12
  13 =head2 OVERVIEW
  14
  15 It is pretty easy to gather status information from all sorts of
  16 things, ranging from the temperature in your office to the number of
  17 octets which have passed through the FDDI interface of your
  18 router. But it is not so trivial to store this data in a efficient and
  19 systematic manner. This is where B<rrdtool> kicks in. It lets you
  20 I<log and analyze> the data you gather from all kinds of data-sources
  21 (B<DS>). The data analysis part of rrdtool is based on the ability to
  22 quickly generate graphical representations of the data values
  23 collected over a definable time period.
  24
  25 In this man page you will find general information on the design and
  26 functionality of the Round Robin Database Tool (rrdtool). For a more
  27 detailed description of how to use the individual functions of the
  28 B<rrdtool> check the corresponding man page.
  29
  30 For an introduction to the usage of rrdtool make sure you check L<rrdtutorial>.
  31
  32 =head2 FUNCTIONS
  33
  34 While the man pages talk of command line switches you have to set in
  35 order to make B<rrdtool> work it is important to note that the
  36 B<rrdtool> can be 'remote controlled' through a set of pipes. This
  37 saves a considerable amount of startup time when you plan to make
  38 B<rrdtool> do a lot of things quickly. Check the section on L<"Remote
  39 Control"> further down. There is also a number of language bindings
  40 for rrdtool which allow you to use it directly from perl, python, tcl,
  41 php, ...
  42
  43 =over 8
  44
  45 =item B<create>
  46
  47 Set up a new Round Robin Database (RRD). Check L<rrdcreate>.
  48
  49 =item B<update>
  50
  51 Store new data values into an RRD. Check L<rrdupdate>.
  52
  53 =item B<graph>
  54
  55 Create a graph from data stored in one or several RRD. Apart from
  56 generating graphs, data can also be extracted to stdout. Check L<rrdgraph>.
  57
  58 =item B<dump>
  59
  60 Dump the contents of an RRD in plain ASCII. In connection with
  61 restore you can use it to transport an rrd from one architecture to another.
  62 Check L<rrddump>.
  63
  64 =item B<restore>
  65
  66 Restore an RRD in XML format to a binary rrd ... Check L<rrdrestore>
  67
  68 =item B<fetch>
  69
  70 Get data for a certain time period from a RRD. The graph function
  71 uses fetch to retrieve its data from an rrd. Check L<rrdfetch>.
  72
  73 =item B<tune>
  74
  75 Alter setup of an RRD. Check L<rrdtune>.
  76
  77 =item B<last>
  78
  79 Find last update time of an RRD. Check L<rrdlast>.
  80
  81 =item B<rrdresize>
  82
  83 Change the size of individual RRAs ... Dangerous! Check L<rrdresize>.
  84
  85 =item B<xport>
  86
  87 Export data retrieved from one or several RRD. Check L<rrdxport>
  88
  89 =item B<rrdcgi>
  90
  91 This is a standalone tool for producing rrd graphs on the fly. Check
  92 L<rrdcgi>.
  93
  94 =back
  95
  96 =head2 HOW DOES RRDTOOL WORK?
  97
  98 =over 8
  99
 100 =item Data acquisition
 101
 102 When monitoring the state of a system, it is convenient to have the
 103 data available at a constant interval. Unfortunately you may not
 104 always be able to fetch data at exactly the time you want
 105 to. Therefore B<rrdtool> lets you update the logfile at any time you
 106 want. It will automatically interpolate the value of the data-source
 107 (B<DS>) at the latest official time-slot and write this value to the
 108 log. The value you have supplied is stored as well and is also taken
 109 into account when interpolating the next log entry.
 110
 111 =item Consolidation
 112
 113 You may log data at a 1 minute interval, but you are also be
 114 interested to know the development of the data over the last year. You
 115 could do this by simply storing the data in 1 minute interval, for one
 116 year. While this would take considerable disk space it would also take
 117 a lot of time to analyze the data when you wanted to create a graph
 118 covering the whole year. B<rrdtool> offers a solution to this of this
 119 problem through its data consolidation feature. When setting up
 120 an Round Robin Database (B<RRD>), you can define at which interval
 121 this consolidation should occur, and what consolidation function
 122 (B<CF>) (average, minimum, maximum, total, last) should be used to
 123 build the consolidated values (see rrdcreate). You can define any
 124 number of different consolidation setups within one B<RRD>. They will
 125 all be maintained on the fly when new data is loaded into the B<RRD>.
 126
 127 =item Round Robin Archives
 128
 129 Data values of the same consolidation setup are stored into Round
 130 Robin Archives (B<RRA>). This is a very efficient manner to store data
 131 for a certain amount of time, while using a known amount of storage
 132 space.
 133
 134 It works like this: If you want to store 1000 values in 5 minute
 135 interval, B<rrdtool> will allocate space for 1000 data values and a
 136 header area. In the header it will store a pointer telling
 137 which one of the values in the storage area was last written to. New
 138 values are written to the Round Robin Archive in a ...  you guess it
 139 ... round robin manner. This automatically limits the history to the last
 140 1000 values. Because you can define several B<RRA>s within a single B<RRD>,
 141 you can setup another one, storing 750 data values at a 2 hour interval
 142 and thus keeping a log for the last two months although at a lower
 143 resolution.
 144
 145 The use of B<RRA>s guarantees that the B<RRD> does not grow over
 146 time and that old data is automatically eliminated. By using the
 147 consolidation feature, you can still keep data for a very long time,
 148 while gradually reducing the resolution of the data along the time
 149 axis. Using different consolidation functions (B<CF>) allows you to
 150 store exactly the type of information that actually interests
 151 you. (Maximum one minute traffic on the LAN, minimum temperature of
 152 the wine cellar, total minutes down time ...)
 153
 154 =item Unknown Data
 155
 156 As mentioned earlier, the B<RRD> stores data at a constant
 157 interval. Now it may happen that no new data is available when a
 158 value has to be written to the B<RRD>. Data acquisition may not be
 159 possible for one reason or an other. The B<rrdtool> handles these
 160 situations by storing an I<*UNKNOWN*> value into the database. The
 161 value 'I<*UNKNOWN*>' is supported through all the functions of the
 162 database. When consolidating the amount of I<*UNKNOWN*> data is
 163 accumulated and when a new consolidated value is ready to be written
 164 to its Round Robin Archive (B<RRA>) a validity check is performed to
 165 make sure that the percentage of unknown data in the new value is
 166 below a configurable level. If so, an I<*UNKNOWN*> value will be
 167 written to the B<RRA>.
 168
 169 =item Graphing
 170
 171 The B<rrdtool> also allows one to generate reports in numerical and
 172 graphical form based on the data stored in one or several
 173 B<RRD>s. The graphing feature is fully configurable. Size, color and
 174 contents of the graph can be defined freely. Check L<rrdgraph>
 175 for more information on this.
 176
 177 =item Aberrant Behavior Detection
 178
 179 by Jake Brutlag E<lt>jakeb@corp.webtv.netE<gt>
 180
 181 The  B<rrdtool> also provides the building blocks for near real-time
 182 aberrant behavior detection. These components include:
 183
 184 =over 12
 185
 186 =item *
 187
 188 An algorithm for predicting the values time series one time step into the future.
 189
 190 =item *
 191
 192 A measure of deviation between the predicted values and the observed values.
 193
 194 =item *
 195
 196 A mechanism to decide if and when an observed value
 197 or sequence of observed values is I<too deviant> from the predicted value(s).
 198
 199 =back
 200
 201 Each of these components is briefly described:
 202
 203 Holt-Winters Time Series Forecasting Algorithm is an online, or incremental,
 204 algorithm that adaptively predicts future observations in a time series. It's
 205 forecast is the sum of three components: a baseline (or intercept), a linear
 206 trend over time (or slope), and a seasonal coefficient (a periodic effect,
 207 such as a daily cycle). There is one seasonal coefficient for each time point
 208 in the period (cycle). After a value is observed, each of these components is
 209 updated via exponential smoothing. So the algorithm learns from past values
 210 and uses them to predict the future. The rate of adaptation is governed by
 211 3 parameters, alpha (intercept), beta (slope), and gamma (seasonal). The prediction
 212 can also be viewed as a smoothed value for the time series.
 213
 214 The measure of deviation is a seasonal weighted absolute deviation. The term
 215 I<seasonal> means deviation is measured separately for each time point in the
 216 seasonal cycle. As with Holt-Winters Forecasting, deviation is predicted using
 217 the measure computed from past values (but only at that point in the seasonal cycle).
 218 After the value is observed, the algorithm learns from the observed value via
 219 exponential smoothing. Confidence bands for the observed time series are generated
 220 by scaling the sequence of predicted deviation values (we usually think of the sequence
 221 as a continuous line rather than a set of discrete points).
 222
 223 Aberrant behavior (a potential failure) is reported whenever the number of
 224 times the observed value violates the confidence bands meets or exceeds a
 225 specified threshold within a specified temporal window (i.e. 5 violations
 226 during the past 45 minutes with a value observed every 5 mintues).
 227
 228 This functionality is embedded in a set of related B<RRAs>. In particular, a FAILURES
 229 B<RRA> logs potential failures. Presumably a front-end application to B<rrdtool> can
 230 utilize this B<RRA> to initiate real-time alerts if that is desired.
 231
 232 You can find a detailed description of how to set this up in L<rrdcreate>.
 233
 234 =back
 235
 236 =head2 REMOTE CONTROL
 237
 238 When you start B<rrdtool> with the command line option 'B<->', it waits
 239 for input via standard in. With this feature you can improve
 240 performance by attaching B<rrdtool> to another process (mrtg is one
 241 example) through a set of pipes. Over the pipes B<rrdtool> accepts the
 242 same arguments as on the command line and some spezial commands like
 243 B<quit, cd, mkdir> and B<ls>. For detail helps about the server commands
 244 type :
 245
 246    rrdtool help cd|mkdir|ls|quit
 247
 248 When a command is completed, rrdtool will print the string  'C<OK>',
 249 followed by timing information of the form B<u:>I<usertime>
 250 B<s:>I<systemtime> both values are running totals of seconds
 251 since rrdtool was started. If an error occurs, a line of the
 252 form 'C<ERROR:> I<Description of error>' will be printed. B<rrdtool>
 253 will not abort if possible, but follow the ERROR line with an OK line.
 254 If a B<workdir> is spezified and the UID is 0, rrdtool will do a
 255 chroot to the workdir. If the UID is not 0, rrdtool only changes the
 256 current directory to B<workdir>.
 257
 258 =head2 RRD Server
 259
 260 If you want to create a RRD-Server, you must choose a TCP/IP Service
 261 number and add them to I</etc/services> like this:
 262
 263  rrdsrv      13900/tcp                       # rrd server
 264
 265 Attention: the tcp port 13900 isn't official registered for rrdsrv. You
 266 can use any unused port in your services, but the server an the client
 267 system must use the same port of curse.
 268 After this you can add the rrdtool as meta-server to I</etc/inetd.conf>
 269 for example:
 270
 271  rrdsrv stream tcp nowait root /opt/rrd/bin/rrdtool rrdtool - /var/rrd
 272
 273 Don't forget to create the database directory /var/rrd and reinitialize
 274 your inetd.
 275 If all was correct, you can access the server with perl sockets, tools
 276 like netcat or a quickhack test 'telnet localhost rrdsrv'.
 277
 278
 279
 280 =head1 SEE ALSO
 281
 282 rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune, rrdlast, rrdxport
 283
 284 =head1 BUGS
 285
 286 Bugs ? Features !
 287
 288 =head1 AUTHOR
 289
 290 Tobias Oetiker <oetiker@ee.ethz.ch>
 291