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.
  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 is specified as a CDEV argument to generate a graph with
  74 confidence bounds. It need agree with the value used internally by the FAILURES
  75 B<RRA> (although common sense dictates it should).
  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 intercept 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 and deviation adaptation parameters the SEASONAL and
 112 DEVSEAONAL B<RRAs>. Must be between 0 and 1.
 113
 114 =back
 115
 116 =head1 EXAMPLE 1
 117
 118 C<rrdtool tune data.rrd -h in:100000 -h out:100000 -h through:100000>
 119
 120 Set the minimum required heartbeat for data sources 'in', 'out'
 121 and 'through' to 10000 seconds which is a little over one day in data.rrd.
 122 This would allow to feed old data from mrtg-2.0 right into
 123 rrdtool without generating *UNKNOWN* entries.
 124
 125 =head1 EXAMPLE 2
 126
 127 C<rrdtool tune monitor.rrd --window-length 5 --failure-threshold 3>
 128
 129 If the FAILURES B<RRA> is implicitly created, the default window-length is 9 and
 130 the default failure-thresold is 7. This command now defines a failure as 3 or more
 131 violations in a temporal window of 5 time points.
 132
 133 =head1 AUTHOR
 134
 135 Tobias Oetiker <oetiker@ee.ethz.ch>
 136