Merge branch 'collectd-5.5'
[collectd.git] / 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>