doc/rrdtune.1

   1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "RRDTUNE 1"
 127 .TH RRDTUNE 1 "2013-05-23" "1.4.8" "rrdtool"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 rrdtune \- Modify some basic properties of a Round Robin Database
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 \&\fBrrdtool\fR \fBtune\fR \fIfilename\fR
 137 [\fB\-\-heartbeat\fR|\fB\-h\fR\ \fIds-name\fR:\fIheartbeat\fR]
 138 [\fB\-\-minimum\fR|\fB\-i\fR\ \fIds-name\fR:\fImin\fR]
 139 [\fB\-\-maximum\fR|\fB\-a\fR\ \fIds-name\fR:\fImax\fR]
 140 [\fB\-\-data\-source\-type\fR|\fB\-d\fR\ \fIds-name\fR:\fI\s-1DST\s0\fR]
 141 [\fB\-\-data\-source\-rename\fR|\fB\-r\fR\ \fIold-name\fR:\fInew-name\fR]
 142 [\fB\-\-deltapos\fR\ \fIscale-value\fR]
 143 [\fB\-\-deltaneg\fR\ \fIscale-value\fR]
 144 [\fB\-\-failure\-threshold\fR\ \fIfailure-threshold\fR]
 145 [\fB\-\-window\-length\fR\ \fIwindow-length\fR]
 146 [\fB\-\-alpha\fR\ \fIadaption-parameter\fR]
 147 [\fB\-\-beta\fR\ \fIadaption-parameter\fR]
 148 [\fB\-\-gamma\fR\ \fIadaption-parameter\fR]
 149 [\fB\-\-gamma\-deviation\fR\ \fIadaption-parameter\fR]
 150 [\fB\-\-smoothing\-window\fR\ \fIfraction-of-season\fR]
 151 [\fB\-\-smoothing\-window\-deviation\fR\ \fIfraction-of-season\fR]
 152 [\fB\-\-aberrant\-reset\fR\ \fIds-name\fR]
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 The tune option allows you to alter some of the basic configuration
 156 values stored in the header area of a Round Robin Database (\fB\s-1RRD\s0\fR).
 157 .PP
 158 One application of the \fBtune\fR function is to relax the
 159 validation rules on an \fB\s-1RRD\s0\fR. This allows to fill a new \fB\s-1RRD\s0\fR with
 160 data available in larger intervals than what you would normally want
 161 to permit. Be very careful with tune operations for \s-1COMPUTE\s0 data sources.
 162 Setting the \fImin\fR, \fImax\fR, and  \fIheartbeat\fR for a \s-1COMPUTE\s0 data source
 163 without changing the data source type to a non-COMPUTE \fB\s-1DST\s0\fR \s-1WILL\s0 corrupt
 164 the data source header in the \fB\s-1RRD\s0\fR.
 165 .PP
 166 A second application of the \fBtune\fR function is to set or alter parameters
 167 used by the specialized function \fBRRAs\fR for aberrant behavior detection.
 168 .IP "\fIfilename\fR" 8
 169 .IX Item "filename"
 170 The name of the \fB\s-1RRD\s0\fR you want to tune.
 171 .IP "\fB\-\-heartbeat\fR|\fB\-h\fR\ \fIds-name\fR:\fIheartbeat\fR" 8
 172 .IX Item "--heartbeat|-hds-name:heartbeat"
 173 modify the \fIheartbeat\fR of a data source. By setting this to a high
 174 value the \s-1RRD\s0 will accept things like one value per day.
 175 .IP "\fB\-\-minimum\fR|\fB\-i\fR\ \fIds-name\fR:\fImin\fR" 8
 176 .IX Item "--minimum|-ids-name:min"
 177 alter the minimum value acceptable as input from the data source.
 178 Setting \fImin\fR to 'U' will disable this limit.
 179 .IP "\fB\-\-maximum\fR|\fB\-a\fR\ \fIds-name\fR:\fImax\fR" 8
 180 .IX Item "--maximum|-ads-name:max"
 181 alter the maximum value acceptable as input from the data source.
 182 Setting \fImax\fR to 'U' will disable this limit.
 183 .IP "\fB\-\-data\-source\-type\fR|\fB\-d\fR\ \fIds-name\fR:\fI\s-1DST\s0\fR" 8
 184 .IX Item "--data-source-type|-dds-name:DST"
 185 alter the type \fB\s-1DST\s0\fR of a data source.
 186 .IP "\fB\-\-data\-source\-rename\fR|\fB\-r\fR\ \fIold-name\fR:\fInew-name\fR" 8
 187 .IX Item "--data-source-rename|-rold-name:new-name"
 188 rename a data source.
 189 .IP "\fB\-\-deltapos\fR\ \fIscale-value\fR" 8
 190 .IX Item "--deltaposscale-value"
 191 Alter the deviation scaling factor for the upper bound of the
 192 confidence band used internally to calculate violations for the
 193 \&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR. The default value is 2. Note that this parameter is
 194 not related to graphing confidence bounds which must be specified as a
 195 \&\s-1CDEF\s0 argument to generate a graph with confidence bounds. The graph
 196 scale factor need not to agree with the value used internally by the
 197 \&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR.
 198 .IP "\fB\-\-deltaneg\fR\ \fIscale-value\fR" 8
 199 .IX Item "--deltanegscale-value"
 200 Alter the deviation scaling factor for the lower bound of the confidence band
 201 used internally to calculate violations for the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. The default
 202 value is 2. As with \fB\-\-deltapos\fR, this argument is unrelated to the scale
 203 factor chosen when graphing confidence bounds.
 204 .IP "\fB\-\-failure\-threshold\fR\ \fIfailure-threshold\fR" 8
 205 .IX Item "--failure-thresholdfailure-threshold"
 206 Alter the number of confidence bound violations that constitute a failure for
 207 purposes of the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. This must be an integer less than or equal to
 208 the window length of the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. This restriction is not verified by
 209 the tune option, so one can reset failure-threshold and window-length
 210 simultaneously. Setting this option will reset the count of violations to 0.
 211 .IP "\fB\-\-window\-length\fR\ \fIwindow-length\fR" 8
 212 .IX Item "--window-lengthwindow-length"
 213 Alter the number of time points in the temporal window for determining
 214 failures. This must be an integer greater than or equal to the window
 215 length of the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR and less than or equal to 28. Setting
 216 this option will reset the count of violations to 0.
 217 .IP "\fB\-\-alpha\fR\ \fIadaption-parameter\fR" 8
 218 .IX Item "--alphaadaption-parameter"
 219 Alter the intercept adaptation parameter for the Holt-Winters
 220 forecasting algorithm. This parameter must be between 0 and 1.
 221 .IP "\fB\-\-beta\fR\ \fIadaption-parameter\fR" 8
 222 .IX Item "--betaadaption-parameter"
 223 Alter the slope adaptation parameter for the Holt-Winters forecasting
 224 algorithm. This parameter must be between 0 and 1.
 225 .IP "\fB\-\-gamma\fR\ \fIadaption-parameter\fR" 8
 226 .IX Item "--gammaadaption-parameter"
 227 Alter the seasonal coefficient adaptation parameter for the \s-1SEASONAL\s0
 228 \&\fB\s-1RRA\s0\fR. This parameter must be between 0 and 1.
 229 .IP "\fB\-\-gamma\-deviation\fR\ \fIadaption-parameter\fR" 8
 230 .IX Item "--gamma-deviationadaption-parameter"
 231 Alter the seasonal deviation adaptation parameter for the \s-1DEVSEASONAL\s0
 232 \&\fB\s-1RRA\s0\fR. This parameter must be between 0 and 1.
 233 .IP "\fB\-\-smoothing\-window\fR\ \fIfraction-of-season\fR" 8
 234 .IX Item "--smoothing-windowfraction-of-season"
 235 Alter the size of the smoothing window for the \s-1SEASONAL\s0 \fB\s-1RRA\s0\fR. This must
 236 be between 0 and 1.
 237 .IP "\fB\-\-smoothing\-window\-deviation\fR\ \fIfraction-of-season\fR" 8
 238 .IX Item "--smoothing-window-deviationfraction-of-season"
 239 Alter the size of the smoothing window for the \s-1DEVSEASONAL\s0 \fB\s-1RRA\s0\fR. This must
 240 be between 0 and 1.
 241 .IP "\fB\-\-aberrant\-reset\fR\ \fIds-name\fR" 8
 242 .IX Item "--aberrant-resetds-name"
 243 This option causes the aberrant behavior detection algorithm to reset
 244 for the specified data source; that is, forget all it is has learnt so far.
 245 Specifically, for the \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0 \fB\s-1RRA\s0\fR, it sets the intercept and
 246 slope coefficients to unknown. For the \s-1SEASONAL\s0 \fB\s-1RRA\s0\fR, it sets all seasonal
 247 coefficients to unknown. For the \s-1DEVSEASONAL\s0 \fB\s-1RRA\s0\fR, it sets all seasonal
 248 deviation coefficients to unknown. For the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR, it erases the
 249 violation history. Note that reset does not erase past predictions
 250 (the values of the \s-1HWPREDICT\s0 or \s-1MHWPREDICT\s0 \fB\s-1RRA\s0\fR), predicted deviations (the
 251 values of the \s-1DEVPREDICT\s0 \fB\s-1RRA\s0\fR), or failure history (the values of the
 252 \&\s-1FAILURES\s0 \fB\s-1RRA\s0\fR).  This option will function even if not all the listed
 253 \&\fBRRAs\fR are present.
 254 .Sp
 255 Due to the implementation of this option, there is an indirect impact on
 256 other data sources in the \s-1RRD\s0. A smoothing algorithm is applied to
 257 \&\s-1SEASONAL\s0 and \s-1DEVSEASONAL\s0 values on a periodic basis. During bootstrap
 258 initialization this smoothing is deferred. For efficiency, the implementation
 259 of smoothing is not data source specific. This means that utilizing
 260 reset for one data source will delay running the smoothing algorithm
 261 for all data sources in the file. This is unlikely to have serious
 262 consequences, unless the data being collected for the non-reset data sources
 263 is unusually volatile during the reinitialization period of the reset
 264 data source.
 265 .Sp
 266 Use of this tuning option is advised when the behavior of the data source
 267 time series changes in a drastic and permanent manner.
 268 .SH "EXAMPLE 1"
 269 .IX Header "EXAMPLE 1"
 270 \&\f(CW\*(C`rrdtool tune data.rrd \-h in:100000 \-h out:100000 \-h through:100000\*(C'\fR
 271 .PP
 272 Set the minimum required heartbeat for data sources 'in', 'out'
 273 and 'through' to 10'000 seconds which is a little over one day in data.rrd.
 274 This would allow to feed old data from \s-1MRTG\-2\s0.0 right into
 275 RRDtool without generating *UNKNOWN* entries.
 276 .SH "EXAMPLE 2"
 277 .IX Header "EXAMPLE 2"
 278 \&\f(CW\*(C`rrdtool tune monitor.rrd \-\-window\-length 5 \-\-failure\-threshold 3\*(C'\fR
 279 .PP
 280 If the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR is implicitly created, the default
 281 window-length is 9 and the default failure-threshold is 7. This
 282 command now defines a failure as 3 or more violations in a temporal
 283 window of 5 time points.
 284 .SH "AUTHOR"
 285 .IX Header "AUTHOR"
 286 Tobias Oetiker <tobi@oetiker.ch>