=head1 SYNOPSIS
-B<rrdtool> B<create> I<filename>
-S<[B<--start>|B<-b> I<start time>]>
-S<[B<--step>|B<-s> I<step>]>
+B<rrdtool> B<create> I<filename>
+S<[B<--start>|B<-b> I<start time>]>
+S<[B<--step>|B<-s> I<step>]>
S<[B<DS:>I<ds-name>B<:>I<DST>B<:>I<dst arguments>]>
S<[B<RRA:>I<CF>B<:>I<cf arguments>]>
=over 4
-=item B<GAUGE>
+=item B<GAUGE>
is for things like temperatures or number of people in a room or the
value of a RedHat share.
=back
-=item B<ABSOLUTE>
+=item B<ABSOLUTE>
is for counters which get reset upon reading. This is used for fast counters
which tend to overflow. So instead of reading them normally you reset them
=back
I<heartbeat> defines the maximum number of seconds that may pass
-between two updates of this data source before the value of the
+between two updates of this data source before the value of the
data source is assumed to be I<*UNKNOWN*>.
-I<min> and I<max> are optional entries defining the expected range of
-the data supplied by this data source. If I<min> and/or I<max> are
-defined, any value outside the defined range will be regarded as
-I<*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-B<COUNTER> type DS this would be the
-maximum and minimum data-rate expected from the device.
+I<min> and I<max> define the expected range values for data supplied by a
+data source. If I<min> and/or I<max> any value outside the defined range
+will be regarded as I<*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-B<COUNTER> type DS this would be
+the maximum and minimum data-rate expected from the device.
I<If information on minimal/maximal expected values is available,
always set the min and/or max properties. This will help RRDtool in
The purpose of an B<RRD> is to store data in the round robin archives
-(B<RRA>). An archive consists of a number of data values or statistics for
+(B<RRA>). An archive consists of a number of data values or statistics for
each of the defined data-sources (B<DS>) and is defined with an B<RRA> line.
When data is entered into an B<RRD>, it is first fit into time slots
I<xff> The xfiles factor defines what part of a consolidation interval may
be made up from I<*UNKNOWN*> data while the consolidated value is still
-regarded as known.
+regarded as known. It is given as the ratio of allowed I<*UNKNOWN*> PDPs
+to the number of PDPs in the interval. Thus, it ranges from 0 to 1 (exclusive).
+
I<steps> defines how many of these I<primary data points> are used to build
a I<consolidated data point> which then goes into the archive.
=item *
-B<RRA:>I<HWPREDICT>B<:>I<rows>B<:>I<alpha>B<:>I<beta>B<:>I<seasonal period>B<:>I<rra-num>
+B<RRA:>I<HWPREDICT>B<:>I<rows>B<:>I<alpha>B<:>I<beta>B<:>I<seasonal period>[B<:>I<rra-num>]
+
+=item *
+
+B<RRA:>I<MHWPREDICT>B<:>I<rows>B<:>I<alpha>B<:>I<beta>B<:>I<seasonal period>[B<:>I<rra-num>]
=item *
These B<RRAs> differ from the true consolidation functions in several ways.
First, each of the B<RRA>s is updated once for every primary data point.
Second, these B<RRAs> are interdependent. To generate real-time confidence
-bounds, a matched set of HWPREDICT, SEASONAL, DEVSEASONAL, and
-DEVPREDICT must exist. Generating smoothed values of the primary data points
-requires both a HWPREDICT B<RRA> and SEASONAL B<RRA>. Aberrant behavior
-detection requires FAILURES, HWPREDICT, DEVSEASONAL, and SEASONAL.
-
-The actual predicted, or smoothed, values are stored in the HWPREDICT
-B<RRA>. The predicted deviations are stored in DEVPREDICT (think a standard
-deviation which can be scaled to yield a confidence band). The FAILURES
-B<RRA> stores binary indicators. A 1 marks the indexed observation as
-failure; that is, the number of confidence bounds violations in the
-preceding window of observations met or exceeded a specified threshold. An
-example of using these B<RRAs> to graph confidence bounds and failures
-appears in L<rrdgraph>.
+bounds, a matched set of SEASONAL, DEVSEASONAL, DEVPREDICT, and either
+HWPREDICT or MHWPREDICT must exist. Generating smoothed values of the primary
+data points requires a SEASONAL B<RRA> and either an HWPREDICT or MHWPREDICT
+B<RRA>. Aberrant behavior detection requires FAILURES, DEVSEASONAL, SEASONAL,
+and either HWPREDICT or MHWPREDICT.
+
+The predicted, or smoothed, values are stored in the HWPREDICT or MHWPREDICT
+B<RRA>. HWPREDICT and MHWPREDICT are actually two variations on the
+Holt-Winters method. They are interchangeable. Both attempt to decompose data
+into three components: a baseline, a trend, and a seasonal coefficient.
+HWPREDICT adds its seasonal coefficient to the baseline to form a prediction, whereas
+MHWPREDICT multiplies its seasonal coefficient by the baseline to form a
+prediction. The difference is noticeable when the baseline changes
+significantly in the course of a season; HWPREDICT will predict the seasonality
+to stay constant as the baseline changes, but MHWPREDICT will predict the
+seasonality to grow or shrink in proportion to the baseline. The proper choice
+of method depends on the thing being modeled. For simplicity, the rest of this
+discussion will refer to HWPREDICT, but MHWPREDICT may be substituted in its
+place.
+
+The predicted deviations are stored in DEVPREDICT (think a standard deviation
+which can be scaled to yield a confidence band). The FAILURES B<RRA> stores
+binary indicators. A 1 marks the indexed observation as failure; that is, the
+number of confidence bounds violations in the preceding window of observations
+met or exceeded a specified threshold. An example of using these B<RRAs> to graph
+confidence bounds and failures appears in L<rrdgraph>.
The SEASONAL and DEVSEASONAL B<RRAs> store the seasonal coefficients for the
Holt-Winters forecasting algorithm and the seasonal deviations, respectively.
HWPREDICT I<rra-num> is the index of the SEASONAL B<RRA>.
-=item *
+=item *
SEASONAL I<rra-num> is the index of the HWPREDICT B<RRA>.
-=item *
+=item *
DEVPREDICT I<rra-num> is the index of the DEVSEASONAL B<RRA>.
DEVSEASONAL I<rra-num> is the index of the HWPREDICT B<RRA>.
-=item *
+=item *
FAILURES I<rra-num> is the index of the DEVSEASONAL B<RRA>.
result in all the PDPs for that entire day period being set to the
same average rate. I<-- Don Baarda E<lt>don.baarda@baesystems.comE<gt>>
+ time|
+ axis|
+ begin__|00|
+ |01|
+ u|02|----* sample1, restart "hb"-timer
+ u|03| /
+ u|04| /
+ u|05| /
+ u|06|/ "hbt" expired
+ u|07|
+ |08|----* sample2, restart "hb"
+ |09| /
+ |10| /
+ u|11|----* sample3, restart "hb"
+ u|12| /
+ u|13| /
+ step1_u|14| /
+ u|15|/ "swt" expired
+ u|16|
+ |17|----* sample4, restart "hb", create "pdp" for step1 =
+ |18| / = unknown due to 10 "u" labled secs > "hb"
+ |19| /
+ |20| /
+ |21|----* sample5, restart "hb"
+ |22| /
+ |23| /
+ |24|----* sample6, restart "hb"
+ |25| /
+ |26| /
+ |27|----* sample7, restart "hb"
+ step2__|28| /
+ |22| /
+ |23|----* sample8, restart "hb", create "pdp" for step1, create "cdp"
+ |24| /
+ |25| /
+
+graphics by I<vladimir.lavrov@desy.de>.
+
=head1 HOW TO MEASURE
=head1 EXAMPLE 2
- rrdtool create monitor.rrd --step 300 \
- DS:ifOutOctets:COUNTER:1800:0:4294967295 \
+ rrdtool create monitor.rrd --step 300 \
+ DS:ifOutOctets:COUNTER:1800:0:4294967295 \
RRA:AVERAGE:0.5:1:2016 \
- RRA:HWPREDICT:1440:0.1:0.0035:288
+ RRA:HWPREDICT:1440:0.1:0.0035:288
This example is a monitor of a router interface. The first B<RRA> tracks the
traffic flow in octets; the second B<RRA> generates the specialized
The same RRD file and B<RRAs> are created with the following command,
which explicitly creates all specialized function B<RRAs>.
- rrdtool create monitor.rrd --step 300 \
- DS:ifOutOctets:COUNTER:1800:0:4294967295 \
- RRA:AVERAGE:0.5:1:2016 \
- RRA:HWPREDICT:1440:0.1:0.0035:288:3 \
- RRA:SEASONAL:288:0.1:2 \
- RRA:DEVPREDICT:1440:5 \
- RRA:DEVSEASONAL:288:0.1:2 \
- RRA:FAILURES:288:7:9:5
+ rrdtool create monitor.rrd --step 300 \
+ DS:ifOutOctets:COUNTER:1800:0:4294967295 \
+ RRA:AVERAGE:0.5:1:2016 \
+ RRA:HWPREDICT:1440:0.1:0.0035:288:3 \
+ RRA:SEASONAL:288:0.1:2 \
+ RRA:DEVPREDICT:1440:5 \
+ RRA:DEVSEASONAL:288:0.1:2 \
+ RRA:FAILURES:288:7:9:5
Of course, explicit creation need not replicate implicit create, a
number of arguments could be changed.
=head1 EXAMPLE 3
- rrdtool create proxy.rrd --step 300 \
- DS:Total:DERIVE:1800:0:U \
- DS:Duration:DERIVE:1800:0:U \
- DS:AvgReqDur:COMPUTE:Duration,Requests,0,EQ,1,Requests,IF,/ \
- RRA:AVERAGE:0.5:1:2016
+ rrdtool create proxy.rrd --step 300 \
+ DS:Total:DERIVE:1800:0:U \
+ DS:Duration:DERIVE:1800:0:U \
+ DS:AvgReqDur:COMPUTE:Duration,Requests,0,EQ,1,Requests,IF,/ \
+ RRA:AVERAGE:0.5:1:2016
-This example is monitoring the average request duration during each 300 sec
+This example is monitoring the average request duration during each 300 sec
interval for requests processed by a web proxy during the interval.
In this case, the proxy exposes two counters, the number of requests
processed since boot and the total cumulative duration of all processed
=head1 AUTHOR
-Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+Tobias Oetiker E<lt>tobi@oetiker.chE<gt>