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