doc/rrdtune.pod

   1 =head1 NAME
   2
   3 rrdtune - Modify some basic properties of a Round Robin Database
   4
   5 =head1 SYNOPSIS
   6
   7 B<rrdtool> B<tune> I<filename>
   8 S<[B<--heartbeat>|B<-h> I<ds-name>:I<heartbeat>]>
   9 S<[B<--minimum>|B<-i> I<ds-name>:I<min>]>
  10 S<[B<--maximum>|B<-a> I<ds-name>:I<max>]>
  11 S<[B<--data-source-type>|B<-d> I<ds-name>:I<DST>]>
  12 S<[B<--data-source-rename>|B<-r> I<old-name>:I<new-name>]>
  13 S<[B<--deltapos> I<scale-value>]>
  14 S<[B<--deltaneg> I<scale-value>]>
  15 S<[B<--failure-threshold> I<failure-threshold>]>
  16 S<[B<--window-length> I<window-length>]>
  17 S<[B<--alpha> I<adaption-parameter>]>
  18 S<[B<--beta> I<adaption-parameter>]>
  19 S<[B<--gamma> I<adaption-parameter>]>
  20 S<[B<--gamma-deviation> I<adaption-parameter>]>
  21 S<[B<--aberrant-reset> I<ds-name>]>
  22
  23 =head1 DESCRIPTION
  24
  25 The tune option allows you to alter some of the basic configuration
  26 values stored in the header area of a Round Robin Database (B<RRD>).
  27
  28 One application of the B<tune> function is to relax the
  29 validation rules on an B<RRD>. This allows to fill a new B<RRD> with
  30 data available in larger intervals than what you would normally want
  31 to permit. Be very careful with tune operations for COMPUTE data sources.
  32 Setting the I<min>, I<max>, and  I<heartbeat> for a COMPUTE data source
  33 without changing the data source type to a non-COMPUTE B<DST> WILL corrupt
  34 the data source header in the B<RRD>.
  35
  36 A second application of the B<tune> function is to set or alter parameters
  37 used by the specialized function B<RRAs> for aberrant behavior detection.
  38
  39 =over 8
  40
  41 =item I<filename>
  42
  43 The name of the B<RRD> you want to tune.
  44
  45 =item S<B<--heartbeat>|B<-h> I<ds-name>:I<heartbeat>>
  46
  47 modify the I<heartbeat> of a data source. By setting this to a high
  48 value the RRD will accept things like one value per day ...
  49
  50 =item S<B<--minimum>|B<-i> I<ds-name>:I<min>>
  51
  52 alter the minimum value acceptable as input from the data source.
  53 Setting I<min> to 'U' will disable this limit.
  54
  55 =item S<B<--maximum>|B<-a> I<ds-name>:I<max>>
  56
  57 alter the maximum value acceptable as input from the data source.
  58 Setting I<max> to 'U' will disable this limit.
  59
  60 =item S<B<--data-source-type>|B<-d> I<ds-name>:I<DST>>
  61
  62 alter the type B<DST> of a data source.
  63
  64 =item S<B<--data-source-rename>|B<-r> I<old-name>:I<new-name>>
  65
  66 rename a data source
  67
  68 =item S<B<--deltapos> I<scale-value>>
  69
  70 Alter the deviation scaling factor for the upper bound of the confidence band
  71 used internally to calculate violations for the FAILURES B<RRA>. The default
  72 value is 2. Note that this parameter is not related to graphing confidence
  73 bounds, that scale factor must be specified as a CDEF argument to generate
  74 a graph with confidence bounds. The graph scale factor need not agree with the
  75 value used internally by the FAILURES B<RRA>.
  76
  77 =item S<B<--deltaneg> I<scale-value>>
  78
  79 Alter the deviation scaling factor for the lower bound of the confidence band
  80 used internally to calculate violations for the FAILURES B<RRA>. The default
  81 value is 2. As with B<--deltapos>, this argument is unrelated to the scale
  82 factor chosen when graphing confidence bounds.
  83
  84 =item S<B<--failure-threshold> I<failure-threshold>>
  85
  86 Alter the number of confidence bound violations that constitute a failure for
  87 purposes of the FAILURES B<RRA>. This must be an integer less than or equal to
  88 the window length of the FAILURES B<RRA>. This restriction is not verified by
  89 the tune option, so one can reset failure-threshold and window-length
  90 simultaneously. Setting this option will reset the count of violations to 0.
  91
  92 =item S<B<--window-length> I<window-length>>
  93
  94 Alter the number of time points in the temporal window for determining failures.
  95 This must be an integer greater than or equal to the window length of the
  96 FAILURES B<RRA> and less than or equal to 28. Setting this option will reset the
  97 count of violations to 0.
  98
  99 =item S<B<--alpha> I<adaption-parameter>>
 100
 101 Alter the intercept adaptation parameter for the Holt-Winters forecasting algorithm.
 102 Must be between 0 and 1.
 103
 104 =item S<B<--beta> I<adaption-parameter>>
 105
 106 Alter the slope adaptation parameter for the Holt-Winters forecasting algorithm.
 107 Must be between 0 and 1.
 108
 109 =item S<B<--gamma> I<adaption-parameter>>
 110
 111 Alter the seasonal coefficient adaptation parameter for the SEASONAL
 112 B<RRA>. Must be between 0 and 1.
 113
 114 =item S<B<--gamma-deviation> I<adaption-parameter>>
 115
 116 Alter the seasonal deviation adaptation parameter for the DEVSEASONAL
 117 B<RRA>. Must be between 0 and 1.
 118
 119 =item S<B<--aberrant-reset> I<ds-name>>
 120
 121 This option causes the aberrant behavior detection algorithm to reset
 122 for the specified data source; that is, forget all it is has learn.
 123 Specifically, for the HWPREDICT B<RRA>, it sets the intercept and slope
 124 coefficients to unknown. For the SEASONAL B<RRA>, it sets all seasonal
 125 coefficients to unknown. For the DEVSEASONAL B<RRA>, it sets all seasonal
 126 deviation coefficients to unknown. For the FAILURES B<RRA>, it erases
 127 the violation history. Note that reset does not erase past predictions
 128 (the values of the HWPREDICT B<RRA>), predicted deviations (the values of the
 129 DEVPREDICT B<RRA>), or failure history (the values of the FAILURES B<RRA>).
 130 This option will function even if not all the listed B<RRAs> are present.
 131
 132 Due to the implementation of this option, there is an indirect impact on
 133 other data sources in the RRD. A smoothing algorithm is applied to
 134 SEASONAL and DEVSEASONAL values on a periodic basis. During bootstrap
 135 initialization this smoothing is deferred. For efficiency, the implementation
 136 of smoothing is not data source specific. This means that utilizing
 137 reset for one data source will delay running the smoothing algorithm
 138 for all data sources in the file. This is unlikely to have serious
 139 consequences, unless the data being collected for the non-reset data sources
 140 is unusually volatile during the reinitialization period of the reset
 141 data source.
 142
 143 Use of this tuning option is advised when the behavior of the data source
 144 time series changes in a drastic and permanent manner.
 145
 146 =back
 147
 148 =head1 EXAMPLE 1
 149
 150 C<rrdtool tune data.rrd -h in:100000 -h out:100000 -h through:100000>
 151
 152 Set the minimum required heartbeat for data sources 'in', 'out'
 153 and 'through' to 10000 seconds which is a little over one day in data.rrd.
 154 This would allow to feed old data from MRTG-2.0 right into
 155 RRDtool without generating *UNKNOWN* entries.
 156
 157 =head1 EXAMPLE 2
 158
 159 C<rrdtool tune monitor.rrd --window-length 5 --failure-threshold 3>
 160
 161 If the FAILURES B<RRA> is implicitly created, the default window-length is 9 and
 162 the default failure-threshold is 7. This command now defines a failure as 3 or more
 163 violations in a temporal window of 5 time points.
 164
 165 =head1 AUTHOR
 166
 167 Tobias Oetiker <oetiker@ee.ethz.ch>
 168