X-Git-Url: https://git.verplant.org/?a=blobdiff_plain;f=doc%2Frrdtune.pod;h=859c14345f407d7c77f6813fc9dd8de8b7071074;hb=a12627275ff8487174cbb907a066f62a00b6ae44;hp=badd5d5f61f60bcadc4f206635b68e7959df7954;hpb=5837606887a6d81e8b1f7588525cb1c8783fb62b;p=rrdtool.git
diff --git a/doc/rrdtune.pod b/doc/rrdtune.pod
index badd5d5..859c143 100644
--- a/doc/rrdtune.pod
+++ b/doc/rrdtune.pod
@@ -1,30 +1,42 @@
=head1 NAME
-rrdtool tune - Modify some basic properties of a Round Robin Database
-
-=for html
+rrdtune - Modify some basic properties of a Round Robin Database
=head1 SYNOPSIS
-B B I
-S<[B<--heartbeat>|B<-h> I:I]>
+B B I
+S<[B<--heartbeat>|B<-h> I:I]>
S<[B<--minimum>|B<-i> I:I]>
S<[B<--maximum>|B<-a> I:I]>
S<[B<--data-source-type>|B<-d> I:I]>
S<[B<--data-source-rename>|B<-r> I:I]>
+S<[B<--deltapos> I]>
+S<[B<--deltaneg> I]>
+S<[B<--failure-threshold> I]>
+S<[B<--window-length> I]>
+S<[B<--alpha> I]>
+S<[B<--beta> I]>
+S<[B<--gamma> I]>
+S<[B<--gamma-deviation> I]>
+S<[B<--smoothing-window> I]>
+S<[B<--smoothing-window-deviation> I]>
+S<[B<--aberrant-reset> I]>
=head1 DESCRIPTION
The tune option allows you to alter some of the basic configuration
values stored in the header area of a Round Robin Database (B).
-All these tunable parameters together decide when data fed into an
-B is to be regarded as invalid. Invalid data is entered into the
-database as *UNKNOWN*.
-The main application of the B function is to relax the
+One application of the B function is to relax the
validation rules on an B. This allows to fill a new B with
data available in larger intervals than what you would normally want
-to permit.
+to permit. Be very careful with tune operations for COMPUTE data sources.
+Setting the I, I, and I for a COMPUTE data source
+without changing the data source type to a non-COMPUTE B WILL corrupt
+the data source header in the B.
+
+A second application of the B function is to set or alter parameters
+used by the specialized function B for aberrant behavior detection.
=over 8
@@ -35,7 +47,7 @@ The name of the B you want to tune.
=item S|B<-h> I:I>
modify the I of a data source. By setting this to a high
-value the rrd will accept things like one value per day ...
+value the RRD will accept things like one value per day.
=item S|B<-i> I:I>
@@ -51,22 +63,121 @@ Setting I to 'U' will disable this limit.
alter the type B of a data source.
-=item S<[B<--data-source-rename>|B<-r> I:I]>
+=item S|B<-r> I:I>
+
+rename a data source.
+
+=item S I>
+
+Alter the deviation scaling factor for the upper bound of the
+confidence band used internally to calculate violations for the
+FAILURES B. The default value is 2. Note that this parameter is
+not related to graphing confidence bounds which must be specified as a
+CDEF argument to generate a graph with confidence bounds. The graph
+scale factor need not to agree with the value used internally by the
+FAILURES B.
+
+=item S I>
+
+Alter the deviation scaling factor for the lower bound of the confidence band
+used internally to calculate violations for the FAILURES B. The default
+value is 2. As with B<--deltapos>, this argument is unrelated to the scale
+factor chosen when graphing confidence bounds.
+
+=item S I>
+
+Alter the number of confidence bound violations that constitute a failure for
+purposes of the FAILURES B. This must be an integer less than or equal to
+the window length of the FAILURES B. This restriction is not verified by
+the tune option, so one can reset failure-threshold and window-length
+simultaneously. Setting this option will reset the count of violations to 0.
+
+=item S I>
+
+Alter the number of time points in the temporal window for determining
+failures. This must be an integer greater than or equal to the window
+length of the FAILURES B and less than or equal to 28. Setting
+this option will reset the count of violations to 0.
+
+=item S I>
+
+Alter the intercept adaptation parameter for the Holt-Winters
+forecasting algorithm. This parameter must be between 0 and 1.
+
+=item S I>
+
+Alter the slope adaptation parameter for the Holt-Winters forecasting
+algorithm. This parameter must be between 0 and 1.
-rename a data source
+=item S I>
+
+Alter the seasonal coefficient adaptation parameter for the SEASONAL
+B. This parameter must be between 0 and 1.
+
+=item S I>
+
+Alter the seasonal deviation adaptation parameter for the DEVSEASONAL
+B. This parameter must be between 0 and 1.
+
+=item S I>
+
+Alter the size of the smoothing window for the SEASONAL B. This must
+be between 0 and 1.
+
+=item S I>
+
+Alter the size of the smoothing window for the DEVSEASONAL B. This must
+be between 0 and 1.
+
+=item S I>
+
+This option causes the aberrant behavior detection algorithm to reset
+for the specified data source; that is, forget all it is has learnt so far.
+Specifically, for the HWPREDICT or MHWPREDICT B, it sets the intercept and
+slope coefficients to unknown. For the SEASONAL B, it sets all seasonal
+coefficients to unknown. For the DEVSEASONAL B, it sets all seasonal
+deviation coefficients to unknown. For the FAILURES B, it erases the
+violation history. Note that reset does not erase past predictions
+(the values of the HWPREDICT or MHWPREDICT B), predicted deviations (the
+values of the DEVPREDICT B), or failure history (the values of the
+FAILURES B). This option will function even if not all the listed
+B are present.
+
+Due to the implementation of this option, there is an indirect impact on
+other data sources in the RRD. A smoothing algorithm is applied to
+SEASONAL and DEVSEASONAL values on a periodic basis. During bootstrap
+initialization this smoothing is deferred. For efficiency, the implementation
+of smoothing is not data source specific. This means that utilizing
+reset for one data source will delay running the smoothing algorithm
+for all data sources in the file. This is unlikely to have serious
+consequences, unless the data being collected for the non-reset data sources
+is unusually volatile during the reinitialization period of the reset
+data source.
+
+Use of this tuning option is advised when the behavior of the data source
+time series changes in a drastic and permanent manner.
=back
-=head1 EXAMPLE
+=head1 EXAMPLE 1
C
-Set the minimum required heartbeat for data sources 'in', 'out'
-and 'through' to 10000 seconds which is a little over one day in data.rrd.
-This would allow to feed old data from mrtg-2.0 right into
-rrdtool without generating *UNKNOWN* entries.
+Set the minimum required heartbeat for data sources 'in', 'out'
+and 'through' to 10'000 seconds which is a little over one day in data.rrd.
+This would allow to feed old data from MRTG-2.0 right into
+RRDtool without generating *UNKNOWN* entries.
+
+=head1 EXAMPLE 2
+
+C
+
+If the FAILURES B is implicitly created, the default
+window-length is 9 and the default failure-threshold is 7. This
+command now defines a failure as 3 or more violations in a temporal
+window of 5 time points.
=head1 AUTHOR
-Tobias Oetiker
+Tobias Oetiker