X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=f7ec2a8f3f6a72ab64511ee6b0f29f57dada1335;hb=2fea822b3984376e9b7ef58ed7d3f087bc65af8c;hp=2eb8d3043184c37b882a05cc50e5520d418d60cb;hpb=105c64c6f20807fa105b6aa350cc79c0d3a38488;p=collectd.git diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod index 2eb8d304..f7ec2a8f 100644 --- a/src/collectd.conf.pod +++ b/src/collectd.conf.pod @@ -57,6 +57,37 @@ directory for the daemon. Loads the plugin I. There must be at least one such line or B will be mostly useless. +Starting with collectd 4.9, this may also be a block in which further options +affecting the behavior of B may be specified. The following +options are allowed inside a B block: + + + Globals true + + +=over 4 + +=item B B + +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. + +This is useful (or possibly even required), e.g., when loading a plugin that +embeds some scripting language into the daemon (e.g. the I and +I). 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.g., L or +L) for details. + +By default, this is disabled. As a special exception, if the plugin name is +either C or C, the default is changed to enabled in order to keep +the average user from ever having to deal with this low level linking stuff. + +=back + =item B I If I points to a file, includes that file. If I points to a @@ -102,6 +133,20 @@ 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. +B You should set this once and then never touch it again. If you do, +I or know some serious RRDtool +magic! (Assuming you're using the I or I plugin.) + +=item B I + +Consider a value list "missing" when no update has been read or received for +I iterations. By default, I considers a value list +missing when no update has been received for twice the update interval. Since +this setting uses iterations, the maximum allowed time without update depends +on the I information contained in each value list. This is used in +the I configuration to dispatch notifications about missing values, +see L for details. + =item B I Number of threads to start for reading plugins. The default value is B<5>, but @@ -118,13 +163,8 @@ hostname will be determined using the L system call. If B 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. - -Using this feature (i.Ee. setting this option to B) is recommended. -However, to preserve backwards compatibility the default is set to B. -The sample config file that is installed with Cinstall> includes a -line which sets this option, though, so that default installations will have -this setting enabled. +This is done using a lookup of the name returned by C. This option +is enabled by default. =item B I @@ -149,6 +189,143 @@ A list of all plugins and a short summary for each plugin can be found in the F file shipped with the sourcecode and hopefully binary packets as well. +=head2 Plugin C + +The I can be used to communicate with other instances of +I or third party applications using an AMQP message broker. Values +are sent to or received from the broker, which handles routing, queueing and +possibly filtering or messages. + + + # Send values to an AMQP broker + + Host "localhost" + Port "5672" + VHost "/" + User "guest" + Password "guest" + Exchange "amq.fanout" + # ExchangeType "fanout" + # RoutingKey "collectd" + # Persistent false + # Format "command" + # StoreRates false + + + # Receive values from an AMQP broker + + Host "localhost" + Port "5672" + VHost "/" + User "guest" + Password "guest" + Exchange "amq.fanout" + # ExchangeType "fanout" + # Queue "queue_name" + # RoutingKey "collectd.#" + + + +The plugin's configuration consists of a number of I and I +blocks, which configure sending and receiving of values respectively. The two +blocks are very similar, so unless otherwise noted, an option can be used in +either block. The name given in the blocks starting tag is only used for +reporting messages, but may be used to support I of certain +I blocks in the future. + +=over 4 + +=item B I + +Hostname or IP-address of the AMQP broker. Defaults to the default behavior of +the underlying communications library, I, which is "localhost". + +=item B I + +Service name or port number on which the AMQP broker accepts connections. This +argument must be a string, even if the numeric form is used. Defaults to +"5672". + +=item B I + +Name of the I on the AMQP broker to use. Defaults to "/". + +=item B I + +=item B I + +Credentials used to authenticate to the AMQP broker. By default "guest"/"guest" +is used. + +=item B I + +In I blocks, this option specifies the I to send values to. +By default, "amq.fanout" will be used. + +In I blocks this option is optional. If given, a I between +the given exchange and the I is created, using the I if +configured. See the B and B options below. + +=item B I + +If given, the plugin will try to create the configured I with this +I after connecting. When in a I block, the I will then +be bound to this exchange. + +=item B I (Subscribe only) + +Configures the I name to subscribe to. If no queue name was configures +explicitly, a unique queue name will be created by the broker. + +=item B I + +In I blocks, this configures the routing key to set on all outgoing +messages. If not given, the routing key will be computed from the I +of the value. The host, plugin, type and the two instances are concatenated +together using dots as the separator and all containing dots replaced with +slashes. For example "collectd.host/example/com.cpu.0.cpu.user". This makes it +possible to receive only specific values using a "topic" exchange. + +In I blocks, configures the I used when creating a +I between an I and the I. The usual wildcards can be +used to filter messages when using a "topic" exchange. If you're only +interested in CPU statistics, you could use the routing key "collectd.*.cpu.#" +for example. + +=item B B|B (Publish only) + +Selects the I to use. If set to B, the I +mode will be used, i.e. delivery is guaranteed. If set to B (the +default), the I delivery mode will be used, i.e. messages may be +lost due to high load, overflowing queues or similar issues. + +=item B B|B (Publish only) + +Selects the format in which messages are sent to the broker. If set to +B (the default), values are sent as C commands which are +identical to the syntax used by the I and I. In this +case, the C header field will be set to C. + +If set to B, the values are encoded in the I, +an easy and straight forward exchange format. The C header field +will be set to C. + +A subscribing client I use the C header field to +determine how to decode the values. Currently, the I itself can +only decode the B format. + +=item B B|B (Publish only) + +Determines whether or not C, C and C data sources +are converted to a I (i.e. a C value). If set to B (the +default), no conversion is performed. Otherwise the conversion is performed +using the internal value cache. + +Please note that currently this option is only used if the B option has +been set to B. + +=back + =head2 Plugin C To configure the C-plugin you first need to configure the Apache @@ -167,7 +344,25 @@ Since its C module is very similar to Apache's, B is also supported. It introduces a new field, called C, to count the number of currently connected clients. This field is also supported. -The following options are accepted by the C-plugin: +The configuration of the I plugin consists of one or more +CInstanceE/E> blocks. Each block requires one string argument +as the instance name. For example: + + + + URL "http://www1.example.com/mod_status?auto" + + + URL "http://www2.example.com/mod_status?auto" + + + +The instance name will be used as the I. To emulate the old +(versionE4) behavior, you can use an empty string (""). In order for the +plugin to work correctly, each instance name must be unique. This is not +enforced by the plugin and it is your responsibility to ensure it. + +The following options are accepted within each I block: =over 4 @@ -175,7 +370,7 @@ The following options are accepted by the C-plugin: Sets the URL of the C output. This needs to be the output generated by C and it needs to be the machine readable output -generated by appending the C argument. +generated by appending the C argument. This option is I. =item B I @@ -544,22 +739,6 @@ runtime statistics module of CouchDB -Another CouchDB example: -The following example will collect the status values from each database: - - - Instance "dbs" - - Type "gauge" - - - Type "counter" - - - Type "bytes" - - - In the B block, there may be one or more B blocks, each defining a URL to be fetched via HTTP (using libcurl) and one or more B blocks. The B string argument must be in a path format, which is used to collect a @@ -619,6 +798,110 @@ Type-instance to use. Defaults to the current map key or current string array el =back +=head2 Plugin C + +The B uses B (L) and B +(L) to retrieve XML data via cURL. + + + + Host "my_host" + Instance "some_instance" + User "collectd" + Password "thaiNg0I" + VerifyPeer true + VerifyHost true + CACert "/path/to/ca.crt" + + + Type "magic_level" + #InstancePrefix "prefix-" + InstanceFrom "td[1]" + ValuesFrom "td[2]/span[@class=\"level\"]" + + + + +In the B block, there may be one or more B blocks, each defining a +URL to be fetched via HTTP (using libcurl). Within each B block there are +options which specify the connection parameters, for example authentication +information, and one or more B blocks. + +Each B block specifies how to get one type of information. The +string argument must be a valid XPath expression which returns a list +of "base elements". One value is dispatched for each "base element". The +I and values are looked up using further I expressions +that should be relative to the base element. + +Within the B block the following options are accepted: + +=over 4 + +=item B I + +Use I as the host name when submitting values. Defaults to the global +host name setting. + +=item B I + +Use I as the plugin instance when submitting values. Defaults to an +empty string (no plugin instance). + +=item B I +=item B I +=item B B|B +=item B B|B +=item B I + +These options behave exactly equivalent to the appropriate options of the +I and I plugins. Please see there for a detailed description. + +=item EB IE + +Within each B block, there must be one or more B blocks. Each +B block specifies how to get one type of information. The string +argument must be a valid XPath expression which returns a list of "base +elements". One value is dispatched for each "base element". + +Within the B block the following options are accepted: + +=over 4 + +=item B I + +Specifies the I used for submitting patches. This determines the number +of values that are required / expected and whether the strings are parsed as +signed or unsigned integer or as double values. See L for details. +This option is required. + +=item B I + +Prefix the I with I. The values are simply +concatenated together without any separator. +This option is optional. + +=item B I + +Specifies a XPath expression to use for determining the I. The +XPath expression must return exactly one element. The element's value is then +used as I, possibly prefixed with I (see above). + +This value is required. As a special exception, if the "base XPath expression" +(the argument to the B block) returns exactly one argument, then this +option may be omitted. + +=item B I [I ...] + +Specifies one or more XPath expression to use for reading the values. The +number of XPath expressions must match the number of data sources in the +I specified with B (see above). Each XPath expression must return +exactly one element. The element's value is then parsed as a number and used as +value for the appropriate value in the value list dispatched to the daemon. + +=back + +=back + =head2 Plugin C This plugin uses the B library (L) to @@ -885,22 +1168,6 @@ Report using the device name rather than the mountpoint. i.e. with this I (the default), it will report a disk as "root", but with it I, it will be "sda1" (or whichever). -=item B B|B - -When enabled, the blocks reserved for root are reported separately. When -disabled (the default for backwards compatibility reasons) the reserved space -will be included in the "free" space. - -When disabled, the "df" type will be used to store "free" and "used" space. The -mount point or disk name (see option B) is used as type -instance in this case (again: backwards compatibility). - -When enabled, the type "df_complex" is used and three files are created. The -mount point or disk name is used as plugin instance and the type instance is -set to "free", "reserved" and "used" as appropriate. - -Enabling this option is recommended. - =item B B|B Enables or disables reporting of free, reserved and used inodes. Defaults to @@ -1104,6 +1371,12 @@ note that there are 1000 bytes in a kilobyte, not 1024. Controls whether or not to recurse into subdirectories. Enabled by default. +=item B I|I + +Controls whether or not to include "hidden" files and directories in the count. +"Hidden" files and directories are those, whose name begins with a dot. +Defaults to I, i.e. by default hidden files and directories are ignored. + =back =head2 Plugin C @@ -1214,13 +1487,6 @@ Hostname to connect to. Defaults to B<127.0.0.1>. TCP-Port to connect to. Defaults to B<7634>. -=item B I|I - -If enabled, translate the disk names to major/minor device numbers -(e.Eg. "8-0" for /dev/sda). For backwards compatibility this defaults to -I but it's recommended to disable it as it will probably be removed in -the next major version. - =back =head2 Plugin C @@ -1448,6 +1714,16 @@ You can also specify combinations of these fields. For example B means to concatenate the guest name and UUID (with a literal colon character between, thus I<"foo:1234-1234-1234-1234">). +=item B B|B
+ +When the libvirt plugin logs interface data, it sets the name of the collected +data according to this setting. The default is to use the path as provided by +the hypervisor (the "dev" property of the target node), which is equal to +setting B. + +B
means use the interface's mac address. This is useful since the +interface path might change between reboots of a guest or across migrations. + =back =head2 Plugin C @@ -1466,19 +1742,51 @@ debugging support. Sets the file to write log messages to. The special strings B and B can be used to write to the standard output and standard error -channels, respectively. This, of course, only makes much sense when collectd is -running in foreground- or non-daemon-mode. +channels, respectively. This, of course, only makes much sense when I +is running in foreground- or non-daemon-mode. =item B B|B Prefix all lines printed by the current time. Defaults to B. +=item B B|B + +When enabled, all lines are prefixed by the severity of the log message, for +example "warning". Defaults to B. + =back B: There is no need to notify the daemon after moving or removing the log file (e.Eg. when rotating the logs). The plugin reopens the file for each line it writes. +=head2 Plugin C + +The I reads CPU statistics of I, a +virtualization technique for IBM POWER processors. It takes into account CPU +time stolen from or donated to a partition, in addition to the usual user, +system, I/O statistics. + +The following configuration options are available: + +=over 4 + +=item B B|B + +When enabled, statistics about the processor pool are read, too. The partition +needs to have pool authority in order to be able to acquire this information. +Defaults to false. + +=item B B|B + +If enabled, the serial of the physical machine the partition is currently +running on is reported as I and the logical hostname of the machine +is reported in the I. Otherwise, the logical hostname will be +used (just like other plugins) and the I will be empty. +Defaults to false. + +=back + =head2 Plugin C The C uses mbmon to retrieve temperature, voltage, etc. @@ -1573,12 +1881,175 @@ TCP-Port to connect to. Defaults to B<11211>. =back +=head2 Plugin C + +The B connects to a Modbus "slave" via Modbus/TCP and reads +register values. It supports reading single registers (unsigned 16Ebit +values), large integer values (unsigned 32Ebit values) and floating point +values (two registers interpreted as IEEE floats in big endian notation). + +Synopsis: + + + RegisterBase 0 + RegisterType float + Type voltage + Instance "input-1" + + + + RegisterBase 2 + RegisterType float + Type voltage + Instance "input-2" + + + + + + Address "192.168.0.42" + Port "502" + Interval 60 + + + Instance "power-supply" + Collect "voltage-input-1" + Collect "voltage-input-2" + + + + Instance "power-supply" + Datagroup "device-type-1" + + + +=over 4 + +=item EB IE blocks + +Data blocks define a mapping between register numbers and the "types" used by +I. + +Within EDataE/E blocks, the following options are allowed: + +=over 4 + +=item B I + +Configures the base register to read from the device. If the option +B has been set to B or B, this and the next +register will be read (the register number is increased by one). + +=item B B|B|B + +Specifies what kind of data is returned by the device. If the type is B +or B, two 16Ebit registers will be read and the data is combined +into one value. Defaults to B. + +=item B I + +Specifies the "type" (data set) to use when dispatching the value to +I. Currently, only data sets with exactly one data source are +supported. + +=item B I + +Sets the type instance to use when dispatching the value to I. If +unset, an empty string (no type instance) is used. + +=back + +=item EB IE blocks + +Datagroup blocks define a group of B-definitions. Datagroups can be used +to collect the same data from a number of similar devices. + +Within EDatagroupE/E blocks, the following options are allowed: + +=over 4 + +=item B I + +Specifies which data to include in the datagroup. I must be the same +string as the I argument passed to a B block. You can specify this +option multiple times to include more than one value in the datagroup. All +values in the datagroup will be collected from the devices that use is. At +least one B option is mandatory. + +=back + +=item EB IE blocks + +Host blocks are used to specify to which hosts to connect and what data to read +from their "slaves". The string argument I is used as hostname when +dispatching the values to I. + +Within EHostE/E blocks, the following options are allowed: + +=over 4 + +=item B
I + +Specifies the node name (the actual network address) used to connect to the +host. This may be an IP address or a hostname. Please note that the used +I library only supports IPv4 at the moment. + +=item B I + +Specifies the port used to connect to the host. The port can either be given as +a number or as a service name. Please note that the I argument must be +a string, even if ports are given in their numerical form. Defaults to "502". + +=item B I + +Sets the interval (in seconds) in which the values will be collected from this +host. By default the global B setting will be used. + +=item EB IE + +Over each TCP connection, multiple Modbus devices may be reached. The slave ID +is used to specify which device should be addressed. For each device you want +to query, one B block must be given. + +Within ESlaveE/E blocks, the following options are allowed: + +=over 4 + +=item B I + +Specify the plugin instance to use when dispatching the values to I. +By default "slave_I" is used. + +=item B I + +Specifies which data to retrieve from the device. I must be the same +string as the I argument passed to a B block. You can specify this +option multiple times to collect more than one value from a slave. At least one +B or B option is mandatory. + +=item B I + +Specifies which data to retrieve from the device. I must be the +same string as the I argument passed to a B block. All data +specified in the Datagroup definition will be retrieved from the device. You +can specify this option multiple or combine it with the B option. At +least one B or B option is mandatory. + +=back + +=back + +=back + =head2 Plugin C The C requires B to be installed. It connects to one or more databases when started and keeps the connection up as long as possible. When the connection is interrupted for whatever reason it will try -to re-connect. The plugin will complaint loudly in case anything goes wrong. +to re-connect. The plugin will complain loudly in case anything goes wrong. This plugin issues the MySQL C / C command and collects information about MySQL network traffic, executed statements, @@ -2271,6 +2742,15 @@ B require this setting. This feature is only available if the I plugin was linked with I. +=item B I + +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 +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. + =back =item BListen> I [I]B> @@ -2319,6 +2799,14 @@ Each time a packet is received, the modification time of the file is checked using L. If the file has been changed, the contents is re-read. While the file is being read, it is locked using L. +=item B I + +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 +behavior is, to let the kernel choose the appropriate interface. Thus incoming +traffic gets only accepted, if it arrives on the given interface. + =back =item B I<1-255> @@ -2331,7 +2819,7 @@ operating systems. =item B I<1024-65535> Set the maximum size for datagrams received over the network. Packets larger -than this will be truncated. +than this will be truncated. Defaults to 1452Ebytes. =item B I @@ -2342,16 +2830,6 @@ the same multicast group. While this results in more network traffic than necessary it's not a huge problem since the plugin has a duplicate detection, so the values will not loop. -=item B I - -For each host/plugin/type combination the C caches the time of -the last value being sent or received. Every I seconds the plugin -searches and removes all entries that are older than I seconds, thus -freeing the unused memory again. Since this process is somewhat expensive and -normally doesn't do much, this value should not be too small. The default is -1800 seconds, but setting this to 86400 seconds (one day) will not do much harm -either. - =item B B|B The network plugin cannot only receive and send statistics, it can also create @@ -2668,12 +3146,24 @@ and the client's "common name" will be used as type instance. This is required when reading multiple status files. Enabling this option is recommended, but to maintain backwards compatibility this option is disabled by default. -=item B B|B +=item B B|B Sets whether or not statistics about the compression used by OpenVPN should be collected. This information is only available in I mode. Enabled by default. +=item B B|B + +Sets whether or not traffic information is collected for each connected client +individually. If set to false, currently no traffic data is collected at all +because aggregating this data in a save manner is tricky. Defaults to B. + +=item B B|B + +When enabled, the number of currently connected clients or users is collected. +This is especially interesting when B is disabled, but +can be configured independently from that option. Defaults to B. + =back =head2 Plugin C @@ -2743,6 +3233,83 @@ refer to them from. This plugin embeds a Perl-interpreter into collectd and provides an interface to collectd's plugin system. See L for its documentation. +=head2 Plugin C + +The I receives profiling information from I, an extension +for the I 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: + + + Address "::0" + Port "30002" + # Overall statistics for the website. + + Server "www.example.com" + + # Statistics for www-a only + + Host "www-a.example.com" + Server "www.example.com" + + # Statistics for www-b only + + Host "www-b.example.com" + Server "www.example.com" + + + +The plugin provides the following configuration options: + +=over 4 + +=item B
I + +Configures the address used to open a listening socket. By default, plugin will +bind to the I address C<::0>. + +=item B I + +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 argument. + +=item EB IE 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 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 I + +Matches the hostname of the system the webserver / script is running on. This +will contain the result of the L system call. If not +configured, all hostnames will be accepted. + +=item B I + +Matches the name of the I, 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