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