doc/rrdtool.pod

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