doc/rrdtool.pod

   1 =head1 NAME
   2
   3 rrdtool - round robin database tool
   4
   5 =for html <div align="right"><a href="rrdtool.pdf">PDF</a> version.</div>
   6
   7 =head1 SYNOPSIS
   8
   9 B<rrdtool> B<-> | I<function>
  10
  11 =head1 DESCRIPTION
  12
  13 =head2 OVERVIEW
  14
  15 It is pretty easy to gather status information from all sorts of
  16 things, ranging from the temperature in your office to the number of
  17 octets which have passed through the FDDI interface of your
  18 router. But it is not so trivial to store this data in a efficient and
  19 systematic manner. This is where B<rrdtool> kicks in. It lets you
  20 I<log and analyze> the data you gather from all kinds of data-sources
  21 (B<DS>). The data analysis part of rrdtool is based on the ability to
  22 quickly generate graphical representations of the data values
  23 collected over a definable time period.
  24
  25 In this man page you will find general information on the design and
  26 functionality of the Round Robin Database Tool (rrdtool). For a more
  27 detailed description of how to use the individual functions of the
  28 B<rrdtool> check the corresponding man page.
  29
  30 For an introduction to the usage of rrdtool make sure you check L<rrdtutorial>.
  31
  32 =head2 FUNCTIONS
  33
  34 While the man pages talk of command line switches you have to set in
  35 order to make B<rrdtool> work it is important to note that the
  36 B<rrdtool> can be 'remote controlled' through a set of pipes. This
  37 saves a considerable amount of startup time when you plan to make
  38 B<rrdtool> do a lot of things quickly. Check the section on L<"Remote
  39 Control"> further down. There is also a number of language bindings
  40 for rrdtool which allow you to use it directly from perl, python, tcl,
  41 php, ...
  42
  43 =over 8
  44
  45 =item B<create>
  46
  47 Set up a new Round Robin Database (RRD). Check L<rrdcreate>.
  48
  49 =item B<update>
  50
  51 Store new data values into an RRD. Check L<rrdupdate>.
  52
  53 =item B<graph>
  54
  55 Create a graph from data stored in one or several RRD. Apart from
  56 generating graphs, data can also be extracted to stdout. Check L<rrdgraph>.
  57
  58 =item B<dump>
  59
  60 Dump the contents of an RRD in plain ASCII. In connection with
  61 restore you can use it to transport an rrd from one architecture to another.
  62 Check L<rrddump>.
  63
  64 =item B<restore>
  65
  66 Restore an RRD in XML format to a binary rrd ... Check L<rrdrestore>
  67
  68 =item B<fetch>
  69
  70 Get data for a certain time period from a RRD. The graph function
  71 uses fetch to retrieve its data from an rrd. Check L<rrdfetch>.
  72
  73 =item B<tune>
  74
  75 Alter setup of an RRD. Check L<rrdtune>.
  76
  77 =item B<last>
  78
  79 Find last update time of an RRD. Check L<rrdlast>.
  80
  81 =item B<rrdresize>
  82
  83 Change the size of individual RRAs ... Dangerous! Check L<rrdresize>.
  84
  85 =item B<rrdcgi>
  86
  87 This is a standalone tool for producing rrd graphs on the fly. Check
  88 L<rrdcgi>.
  89
  90 =back
  91
  92 =head2 HOW DOES RRDTOOL WORK?
  93
  94 =over 8
  95
  96 =item Data acquisition
  97
  98 When monitoring the state of a system, it is convenient to have the
  99 data available at a constant interval. Unfortunately you may not
 100 always be able to fetch data at exactly the time you want
 101 to. Therefore B<rrdtool> lets you update the logfile at any time you
 102 want. It will automatically interpolate the value of the data-source
 103 (B<DS>) at the latest official time-slot and write this value to the
 104 log. The value you have supplied is stored as well and is also taken
 105 into account when interpolating the next log entry.
 106
 107 =item Consolidation
 108
 109 You may log data at a 1 minute interval, but you are also be
 110 interested to know the development of the data over the last year. You
 111 could do this by simply storing the data in 1 minute interval, for one
 112 year. While this would take considerable disk space it would also take
 113 a lot of time to analyze the data when you wanted to create a graph
 114 covering the whole year. B<rrdtool> offers a solution to this of this
 115 problem through its data consolidation feature. When setting up
 116 an Round Robin Database (B<RRD>), you can define at which interval
 117 this consolidation should occur, and what consolidation function
 118 (B<CF>) (average, minimum, maximum, total, last) should be used to
 119 build the consolidated values (see rrdcreate). You can define any
 120 number of different consolidation setups within one B<RRD>. They will
 121 all be maintained on the fly when new data is loaded into the B<RRD>.
 122
 123 =item Round Robin Archives
 124
 125 Data values of the same consolidation setup are stored into Round
 126 Robin Archives (B<RRA>). This is a very efficient manner to store data
 127 for a certain amount of time, while using a known amount of storage
 128 space.
 129
 130 It works like this: If you want to store 1000 values in 5 minute
 131 interval, B<rrdtool> will allocate space for 1000 data values and a
 132 header area. In the header it will store a pointer telling
 133 which one of the values in the storage area was last written to. New
 134 values are written to the Round Robin Archive in a ...  you guess it
 135 ... round robin manner. This automatically limits the history to the last
 136 1000 values. Because you can define several B<RRA>s within a single B<RRD>,
 137 you can setup another one, storing 750 data values at a 2 hour interval
 138 and thus keeping a log for the last two months although at a lower
 139 resolution.
 140
 141 The use of B<RRA>s guarantees that the B<RRD> does not grow over
 142 time and that old data is automatically eliminated. By using the
 143 consolidation feature, you can still keep data for a very long time,
 144 while gradually reducing the resolution of the data along the time
 145 axis. Using different consolidation functions (B<CF>) allows you to
 146 store exactly the type of information that actually interests
 147 you. (Maximum one minute traffic on the LAN, minimum temperature of
 148 the wine cellar, total minutes down time ...)
 149
 150 =item Unknown Data
 151
 152 As mentioned earlier, the B<RRD> stores data at a constant
 153 interval. Now it may happen that no new data is available when a
 154 value has to be written to the B<RRD>. Data acquisition may not be
 155 possible for one reason or an other. The B<rrdtool> handles these
 156 situations by storing an I<*UNKNOWN*> value into the database. The
 157 value 'I<*UNKNOWN*>' is supported through all the functions of the
 158 database. When consolidating the amount of I<*UNKNOWN*> data is
 159 accumulated and when a new consolidated value is ready to be written
 160 to its Round Robin Archive (B<RRA>) a validity check is performed to
 161 make sure that the percentage of unknown data in the new value is
 162 below a configurable level. If so, an I<*UNKNOWN*> value will be
 163 written to the B<RRA>.
 164
 165 =item Graphing
 166
 167 The B<rrdtool> also allows one to generate reports in numerical and
 168 graphical form based on the data stored in one or several
 169 B<RRD>s. The graphing feature is fully configurable. Size, color and
 170 contents of the graph can be defined freely. Check L<rrdgraph>
 171 for more information on this.
 172
 173 =back
 174
 175 =head2 REMOTE CONTROL
 176
 177 When you start B<rrdtool> with the command line option 'B<->', it waits
 178 for input via standard in. With this feature you can improve
 179 performance by attaching B<rrdtool> to another process (mrtg is one
 180 example) through a set of pipes. Over the pipes B<rrdtool> accepts the
 181 same arguments as on the command line. When a command is completed,
 182 rrdtool will print the string  'C<OK>', followed by timing information of
 183 the form B<u:>I<usertime> B<s:>I<systemtime> both values are running
 184 totals of seconds since rrdtool was started. If an error occurs, a line
 185 of the form 'C<ERROR:> I<Description of error>' will be printed. B<rrdtool>
 186 will not abort if possible, but follow the ERROR line with an OK line.
 187
 188
 189 =head1 SEE ALSO
 190
 191 rrdcreate, rrdupdate, rrdgraph, rrddump, rrdfetch, rrdtune, rrdlast
 192
 193 =head1 BUGS
 194
 195 Bugs ? Features !
 196
 197 =head1 AUTHOR
 198
 199 Tobias Oetiker <oetiker@ee.ethz.ch>
 200