rrdcreate - Set up a new Round Robin Database
rrdtool create filename [--start|-b start time] [--step|-s step] [DS:ds-name:DST:dst arguments] [RRA:CF:cf arguments]
The create function of 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.
See also AT-STYLE TIME SPECIFICATION section in the rrdfetch documentation for other ways to specify time.
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. The remaining arguments of a data source entry depend on the data source type. For GAUGE, COUNTER, DERIVE, and ABSOLUTE the format for a data source entry is:
DS:ds-name:GAUGE | COUNTER | DERIVE | ABSOLUTE:heartbeat:min:max
For COMPUTE data sources, the format is:
DS:ds-name:COMPUTE:rpn-expression
In order to decide which data source type to use, review the definitions that follow. Also consult the section on ``HOW TO MEASURE'' for further insight.
If you cannot tolerate ever mistaking the occasional counter reset for a legitimate counter wrap, and would prefer ``Unknowns'' for all legitimate counter wraps and resets, always use DERIVE with min=0. Otherwise, using COUNTER with a suitable max will return correct values for all legitimate counter wraps, mark some counter resets as ``Unknown'', but can mistake some counter resets for a legitimate counter wrap.
For a 5 minute step and 32-bit counter, the probability of mistaking a counter reset for a legitimate wrap is arguably about 0.8% per 1Mbps of maximum bandwidth. Note that this equates to 80% for 100Mbps interfaces, so for high bandwidth interfaces and a 32bit counter, DERIVE with min=0 is probably preferable. If you are using a 64bit counter, just about any max setting will eliminate the possibility of mistaking a reset for a counter wrap.
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 define the expected range values for data supplied by a data source. If min and/or max 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 maximum and minimum 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.
rpn-expression defines the formula used to compute the PDPs of a COMPUTE data source from other data sources in the same <RRD>. It is similar to defining a CDEF argument for the graph command. Please refer to that manual page for a list and description of RPN operations supported. For COMPUTE data sources, the following RPN operations are not supported: COUNT, PREV, TIME, and LTIME. In addition, in defining the RPN expression, the COMPUTE data source may only refer to the names of data source listed previously in the create command. This is similar to the restriction that CDEFs must refer only to DEFs and CDEFs previously defined in the same graph command.
When data is entered into an RRD, it is first fit into time slots of the length defined with the -s option, thus becoming a primary data point.
The data is also processed with the consolidation function (CF) of the archive. There are several consolidation functions that consolidate primary data points via an aggregate function: AVERAGE, MIN, MAX, LAST. The format of RRA line for these consolidation functions is:
RRA:AVERAGE | MIN | MAX | LAST:xff:steps:rows
xff The xfiles factor defines what part of a consolidation interval may be made up from *UNKNOWN* data while the consolidated value is still 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 are kept in an RRA.
In addition to the aggregate functions, there are a set of specialized
functions that enable RRDtool to provide data smoothing (via the
Holt-Winters and_variables">Data and variables
CDEF:vname=RPN expression
VDEF:vname=RPN expression
You need at least one DEF statement to generate anything. The other statements are useful but optional. See the rrdgraph_data manpage and the rrdgraph_rpn manpage for the exact format.
the rrdgraph manpage gives an overview of how rrdtool graph works. the rrdgraph_data manpage describes DEF,CDEF and VDEF in detail. the rrdgraph_rpn manpage describes the RPN language used in the ?DEF statements. the rrdgraph_graph manpage page describes all of the graph and print functions.
Make sure to read the rrdgraph_examples manpage for tips&tricks.
Program by Tobias Oetiker <oetiker@ee.ethz.ch>
This manual page by Alex van den Bogaerdt <alex@ergens.op.het.net>