doc/rrdtune.1

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