| 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 its 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> |