src/collectd-threshold.pod

   1 =encoding UTF-8
   2
   3 =head1 NAME
   4
   5 collectd-threshold - Documentation of collectd's I<Threshold plugin>
   6
   7 =head1 SYNOPSIS
   8
   9  LoadPlugin "threshold"
  10  <Plugin "threshold">
  11    <Type "foo">
  12      WarningMin    0.00
  13      WarningMax 1000.00
  14      FailureMin    0.00
  15      FailureMax 1200.00
  16      Invert false
  17      Instance "bar"
  18    </Type>
  19  </Plugin>
  20
  21 =head1 DESCRIPTION
  22
  23 Starting with version C<4.3.0> I<collectd> has support for B<monitoring>. By
  24 that we mean that the values are not only stored or sent somewhere, but that
  25 they are judged and, if a problem is recognized, acted upon. The only action
  26 the I<Threshold plugin> takes itself is to generate and dispatch a
  27 I<notification>. Other plugins can register to receive notifications and
  28 perform appropriate further actions.
  29
  30 Since systems and what you expect them to do differ a lot, you can configure
  31 I<thresholds> for your values freely. This gives you a lot of flexibility but
  32 also a lot of responsibility.
  33
  34 Every time a value is out of range, a notification is dispatched. This means
  35 that the idle percentage of your CPU needs to be less then the configured
  36 threshold only once for a notification to be generated. There's no such thing
  37 as a moving average or similar - at least not now.
  38
  39 Also, all values that match a threshold are considered to be relevant or
  40 "interesting". As a consequence collectd will issue a notification if they are
  41 not received for B<Timeout> iterations. The B<Timeout> configuration option is
  42 explained in section L<collectd.conf(5)/"GLOBAL OPTIONS">. If, for example,
  43 B<Timeout> is set to "2" (the default) and some hosts sends it's CPU statistics
  44 to the server every 60 seconds, a notification will be dispatched after about
  45 120 seconds. It may take a little longer because the timeout is checked only
  46 once each B<Interval> on the server.
  47
  48 When a value comes within range again or is received after it was missing, an
  49 "OKAY-notification" is dispatched.
  50
  51 =head1 CONFIGURATION
  52
  53 Here is a configuration example to get you started. Read below for more
  54 information.
  55
  56  LoadPlugin "threshold"
  57  <Plugin "threshold">
  58    <Type "foo">
  59      WarningMin    0.00
  60      WarningMax 1000.00
  61      FailureMin    0.00
  62      FailureMax 1200.00
  63      Invert false
  64      Instance "bar"
  65    </Type>
  66
  67    <Plugin "interface">
  68      Instance "eth0"
  69      <Type "if_octets">
  70        FailureMax 10000000
  71        DataSource "rx"
  72      </Type>
  73    </Plugin>
  74
  75    <Host "hostname">
  76      <Type "cpu">
  77        Instance "idle"
  78        FailureMin 10
  79      </Type>
  80
  81      <Plugin "memory">
  82        <Type "memory">
  83          Instance "cached"
  84          WarningMin 100000000
  85        </Type>
  86      </Plugin>
  87
  88      <Type "load">
  89         DataSource "midterm"
  90         FailureMax 4
  91         Hits 3
  92         Hysteresis 3
  93      </Type>
  94    </Host>
  95  </Plugin>
  96
  97 There are basically two types of configuration statements: The C<Host>,
  98 C<Plugin>, and C<Type> blocks select the value for which a threshold should be
  99 configured. The C<Plugin> and C<Type> blocks may be specified further using the
 100 C<Instance> option. You can combine the block by nesting the blocks, though
 101 they must be nested in the above order, i.e. C<Host> may contain either
 102 C<Plugin> and C<Type> blocks, C<Plugin> may only contain C<Type> blocks and
 103 C<Type> may not contain other blocks. If multiple blocks apply to the same
 104 value the most specific block is used.
 105
 106 The other statements specify the threshold to configure. They B<must> be
 107 included in a C<Type> block. Currently the following statements are recognized:
 108
 109 =over 4
 110
 111 =item B<FailureMax> I<Value>
 112
 113 =item B<WarningMax> I<Value>
 114
 115 Sets the upper bound of acceptable values. If unset defaults to positive
 116 infinity. If a value is greater than B<FailureMax> a B<FAILURE> notification
 117 will be created. If the value is greater than B<WarningMax> but less than (or
 118 equal to) B<FailureMax> a B<WARNING> notification will be created.
 119
 120 =item B<FailureMin> I<Value>
 121
 122 =item B<WarningMin> I<Value>
 123
 124 Sets the lower bound of acceptable values. If unset defaults to negative
 125 infinity. If a value is less than B<FailureMin> a B<FAILURE> notification will
 126 be created. If the value is less than B<WarningMin> but greater than (or equal
 127 to) B<FailureMin> a B<WARNING> notification will be created.
 128
 129 =item B<DataSource> I<DSName>
 130
 131 Some data sets have more than one "data source". Interesting examples are the
 132 C<if_octets> data set, which has received (C<rx>) and sent (C<tx>) bytes and
 133 the C<disk_ops> data set, which holds C<read> and C<write> operations. The
 134 system load data set, C<load>, even has three data sources: C<shortterm>,
 135 C<midterm>, and C<longterm>.
 136
 137 Normally, all data sources are checked against a configured threshold. If this
 138 is undesirable, or if you want to specify different limits for each data
 139 source, you can use the B<DataSource> option to have a threshold apply only to
 140 one data source.
 141
 142 =item B<Invert> B<true>|B<false>
 143
 144 If set to B<true> the range of acceptable values is inverted, i.e. values
 145 between B<FailureMin> and B<FailureMax> (B<WarningMin> and B<WarningMax>) are
 146 not okay. Defaults to B<false>.
 147
 148 =item B<Persist> B<true>|B<false>
 149
 150 Sets how often notifications are generated. If set to B<true> one notification
 151 will be generated for each value that is out of the acceptable range. If set to
 152 B<false> (the default) then a notification is only generated if a value is out
 153 of range but the previous value was okay.
 154
 155 This applies to missing values, too: If set to B<true> a notification about a
 156 missing value is generated once every B<Interval> seconds. If set to B<false>
 157 only one such notification is generated until the value appears again.
 158
 159 =item B<PersistOK> B<true>|B<false>
 160
 161 Sets how OKAY notifications act. If set to B<true> one notification will be
 162 generated for each value that is in the acceptable range. If set to B<false>
 163 (the default) then a notification is only generated if a value is in range but
 164 the previous value was not.
 165
 166 =item B<Percentage> B<true>|B<false>
 167
 168 If set to B<true>, the minimum and maximum values given are interpreted as
 169 percentage value, relative to the other data sources. This is helpful for
 170 example for the "df" type, where you may want to issue a warning when less than
 171 5E<nbsp>% of the total space is available. Defaults to B<false>.
 172
 173 =item B<Hits> I<Value>
 174
 175 Sets the number of occurrences which the threshold must be raised before to
 176 dispatch any notification or, in other words, the number of B<Interval>s
 177 that the threshold must be match before dispatch any notification.
 178
 179 =item B<Hysteresis> I<Value>
 180
 181 Sets the hysteresis value for threshold. The hysteresis is a method to prevent
 182 flapping between states, until a new received value for a previously matched
 183 threshold down below the threshold condition (B<WarningMax>, B<FailureMin> or
 184 everything else) minus the hysteresis value, the failure (respectively warning)
 185 state will be keep.
 186
 187 =item B<Interesting> B<true>|B<false>
 188
 189 If set to B<true> (the default), a notification with severity C<FAILURE> will
 190 be created when a matching value list is no longer updated and purged from the
 191 internal cache. When this happens depends on the I<interval> of the value list
 192 and the global B<Timeout> setting. See the B<Interval> and B<Timeout> settings
 193 in L<collectd.conf(5)> for details. If set to B<false>, this event will be
 194 ignored.
 195
 196 =back
 197
 198 =head1 SEE ALSO
 199
 200 L<collectd(1)>,
 201 L<collectd.conf(5)>
 202
 203 =head1 AUTHOR
 204
 205 Florian Forster E<lt>octoE<nbsp>atE<nbsp>collectd.orgE<gt>