src/utils_threshold.c: Implemented the new `Persist' option.
[collectd.git] / src / collectd.conf.pod
index b1fcc91..447870d 100644 (file)
@@ -32,6 +32,10 @@ ignored. Values are either string, enclosed in double-quotes,
 B<false>. String containing of only alphanumeric characters and underscores do
 not need to be quoted.
 
+Plugins are loaded in the order listed in this config file. It is a good idea
+to load any logging plugins first in order to catch messages from plugins
+during configuration.
+
 =head1 GLOBAL OPTIONS
 
 =over 4
@@ -73,16 +77,33 @@ Set the file that contains the data-set descriptions.
 =item B<Interval> I<Seconds>
 
 Configures the interval in which to query the read plugins. Obviously smaller
-values lead to a higher system load produces by collectd, while higher values
+values lead to a higher system load produced by collectd, while higher values
 lead to more coarse statistics.
 
 =item B<ReadThreads> I<Num>
 
-Number of threads to start for reading plugins. The default value if B<5>, but
+Number of threads to start for reading plugins. The default value is B<5>, but
 you may want to increase this if you have more than five plugins that take a
 long time to read. Mostly those are plugin that do network-IO. Setting this to
 a value higher than the number of plugins you've loaded is totally useless.
 
+=item B<Hostname> I<Name>
+
+Sets the hostname that identifies a host. If you omit this setting, the
+hostname will be determinded using the L<gethostname(2)> system call.
+
+=item B<FQDNLookup> B<true|false>
+
+If B<Hostname> is determined automatically this setting controls whether or not
+the daemon should try to figure out the "fully qualified domain name", FQDN.
+This is done using a lookup of the name returned by C<gethostname>.
+
+Using this feature (i.E<nbsp>e. setting this option to B<true>) is recommended.
+However, to preserve backwards compatibility the default is set to B<false>.
+The sample config file that is installed with C<makeE<nbsp>install> includes a
+line which sets this option, though, so that default installations will have
+this setting enabled.
+
 =back
 
 =head1 PLUGIN OPTIONS
@@ -175,6 +196,12 @@ installed and an "cpu governor" (that's a kernel module) is loaded.
 Set the directory to store CSV-files under. Per default CSV-files are generated
 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
 
+=item B<StoreRates> B<true|false>
+
+If set to B<true>, convert counter values to rates. If set to B<false> (the
+default) counter values are stored as is, i.E<nbsp>e. as an increasing integer
+number.
+
 =back
 
 =head2 Plugin C<df>
@@ -229,7 +256,7 @@ Sets the socket-file which is to be created.
 
 =item B<SocketGroup> I<Group>
 
-If running as root change the group of the UNIX-socket after it has been 
+If running as root change the group of the UNIX-socket after it has been
 created. Defaults to B<collectd>.
 
 =item B<SocketPerms> I<Permissions>
@@ -712,6 +739,13 @@ Hostname of the host running B<ntpd>. Defaults to B<localhost>.
 
 UDP-Port to connect to. Defaults to B<123>.
 
+=item B<ReverseLookups> B<true>|B<false>
+
+Sets wether or not to perform reverse lookups on peers. Since the name or
+IP-address may be used in a filename it is recommended to disable reverse
+lookups. The default is to do reverse lookups to preserve backwards
+compatibility, though.
+
 =back
 
 =head2 Plugin C<nut>
@@ -934,7 +968,7 @@ Sets the socket-file which is to be created.
 
 =item B<SocketGroup> I<Group>
 
-If running as root change the group of the UNIX-socket after it has been 
+If running as root change the group of the UNIX-socket after it has been
 created. Defaults to B<collectd>.
 
 =item B<SocketPerms> I<Permissions>
@@ -996,6 +1030,106 @@ the F</proc/virtual> filesystem that is required by this plugin.
 
 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
 
+=head1 THRESHOLD CONFIGURATION
+
+Starting with version C<4.3.0> collectd has support for B<monitoring>. By that
+we mean that the values are not only stored or sent somewhere, but that they
+are judged and, if a problem is recognized, acted upon. The only action
+collectd takes itself is to generate and dispatch a "notification". Plugins can
+register to receive notifications and perform appropriate further actions.
+
+Since systems and what you expect them to do differ a lot, you can configure
+B<thresholds> for your values freely. This gives you a lot of flexibility but
+also a lot of responsibility.
+
+Every time a value is out of range a notification is dispatched. This means
+that the idle percentage of your CPU needs to be less then the configured
+threshold only once for a notification to be generated. There's no such thing
+as a moving average or similar - at least not now.
+
+Also, all values that match a threshold are considered to be relevant or
+"interesting". As a consequence collectd will issue a notification if they are
+not received for twice the last timeout of the values. If, for example, some
+hosts sends it's CPU statistics to the server every 60 seconds, a notification
+will be dispatched after about 120 seconds. It may take a little longer because
+the timeout is checked only once each B<Interval> on the server.
+
+Here is a configuration example to get you started. Read below for more
+information.
+
+ <Threshold>
+   <Type "foo">
+     Min    0.00
+     Max 1000.00
+     Invert false
+     Instance "bar"
+   </Type>
+
+   <Plugin "interface">
+     Instance "eth0"
+     <Type "if_octets">
+       Max 10000000
+     </Type>
+   </Plugin>
+
+   <Host "hostname">
+     <Type "cpu">
+       Instance "idle"
+       Min 10
+     </Type>
+
+     <Plugin "memory">
+       <Type "memory">
+         Instance "cached"
+        Min 100000000
+       </Type>
+     </Plugin>
+   </Host>
+ </Threshold>
+
+There are basically two types of configuration statements: The C<Host>,
+C<Plugin>, and C<Type> blocks select the value for which a threshold should be
+configured. The C<Plugin> and C<Type> blocks may be specified further using the
+C<Instance> option. You can combine the block by nesting the blocks, though
+they must be nested in the above order, i.E<nbsp>e. C<Host> may contain either
+C<Plugin> and C<Type> blocks, C<Plugin> may only contain C<Type> blocks and
+C<Type> may not contain other blocks. If multiple blocks apply to the same
+value the most specific block is used.
+
+The other statements specify the threshold to configure. They B<must> be
+included in a C<Type> block. Currently the following statements are recognized:
+
+=over 4
+
+=item B<Max> I<Value>
+
+Sets the upper bound of acceptable values. If unset defaults to positive
+infinity.
+
+=item B<Min> I<Value>
+
+Sets the lower bound of acceptable values. If unset defaults to negative
+infinity.
+
+=item B<Invert> B<true>|B<false>
+
+If set to B<true> the range of acceptable values is inverted, i.E<nbsp>e.
+values between B<Min> and B<Max> are not okay. Defaults, of course, to
+B<false>.
+
+=item B<Persist> B<true>|B<false>
+
+Sets how often notifications are generated. If set to B<true> one notification
+will be generated for each value that is out of the acceptable range. If set to
+B<false> (the default) then a notification is only generated if a value is out
+of range but the previous value was okay.
+
+This applies to missing values, too: If set to B<true> a notification about a
+missing value is generated once every B<Interval> seconds. If set to B<false>
+only one such notification is generated until the value appears again.
+
+=back
+
 =head1 SEE ALSO
 
 L<collectd(1)>,