doc/rrdtool.txt

   1 RRDTOOL(1)                          rrdtool                         RRDTOOL(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdtool - Round Robin Database Tool
   7
   8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   9        r\brr\brd\bdt\bto\boo\bol\bl -\b- [workdir]| _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn
  10
  11 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  12    O\bOV\bVE\bER\bRV\bVI\bIE\bEW\bW
  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 router. But
  16        it is not so trivial to store this data in an efficient and systematic
  17        manner. This is where R\bRR\bRD\bDt\bto\boo\bol\bl comes in handy. It lets you _\bl_\bo_\bg _\ba_\bn_\bd
  18        _\ba_\bn_\ba_\bl_\by_\bz_\be the data you gather from all kinds of data-sources (D\bDS\bS). The
  19        data analysis part of RRDtool is based on the ability to quickly
  20        generate graphical representations of the data values collected over a
  21        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 R\bRR\bRD\bDt\bto\boo\bol\bl
  26        check the corresponding man page.
  27
  28        For an introduction to the usage of RRDtool make sure you consult the
  29        rrdtutorial.
  30
  31    F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS
  32        While the man pages talk of command line switches you have to set in
  33        order to make R\bRR\bRD\bDt\bto\boo\bol\bl work it is important to note that R\bRR\bRD\bDt\bto\boo\bol\bl can be
  34        remotely controlled through a set of pipes. This saves a considerable
  35        amount of startup time when you plan to make R\bRR\bRD\bDt\bto\boo\bol\bl do a lot of things
  36        quickly. Check the section on Remote_Control further down. There is
  37        also a number of language bindings for RRDtool which allow you to use
  38        it directly from Perl, python, Tcl, PHP, etc.
  39
  40        c\bcr\bre\bea\bat\bte\be  Set up a new Round Robin Database (RRD). Check rrdcreate.
  41
  42        u\bup\bpd\bda\bat\bte\be  Store new data values into an RRD. Check rrdupdate.
  43
  44        u\bup\bpd\bda\bat\bte\bev\bv Operationally equivalent to u\bup\bpd\bda\bat\bte\be except for output. Check
  45                rrdupdate.
  46
  47        g\bgr\bra\bap\bph\bh   Create a graph from data stored in one or several RRDs. Apart
  48                from generating graphs, data can also be extracted to stdout.
  49                Check rrdgraph.
  50
  51        d\bdu\bum\bmp\bp    Dump the contents of an RRD in plain ASCII. In connection with
  52                restore you can use this to move an RRD from one computer
  53                architecture to another.  Check rrddump.
  54
  55        r\bre\bes\bst\bto\bor\bre\be Restore an RRD in XML format to a binary RRD. Check rrdrestore
  56
  57        f\bfe\bet\btc\bch\bh   Get data for a certain time period from a RRD. The graph
  58                function uses fetch to retrieve its data from an RRD. Check
  59                rrdfetch.
  60
  61        t\btu\bun\bne\be    Alter setup of an RRD. Check rrdtune.
  62
  63        l\bla\bas\bst\bt    Find the last update time of an RRD. Check rrdlast.
  64
  65        i\bin\bnf\bfo\bo    Get information about an RRD. Check rrdinfo.
  66
  67        r\brr\brd\bdr\bre\bes\bsi\biz\bze\be
  68                Change the size of individual RRAs. This is dangerous! Check
  69                rrdresize.
  70
  71        x\bxp\bpo\bor\brt\bt   Export data retrieved from one or several RRDs. Check rrdxport
  72
  73        r\brr\brd\bdc\bcg\bgi\bi  This is a standalone tool for producing RRD graphs on the fly.
  74                Check rrdcgi.
  75
  76    H\bHO\bOW\bW D\bDO\bOE\bES\bS R\bRR\bRD\bDT\bTO\bOO\bOL\bL W\bWO\bOR\bRK\bK?\b?
  77        Data Acquisition
  78                When monitoring the state of a system, it is convenient to have
  79                the data available at a constant time interval. Unfortunately,
  80                you may not always be able to fetch data at exactly the time
  81                you want to. Therefore R\bRR\bRD\bDt\bto\boo\bol\bl lets you update the logfile at
  82                any time you want. It will automatically interpolate the value
  83                of the data-source (D\bDS\bS) at the latest official time-slot
  84                (interval) and write this interpolated value to the log. The
  85                original value you have supplied is stored as well and is also
  86                taken into account when interpolating the next log entry.
  87
  88        Consolidation
  89                You may log data at a 1 minute interval, but you might also be
  90                interested to know the development of the data over the last
  91                year. You could do this by simply storing the data in 1 minute
  92                intervals for the whole year. While this would take
  93                considerable disk space it would also take a lot of time to
  94                analyze the data when you wanted to create a graph covering the
  95                whole year. R\bRR\bRD\bDt\bto\boo\bol\bl offers a solution to this problem through
  96                its data consolidation feature. When setting up an Round Robin
  97                Database (R\bRR\bRD\bD), you can define at which interval this
  98                consolidation should occur, and what consolidation function
  99                (C\bCF\bF) (average, minimum, maximum, total, last) should be used to
 100                build the consolidated values (see rrdcreate). You can define
 101                any number of different consolidation setups within one R\bRR\bRD\bD.
 102                They will all be maintained on the fly when new data is loaded
 103                into the R\bRR\bRD\bD.
 104
 105        Round Robin Archives
 106                Data values of the same consolidation setup are stored into
 107                Round Robin Archives (R\bRR\bRA\bA). This is a very efficient manner to
 108                store data for a certain amount of time, while using a known
 109                and constant amount of storage space.
 110
 111                It works like this: If you want to store 1'000 values in 5
 112                minute interval, R\bRR\bRD\bDt\bto\boo\bol\bl will allocate space for 1'000 data
 113                values and a header area. In the header it will store a pointer
 114                telling which slots (value) in the storage area was last
 115                written to. New values are written to the Round Robin Archive
 116                in, you guessed it, a round robin manner. This automatically
 117                limits the history to the last 1'000 values (in our example).
 118                Because you can define several R\bRR\bRA\bAs within a single R\bRR\bRD\bD, you
 119                can setup another one, for storing 750 data values at a 2 hour
 120                interval, for example, and thus keep a log for the last two
 121                months at a lower resolution.
 122
 123                The use of R\bRR\bRA\bAs guarantees that the R\bRR\bRD\bD does not grow over time
 124                and that old data is automatically eliminated. By using the
 125                consolidation feature, you can still keep data for a very long
 126                time, while gradually reducing the resolution of the data along
 127                the time axis.
 128
 129                Using different consolidation functions (C\bCF\bF) allows you to
 130                store exactly the type of information that actually interests
 131                you: the maximum one minute traffic on the LAN, the minimum
 132                temperature of your wine cellar, the total minutes of down
 133                time, etc.
 134
 135        Unknown Data
 136                As mentioned earlier, the R\bRR\bRD\bD stores data at a constant
 137                interval. Sometimes it may happen that no new data is available
 138                when a value has to be written to the R\bRR\bRD\bD. Data acquisition may
 139                not be possible for one reason or other. With R\bRR\bRD\bDt\bto\boo\bol\bl you can
 140                handle these situations by storing an _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* value into the
 141                database. The value '_\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b*' is supported through all the
 142                functions of the tool. When consolidating a data set, the
 143                amount of _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data values is accounted for and when a new
 144                consolidated value is ready to be written to its Round Robin
 145                Archive (R\bRR\bRA\bA), a validity check is performed to make sure that
 146                the percentage of unknown values in the data point is above a
 147                configurable level. If not, an _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* value will be written
 148                to the R\bRR\bRA\bA.
 149
 150        Graphing
 151                R\bRR\bRD\bDt\bto\boo\bol\bl allows you to generate reports in numerical and
 152                graphical form based on the data stored in one or several R\bRR\bRD\bDs.
 153                The graphing feature is fully configurable. Size, color and
 154                contents of the graph can be defined freely. Check rrdgraph for
 155                more information on this.
 156
 157        Aberrant Behavior Detection
 158                by Jake Brutlag
 159
 160                R\bRR\bRD\bDt\bto\boo\bol\bl provides the building blocks for near real-time
 161                aberrant behavior detection. These components include:
 162
 163                ·   An algorithm for predicting the value of a time series one
 164                    time step into the future.
 165
 166                ·   A measure of deviation between predicted and observed
 167                    values.
 168
 169                ·   A mechanism to decide if and when an observed value or
 170                    sequence of observed values is _\bt_\bo_\bo _\bd_\be_\bv_\bi_\ba_\bn_\bt from the
 171                    predicted value(s).
 172
 173                Here is a brief explanation of these components:
 174
 175                The Holt-Winters time series forecasting algorithm is an on-
 176                line (or incremental) algorithm that adaptively predicts future
 177                observations in a time series. Its forecast is the sum of three
 178                components: a baseline (or intercept), a linear trend over time
 179                (or slope), and a seasonal coefficient (a periodic effect, such
 180                as a daily cycle). There is one seasonal coefficient for each
 181                time point in the period (cycle). After a value is observed,
 182                each of these components is updated via exponential smoothing.
 183                This means that the algorithm "learns" from past values and
 184                uses them to predict the future. The rate of adaptation is
 185                governed by 3 parameters, alpha (intercept), beta (slope), and
 186                gamma (seasonal). The prediction can also be viewed as a
 187                smoothed value for the time series.
 188
 189                The measure of deviation is a seasonal weighted absolute
 190                deviation. The term _\bs_\be_\ba_\bs_\bo_\bn_\ba_\bl means deviation is measured
 191                separately for each time point in the seasonal cycle. As with
 192                Holt-Winters forecasting, deviation is predicted using the
 193                measure computed from past values (but only at that point in
 194                the seasonal cycle). After the value is observed, the algorithm
 195                learns from the observed value via exponential smoothing.
 196                Confidence bands for the observed time series are generated by
 197                scaling the sequence of predicted deviation values (we usually
 198                think of the sequence as a continuous line rather than a set of
 199                discrete points).
 200
 201                Aberrant behavior (a potential failure) is reported whenever
 202                the number of times the observed value violates the confidence
 203                bands meets or exceeds a specified threshold within a specified
 204                temporal window (e.g. 5 violations during the past 45 minutes
 205                with a value observed every 5 minutes).
 206
 207                This functionality is embedded in a set of related R\bRR\bRA\bAs\bs. In
 208                particular, a FAILURES R\bRR\bRA\bA logs potential failures. With these
 209                data you could, for example, use a front-end application to
 210                R\bRR\bRD\bDt\bto\boo\bol\bl to initiate real-time alerts.
 211
 212                For a detailed description on how to set this up, see
 213                rrdcreate.
 214
 215    R\bRE\bEM\bMO\bOT\bTE\bE C\bCO\bON\bNT\bTR\bRO\bOL\bL
 216        When you start R\bRR\bRD\bDt\bto\boo\bol\bl with the command line option '-\b-' it waits for
 217        input via standard input (STDIN). With this feature you can improve
 218        performance by attaching R\bRR\bRD\bDt\bto\boo\bol\bl to another process (MRTG is one
 219        example) through a set of pipes. Over these pipes R\bRR\bRD\bDt\bto\boo\bol\bl accepts the
 220        same arguments as on the command line and some special commands like
 221        q\bqu\bui\bit\bt,\b, c\bcd\bd,\b, m\bmk\bkd\bdi\bir\br and l\bls\bs. For detailed help on the server commands type:
 222
 223           rrdtool help cd|mkdir|pwd|ls|quit
 224
 225        When a command is completed, RRDtool will print the string  '"OK"',
 226        followed by timing information of the form u\bu:\b:_\bu_\bs_\be_\br_\bt_\bi_\bm_\be s\bs:\b:_\bs_\by_\bs_\bt_\be_\bm_\bt_\bi_\bm_\be.
 227        Both values are the running totals of seconds since RRDtool was
 228        started. If an error occurs, a line of the form '"ERROR:" _\bD_\be_\bs_\bc_\br_\bi_\bp_\bt_\bi_\bo_\bn
 229        _\bo_\bf _\be_\br_\br_\bo_\br' will be printed instead. R\bRR\bRD\bDt\bto\boo\bol\bl will not abort, unless
 230        something really serious happens. If a w\bwo\bor\brk\bkd\bdi\bir\br is specified and the UID
 231        is 0, RRDtool will do a chroot to that workdir. If the UID is not 0,
 232        RRDtool only changes the current directory to w\bwo\bor\brk\bkd\bdi\bir\br.
 233
 234    R\bRR\bRD\bD S\bSe\ber\brv\bve\ber\br
 235        If you want to create a RRD-Server, you must choose a TCP/IP Service
 236        number and add them to _\b/_\be_\bt_\bc_\b/_\bs_\be_\br_\bv_\bi_\bc_\be_\bs like this:
 237
 238         rrdsrv      13900/tcp                       # RRD server
 239
 240        Attention: the TCP port 13900 isn't officially registered for rrdsrv.
 241        You can use any unused port in your services file, but the server and
 242        the client system must use the same port, of course.
 243
 244        With this configuration you can add RRDtool as meta-server to
 245        _\b/_\be_\bt_\bc_\b/_\bi_\bn_\be_\bt_\bd_\b._\bc_\bo_\bn_\bf. For example:
 246
 247         rrdsrv stream tcp nowait root /opt/rrd/bin/rrdtool rrdtool - /var/rrd
 248
 249        Don't forget to create the database directory /var/rrd and reinitialize
 250        your inetd.
 251
 252        If all was setup correctly, you can access the server with Perl
 253        sockets, tools like netcat, or in a quick interactive test by using
 254        'telnet localhost rrdsrv'.
 255
 256        N\bNO\bOT\bTE\bE:\b: that there is no authentication with this feature! Do not setup
 257        such a port unless you are sure what you are doing.
 258
 259 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 260        rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune, rrdlast,
 261        rrdxport
 262
 263 B\bBU\bUG\bGS\bS
 264        Bugs? Features!
 265
 266 A\bAU\bUT\bTH\bHO\bOR\bR
 267        Tobias Oetiker <tobi@oetiker.ch>
 268
 269
 270
 271 1.3.8                             2008-12-22                        RRDTOOL(1)