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