X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdcreate.pod;h=941cfdd9d8cca553d50ebd0f6de7ada1083acb10;hb=fc04186840774d769fbc2ffcc683cdc1019c089b;hp=0d5c6ceb5bdc725fd9a2bc3d0fedf6153d81b50c;hpb=ab57ac1a5ec5c7cf3aeaa586eac9259d7357d6c2;p=rrdtool.git

diff --git a/doc/rrdcreate.pod b/doc/rrdcreate.pod
index 0d5c6ce..941cfdd 100644
--- 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>]> 
-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
@@ -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>.
 
-=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
@@ -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_].
 
-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
 
@@ -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.
 
+=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
@@ -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.>
 
+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>
-  
+
+
 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 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>
 
@@ -156,7 +188,7 @@ I<rows> defines how many generations of data values are kept in an B<RRA>.
 
 =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>
 
@@ -396,7 +428,7 @@ 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
+third and the fourth RRA's do the same for the maximum and
 average temperature, respectively.
 
 =head1 EXAMPLE 2
@@ -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.
 
+=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>