


RRDCREATE(1)                 rrdtool                 RRDCREATE(1)


NAME
       rrdtool create - Set up a new Round Robin Database

SYNOPSIS
       rrdtool create filename [--start|-b start time]
       [--step|-s step] [DS:ds-name:DST:heartbeat:min:max]
       [RRA:CF:xff:steps:rows]

DESCRIPTION
       The create function of the RRDtool lets you set up new
       Round Robin Database (RRD) files.  The file is created at
       its final, full size and filled with *UNKNOWN* data.

       filename
               The name of the RRD you want to create. RRD files
               should end with the extension .rrd. However,
               rrdtool will accept any filename.

       --start|-b start time (default: now - 10s)
               Specifies the time in seconds since 1970-01-01 UTC
               when the first value should be added to the RRD.
               rrdtool will not accept any data timed before or
               at the time specified.

               See also AT-STYLE TIME SPECIFICATION section in
               the rrdfetch documentation for more ways to
               specify time.

       --step|-s step (default: 300 seconds)
               Specifies the base interval in seconds with which
               data will be fed into the RRD.

       DS:ds-name:DST:heartbeat:min:max
               A single RRD can accept input from several data
               sources (DS).  (e.g. Incoming and Outgoing traffic
               on a specific communication line). With the DS
               configuration option you must define some basic
               properties of each data source you want to use to
               feed the RRD.

               ds-name is the name you will use to reference this
               particular data source from an RRD. A ds-name must
               be 1 to 19 characters long in the characters [a-
               zA-Z0-9_].

               DST defines the Data Source Type. It can be one of
               the following: GAUGE this is for things like
               temperatures or number of people in a room.
               COUNTER is for continuous incrementing counters
               like the InOctets counter in a router. The COUNTER
               data source assumes that the counter never
               decreases, except when a counter overflows.  The
               update function takes the overflow into account.
               The counter is stored as a per-second rate. DERIVE



20/Aug/99                     1.0.7                             1





RRDCREATE(1)                 rrdtool                 RRDCREATE(1)


               will store the the derivative of the line going
               from the last to the current value of the data
               source. This can be useful for gauges, for
               example, to measure the rate of people entering or
               leaving a room. ABSOLUTE is for counters which get
               reset upon reading.

               heartbeat defines the maximum number of seconds
               that may pass between two updates of this data
               source before the value of the data source is
               assumed to be *UNKNOWN*.

               min and max are optional entries defining the
               expected range of the data supplied by this data
               source. If min and/or max are defined, any value
               outside the defined range will be regarded as
               *UNKNOWN*. If you do not know or care about min
               and max, set them to U for unknown. Note that min
               and max always refer to the processed values of
               the DS. For a traffic-COUNTER type DS this would
               be the max and min data-rate expected from the
               device.

               If information on minimal/maximal expected values
               is available, always set the min and/or max
               properties. This will help RRDtool in doing a
               simple sanity check on the data supplied when
               running update.

       RRA:CF:xff:steps:rows
               The purpose of an RRD is to store data in the
               round robin archives (RRA). An archive consists of
               a number of data values from all the defined data-
               sources (DS) and is defined with an RRA line.

               When data is entered into an RRD, it is first fit
               into time slots of the length defined with the -s
               option becoming a primary data point.

               The data is also consolidated with the
               consolidation function (CF) of the archive. The
               following consolidation functions are defined:
               AVERAGE, MIN, MAX, LAST.

               xff The xfiles factor defines what part of a
               consolidation interval may be made up from
               *UNKNOWN* data while the consolidated value is
               sill regarded as known.

               steps defines how many of these primary data
               points are used to build a consolidated data point
               which then goes into the archive.

               rows defines how many generations of data values



20/Aug/99                     1.0.7                             2





RRDCREATE(1)                 rrdtool                 RRDCREATE(1)


               are kept in an RRA.

EXAMPLE
       rrdtool create temperature.rrd --step 300
       DS:temp:GAUGE:600:-273:5000 RRA:AVERAGE:0.5:1:1200
       RRA:MIN:0.5:12:2400 RRA:MAX:0.5:12:2400
       RRA:AVERAGE:0.5:12:2400

       This sets up an RRD called temperature.rrd which accepts
       one temperature value every 300 seconds. If no new data is
       supplied for more than 600 seconds, the temperature
       becomes *UNKNOWN*.  The minimum acceptable value is -273
       and the maximum is 5000.

       A few archives areas are also defined. The first stores
       the temperatures supplied for 100 hours (1200 * 300
       seconds = 100 hours). The second RRA stores the minimum
       temperature recorded over every hour (12 * 300 seconds = 1
       hour), for 100 days (2400 hours). The third and the fourth
       RRA's do the same with the for the maximum and average
       temperature, respectively.

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

































20/Aug/99                     1.0.7                             3


