doc/rrdtune.pod

   1 =head1 NAME
   2
   3 rrdtool tune - Modify some basic properties of a Round Robin Database
   4
   5 =for html <div align="right"><a href="rrdtune.pdf">PDF</a> version.</div>
   6
   7 =head1 SYNOPSIS
   8
   9 B<rrdtool> B<tune> I<filename>
  10 S<[B<--heartbeat>|B<-h> I<ds-name>:I<heartbeat>]>
  11 S<[B<--minimum>|B<-i> I<ds-name>:I<min>]>
  12 S<[B<--maximum>|B<-a> I<ds-name>:I<max>]>
  13 S<[B<--data-source-type>|B<-d> I<ds-name>:I<DST>]>
  14 S<[B<--data-source-rename>|B<-r> I<old-name>:I<new-name>]>
  15 S<[B<--deltapos> I<scale-value>]>
  16 S<[B<--deltaneg> I<scale value>]>
  17 S<[B<--failure-threshold> I<failure-threshold>]>
  18 S<[B<--window-length> I<window-length>]>
  19 S<[B<--alpha> I<adaption-parameter>]>
  20 S<[B<--beta> I<adaption-parameter>]>
  21 S<[B<--gamma> I<adaption-parameter>]>
  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 All these tunable parameters together decide when data fed into an
  28 B<RRD> is to be regarded as invalid. Invalid data is entered into the
  29 database as *UNKNOWN*.
  30
  31 One application of the B<tune> function is to relax the
  32 validation rules on an B<RRD>. This allows to fill a new B<RRD> with
  33 data available in larger intervals than what you would normally want
  34 to permit. Be very careful with tune operations for COMPUTE data sources.
  35 Setting the I<min>, I<max>, and  I<heartbeat> for a COMPUTE data source
  36 without changing the data source type to a non-COMPUTE B<DST> WILL corrupt
  37 the data source header in the B<RRD>.
  38
  39 A second application of the B<tune> function is to set or alter parameters
  40 used by the specialized function B<RRAs> for aberrant behavior detection.
  41
  42 =over 8
  43
  44 =item I<filename>
  45
  46 The name of the B<RRD> you want to tune.
  47
  48 =item S<B<--heartbeat>|B<-h> I<ds-name>:I<heartbeat>>
  49
  50 modify the I<heartbeat> of a data source. By setting this to a high
  51 value the rrd will accept things like one value per day ...
  52
  53 =item S<B<--minimum>|B<-i> I<ds-name>:I<min>>
  54
  55 alter the minimum value acceptable as input from the data source.
  56 Setting I<min> to 'U' will disable this limit.
  57
  58 =item S<B<--maximum>|B<-a> I<ds-name>:I<max>>
  59
  60 alter the maximum value acceptable as input from the data source.
  61 Setting I<max> to 'U' will disable this limit.
  62
  63 =item S<B<--data-source-type>|B<-d> I<ds-name>:I<DST>>
  64
  65 alter the type B<DST> of a data source.
  66
  67 =item S<B<--data-source-rename>|B<-r> I<old-name>:I<new-name>>
  68
  69 rename a data source
  70
  71 =item S<B<--deltapos> I<scale-value>>
  72
  73 Alter the deviation scaling factor for the upper bound of the confidence band
  74 used internally to calculate violations for the FAILURES B<RRA>. The default
  75 value is 2. Note that this parameter is not related to graphing confidence
  76 bounds, that scale factor must be specified as a CDEF argument to generate
  77 a graph with confidence bounds. It need not agree with the value used internally
  78 by the FAILURES B<RRA> (although common sense dictates it should).
  79
  80 =item S<B<--deltaneg> I<scale-value>>
  81
  82 Alter the deviation scaling factor for the lower bound of the confidence band
  83 used internally to calculate violations for the FAILURES B<RRA>. The default
  84 value is 2. As with B<--deltapos>, this argument is unrelated to the scale
  85 factor chosen when graphing confidence bounds.
  86
  87 =item S<B<--failure-threshold> I<failure-threshold>>
  88
  89 Alter the number of confidence bound violations that constitute a failure for
  90 purposes of the FAILURES B<RRA>. This must be an integer less than or equal to
  91 the window length of the FAILURES B<RRA>. This restriction is not verified by
  92 the tune option, so one can reset failure-threshold and window-length
  93 simultaneously. Setting this option will reset the count of violations to 0.
  94
  95 =item S<B<--window-length> I<window-length>>
  96
  97 Alter the number of time points in the temporal window for determining failures.
  98 This must be an integer greater than or equal to the window length of the
  99 FAILURES B<RRA> and less than or equal to 28. Setting this option will reset the
 100 count of violations to 0.
 101
 102 =item S<B<--alpha> I<adaption-parameter>>
 103
 104 Alter the intercept adaptation parameter for the Holt-Winters forecasting algorithm.
 105 Must be between 0 and 1.
 106
 107 =item S<B<--beta> I<adaption-parameter>>
 108
 109 Alter the intercept adaptation parameter for the Holt-Winters forecasting algorithm.
 110 Must be between 0 and 1.
 111
 112 =item S<B<--gamma> I<adaption-parameter>>
 113
 114 Alter the seasonal coefficient and deviation adaptation parameters the SEASONAL and
 115 DEVSEAONAL B<RRAs>. Must be between 0 and 1.
 116
 117 =back
 118
 119 =head1 EXAMPLE 1
 120
 121 C<rrdtool tune data.rrd -h in:100000 -h out:100000 -h through:100000>
 122
 123 Set the minimum required heartbeat for data sources 'in', 'out'
 124 and 'through' to 10000 seconds which is a little over one day in data.rrd.
 125 This would allow to feed old data from mrtg-2.0 right into
 126 rrdtool without generating *UNKNOWN* entries.
 127
 128 =head1 EXAMPLE 2
 129
 130 C<rrdtool tune monitor.rrd --window-length 5 --failure-threshold 3>
 131
 132 If the FAILURES B<RRA> is implicitly created, the default window-length is 9 and
 133 the default failure-thresold is 7. This command now defines a failure as 3 or more
 134 violations in a temporal window of 5 time points.
 135
 136 =head1 AUTHOR
 137
 138 Tobias Oetiker <oetiker@ee.ethz.ch>
 139