=encoding UTF-8 =head1 NAME collectd.conf - Configuration for the system statistics collection daemon B =head1 SYNOPSIS BaseDir "/path/to/data/" PIDFile "/path/to/pidfile/collectd.pid" Server "123.123.123.123" 12345 LoadPlugin cpu LoadPlugin load Interval 3600 LoadPlugin ping Host "example.org" Host "provider.net" =head1 DESCRIPTION This config file controls how the system statistics collection daemon B behaves. The most significant option is B, which controls which plugins to load. These plugins ultimately define collectd's behavior. The syntax of this config file is similar to the config file of the famous I webserver. Each line contains either an option (a key and a list of one or more values) or a section-start or -end. Empty lines and everything after a non-quoted hash-symbol (C<#>) is ignored. I are unquoted strings, consisting only of alphanumeric characters and the underscore (C<_>) character. Keys are handled case insensitive by I itself and all plugins included with it. I can either be an I, a I (enclosed in double-quotes) a I or a I expression. I consist of only alphanumeric characters and underscores (C<_>) and do not need to be quoted. I are enclosed in double quotes (C<">). You can use the backslash character (C<\>) to include double quotes as part of the string. I can be specified in decimal and floating point format (using a dot C<.> as decimal separator), hexadecimal when using the C<0x> prefix and octal with a leading zero (C<0>). I values are either B or B. Lines may be wrapped by using C<\> as the last character before the newline. This allows long lines to be split into multiple lines. Quoted strings may be wrapped as well. However, those are treated special in that whitespace at the beginning of the following lines will be ignored, which allows for nicely indenting the wrapped lines. The configuration is read and processed in order, i.e. from top to bottom. So the 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. Also, the C option B occur B the appropriate CPlugin ...E> block. =head1 GLOBAL OPTIONS =over 4 =item B I Sets the base directory. This is the directory beneath all RRD-files are created. Possibly more subdirectories are created. This is also the working directory for the daemon. =item B I Loads the plugin I. This is required to load plugins, unless the B option is enabled (see below). Without any loaded plugins, I will be mostly useless. Only the first B statement or block for a given plugin name has any effect. This is useful when you want to split up the configuration into smaller files and want each file to be "self contained", i.e. it contains a B block I then appropriate B statement. The downside is that if you have multiple conflicting B blocks, e.g. when they specify different intervals, only one of them (the first one encountered) will take effect and all others will be silently ignored. B may either be a simple configuration I or a I with additional options, affecting the behavior of B. A simple statement looks like this: LoadPlugin "cpu" Options inside a B block can override default settings and influence the way plugins are loaded, e.g.: Globals true Interval 60 The following options are valid inside B blocks: =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. =item B I Sets a plugin-specific interval for collecting metrics. This overrides the global B setting. If a plugin provides own support for specifying an interval, that setting will take precedence. =back =item B B|B When set to B (the default), each plugin needs to be loaded explicitly, using the B statement documented above. If a BPluginE...E> block is encountered and no configuration handling callback for this plugin has been registered, a warning is logged and the block is ignored. When set to B, explicit B statements are not required. Each BPluginE...E> block acts as if it was immediately preceded by a B statement. B statements are still required for plugins that don't provide any configuration, e.g. the I. =item B I [I] If I points to a file, includes that file. If I points to a directory, recursively includes all files within that directory and its subdirectories. If the C function is available on your system, shell-like wildcards are expanded before files are included. This means you can use statements like the following: Include "/etc/collectd.d/*.conf" Starting with version 5.3, this may also be a block in which further options affecting the behavior of B may be specified. The following option is currently allowed: Filter "*.conf" =over 4 =item B I If the C function is available on your system, a shell-like wildcard I may be specified to filter which files to include. This may be used in combination with recursively including a directory to easily be able to arbitrarily mix configuration files and other documents (e.g. README files). The given example is similar to the first example above but includes all files matching C<*.conf> in any subdirectory of C: Include "/etc/collectd.d" "*.conf" =back If more than one files are included by a single B option, the files will be included in lexicographical order (as defined by the C function). Thus, you can e.Eg. use numbered prefixes to specify the order in which the files are loaded. To prevent loops and shooting yourself in the foot in interesting ways the nesting is limited to a depth of 8Elevels, which should be sufficient for most uses. Since symlinks are followed it is still possible to crash the daemon by looping symlinks. In our opinion significant stupidity should result in an appropriate amount of pain. It is no problem to have a block like CPlugin fooE> in more than one file, but you cannot include files from within blocks. =item B I Sets where to write the PID file to. This file is overwritten when it exists and deleted when the program is stopped. Some init-scripts might override this setting using the B<-P> command-line option. =item B I Path to the plugins (shared objects) of collectd. =item B I [I ...] Set one or more files that contain the data-set descriptions. See L for a description of the format of this file. =item B I 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 you may want to increase this if you have more than five plugins that take a long time to read. Mostly those are plugins that do network-IO. Setting this to a value higher than the number of registered read callbacks is not recommended. =item B I Number of threads to start for dispatching value lists to write plugins. The default value is B<5>, but you may want to increase this if you have more than five plugins that may take relatively long to write to. =item B I =item B I Metrics are read by the I and then put into a queue to be handled by the I. If one of the I is slow (e.g. network timeouts, I/O saturation of the disk) this queue will grow. In order to avoid running into memory issues in such a case, you can limit the size of this queue. By default, there is no limit and memory may grow indefinitely. This is most likely not an issue for clients, i.e. instances that only handle the local metrics. For servers it is recommended to set this to a non-zero value, though. You can set the limits using B and B. Each of them takes a numerical argument which is the number of metrics in the queue. If there are I metrics in the queue, any new metrics I be dropped. If there are less than I metrics in the queue, all new metrics I be enqueued. If the number of metrics currently in the queue is between I and I, the metric is dropped with a probability that is proportional to the number of metrics in the queue (i.e. it increases linearly until it reaches 100%.) If B is set to non-zero and B is unset, the latter will default to half of B. If you do not want to randomly drop values when the queue size is between I and I, set If B and B to same value. =item B I Sets the hostname that identifies a host. If you omit this setting, the hostname will be determined using the L system call. =item B B 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. This option is enabled by default. =item B I =item B I Configure the name of the "pre-cache chain" and the "post-cache chain". Please see L below on information on chains and how these setting change the daemon's behavior. =back =head1 PLUGIN OPTIONS Some plugins may register own options. These options must be enclosed in a C-Section. Which options exist depends on the plugin used. Some plugins require external configuration, too. The C, for example, required C to be configured in the webserver you're going to collect data from. These plugins are listed below as well, even if they don't require any configuration within collectd's configuration file. 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 makes it possible to aggregate several values into one using aggregation functions such as I, I, I and I. This can be put to a wide variety of uses, e.g. average and total CPU statistics for your entire fleet. The grouping is powerful but, as with many powerful tools, may be a bit difficult to wrap your head around. The grouping will therefore be demonstrated using an example: The average and sum of the CPU usage across all CPUs of each host is to be calculated. To select all the affected values for our example, set C and C. The other values are left unspecified, meaning "all values". The I, I, I, I and I options work as if they were specified in the C clause of an C