doc/rrdtune.txt

   1 RRDTUNE(1)                          rrdtool                         RRDTUNE(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdtune - Modify some basic properties of a Round Robin Database
   7
   8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   9        r\brr\brd\bdt\bto\boo\bol\bl t\btu\bun\bne\be _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [-\b--\b-h\bhe\bea\bar\brt\btb\bbe\bea\bat\bt|-\b-h\bh _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt] [-\b--\b-m\bmi\bin\bni\bi-\b-
  10        m\bmu\bum\bm|-\b-i\bi _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bm_\bi_\bn] [-\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm|-\b-a\ba _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bm_\ba_\bx]
  11        [-\b--\b-d\bda\bat\bta\ba-\b-s\bso\bou\bur\brc\bce\be-\b-t\bty\byp\bpe\be|-\b-d\bd _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bD_\bS_\bT] [-\b--\b-d\bda\bat\bta\ba-\b-s\bso\bou\bur\brc\bce\be-\b-r\bre\ben\bna\bam\bme\be|-\b-r\br _\bo_\bl_\bd_\b-
  12        _\bn_\ba_\bm_\be:_\bn_\be_\bw_\b-_\bn_\ba_\bm_\be] [-\b--\b-d\bde\bel\blt\bta\bap\bpo\bos\bs _\bs_\bc_\ba_\bl_\be_\b-_\bv_\ba_\bl_\bu_\be] [-\b--\b-d\bde\bel\blt\bta\ban\bne\beg\bg _\bs_\bc_\ba_\bl_\be_\b-_\bv_\ba_\bl_\bu_\be]
  13        [-\b--\b-f\bfa\bai\bil\blu\bur\bre\be-\b-t\bth\bhr\bre\bes\bsh\bho\bol\bld\bd _\bf_\ba_\bi_\bl_\bu_\br_\be_\b-_\bt_\bh_\br_\be_\bs_\bh_\bo_\bl_\bd] [-\b--\b-w\bwi\bin\bnd\bdo\bow\bw-\b-l\ble\ben\bng\bgt\bth\bh _\bw_\bi_\bn_\bd_\bo_\bw_\b-_\bl_\be_\bn_\bg_\bt_\bh]
  14        [-\b--\b-a\bal\blp\bph\bha\ba _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br] [-\b--\b-b\bbe\bet\bta\ba _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br] [-\b--\b-g\bga\bam\bmm\bma\ba _\ba_\bd_\ba_\bp_\b-
  15        _\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br] [-\b--\b-g\bga\bam\bmm\bma\ba-\b-d\bde\bev\bvi\bia\bat\bti\bio\bon\bn _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br] [-\b--\b-s\bsm\bmo\boo\bot\bth\bh-\b-
  16        i\bin\bng\bg-\b-w\bwi\bin\bnd\bdo\bow\bw _\bf_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b-_\bo_\bf_\b-_\bs_\be_\ba_\bs_\bo_\bn] [-\b--\b-s\bsm\bmo\boo\bot\bth\bhi\bin\bng\bg-\b-w\bwi\bin\bnd\bdo\bow\bw-\b-d\bde\bev\bvi\bia\bat\bti\bio\bon\bn _\bf_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b-
  17        _\bo_\bf_\b-_\bs_\be_\ba_\bs_\bo_\bn] [-\b--\b-a\bab\bbe\ber\brr\bra\ban\bnt\bt-\b-r\bre\bes\bse\bet\bt _\bd_\bs_\b-_\bn_\ba_\bm_\be]
  18
  19 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  20        The tune option allows you to alter some of the basic configuration
  21        values stored in the header area of a Round Robin Database (R\bRR\bRD\bD).
  22
  23        One application of the t\btu\bun\bne\be function is to relax the validation rules
  24        on an R\bRR\bRD\bD. This allows to fill a new R\bRR\bRD\bD with data available in larger
  25        intervals than what you would normally want to permit. Be very careful
  26        with tune operations for COMPUTE data sources.  Setting the _\bm_\bi_\bn, _\bm_\ba_\bx,
  27        and  _\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt for a COMPUTE data source without changing the data
  28        source type to a non-COMPUTE D\bDS\bST\bT WILL corrupt the data source header in
  29        the R\bRR\bRD\bD.
  30
  31        A second application of the t\btu\bun\bne\be function is to set or alter parameters
  32        used by the specialized function R\bRR\bRA\bAs\bs for aberrant behavior detection.
  33
  34        _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  35                The name of the R\bRR\bRD\bD you want to tune.
  36
  37        -\b--\b-h\bhe\bea\bar\brt\btb\bbe\bea\bat\bt|-\b-h\bh _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt
  38                modify the _\bh_\be_\ba_\br_\bt_\bb_\be_\ba_\bt of a data source. By setting this to a
  39                high value the RRD will accept things like one value per day.
  40
  41        -\b--\b-m\bmi\bin\bni\bim\bmu\bum\bm|-\b-i\bi _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bm_\bi_\bn
  42                alter the minimum value acceptable as input from the data
  43                source.  Setting _\bm_\bi_\bn to 'U' will disable this limit.
  44
  45        -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm|-\b-a\ba _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bm_\ba_\bx
  46                alter the maximum value acceptable as input from the data
  47                source.  Setting _\bm_\ba_\bx to 'U' will disable this limit.
  48
  49        -\b--\b-d\bda\bat\bta\ba-\b-s\bso\bou\bur\brc\bce\be-\b-t\bty\byp\bpe\be|-\b-d\bd _\bd_\bs_\b-_\bn_\ba_\bm_\be:_\bD_\bS_\bT
  50                alter the type D\bDS\bST\bT of a data source.
  51
  52        -\b--\b-d\bda\bat\bta\ba-\b-s\bso\bou\bur\brc\bce\be-\b-r\bre\ben\bna\bam\bme\be|-\b-r\br _\bo_\bl_\bd_\b-_\bn_\ba_\bm_\be:_\bn_\be_\bw_\b-_\bn_\ba_\bm_\be
  53                rename a data source.
  54
  55        -\b--\b-d\bde\bel\blt\bta\bap\bpo\bos\bs _\bs_\bc_\ba_\bl_\be_\b-_\bv_\ba_\bl_\bu_\be
  56                Alter the deviation scaling factor for the upper bound of the
  57                confidence band used internally to calculate violations for the
  58                FAILURES R\bRR\bRA\bA. The default value is 2. Note that this parameter
  59                is not related to graphing confidence bounds which must be
  60                specified as a CDEF argument to generate a graph with confi-
  61                dence bounds. The graph scale factor need not to agree with the
  62                value used internally by the FAILURES R\bRR\bRA\bA.
  63
  64        -\b--\b-d\bde\bel\blt\bta\ban\bne\beg\bg _\bs_\bc_\ba_\bl_\be_\b-_\bv_\ba_\bl_\bu_\be
  65                Alter the deviation scaling factor for the lower bound of the
  66                confidence band used internally to calculate violations for the
  67                FAILURES R\bRR\bRA\bA. The default value is 2. As with -\b--\b-d\bde\bel\blt\bta\bap\bpo\bos\bs, this
  68                argument is unrelated to the scale factor chosen when graphing
  69                confidence bounds.
  70
  71        -\b--\b-f\bfa\bai\bil\blu\bur\bre\be-\b-t\bth\bhr\bre\bes\bsh\bho\bol\bld\bd _\bf_\ba_\bi_\bl_\bu_\br_\be_\b-_\bt_\bh_\br_\be_\bs_\bh_\bo_\bl_\bd
  72                Alter the number of confidence bound violations that constitute
  73                a failure for purposes of the FAILURES R\bRR\bRA\bA. This must be an
  74                integer less than or equal to the window length of the FAILURES
  75                R\bRR\bRA\bA. This restriction is not verified by the tune option, so
  76                one can reset failure-threshold and window-length simultane-
  77                ously. Setting this option will reset the count of violations
  78                to 0.
  79
  80        -\b--\b-w\bwi\bin\bnd\bdo\bow\bw-\b-l\ble\ben\bng\bgt\bth\bh _\bw_\bi_\bn_\bd_\bo_\bw_\b-_\bl_\be_\bn_\bg_\bt_\bh
  81                Alter the number of time points in the temporal window for
  82                determining failures. This must be an integer greater than or
  83                equal to the window length of the FAILURES R\bRR\bRA\bA and less than or
  84                equal to 28. Setting this option will reset the count of viola-
  85                tions to 0.
  86
  87        -\b--\b-a\bal\blp\bph\bha\ba _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br
  88                Alter the intercept adaptation parameter for the Holt-Winters
  89                forecasting algorithm. This parameter must be between 0 and 1.
  90
  91        -\b--\b-b\bbe\bet\bta\ba _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br
  92                Alter the slope adaptation parameter for the Holt-Winters fore-
  93                casting algorithm. This parameter must be between 0 and 1.
  94
  95        -\b--\b-g\bga\bam\bmm\bma\ba _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br
  96                Alter the seasonal coefficient adaptation parameter for the
  97                SEASONAL R\bRR\bRA\bA. This parameter must be between 0 and 1.
  98
  99        -\b--\b-g\bga\bam\bmm\bma\ba-\b-d\bde\bev\bvi\bia\bat\bti\bio\bon\bn _\ba_\bd_\ba_\bp_\bt_\bi_\bo_\bn_\b-_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br
 100                Alter the seasonal deviation adaptation parameter for the
 101                DEVSEASONAL R\bRR\bRA\bA. This parameter must be between 0 and 1.
 102
 103        -\b--\b-s\bsm\bmo\boo\bot\bth\bhi\bin\bng\bg-\b-w\bwi\bin\bnd\bdo\bow\bw _\bf_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b-_\bo_\bf_\b-_\bs_\be_\ba_\bs_\bo_\bn
 104                Alter the size of the smoothing window for the SEASONAL R\bRR\bRA\bA.
 105                This must be between 0 and 1.
 106
 107        -\b--\b-s\bsm\bmo\boo\bot\bth\bhi\bin\bng\bg-\b-w\bwi\bin\bnd\bdo\bow\bw-\b-d\bde\bev\bvi\bia\bat\bti\bio\bon\bn _\bf_\br_\ba_\bc_\bt_\bi_\bo_\bn_\b-_\bo_\bf_\b-_\bs_\be_\ba_\bs_\bo_\bn
 108                Alter the size of the smoothing window for the DEVSEASONAL R\bRR\bRA\bA.
 109                This must be between 0 and 1.
 110
 111        -\b--\b-a\bab\bbe\ber\brr\bra\ban\bnt\bt-\b-r\bre\bes\bse\bet\bt _\bd_\bs_\b-_\bn_\ba_\bm_\be
 112                This option causes the aberrant behavior detection algorithm to
 113                reset for the specified data source; that is, forget all it is
 114                has learnt so far.  Specifically, for the HWPREDICT or MHWPRE-
 115                DICT R\bRR\bRA\bA, it sets the intercept and slope coefficients to
 116                unknown. For the SEASONAL R\bRR\bRA\bA, it sets all seasonal coeffi-
 117                cients to unknown. For the DEVSEASONAL R\bRR\bRA\bA, it sets all sea-
 118                sonal deviation coefficients to unknown. For the FAILURES R\bRR\bRA\bA,
 119                it erases the violation history. Note that reset does not erase
 120                past predictions (the values of the HWPREDICT or MHWPREDICT
 121                R\bRR\bRA\bA), predicted deviations (the values of the DEVPREDICT R\bRR\bRA\bA),
 122                or failure history (the values of the FAILURES R\bRR\bRA\bA).  This
 123                option will function even if not all the listed R\bRR\bRA\bAs\bs are
 124                present.
 125
 126                Due to the implementation of this option, there is an indirect
 127                impact on other data sources in the RRD. A smoothing algorithm
 128                is applied to SEASONAL and DEVSEASONAL values on a periodic
 129                basis. During bootstrap initialization this smoothing is
 130                deferred. For efficiency, the implementation of smoothing is
 131                not data source specific. This means that utilizing reset for
 132                one data source will delay running the smoothing algorithm for
 133                all data sources in the file. This is unlikely to have serious
 134                consequences, unless the data being collected for the non-reset
 135                data sources is unusually volatile during the reinitialization
 136                period of the reset data source.
 137
 138                Use of this tuning option is advised when the behavior of the
 139                data source time series changes in a drastic and permanent man-
 140                ner.
 141
 142 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 1\b1
 143        "rrdtool tune data.rrd -h in:100000 -h out:100000 -h through:100000"
 144
 145        Set the minimum required heartbeat for data sources 'in', 'out' and
 146        'through' to 10'000 seconds which is a little over one day in data.rrd.
 147        This would allow to feed old data from MRTG-2.0 right into RRDtool
 148        without generating *UNKNOWN* entries.
 149
 150 E\bEX\bXA\bAM\bMP\bPL\bLE\bE 2\b2
 151        "rrdtool tune monitor.rrd --window-length 5 --failure-threshold 3"
 152
 153        If the FAILURES R\bRR\bRA\bA is implicitly created, the default window-length is
 154        9 and the default failure-threshold is 7. This command now defines a
 155        failure as 3 or more violations in a temporal window of 5 time points.
 156
 157 A\bAU\bUT\bTH\bHO\bOR\bR
 158        Tobias Oetiker <tobi@oetiker.ch>
 159
 160
 161
 162 1.3.5                             2008-03-15                        RRDTUNE(1)