Merge branch 'collectd-4.9' into collectd-4.10

[collectd.git] / src / collectd.conf.pod

diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index 773fc36..187133c 100644 (file)
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -57,6 +57,33 @@ directory for the daemon.
 Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
 will be mostly useless.
 
 Loads the plugin I<Plugin>. There must be at least one such line or B<collectd>
 will be mostly useless.
 

+Starting with collectd 4.9, this may also be a block in which further options
+affecting the behavior of B<LoadPlugin> may be specified. The following
+options are allowed inside a B<LoadPlugin> block:
+
+  <LoadPlugin perl>
+    Globals true
+  </LoadPlugin>
+
+=over 4
+
+=item B<Globals> B<true|false>
+
+If enabled, collectd will export all global symbols of the plugin (and of all
+libraries loaded as dependencies of the plugin) and, thus, makes those symbols
+available for resolving unresolved symbols in subsequently loaded plugins if
+that is supported by your system. By default, this is disabled.
+
+This is useful (or possibly even required), e.E<nbsp>g., when loading a plugin
+that embeds some scripting language into the daemon (e.E<nbsp>g. the C<perl>
+or C<python> plugins). Scripting languages usually provide means to load
+extensions written in C. Those extensions require symbols provided by the
+interpreter, which is loaded as a dependency of the respective collectd
+plugin. See the documentation of those plugins (e.E<nbsp>g.,
+L<collectd-perl(5)> or L<collectd-python(5)>) for details.
+
+=back
+

 =item B<Include> I<Path>
 
 If I<Path> points to a file, includes that file. If I<Path> points to a
 =item B<Include> I<Path>
 
 If I<Path> points to a file, includes that file. If I<Path> points to a


@@ -102,6 +129,10 @@ Configures the interval in which to query the read plugins. Obviously smaller
 values lead to a higher system load produced by collectd, while higher values
 lead to more coarse statistics.
 
 values lead to a higher system load produced by collectd, while higher values
 lead to more coarse statistics.
 

+B<Warning:> You should set this once and then never touch it again. If you do,
+I<you will have to delete all your RRD files> or know some serious RRDtool
+magic! (Assuming you're using the I<RRDtool> or I<RRDCacheD> plugin.)
+

 =item B<Timeout> I<Iterations>
 
 Consider a value list "missing" when no update has been read or received for
 =item B<Timeout> I<Iterations>
 
 Consider a value list "missing" when no update has been read or received for


@@ -1880,8 +1911,10 @@ Hostname of the database server. Defaults to B<localhost>.
 =item B<User> I<Username>
 
 Username to use when connecting to the database. The user does not have to be
 =item B<User> I<Username>
 
 Username to use when connecting to the database. The user does not have to be

-granted any privileges (which is synonym to granting the C<USAGE> privilege).
-Any existing MySQL user will do.
+granted any privileges (which is synonym to granting the C<USAGE> privilege),
+unless you want to collectd replication statistics (see B<MasterStats> and
+B<SlaveStats> below). In this case, the user needs the C<REPLICATION CLIENT>
+(or C<SUPER>) privileges. Else, any existing MySQL user will do.

 
 =item B<Password> I<Password>
 
 
 =item B<Password> I<Password>
 


@@ -1913,7 +1946,9 @@ C<mysql_real_connect> function for details.
 
 =item B<SlaveStats> I<true|false>
 
 
 =item B<SlaveStats> I<true|false>
 

-Enable the collection of master / slave statistics in a replication setup.
+Enable the collection of master / slave statistics in a replication setup. In
+order to be able to get access to these statistics, the user needs special
+privileges. See the B<User> documentation above.

 
 =item B<SlaveNotifications> I<true|false>
 
 
 =item B<SlaveNotifications> I<true|false>
 


@@ -2527,7 +2562,7 @@ I<libgcrypt>.
 Set the outgoing interface for IP packets. This applies at least
 to IPv6 packets and if possible to IPv4. If this option is not applicable,
 undefined or a non-existent interface name is specified, the default
 Set the outgoing interface for IP packets. This applies at least
 to IPv6 packets and if possible to IPv4. If this option is not applicable,
 undefined or a non-existent interface name is specified, the default

-behaviour is to let the kernel choose the appropriate interface. Be warned
+behavior is to let the kernel choose the appropriate interface. Be warned

 that the manual selection of an interface for unicast traffic is only
 necessary in rare cases.
 
 that the manual selection of an interface for unicast traffic is only
 necessary in rare cases.
 


@@ -2584,7 +2619,7 @@ the file is being read, it is locked using L<fcntl(2)>.
 Set the incoming interface for IP packets explicitly. This applies at least
 to IPv6 packets and if possible to IPv4. If this option is not applicable,
 undefined or a non-existent interface name is specified, the default
 Set the incoming interface for IP packets explicitly. This applies at least
 to IPv6 packets and if possible to IPv4. If this option is not applicable,
 undefined or a non-existent interface name is specified, the default

-behaviour is, to let the kernel choose the appropriate interface. Thus incoming
+behavior is, to let the kernel choose the appropriate interface. Thus incoming

 traffic gets only accepted, if it arrives on the given interface.
 
 =back
 traffic gets only accepted, if it arrives on the given interface.
 
 =back


@@ -2681,7 +2716,8 @@ and are checked by default depends on the distribution you use.
 This plugin sends a desktop notification to a notification daemon, as defined
 in the Desktop Notification Specification. To actually display the
 notifications, B<notification-daemon> is required and B<collectd> has to be
 This plugin sends a desktop notification to a notification daemon, as defined
 in the Desktop Notification Specification. To actually display the
 notifications, B<notification-daemon> is required and B<collectd> has to be

-able to access the X server.
+able to access the X server (i.E<nbsp>e., the C<DISPLAY> and C<XAUTHORITY>
+environment variables have to be set correctly) and the D-Bus message bus.

 
 The Desktop Notification Specification can be found at
 L<http://www.galago-project.org/specs/notification/>.
 
 The Desktop Notification Specification can be found at
 L<http://www.galago-project.org/specs/notification/>.


@@ -2951,7 +2987,7 @@ because aggregating this data in a save manner is tricky. Defaults to B<true>.
 =item B<CollectUserCount> B<true>|B<false>
 
 When enabled, the number of currently connected clients or users is collected.
 =item B<CollectUserCount> B<true>|B<false>
 
 When enabled, the number of currently connected clients or users is collected.

-This is expecially interesting when B<CollectIndividualUsers> is disabled, but
+This is especially interesting when B<CollectIndividualUsers> is disabled, but

 can be configured independently from that option. Defaults to B<false>.
 
 =back
 can be configured independently from that option. Defaults to B<false>.
 
 =back


@@ -3023,6 +3059,83 @@ refer to them from.
 This plugin embeds a Perl-interpreter into collectd and provides an interface
 to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
 
 This plugin embeds a Perl-interpreter into collectd and provides an interface
 to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
 

+=head2 Plugin C<pinba>
+
+The I<Pinba plugin> receives profiling information from I<Pinba>, an extension
+for the I<PHP> interpreter. At the end of executing a script, i.e. after a
+PHP-based webpage has been delivered, the extension will send a UDP packet
+containing timing information, peak memory usage and so on. The plugin will
+wait for such packets, parse them and account the provided information, which
+is then dispatched to the daemon once per interval.
+
+Synopsis:
+
+ <Plugin pinba>
+   Address "::0"
+   Port "30002"
+   # Overall statistics for the website.
+   <View "www-total">
+     Server "www.example.com"
+   </View>
+   # Statistics for www-a only
+   <View "www-a">
+     Host "www-a.example.com"
+     Server "www.example.com"
+   </View>
+   # Statistics for www-b only
+   <View "www-b">
+     Host "www-b.example.com"
+     Server "www.example.com"
+   </View>
+ </Plugin>
+
+The plugin provides the following configuration options:
+
+=over 4
+
+=item B<Address> I<Node>
+
+Configures the address used to open a listening socket. By default, plugin will
+bind to the I<any> address C<::0>.
+
+=item B<Port> I<Service>
+
+Configures the port (service) to bind to. By default the default Pinba port
+"30002" will be used. The option accepts service names in addition to port
+numbers and thus requires a I<string> argument.
+
+=item E<lt>B<View> I<Name>E<gt> block
+
+The packets sent by the Pinba extension include the hostname of the server, the
+server name (the name of the virtual host) and the script that was executed.
+Using B<View> blocks it is possible to separate the data into multiple groups
+to get more meaningful statistics. Each packet is added to all matching groups,
+so that a packet may be accounted for more than once.
+
+=over 4
+
+=item B<Host> I<Host>
+
+Matches the hostname of the system the webserver / script is running on. This
+will contain the result of the L<gethostname(2)> system call. If not
+configured, all hostnames will be accepted.
+
+=item B<Server> I<Server>
+
+Matches the name of the I<virtual host>, i.e. the contents of the
+C<$_SERVER["SERVER_NAME"]> variable when within PHP. If not configured, all
+server names will be accepted.
+
+=item B<Script> I<Script>
+
+Matches the name of the I<script name>, i.e. the contents of the
+C<$_SERVER["SCRIPT_NAME"]> variable when within PHP. If not configured, all
+script names will be accepted.
+
+=back
+
+=back
+

 =head2 Plugin C<ping>
 
 The I<Ping> plugin starts a new thread which sends ICMP "ping" packets to the
 =head2 Plugin C<ping>
 
 The I<Ping> plugin starts a new thread which sends ICMP "ping" packets to the


@@ -3076,7 +3189,7 @@ operating systems.
 
 =item B<MaxMissed> I<Packets>
 
 
 =item B<MaxMissed> I<Packets>
 

-Trigger a DNS resolv after the host has not replied to I<Packets> packets. This
+Trigger a DNS resolve after the host has not replied to I<Packets> packets. This

 enables the use of dynamic DNS services (like dyndns.org) with the ping plugin.
 
 Default: B<-1> (disabled)
 enables the use of dynamic DNS services (like dyndns.org) with the ping plugin.
 
 Default: B<-1> (disabled)


@@ -4098,25 +4211,37 @@ Use the last number found.
 
 =item B<CounterSet>
 
 
 =item B<CounterSet>
 

-The matched number is a counter. Simply sets the internal counter to this
-value.
+=item B<DeriveSet>
+
+=item B<AbsoluteSet>
+
+The matched number is a counter. Simply I<sets> the internal counter to this
+value. Variants exist for C<COUNTER>, C<DERIVE>, and C<ABSOLUTE> data sources.

 
 =item B<CounterAdd>
 
 
 =item B<CounterAdd>
 

-Add the matched value to the internal counter.
+=item B<DeriveAdd>
+
+Add the matched value to the internal counter. In case of B<DeriveAdd>, the
+matched number may be negative, which will effectively subtract from the
+internal counter.

 
 =item B<CounterInc>
 
 
 =item B<CounterInc>
 

-Increase the internal counter by one. This B<DSType> is the only one that does
-not use the matched subexpression, but simply counts the number of matched
+=item B<DeriveInc>
+
+Increase the internal counter by one. These B<DSType> are the only ones that do
+not use the matched subexpression, but simply count the number of matched

 lines. Thus, you may use a regular expression without submatch in this case.
 
 =back
 
 As you'd expect the B<Gauge*> types interpret the submatch as a floating point
 lines. Thus, you may use a regular expression without submatch in this case.
 
 =back
 
 As you'd expect the B<Gauge*> types interpret the submatch as a floating point

-number, using L<strtod(3)>. The B<CounterSet> and B<CounterAdd> interpret the
-submatch as an integer using L<strtoll(3)>. B<CounterInc> does not use the
-submatch at all and it may be omitted in this case.
+number, using L<strtod(3)>. The B<Counter*> and B<AbsoluteSet> types interpret
+the submatch as an unsigned integer using L<strtoull(3)>. The B<Derive*> types
+interpret the submatch as a signed integer using L<strtoll(3)>. B<CounterInc>
+and B<DeriveInc> do not use the submatch at all and it may be omitted in this
+case.

 
 =item B<Type> I<Type>
 
 
 =item B<Type> I<Type>