


rrdtool                                                RRDTOOL(1)



NNNNAAAAMMMMEEEE
     rrdtool - round robin database tool

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     rrrrrrrrddddttttoooooooollll ---- | _f_u_n_c_t_i_o_n

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW

     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 a efficient and systematic manner. This is
     where rrrrrrrrddddttttoooooooollll kicks in. 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 (DDDDSSSS). 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 the rrrrrrrrddddttttoooooooollll check the corresponding
     man page.

     For an introduction to the usage of rrdtool make sure you
     check the rrdtutorial manpage.

     FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS

     While the man pages talk of command line switches you have
     to set in order to make rrrrrrrrddddttttoooooooollll work it is important to note
     that the rrrrrrrrddddttttoooooooollll can be 'remote controlled' through a set of
     pipes. This saves a considerable amount of startup time when
     you plan to make rrrrrrrrddddttttoooooooollll do a lot of things quickly. Check
     the section on 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, ...

     ccccrrrreeeeaaaatttteeee  Set up a new Round Robin Database (RRD). Check the
             rrdcreate manpage.

     uuuuppppddddaaaatttteeee  Store new data values into an RRD. Check the
             rrdupdate manpage.

     ggggrrrraaaapppphhhh   Create a graph from data stored in one or several
             RRD. Apart from generating graphs, data can also be
             extracted to stdout. Check the rrdgraph manpage.





2001-02-20             Last change: 1.0.33                      1






rrdtool                                                RRDTOOL(1)



     dddduuuummmmpppp    Dump the contents of an RRD in plain ASCII. In
             connection with restore you can use it to transport
             an rrd from one architecture to another.  Check the
             rrddump manpage.

     rrrreeeessssttttoooorrrreeee Restore an RRD in XML format to a binary rrd ...
             Check the rrdrestore manpage

     ffffeeeettttcccchhhh   Get data for a certain time period from a RRD. The
             graph function uses fetch to retrieve its data from
             an rrd. Check the rrdfetch manpage.

     ttttuuuunnnneeee    Alter setup of an RRD. Check the rrdtune manpage.

     llllaaaasssstttt    Find last update time of an RRD. Check the rrdlast
             manpage.

     rrrrrrrrddddrrrreeeessssiiiizzzzeeee
             Change the size of individual RRAs ... Dangerous!
             Check the rrdresize manpage.

     rrrrrrrrddddccccggggiiii  This is a standalone tool for producing rrd graphs
             on the fly. Check the rrdcgi manpage.

     HHHHOOOOWWWW DDDDOOOOEEEESSSS RRRRRRRRDDDDTTTTOOOOOOOOLLLL WWWWOOOORRRRKKKK????

     Data acquisition
             When monitoring the state of a system, it is
             convenient to have the data available at a constant
             interval. Unfortunately you may not always be able
             to fetch data at exactly the time you want to.
             Therefore rrrrrrrrddddttttoooooooollll lets you update the logfile at any
             time you want. It will automatically interpolate the
             value of the data-source (DDDDSSSS) at the latest official
             time-slot and write this value to the log. The 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 are
             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 interval, for one 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. rrrrrrrrddddttttoooooooollll offers a solution to this of this
             problem through its data consolidation feature. When
             setting up an Round Robin Database (RRRRRRRRDDDD), you can
             define at which interval this consolidation should
             occur, and what consolidation function (CCCCFFFF)



2001-02-20             Last change: 1.0.33                      2






rrdtool                                                RRDTOOL(1)



             (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 RRRRRRRRDDDD. They will all
             be maintained on the fly when new data is loaded
             into the RRRRRRRRDDDD.

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

             It works like this: If you want to store 1000 values
             in 5 minute interval, rrrrrrrrddddttttoooooooollll will allocate space
             for 1000 data values and a header area. In the
             header it will store a pointer telling which one of
             the values in the storage area was last written to.
             New values are written to the Round Robin Archive in
             a ...  you guess it ... round robin manner. This
             automatically limits the history to the last 1000
             values. Because you can define several RRRRRRRRAAAAs within a
             single RRRRRRRRDDDD, you can setup another one, storing 750
             data values at a 2 hour interval and thus keeping a
             log for the last two months although at a lower
             resolution.

             The use of RRRRRRRRAAAAs guarantees that the RRRRRRRRDDDD 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 (CCCCFFFF) allows you to store exactly the type
             of information that actually interests you. (Maximum
             one minute traffic on the LAN, minimum temperature
             of the wine cellar, total minutes down time ...)

     Unknown Data
             As mentioned earlier, the RRRRRRRRDDDD stores data at a
             constant interval. Now it may happen that no new
             data is available when a value has to be written to
             the RRRRRRRRDDDD. Data acquisition may not be possible for
             one reason or an other. The rrrrrrrrddddttttoooooooollll handles these
             situations by storing an _*_U_N_K_N_O_W_N_* value into the
             database. The value '_*_U_N_K_N_O_W_N_*' is supported through
             all the functions of the database. When
             consolidating the amount of _*_U_N_K_N_O_W_N_* data is
             accumulated and when a new consolidated value is
             ready to be written to its Round Robin Archive (RRRRRRRRAAAA)
             a validity check is performed to make sure that the



2001-02-20             Last change: 1.0.33                      3






rrdtool                                                RRDTOOL(1)



             percentage of unknown data in the new value is below
             a configurable level. If so, an _*_U_N_K_N_O_W_N_* value will
             be written to the RRRRRRRRAAAA.

     Graphing
             The rrrrrrrrddddttttoooooooollll also allows one to generate reports in
             numerical and graphical form based on the data
             stored in one or several RRRRRRRRDDDDs. The graphing feature
             is fully configurable. Size, color and contents of
             the graph can be defined freely. Check the rrdgraph
             manpage for more information on this.

     RRRREEEEMMMMOOOOTTTTEEEE CCCCOOOONNNNTTTTRRRROOOOLLLL

     When you start rrrrrrrrddddttttoooooooollll with the command line option '----', it
     waits for input via standard in. With this feature you can
     improve performance by attaching rrrrrrrrddddttttoooooooollll to another process
     (mrtg is one example) through a set of pipes. Over the pipes
     rrrrrrrrddddttttoooooooollll accepts the same arguments as on the command line.
     When a command is completed, rrdtool will print the string
     '`OK'', followed by timing information of the form
     uuuu::::_u_s_e_r_t_i_m_e ssss::::_s_y_s_t_e_m_t_i_m_e both values are 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. rrrrrrrrddddttttoooooooollll will not abort if possible, but follow the
     ERROR line with an OK line.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune,
     rrdlast

BBBBUUUUGGGGSSSS
     Bugs ? Features !

AAAAUUUUTTTTHHHHOOOORRRR
     Tobias Oetiker <oetiker@ee.ethz.ch>



















2001-02-20             Last change: 1.0.33                      4



