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