Bug fix: when update of multiple PDP/CDP RRAs coincided

[rrdtool.git] / doc / rrdcreate.pod

diff --git a/doc/rrdcreate.pod b/doc/rrdcreate.pod
index 0d5c6ce..b43f70a 100644 (file)
--- a/doc/rrdcreate.pod
+++ b/doc/rrdcreate.pod
@@ -9,7 +9,8 @@ rrdtool create - Set up a new Round Robin Database
 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<heartbeat>B<:>I<min>B<:>I<max>]>
+S<[B<DS:>I<ds-name>B<:>I<DST>B<:>I<dst arguments>]>
+I<heartbeat>B<:>I<min>B<:>I<max>]>

 S<[B<RRA:>I<CF>B<:>I<cf arguments>]>
 
 =head1 DESCRIPTION
 S<[B<RRA:>I<CF>B<:>I<cf arguments>]>
 
 =head1 DESCRIPTION


@@ -41,7 +42,7 @@ I<rrdfetch> documentation for more ways to specify time.
 Specifies the base interval in seconds with which data will be fed
 into the B<RRD>.
 
 Specifies the base interval in seconds with which data will be fed
 into the B<RRD>.
 

-=item B<DS:>I<ds-name>B<:>I<DST>B<:>I<heartbeat>B<:>I<min>B<:>I<max>
+=item B<DS:>I<ds-name>B<:>I<DST>B<:>I<dst arguments>

 
 A single B<RRD> can accept input from several data sources (B<DS>).
 (e.g. Incoming and Outgoing traffic on a specific communication
 
 A single B<RRD> can accept input from several data sources (B<DS>).
 (e.g. Incoming and Outgoing traffic on a specific communication


@@ -52,8 +53,18 @@ I<ds-name> is the name you will use to reference this particular data
 source from an B<RRD>. A I<ds-name> must be 1 to 19 characters long in
 the characters [a-zA-Z0-9_].
 
 source from an B<RRD>. A I<ds-name> must be 1 to 19 characters long in
 the characters [a-zA-Z0-9_].
 

-I<DST> defines the Data Source Type. See the section on "How to Measure" below for further insight.
-The Datasource Type must be onw of the following:
+I<DST> defines the Data Source Type. The remaining arguments of a
+data source entry depend upon the data source type. For GAUGE, COUNTER,
+DERIVE, and ABSOLUTE the format for a data source entry is:
+
+B<DS:>I<ds-name>B<:>I<GAUGE | COUNTER | DERIVE | ABSOLUTE>B<:>I<heartbeat>B<:>I<min>B<:>I<max>
+
+For COMPUTE data sources, the format is:
+
+B<DS:>I<ds-name>B<:>I<COMPUTE>B<:>I<rpn-expression>
+
+To decide on a data source type, review the definitions that follow. 
+Consult the section on "HOW TO MEASURE" for further insight.

 
 =over 4
 
 
 =over 4
 


@@ -111,6 +122,16 @@ after every read to make sure you have a maximal time available before the
 next overflow. Another usage is for things you count like number of messages
 since the last update.
 
 next overflow. Another usage is for things you count like number of messages
 since the last update.
 

+=item B<COMPUTE>
+
+is for storing the result of a formula applied to other data sources in
+the B<RRD>. This data source is not supplied a value on update, but rather
+its Primary Data Points (PDPs) are computed from the PDPs of the data sources
+according to the rpn-expression that defines the formula. Consolidation 
+functions are then applied normally to the PDPs of the COMPUTE data source
+(that is the rpn-expression is only applied to generate PDPs). In database
+software, these are referred to as "virtual" or "computed" columns.
+

 =back
 
 I<heartbeat> defines the maximum number of seconds that may pass
 =back
 
 I<heartbeat> defines the maximum number of seconds that may pass


@@ -129,8 +150,19 @@ I<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.>
 
 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.>
 

+I<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 B<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: 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 B<CDEF>s must
+refer only to B<DEF>s and B<CDEF>s previously defined in the same graph command.
+

 =item B<RRA:>I<CF>B<:>I<cf arguments>
 =item B<RRA:>I<CF>B<:>I<cf arguments>

-  
+
+

 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 
 each of the defined data-sources (B<DS>) and is defined with an B<RRA> line.
 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 
 each of the defined data-sources (B<DS>) and is defined with an B<RRA> line.


@@ -141,7 +173,7 @@ the length defined with the B<-s> option becoming a I<primary data point>.
 The data is also processed with the consolidation function (I<CF>)
 of the archive. There are several consolidation functions that consolidate
 primary data points via an aggregate function: B<AVERAGE>, B<MIN>, B<MAX>, B<LAST>.
 The data is also processed with the consolidation function (I<CF>)
 of the archive. There are several consolidation functions that consolidate
 primary data points via an aggregate function: B<AVERAGE>, B<MIN>, B<MAX>, B<LAST>.

-The format of B<RRA> line for these consolidation function is:
+The format of B<RRA> line for these consolidation functions is:

 
 B<RRA:>I<AVERAGE | MIN | MAX | LAST>B<:>I<xff>B<:>I<steps>B<:>I<rows>
 
 
 B<RRA:>I<AVERAGE | MIN | MAX | LAST>B<:>I<xff>B<:>I<steps>B<:>I<rows>
 


@@ -156,7 +188,7 @@ I<rows> defines how many generations of data values are kept in an B<RRA>.
 
 =back
 
 
 =back
 

-=head1 Aberrant Behaviour detection with Holt-Winters forecasting
+=head1 Aberrant Behavior Detection with Holt-Winters Forecasting

 
 by Jake Brutlag E<lt>jakeb@corp.webtv.netE<gt>
 
 
 by Jake Brutlag E<lt>jakeb@corp.webtv.netE<gt>
 


@@ -439,6 +471,29 @@ RRA:FAILURES:288:7:9:5>
 Of course, explicit creation need not replicate implicit create, a number of arguments 
 could be changed.
 
 Of course, explicit creation need not replicate implicit create, a number of arguments 
 could be changed.
 

+=head1 EXAMPLE 3
+
+C<rrdtool create proxy.rrd --step 300 
+DS:TotalRequests:DERIVE:1800:0:U
+DS:AccumDuration:DERIVE:1800:0:U
+DS:AvgReqDuration:COMPUTE:AccumDuration,TotalRequests,0,EQ,1,TotalRequests,IF,/
+RRA:AVERAGE:0.5:1:2016>
+
+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
+requests. Clearly these counters both have some rollover point, but using the
+DERIVE data source also handles the reset that occurs when the web proxy is
+stopped and restarted.
+
+In the B<RRD>, the first data source stores the requests per second rate
+during the interval. The second data source stores the total duration of all
+requests processed during the interval divided by 300. The COMPUTE data source
+divides each PDP of the AccumDuration by the corresponding PDP of
+TotalRequests and stores the average request duration. The remainder of the
+RPN expression handles the divide by zero case.
+

 =head1 AUTHOR
 
 Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
 =head1 AUTHOR
 
 Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>