X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=f7ec2a8f3f6a72ab64511ee6b0f29f57dada1335;hb=2fea822b3984376e9b7ef58ed7d3f087bc65af8c;hp=33d4f352fa9830cbdba1e7f83e618a495da133a3;hpb=9988d61c84dfff5d04ddf48f4b93f6c9449cdc41;p=collectd.git diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod index 33d4f352..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 @@ -2661,12 +3139,31 @@ Available options: Specifies the location of the status file. -=item B B|B +=item B B|B + +When enabled, the filename of the status file will be used as plugin instance +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 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 @@ -2736,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