


     RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))             1111....2222....11113333 ((((2222000000006666----00005555----00004444))))             RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))



     NNNNAAAAMMMMEEEE
          rrdtool - Round Robin Database Tool

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          rrrrrrrrddddttttoooooooollll ---- [workdir]| _f_u_n_c_t_i_o_n

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW

          It is pretty easy to gather status information from all
          sorts of things, ranging from the temperature in your office
          to the number of octets which have passed through the FDDI
          interface of your router. But it is not so trivial to store
          this data in an efficient and systematic manner. This is
          where RRRRRRRRDDDDttttoooooooollll comes in handy. It lets you _l_o_g _a_n_d _a_n_a_l_y_z_e
          the data you gather from all kinds of data-sources (DDDDSSSS). The
          data analysis part of RRDtool is based on the ability to
          quickly generate graphical representations of the data
          values collected over a definable time period.

          In this man page you will find general information on the
          design and functionality of the Round Robin Database Tool
          (RRDtool). For a more detailed description of how to use the
          individual functions of RRRRRRRRDDDDttttoooooooollll check the corresponding man
          page.

          For an introduction to the usage of RRDtool make sure you
          consult the rrdtutorial.

          FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS

          While the man pages talk of command line switches you have
          to set in order to make RRRRRRRRDDDDttttoooooooollll work it is important to note
          that RRRRRRRRDDDDttttoooooooollll can be remotely controlled through a set of
          pipes. This saves a considerable amount of startup time when
          you plan to make RRRRRRRRDDDDttttoooooooollll do a lot of things quickly. Check
          the section on "Remote Control" further down. There is also
          a number of language bindings for RRDtool which allow you to
          use it directly from perl, python, tcl, php, etc.

          ccccrrrreeeeaaaatttteeee  Set up a new Round Robin Database (RRD). Check
                  rrdcreate.

          uuuuppppddddaaaatttteeee  Store new data values into an RRD. Check rrdupdate.

          uuuuppppddddaaaatttteeeevvvv Operationally equivalent to uuuuppppddddaaaatttteeee except for
                  output. Check rrdupdate.

          ggggrrrraaaapppphhhh   Create a graph from data stored in one or several
                  RRDs. Apart from generating graphs, data can also be
                  extracted to stdout. Check rrdgraph.




     Page 1                                          (printed 6/13/06)






     RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))             1111....2222....11113333 ((((2222000000006666----00005555----00004444))))             RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))



          dddduuuummmmpppp    Dump the contents of an RRD in plain ASCII. In
                  connection with restore you can use this to move an
                  RRD from one computer architecture to another.
                  Check rrddump.

          rrrreeeessssttttoooorrrreeee Restore an RRD in XML format to a binary RRD. Check
                  rrdrestore

          ffffeeeettttcccchhhh   Get data for a certain time period from a RRD. The
                  graph function uses fetch to retrieve its data from
                  an RRD. Check rrdfetch.

          ttttuuuunnnneeee    Alter setup of an RRD. Check rrdtune.

          llllaaaasssstttt    Find the last update time of an RRD. Check rrdlast.

          iiiinnnnffffoooo    Get information about an RRD. Check rrdinfo.

          rrrrrrrrddddrrrreeeessssiiiizzzzeeee
                  Change the size of individual RRAs. This is
                  dangerous! Check rrdresize.

          xxxxppppoooorrrrtttt   Export data retrieved from one or several RRDs.
                  Check rrdxport

          rrrrrrrrddddccccggggiiii  This is a standalone tool for producing RRD graphs
                  on the fly. Check rrdcgi.

          HHHHOOOOWWWW DDDDOOOOEEEESSSS RRRRRRRRDDDDTTTTOOOOOOOOLLLL WWWWOOOORRRRKKKK????

          Data Acquisition
                  When monitoring the state of a system, it is
                  convenient to have the data available at a constant
                  time interval. Unfortunately, you may not always be
                  able to fetch data at exactly the time you want to.
                  Therefore RRRRRRRRDDDDttttoooooooollll lets you update the logfile at any
                  time you want. It will automatically interpolate the
                  value of the data-source (DDDDSSSS) at the latest official
                  time-slot (intervall) and write this interpolated
                  value to the log. The original value you have
                  supplied is stored as well and is also taken into
                  account when interpolating the next log entry.

          Consolidation
                  You may log data at a 1 minute interval, but you
                  might also be interested to know the development of
                  the data over the last year. You could do this by
                  simply storing the data in 1 minute intervals for
                  the whole year. While this would take considerable
                  disk space it would also take a lot of time to
                  analyze the data when you wanted to create a graph
                  covering the whole year. RRRRRRRRDDDDttttoooooooollll offers a solution



     Page 2                                          (printed 6/13/06)






     RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))             1111....2222....11113333 ((((2222000000006666----00005555----00004444))))             RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))



                  to this problem through its data consolidation
                  feature. When setting up an Round Robin Database
                  (RRRRRRRRDDDD), you can define at which interval this
                  consolidation should occur, and what consolidation
                  function (CCCCFFFF) (average, minimum, maximum, total,
                  last) should be used to build the consolidated
                  values (see rrdcreate). You can define any number of
                  different consolidation setups within one RRRRRRRRDDDD. They
                  will all be maintained on the fly when new data is
                  loaded into the RRRRRRRRDDDD.

          Round Robin Archives
                  Data values of the same consolidation setup are
                  stored into Round Robin Archives (RRRRRRRRAAAA). This is a
                  very efficient manner to store data for a certain
                  amount of time, while using a known and constant
                  amount of storage space.

                  It works like this: If you want to store 1'000
                  values in 5 minute interval, RRRRRRRRDDDDttttoooooooollll will allocate
                  space for 1'000 data values and a header area. In
                  the header it will store a pointer telling which
                  slots (value) in the storage area was last written
                  to. New values are written to the Round Robin
                  Archive in, you guessed it, a round robin manner.
                  This automatically limits the history to the last
                  1'000 values (in our example). Because you can
                  define several RRRRRRRRAAAAs within a single RRRRRRRRDDDD, you can
                  setup another one, for storing 750 data values at a
                  2 hour interval, for example, and thus keep a log
                  for the last two months at a lower resolution.

                  The use of RRRRRRRRAAAAs guarantees that the RRRRRRRRDDDD does not
                  grow over time and that old data is automatically
                  eliminated. By using the consolidation feature, you
                  can still keep data for a very long time, while
                  gradually reducing the resolution of the data along
                  the time axis.

                  Using different consolidation functions (CCCCFFFF) allows
                  you to store exactly the type of information that
                  actually interests you: the maximum one minute
                  traffic on the LAN, the minimum temperature of your
                  wine cellar, the total minutes of down time, etc.

          Unknown Data
                  As mentioned earlier, the RRRRRRRRDDDD stores data at a
                  constant interval. Sometimes it may happen that no
                  new data is available when a value has to be written
                  to the RRRRRRRRDDDD. Data acquisition may not be possible for
                  one reason or other. With RRRRRRRRDDDDttttoooooooollll you can handle
                  these situations by storing an *_U_N_K_N_O_W_N* value into



     Page 3                                          (printed 6/13/06)






     RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))             1111....2222....11113333 ((((2222000000006666----00005555----00004444))))             RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))



                  the database. The value '*_U_N_K_N_O_W_N*' is supported
                  through all the functions of the tool. When
                  consolidating a data set, the amount of *_U_N_K_N_O_W_N*
                  data values is accounted for and when a new
                  consolidated value is ready to be written to its
                  Round Robin Archive (RRRRRRRRAAAA), a validity check is
                  performed to make sure that the percentage of
                  unknown values in the data point is above a
                  configurable level. If not, an *_U_N_K_N_O_W_N* value will
                  be written to the RRRRRRRRAAAA.

          Graphing
                  RRRRRRRRDDDDttttoooooooollll allows you to generate reports in numerical
                  and graphical form based on the data stored in one
                  or several RRRRRRRRDDDDs. The graphing feature is fully
                  configurable. Size, color and contents of the graph
                  can be defined freely. Check rrdgraph for more
                  information on this.

          Aberrant Behavior Detection
                  by Jake Brutlag

                  RRRRRRRRDDDDttttoooooooollll provides the building blocks for near real-
                  time aberrant behavior detection. These components
                  include:

                  +o   An algorithm for predicting the value of a time
                      series one time step into the future.

                  +o   A measure of deviation between predicted and
                      observed values.

                  +o   A mechanism to decide if and when an observed
                      value or sequence of observed values is _t_o_o
                      _d_e_v_i_a_n_t from the predicted value(s).

                  Here is a brief explanation of these components:

                  The Holt-Winters time series forecasting algorithm
                  is an on-line (or incremental) algorithm that
                  adaptively predicts future observations in a time
                  series. Its forecast is the sum of three components:
                  a baseline (or intercept), a linear trend over time
                  (or slope), and a seasonal coefficient (a periodic
                  effect, such as a daily cycle). There is one
                  seasonal coefficient for each time point in the
                  period (cycle). After a value is observed, each of
                  these components is updated via exponential
                  smoothing. This means that the algorithm "learns"
                  from past values and uses them to predict the
                  future. The rate of adaptation is governed by 3
                  parameters, alpha (intercept), beta (slope), and



     Page 4                                          (printed 6/13/06)






     RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))             1111....2222....11113333 ((((2222000000006666----00005555----00004444))))             RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))



                  gamma (seasonal). The prediction can also be viewed
                  as a smoothed value for the time series.

                  The measure of deviation is a seasonal weighted
                  absolute deviation. The term _s_e_a_s_o_n_a_l means
                  deviation is measured separately for each time point
                  in the seasonal cycle. As with Holt-Winters
                  forecasting, deviation is predicted using the
                  measure computed from past values (but only at that
                  point in the seasonal cycle). After the value is
                  observed, the algorithm learns from the observed
                  value via exponential smoothing. Confidence bands
                  for the observed time series are generated by
                  scaling the sequence of predicted deviation values
                  (we usually think of the sequence as a continuous
                  line rather than a set of discrete points).

                  Aberrant behavior (a potential failure) is reported
                  whenever the number of times the observed value
                  violates the confidence bands meets or exceeds a
                  specified threshold within a specified temporal
                  window (e.g. 5 violations during the past 45 minutes
                  with a value observed every 5 minutes).

                  This functionality is embedded in a set of related
                  RRRRRRRRAAAAssss. In particular, a FAILURES RRRRRRRRAAAA logs potential
                  failures. With these data you could, for example,
                  use a front-end application to RRRRRRRRDDDDttttoooooooollll to initiate
                  real-time alerts.

                  For a detailed description on how to set this up,
                  see rrdcreate.

          RRRREEEEMMMMOOOOTTTTEEEE CCCCOOOONNNNTTTTRRRROOOOLLLL

          When you start RRRRRRRRDDDDttttoooooooollll with the command line option '----' it
          waits for input via standard input (STDIN). With this
          feature you can improve performance by attaching RRRRRRRRDDDDttttoooooooollll to
          another process (MRTG is one example) through a set of
          pipes. Over these pipes RRRRRRRRDDDDttttoooooooollll accepts the same arguments
          as on the command line and some special commands like qqqquuuuiiiitttt,,,,
          ccccdddd,,,, mmmmkkkkddddiiiirrrr and llllssss. For detailed help on the server commands
          type:

             rrdtool help cd|mkdir|ls|quit

          When a command is completed, RRDtool will print the string
          '"OK"', followed by timing information of the form
          uuuu::::_u_s_e_r_t_i_m_e ssss::::_s_y_s_t_e_m_t_i_m_e. Both values are the running totals
          of seconds since RRDtool was started. If an error occurs, a
          line of the form '"ERROR:"  _D_e_s_c_r_i_p_t_i_o_n _o_f _e_r_r_o_r' will be
          printed instead. RRRRRRRRDDDDttttoooooooollll will not abort, unless something



     Page 5                                          (printed 6/13/06)






     RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))             1111....2222....11113333 ((((2222000000006666----00005555----00004444))))             RRRRRRRRDDDDTTTTOOOOOOOOLLLL((((1111))))



          realy serious happens. If a wwwwoooorrrrkkkkddddiiiirrrr is specified and the UID
          is 0, RRDtool will do a chroot to that workdir. If the UID
          is not 0, RRDtool only changes the current directory to
          wwwwoooorrrrkkkkddddiiiirrrr.

          RRRRRRRRDDDD SSSSeeeerrrrvvvveeeerrrr

          If you want to create a RRD-Server, you must choose a TCP/IP
          Service number and add them to /_e_t_c/_s_e_r_v_i_c_e_s like this:

           rrdsrv      13900/tcp                       # RRD server

          Attention: the TCP port 13900 isn't officially registered
          for rrdsrv. You can use any unused port in your services
          file, but the server and the client system must use the same
          port, of course.

          With this configuration you can add RRDtool as meta-server
          to /_e_t_c/_i_n_e_t_d._c_o_n_f. For example:

           rrdsrv stream tcp nowait root /opt/rrd/bin/rrdtool rrdtool - /var/rrd

          Don't forget to create the database directory /var/rrd and
          reinitialize your inetd.

          If all was setup correctly, you can access the server with
          perl sockets, tools like netcat, or in a quick interactive
          test by using 'telnet localhost rrdsrv'.

          NNNNOOOOTTTTEEEE:::: that there is no authentication with this feature! Do
          not setup such a port unless you are sure what you are
          doing.

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
          rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune,
          rrdlast, rrdxport

     BBBBUUUUGGGGSSSS
          Bugs? Features!

     AAAAUUUUTTTTHHHHOOOORRRR
          Tobias Oetiker <tobi@oetiker.ch>













     Page 6                                          (printed 6/13/06)



