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        f\bfl\blu\bus\bsh\bhc\bca\bac\bch\bhe\bed\bd
  74                Flush the values for a specific RRD file from memory. Check
  75                rrdflushcached.
  76
  77        r\brr\brd\bdc\bcg\bgi\bi  This is a standalone tool for producing RRD graphs on the fly.
  78                Check rrdcgi.
  79
  80    H\bHO\bOW\bW D\bDO\bOE\bES\bS R\bRR\bRD\bDT\bTO\bOO\bOL\bL W\bWO\bOR\bRK\bK?\b?
  81        Data Acquisition
  82                When monitoring the state of a system, it is convenient to have
  83                the data available at a constant time interval. Unfortunately,
  84                you may not always be able to fetch data at exactly the time
  85                you want to. Therefore R\bRR\bRD\bDt\bto\boo\bol\bl lets you update the log file at
  86                any time you want. It will automatically interpolate the value
  87                of the data-source (D\bDS\bS) at the latest official time-slot
  88                (interval) and write this interpolated value to the log. The
  89                original value you have supplied is stored as well and is also
  90                taken into account when interpolating the next log entry.
  91
  92        Consolidation
  93                You may log data at a 1 minute interval, but you might also be
  94                interested to know the development of the data over the last
  95                year. You could do this by simply storing the data in 1 minute
  96                intervals for the whole year. While this would take
  97                considerable disk space it would also take a lot of time to
  98                analyze the data when you wanted to create a graph covering the
  99                whole year. R\bRR\bRD\bDt\bto\boo\bol\bl offers a solution to this problem through
 100                its data consolidation feature. When setting up an Round Robin
 101                Database (R\bRR\bRD\bD), you can define at which interval this
 102                consolidation should occur, and what consolidation function
 103                (C\bCF\bF) (average, minimum, maximum, total, last) should be used to
 104                build the consolidated values (see rrdcreate). You can define
 105                any number of different consolidation setups within one R\bRR\bRD\bD.
 106                They will all be maintained on the fly when new data is loaded
 107                into the R\bRR\bRD\bD.
 108
 109        Round Robin Archives
 110                Data values of the same consolidation setup are stored into
 111                Round Robin Archives (R\bRR\bRA\bA). This is a very efficient manner to
 112                store data for a certain amount of time, while using a known
 113                and constant amount of storage space.
 114
 115                It works like this: If you want to store 1'000 values in 5
 116                minute interval, R\bRR\bRD\bDt\bto\boo\bol\bl will allocate space for 1'000 data
 117                values and a header area. In the header it will store a pointer
 118                telling which slots (value) in the storage area was last
 119                written to. New values are written to the Round Robin Archive
 120                in, you guessed it, a round robin manner. This automatically
 121                limits the history to the last 1'000 values (in our example).
 122                Because you can define several R\bRR\bRA\bAs within a single R\bRR\bRD\bD, you
 123                can setup another one, for storing 750 data values at a 2 hour
 124                interval, for example, and thus keep a log for the last two
 125                months at a lower resolution.
 126
 127                The use of R\bRR\bRA\bAs guarantees that the R\bRR\bRD\bD does not grow over time
 128                and that old data is automatically eliminated. By using the
 129                consolidation feature, you can still keep data for a very long
 130                time, while gradually reducing the resolution of the data along
 131                the time axis.
 132
 133                Using different consolidation functions (C\bCF\bF) allows you to
 134                store exactly the type of information that actually interests
 135                you: the maximum one minute traffic on the LAN, the minimum
 136                temperature of your wine cellar, the total minutes of down
 137                time, etc.
 138
 139        Unknown Data
 140                As mentioned earlier, the R\bRR\bRD\bD stores data at a constant
 141                interval. Sometimes it may happen that no new data is available
 142                when a value has to be written to the R\bRR\bRD\bD. Data acquisition may
 143                not be possible for one reason or other. With R\bRR\bRD\bDt\bto\boo\bol\bl you can
 144                handle these situations by storing an _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* value into the
 145                database. The value '_\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b*' is supported through all the
 146                functions of the tool. When consolidating a data set, the
 147                amount of _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data values is accounted for and when a new
 148                consolidated value is ready to be written to its Round Robin
 149                Archive (R\bRR\bRA\bA), a validity check is performed to make sure that
 150                the percentage of unknown values in the data point is above a
 151                configurable level. If not, an _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* value will be written
 152                to the R\bRR\bRA\bA.
 153
 154        Graphing
 155                R\bRR\bRD\bDt\bto\boo\bol\bl allows you to generate reports in numerical and
 156                graphical form based on the data stored in one or several R\bRR\bRD\bDs.
 157                The graphing feature is fully configurable. Size, color and
 158                contents of the graph can be defined freely. Check rrdgraph for
 159                more information on this.
 160
 161        Aberrant Behavior Detection
 162                by Jake Brutlag
 163
 164                R\bRR\bRD\bDt\bto\boo\bol\bl provides the building blocks for near real-time
 165                aberrant behavior detection. These components include:
 166
 167                ·   An algorithm for predicting the value of a time series one
 168                    time step into the future.
 169
 170                ·   A measure of deviation between predicted and observed
 171                    values.
 172
 173                ·   A mechanism to decide if and when an observed value or
 174                    sequence of observed values is _\bt_\bo_\bo _\bd_\be_\bv_\bi_\ba_\bn_\bt from the
 175                    predicted value(s).
 176
 177                Here is a brief explanation of these components:
 178
 179                The Holt-Winters time series forecasting algorithm is an on-
 180                line (or incremental) algorithm that adaptively predicts future
 181                observations in a time series. Its forecast is the sum of three
 182                components: a baseline (or intercept), a linear trend over time
 183                (or slope), and a seasonal coefficient (a periodic effect, such
 184                as a daily cycle). There is one seasonal coefficient for each
 185                time point in the period (cycle). After a value is observed,
 186                each of these components is updated via exponential smoothing.
 187                This means that the algorithm "learns" from past values and
 188                uses them to predict the future. The rate of adaptation is
 189                governed by 3 parameters, alpha (intercept), beta (slope), and
 190                gamma (seasonal). The prediction can also be viewed as a
 191                smoothed value for the time series.
 192
 193                The measure of deviation is a seasonal weighted absolute
 194                deviation. The term _\bs_\be_\ba_\bs_\bo_\bn_\ba_\bl means deviation is measured
 195                separately for each time point in the seasonal cycle. As with
 196                Holt-Winters forecasting, deviation is predicted using the
 197                measure computed from past values (but only at that point in
 198                the seasonal cycle). After the value is observed, the algorithm
 199                learns from the observed value via exponential smoothing.
 200                Confidence bands for the observed time series are generated by
 201                scaling the sequence of predicted deviation values (we usually
 202                think of the sequence as a continuous line rather than a set of
 203                discrete points).
 204
 205                Aberrant behavior (a potential failure) is reported whenever
 206                the number of times the observed value violates the confidence
 207                bands meets or exceeds a specified threshold within a specified
 208                temporal window (e.g. 5 violations during the past 45 minutes
 209                with a value observed every 5 minutes).
 210
 211                This functionality is embedded in a set of related R\bRR\bRA\bAs\bs. In
 212                particular, a FAILURES R\bRR\bRA\bA logs potential failures. With these
 213                data you could, for example, use a front-end application to
 214                R\bRR\bRD\bDt\bto\boo\bol\bl to initiate real-time alerts.
 215
 216                For a detailed description on how to set this up, see
 217                rrdcreate.
 218
 219    R\bRE\bEM\bMO\bOT\bTE\bE C\bCO\bON\bNT\bTR\bRO\bOL\bL
 220        When you start R\bRR\bRD\bDt\bto\boo\bol\bl with the command line option '-\b-' it waits for
 221        input via standard input (STDIN). With this feature you can improve
 222        performance by attaching R\bRR\bRD\bDt\bto\boo\bol\bl to another process (MRTG is one
 223        example) through a set of pipes. Over these pipes R\bRR\bRD\bDt\bto\boo\bol\bl accepts the
 224        same arguments as on the command line and some special commands like
 225        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:
 226
 227           rrdtool help cd|mkdir|pwd|ls|quit
 228
 229        When a command is completed, RRDtool will print the string  '"OK"',
 230        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.
 231        Both values are the running totals of seconds since RRDtool was
 232        started. If an error occurs, a line of the form '"ERROR:" _\bD_\be_\bs_\bc_\br_\bi_\bp_\bt_\bi_\bo_\bn
 233        _\bo_\bf _\be_\br_\br_\bo_\br' will be printed instead. R\bRR\bRD\bDt\bto\boo\bol\bl will not abort, unless
 234        something really serious happens. If a w\bwo\bor\brk\bkd\bdi\bir\br is specified and the UID
 235        is 0, RRDtool will do a chroot to that workdir. If the UID is not 0,
 236        RRDtool only changes the current directory to w\bwo\bor\brk\bkd\bdi\bir\br.
 237
 238    R\bRR\bRD\bD S\bSe\ber\brv\bve\ber\br
 239        If you want to create a RRD-Server, you must choose a TCP/IP Service
 240        number and add them to _\b/_\be_\bt_\bc_\b/_\bs_\be_\br_\bv_\bi_\bc_\be_\bs like this:
 241
 242         rrdsrv      13900/tcp                       # RRD server
 243
 244        Attention: the TCP port 13900 isn't officially registered for rrdsrv.
 245        You can use any unused port in your services file, but the server and
 246        the client system must use the same port, of course.
 247
 248        With this configuration you can add RRDtool as meta-server to
 249        _\b/_\be_\bt_\bc_\b/_\bi_\bn_\be_\bt_\bd_\b._\bc_\bo_\bn_\bf. For example:
 250
 251         rrdsrv stream tcp nowait root /opt/rrd/bin/rrdtool rrdtool - /var/rrd
 252
 253        Don't forget to create the database directory /var/rrd and reinitialize
 254        your inetd.
 255
 256        If all was setup correctly, you can access the server with Perl
 257        sockets, tools like netcat, or in a quick interactive test by using
 258        'telnet localhost rrdsrv'.
 259
 260        N\bNO\bOT\bTE\bE:\b: that there is no authentication with this feature! Do not setup
 261        such a port unless you are sure what you are doing.
 262
 263 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
 264        For very big setups, updating thousands of RRD files often becomes a
 265        serious IO problem. If you run into such problems, you might want to
 266        take a look at rrdcached, a caching daemon for RRDtool which may help
 267        you lessen the stress on your disks.
 268
 269 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 270        rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune, rrdlast,
 271        rrdxport, rrdflushcached, rrdcached
 272
 273 B\bBU\bUG\bGS\bS
 274        Bugs? Features!
 275
 276 A\bAU\bUT\bTH\bHO\bOR\bR
 277        Tobias Oetiker <tobi@oetiker.ch>
 278
 279
 280
 281 1.4.8                             2013-05-23                        RRDTOOL(1)