X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.conf.pod;h=a279d0b084b55944edfd0916de0eb86f87578de7;hb=442f435a3d57762d7db6ed23307e3e32478e68be;hp=1f9367353d8fc2291710591d7846a4937e6a6612;hpb=56159e13f4b983a2e8c846b39ca96b2384ec746a;p=collectd.git diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod index 1f936735..a279d0b0 100644 --- a/src/collectd.conf.pod +++ b/src/collectd.conf.pod @@ -279,6 +279,32 @@ available. This is done with the C configuration option: inet localhost port 8053; }; +The configuration follows the grouping that can be seen when looking at the +data with an XSLT compatible viewer, such as a modern web browser. It's +probably a good idea to make yourself familiar with the provided values, so you +can understand what the collected statistics actually mean. + +Synopsis: + + + URL "http://localhost:8053/" + OpCodes true + QTypes true + + ServerStats true + ZoneMaintStats true + ResolverStats false + MemoryStats true + + + QTypes true + ResolverStats true + CacheRRSets true + + Zone "127.in-addr.arpa/IN" + + + The bind plugin accepts the following configuration options: =over 4 @@ -288,34 +314,198 @@ The bind plugin accepts the following configuration options: URL from which to retrieve the XML data. If not specified, C will be used. -=item B I|I - =item B I|I -=item B I|I +When enabled, statistics about the I<"OpCodes">, for example the number of +C packets, are collected. + +Default: Enabled. + +=item B I|I + +When enabled, the number of I queries by query types (for example +C, C, C) is collected. + +Default: Enabled. + +=item B I|I + +Collect global server statistics, such as requests received over IPv4 and IPv6, +successful queries, and failed updates. + +Default: Enabled. + +=item B I|I + +Collect zone maintenance statistics, mostly information about notifications +(zone updates) and zone transfers. + +Default: Enabled. + +=item B I|I + +Collect resolver statistics, i.Ee. statistics about outgoing requests +(e.Eg. queries over IPv4, lame servers). Since the global resolver +counters apparently were removed in BIND 9.5.1 and 9.6.0, this is disabled by +default. Use the B option within a B block +instead for the same functionality. + +Default: Disabled. + +=item B + +Collect global memory statistics. + +Default: Enabled. + +=item B I + +Collect statistics about a specific I<"view">. BIND can behave different, +mostly depending on the source IP-address of the request. These different +configurations are called "views". If you don't use this feature, you most +likely are only interested in the C<_default> view. + +Within a EBEIE block, you can specify which +information you want to collect about a view. If no B block is +configured, no detailed view statistics will be collected. + +=over 4 + +=item B I|I + +If enabled, the number of I queries by query type (e.Eg. C, +C) is collected. + +Default: Enabled. + +=item B I|I + +Collect resolver statistics, i.Ee. statistics about outgoing requests +(e.Eg. queries over IPv4, lame servers). + +Default: Enabled. + +=item B I|I + +If enabled, the number of entries (I<"RR sets">) in the view's cache by query +type is collected. Negative entries (queries which resulted in an error, for +example names that do not exist) are reported with a leading exclamation mark, +e.Eg. "!A". + +Default: Enabled. + +=item B I + +When given, collect detailed information about the given zone in the view. The +information collected if very similar to the global B information +(see above). + +You can repeat this option to collect detailed information about multiple +zones. + +By default no detailed zone information is collected. + +=back + +=back + +=head2 Plugin C + +The couchdb plugin uses B (L) and B +(L) to collect values from CouchDB +documents (stored JSON notation). -=item B I|I +The following example will collect several values from the built-in `_stats' +runtime statistics module (L). -=item B I|I + + + Instance "httpd" + + Type "http_requests" + -=item B I|I + + Type "http_request_methods" + -=item B I|I + + Type "http_response_codes" + + + + +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 (libcurl) and one or more B blocks. +The B string argument must be in a path format, of which is used to collect +a value from a JSON map object. If a B path element is that of a I<*> wildcard, +the values for all keys will be collectd. + +The following options are valid within B blocks: + +=over 4 + +=item B I -=item B I|I +Sets the plugin instance to I. -=item B I|I +=item B I -=item B I|I +Username to use if authorization is required to read the page. + +=item B I + +Password to use if authorization is required to read the page. + +=item B B|B + +Enable or disable peer SSL certificate verification. See +L for details. Enabled by default. -=item B I|I +=item B B|B -=item B I|I +Enable or disable peer host name verification. If enabled, the plugin checks if +the C or a C field of the SSL certificate +matches the host name provided by the B option. If this identity check +fails, the connection is aborted. Obviously, only works when connecting to a +SSL enabled server. Enabled by default. -=item B I|I +=item B I -Enables or disables collection of specific counters. -TODO: Options must be described in detail! +File that holds one or more SSL certificates. If you want to use HTTPS you will +possibly need this option. What CA certificates come bundled with C +and are checked by default depends on the distribution you use. + +=back + +The following options are valid within B blocks: + +=over 4 + +=item B I + +Sets the type used to dispatch the values to the daemon. Detailed information +about types and their configuration can be found in L. This +option is mandatory. + +=item B I + +Type-instance to use. Defaults to the current map key or current string array element value. =back @@ -347,6 +537,79 @@ number. =back +=head2 Plugin C + +The curl plugin uses the B (L) to read web pages +and the match infrastructure (the same code used by the tail plugin) to use +regular expressions with the received data. + +The following example will read the current value of AMD stock from google's +finance page and dispatch the value to collectd. + + + + URL "http://finance.google.com/finance?q=NYSE%3AAMD" + User "foo" + Password "bar" + + Regex "]*> *([0-9]*\\.[0-9]+) *" + DSType "GaugeAverage" + # Note: `stock_value' is not a standard type. + Type "stock_value" + Instance "AMD" + + + + +In the B block, there may be one or more B blocks, each defining +a web page and one or more "matches" to be performed on the returned data. The +string argument to the B block is used as plugin instance. + +The following options are valid within B blocks: + +=over 4 + +=item B I + +URL of the web site to retrieve. Since a regular expression will be used to +extract information from this data, non-binary data is a big plus here ;) + +=item B I + +Username to use if authorization is required to read the page. + +=item B I + +Password to use if authorization is required to read the page. + +=item B B|B + +Enable or disable peer SSL certificate verification. See +L for details. Enabled by default. + +=item B B|B + +Enable or disable peer host name verification. If enabled, the plugin checks if +the C or a C field of the SSL certificate +matches the host name provided by the B option. If this identity check +fails, the connection is aborted. Obviously, only works when connecting to a +SSL enabled server. Enabled by default. + +=item B I + +File that holds one or more SSL certificates. If you want to use HTTPS you will +possibly need this option. What CA certificates come bundled with C +and are checked by default depends on the distribution you use. + +=item BMatchE> + +One or more B blocks that define how to match information in the data +returned by C. The C plugin uses the same infrastructure that's +used by the C plugin, so please see the documentation of the C +plugin below on how matches are defined. + +=back + =head2 Plugin C This plugin uses the B library (L) to @@ -366,7 +629,7 @@ than those of other plugins. It usually looks something like this: MinVersion 50000 Type "gauge" - InstancePrefix "out_of_stock" + InstancePrefix "out_of_stock" InstancesFrom "category" ValuesFrom "value" @@ -443,6 +706,9 @@ like this: use a more strict database server, you may have to select from a dummy table or something.) +Please note that some databases, for example B, will fail if you +include a semicolon at the end of the statement. + =item B I =item B I @@ -490,20 +756,24 @@ There must be exactly one B option inside each B block. =item B I -Prepends I followed by a dash I<("-")> to the type instance. See -B on how the rest of the type instance is built. +Prepends I to the type instance. If B (see below) is not +given, the string is simply copied. If B is given, I and +all strings returned in the appropriate columns are concatenated together, +separated by dashes I<("-")>. =item B I [I ...] -Specifies the columns whose values will be used to create the "TypeInstance" -for each row. You need to specify at least one column for each query. If you -specify more than one column, the value of all columns will be join together -with the hyphen as separation character. +Specifies the columns whose values will be used to create the "type-instance" +for each row. If you specify more than one column, the value of all columns +will be joined together with dashes I<("-")> as separation characters. The plugin itself does not check whether or not all built instances are -different. It's your responsibility to assure that each is unique. +different. It's your responsibility to assure that each is unique. This is +especially true, if you do not specify B: B have to make +sure that only one row is returned in this case. -There must be at least one B option inside each B block. +If neither B nor B is given, the type-instance +will be empty. =item B I [I ...] @@ -651,6 +921,10 @@ may not work on certain platforms, such as MacEOSEX. Ignore packets that originate from this address. +=item B B|B + +Enabled by default, collects unknown (and thus presented as numeric only) query types. + =back =head2 Plugin C @@ -792,94 +1066,85 @@ Controls whether or not to recurse into subdirectories. Enabled by default. =back -=head2 Plugin C +=head2 Plugin C -This plugin allows you to filter and rewrite value lists based on -Perl-compatible regular expressions whose syntax and semantics are as close as -possible to those of the Perl 5 language. See L for details. +The I plugin received the multicast traffic sent by B, the +statistics collection daemon of Ganglia. Mappings for the standard "metrics" +are built-in, custom mappings may be added via B blocks, see below. - - - Host "^mail\d+$" - Plugin "^tcpconns$" - TypeInstance "^SYN_" +Synopsis: - Action NoWrite - + + MCReceiveFrom "239.2.11.71" "8649" + + Type "swap" + TypeInstance "total" + DataSource "value" + + + Type "swap" + TypeInstance "free" + DataSource "value" + + - - Plugin "^sensors$" - PluginInstance "^Some Weird Sensor Chip Name Prefix" +The following metrics are built-in: - SubstitutePluginInstance "foo" - - +=over 4 -The configuration consists of one or more C blocks, each of which -specifies a regular expression identifying a set of value lists and how to -handle successful matches. A value list keeps the values of a single data-set -and is identified by the tuple (host, plugin, plugin instance, type, type -instance). The plugin and type instances are optional components. If they are -missing they are treated as empty strings. Within those blocks, the following -options are recognized: +=item * -=over 4 +load_one, load_five, load_fifteen -=item B I +=item * -=item B I +cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio -=item B I +=item * -=item B I +mem_free, mem_shared, mem_buffers, mem_cached, mem_total -=item B I +=item * -Specifies the regular expression for each component of the identifier. If any -of these options is missing it is interpreted as a pattern which matches any -string. All five components of a value list have to match the appropriate -regular expression to trigger the specified action. +bytes_in, bytes_out -=item B I|I|I +=item * -Specify how to handle successful matches: +pkts_in, pkts_out -=over 4 +=back -=item B +Available configuration options: -Do not send the value list to any output (a.k.a. write) plugins. +=over 4 -=item B +=item B I [I] -Skip threshold checking for this value list. +Sets sets the multicast group and UDP port to which to subscribe. -=item B +Default: B<239.2.11.71>E/EB<8649> -Completely ignore this value list. +=item EB IE -=back +These blocks add a new metric conversion to the internal table. I, the +string argument to the B block, is the metric name as used by Ganglia. -Two or more actions may be combined by specifying multiple B options. +=over 4 -=item B I +=item B I -=item B I +Type to map this metric to. Required. -=item B I +=item B I -=item B I +Type-instance to use. Optional. -=item B I +=item B I -Upon a successful match, the matching substring will be replaced by the -specified I text. These options require that an appropriate regex -has been specified before, e.Eg. B requires that the -B option has been specified before. +Data source to map this metric to. If the configured type has exactly one data +source, this is optional. Otherwise the option is required. -B: It is not recommended to modify the type unless you really know what -you are doing. The type is used to identify the data-set definition of the -dispatched values. +=back =back @@ -1007,6 +1272,62 @@ and all other interrupts are collected. =back +=head2 Plugin C + +The I plugin makes it possible to write extensions for collectd in Java. +This section only discusses the syntax and semantic of the configuration +options. For more in-depth information on the I plugin, please read +L. + +Synopsis: + + + JVMArg "-verbose:jni" + JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java" + LoadPlugin "org.collectd.java.Foobar" + + # To be parsed by the plugin + + + +Available configuration options: + +=over 4 + +=item B I + +Argument that is to be passed to the I (JVM). This works +exactly the way the arguments to the I binary on the command line work. +Execute C--help> for details. + +Please note that B these options must appear B (i.Ee. above) +any other options! When another option is found, the JVM will be started and +later options will have to be ignored! + +=item B I + +Instantiates a new I object. The constructor of this object very +likely then registers one or more callback methods with the server. + +See L for details. + +When the first such option is found, the virtual machine (JVM) is created. This +means that all B options must appear before (i.Ee. above) all +B options! + +=item B I + +The entire block is passed to the Java plugin as an +I object. + +For this to work, the plugin has to register a configuration callback first, +see L. This means, that the B block +must appear after the appropriate B block. Also note, that I +depends on the (Java) plugin registering the callback and is completely +independent from the I argument passed to B. + +=back + =head2 Plugin C This plugin allows CPU, disk and network load to be collected for virtualized @@ -1138,6 +1459,57 @@ TCP-Port to connect to. Defaults to B<411>. =back +=head2 Plugin C + +The C connects to a memcached server, queries one or more +given I and parses the returned data according to user specification. +The I used are the same as the matches used in the C and C +plugins. + +In order to talk to the memcached server, this plugin uses the I +library. Please note that there is another library with a very similar name, +libmemcache (notice the missing `d'), which is not applicable. + +Synopsis of the configuration: + + + + Server "localhost" + Key "page_key" + + Regex "(\\d+) bytes sent" + DSType CounterAdd + Type "ipt_octets" + Instance "type_instance" + + + + +The configuration options are: + +=over 4 + +=item EB IE + +Each B block defines one I to be queried from the memcached server. +The block requires one string argument which is used as I. + +=item B I
+ +Sets the server address to connect to when querying the page. Must be inside a +B block. + +=item B I + +When connected to the memcached server, asks for the page I. + +=item EBE + +Match blocks define which strings to look for and how matches substrings are +interpreted. For a description of match blocks, please see L<"Plugin tail">. + +=back + =head2 Plugin C The C connects to a memcached server and queries statistics @@ -1158,19 +1530,50 @@ TCP-Port to connect to. Defaults to B<11211>. =head2 Plugin C -The C requires B to be installed. It connects to the -database 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. +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. + +This plugin issues the MySQL C / C command +and collects information about MySQL network traffic, executed statements, +requests, the query cache and threads by evaluating the +C, C, C, C and C +return values. Please refer to the B, I<5.1.6. Server +Status Variables> for an explanation of these values. + +Optionally, master and slave statistics may be collected in a MySQL +replication setup. In that case, information about the synchronization state +of the nodes are collected by evaluating the C return value of the +C command and the C, +C and C return values of the +C command. See the B, +I<12.5.5.21 SHOW MASTER STATUS Syntax> and +I<12.5.5.31 SHOW SLAVE STATUS Syntax> for details. + +Synopsis: + + + + Host "hostname" + User "username" + Password "password" + Port "3306" + MasterStats true + -This plugin issues the MySQL C command and collects information -about MySQL network traffic, executed statements, requests, the query cache -and threads by evaluating the C, C, -C, C and C return values. Please refer to the -B, I<5.1.6. Server Status Variables> for an -explanation of these values. + + Host "localhost" + Socket "/var/run/mysql/mysqld.sock" + SlaveStats true + SlaveNotifications true + + -Use the following options to configure the plugin: +A B block defines one connection to a MySQL database. It accepts a +single argument which specifies the name of the database. None of the other +options are required. MySQL will use default values as documented in the +section "mysql_real_connect()" in the B. =over 4 @@ -1210,6 +1613,17 @@ only has any effect, if B is set to B (the default). Otherwise, use the B option above. See the documentation for the C function for details. +=item B I + +=item B I + +Enable the collection of master / slave statistics in a replication setup. + +=item B I + +If enabled, the plugin sends a notification if the replication slave I/O and / +or SQL threads are not running. + =back =head2 Plugin C @@ -1291,32 +1705,119 @@ specified statistics will not be collected. =head2 Plugin C +The Network plugin sends data to a remote instance of collectd, receives data +from a remote instance, or both at the same time. Data which has been received +from the network is usually not transmitted again, but this can be actived, see +the B option below. + +The default IPv6 multicast group is C. The default IPv4 +multicast group is C<239.192.74.66>. The default I port is B<25826>. + +Both, B and B can be used as single option or as block. When +used as block, given options are valid for this socket only. For example: + + + Server "collectd.internal.tld" + + SecurityLevel "sign" + Username "myhostname" + Password "ohl0eQue" + + + =over 4 -=item B I [I] +=item BServer> I [I]B> + +The B statement/block sets the server to send datagrams to. The +statement may occur multiple times to send each datagram to multiple +destinations. + +The argument I may be a hostname, an IPv4 address or an IPv6 address. The +optional second argument specifies a port number or a service name. If not +given, the default, B<25826>, is used. + +The following options are recognized within B blocks: + +=over 4 + +=item B B|B|B + +Set the security you require for network communication. When the security level +has been set to B, data sent over the network will be encrypted using +I. The integrity of encrypted packets is ensured using I. When +set to B, transmitted data is signed using the I message +authentication code. When set to B, data is sent without any security. + +This feature is only available if the I plugin was linked with +I. + +=item B I -=item B I [I] +Sets the username to transmit. This is used by the server to lookup the +password. See B below. All security levels except B require +this setting. -The B statement sets the server to send datagrams B. The statement -may occur multiple times to send each datagram to multiple destinations. +This feature is only available if the I plugin was linked with +I. + +=item B I + +Sets a password (shared secret) for this socket. All security levels except +B require this setting. + +This feature is only available if the I plugin was linked with +I. + +=back + +=item BListen> I [I]B> The B statement sets the interfaces to bind to. When multiple statements are found the daemon will bind to multiple interfaces. The argument I may be a hostname, an IPv4 address or an IPv6 address. If the argument is a multicast address the daemon will join that multicast group. +The optional second argument specifies a port number or a service name. If not +given, the default, B<25826>, is used. -If no B statement is found the server tries join both, the default IPv6 -multicast group and the default IPv4 multicast group. If no B statement -is found the client will try to send data to the IPv6 multicast group first. If -that fails the client will try the IPv4 multicast group. +The following options are recognized within CListenE> blocks: -The default IPv6 multicast group is C. The default IPv4 -multicast group is C<239.192.74.66>. +=over 4 + +=item B B|B|B + +Set the security you require for network communication. When the security level +has been set to B, only encrypted data will be accepted. The integrity +of encrypted packets is ensured using I. When set to B, only +signed and encrypted data is accepted. When set to B, all data will be +accepted. If an B option was given (see below), encrypted data is +decrypted if possible. + +This feature is only available if the I plugin was linked with +I. -The optional I argument sets the port to use. It can either be given -using a numeric port number or a service name. If the argument is omitted the -default port B<25826> is assumed. +=item B I + +Sets a file in which usernames are mapped to passwords. These passwords are +used to verify signatures and to decrypt encrypted network packets. If +B is set to B, this is optional. If given, signed data is +verified and encrypted packets are decrypted. Otherwise, signed data is +accepted without checking the signature and encrypted data cannot be decrypted. +For the other security levels this option is mandatory. + +The file format is very simple: Each line consists of a username followed by a +colon and any number of spaces followed by the password. To demonstrate, an +example file could look like this: + + user0: foo + user1: bar + +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. + +=back =item B I<1-255> @@ -1418,6 +1919,61 @@ has been specified, the default is used as well. =back +=head2 Plugin C + +The I plugin uses the I library to send notifications to a +configured email address. + +I is available from L. + +Available configuration options: + +=over 4 + +=item B I
+ +Email address from which the emails should appear to come from. + +Default: C + +=item B I
+ +Configures the email address(es) to which the notifications should be mailed. +May be repeated to send notifications to multiple addresses. + +At least one B must be present for the plugin to work correctly. + +=item B I + +Hostname of the SMTP server to connect to. + +Default: C + +=item B I + +TCP port to connect to. + +Default: C<25> + +=item B I + +Username for ASMTP authentication. Optional. + +=item B I + +Password for ASMTP authentication. Optional. + +=item B I + +Subject-template to use when sending emails. There must be exactly two +string-placeholders in the subject, given in the standard I syntax, +i.Ee. C<%s>. The first will be replaced with the severity, the second +with the hostname. + +Default: C + +=back + =head2 Plugin C =over 4 @@ -1450,6 +2006,55 @@ L. =back +=head2 Plugin C + +The I plugin connects to the TCP port opened by the I plugin of +the Optimized Link State Routing daemon and reads information about the current +state of the meshed network. + +The following configuration options are understood: + +=over 4 + +=item B I + +Connect to I. Defaults to B<"localhost">. + +=item B I + +Specifies the port to connect to. This must be a string, even if you give the +port as a number rather than a service name. Defaults to B<"2006">. + +=item B B|B|B + +Specifies what information to collect about links, i.Ee. direct +connections of the daemon queried. If set to B, no information is +collected. If set to B, the number of links and the average of all +I (LQ) and I (NLQ) values is calculated. +If set to B LQ and NLQ are collected per link. + +Defaults to B. + +=item B B|B|B + +Specifies what information to collect about routes of the daemon queried. If +set to B, no information is collected. If set to B, the number of +routes and the average I and I is calculated. If set to B +metric and ETX are collected per route. + +Defaults to B. + +=item B B|B|B + +Specifies what information to collect about the global topology. If set to +B, no information is collected. If set to B, the number of links +in the entire topology and the average I (LQ) is calculated. +If set to B LQ and NLQ are collected for each link in the entire topology. + +Defaults to B. + +=back + =head2 Plugin C B See notes below. @@ -1499,6 +2104,11 @@ enables you to do that: By setting B to I the effect of B is inverted: All selected interfaces are ignored and all other interfaces are collected. +=item B I + +Sets the interval in which all sensors should be read. If not specified, the +global B setting is used. + =back B The C plugin is experimental, because it doesn't yet @@ -1607,6 +2217,13 @@ to collectd's plugin system. See L for its documentation. =head2 Plugin C +The I plugin starts a new thread which sends ICMP "ping" packets to the +configured hosts periodically and measures the network latency. Whenever the +C function of the plugin is called, it submits the average latency, the +standard deviation and the drop rate for each host. + +Available configuration options: + =over 4 =item B I @@ -1614,6 +2231,26 @@ to collectd's plugin system. See L for its documentation. Host to ping periodically. This option may be repeated several times to ping multiple hosts. +=item B I + +Sets the interval in which to send ICMP echo packets to the configured hosts. +This is B the interval in which statistics are queries from the plugin but +the interval in which the hosts are "pinged". Therefore, the setting here +should be smaller than or equal to the global B setting. Fractional +times, such as "1.24" are allowed. + +Default: B<1.0> + +=item B I + +Time to wait for a response from the host to which an ICMP packet had been +sent. If a reply was not received after I seconds, the host is assumed +to be down or the packet to be dropped. This setting must be smaller than the +B setting above for the plugin to work correctly. Fractional +arguments are accepted. + +Default: B<0.9> + =item B I<0-255> Sets the Time-To-Live of generated ICMP packets. @@ -2100,6 +2737,39 @@ slashes. =back +=head2 Plugin C + +Collects a lot of information about various network protocols, such as I, +I, I, etc. + +Available configuration options: + +=over 4 + +=item B I + +Selects whether or not to select a specific value. The string being matched is +of the form "I:I", where I will be used as the +plugin instance and I will be used as type instance. An example of +the string being used would be C. + +You can use regular expressions to match a large number of values with just one +configuration option. To select all "extended" I values, you could use the +following statement: + + Value "/^TcpExt:/" + +Whether only matched values are selected or all matched values are ignored +depends on the B. By default, only matched values are selected. +If no value is configured at all, all values will be selected. + +=item B B|B + +If set to B, inverts the selection made by B, i.Ee. all +matching values will be ignored. + +=back + =head2 Plugin C The C plugin uses the RRDTool accelerator daemon, L, @@ -2227,7 +2897,7 @@ reduces IO-operations and thus lessens the load produced by updating the files. The trade off is that the graphs kind of "drag behind" and that more memory is used. -=item B B +=item B I When collecting many statistics with collectd and the C plugin, you will run serious performance problems. The B setting and the @@ -2305,9 +2975,109 @@ debugging support. =back +=head2 Plugin C + +The C
provides generic means to parse tabular data and dispatch +user specified values. Values are selected based on column numbers. For +example, this plugin may be used to get values from the Linux L +filesystem or CSV (comma separated values) files. + + +
+ Instance "slabinfo" + Separator " " + + Type gauge + InstancePrefix "active_objs" + InstancesFrom 0 + ValuesFrom 1 + + + Type gauge + InstancePrefix "objperslab" + InstancesFrom 0 + ValuesFrom 4 + +
+ + +The configuration consists of one or more B blocks, each of which +configures one file to parse. Within each B
block, there are one or +more B blocks, which configure which data to select and how to +interpret it. + +The following options are available inside a B
block: + +=over 4 + +=item B I + +If specified, I is used as the plugin instance. So, in the above +example, the plugin name C would be used. If omitted, the +filename of the table is used instead, with all special characters replaced +with an underscore (C<_>). + +=item B I + +Any character of I is interpreted as a delimiter between the different +columns of the table. A sequence of two or more contiguous delimiters in the +table is considered to be a single delimiter, i.Ee. there cannot be any +empty columns. The plugin uses the L function to parse the lines +of a table - see its documentation for more details. This option is mandatory. + +A horizontal tab, newline and carriage return may be specified by C<\\t>, +C<\\n> and C<\\r> respectively. Please note that the double backslashes are +required because of collectd's config parsing. + +=back + +The following options are available inside a B block: + +=over 4 + +=item B I + +Sets the type used to dispatch the values to the daemon. Detailed information +about types and their configuration can be found in L. This +option is mandatory. + +=item B I + +If specified, prepend I to the type instance. If omitted, only the +B option is considered for the type instance. + +=item B I [I ...] + +If specified, the content of the given columns (identified by the column +number starting at zero) will be used to create the type instance for each +row. Multiple values (and the instance prefix) will be joined together with +dashes (I<->) as separation character. If omitted, only the B +option is considered for the type instance. + +The plugin itself does not check whether or not all built instances are +different. It’s your responsibility to assure that each is unique. This is +especially true, if you do not specify B: B have to make +sure that the table only contains one row. + +If neither B nor B is given, the type instance +will be empty. + +=item B I [I ...] + +Specifies the columns (identified by the column numbers starting at zero) +whose content is used as the actual data for the data sets that are dispatched +to the daemon. How many such columns you need is determined by the B +setting above. If you specify too many or not enough columns, the plugin will +complain about that and no data will be submitted to the daemon. The plugin +uses L and L to parse counter and gauge values +respectively, so anything supported by those functions is supported by the +plugin as well. This option is mandatory. + +=back + =head2 Plugin C -The C plugins follows logfiles, just like L does, parses +The C follows logfiles, just like L does, parses each line and dispatches found values. What is matched can be configured by the user using (extended) regular expressions, as described in L. @@ -2444,6 +3214,37 @@ will be collected. =back +=head2 Plugin C + +The I plugin connects to a device of "The Energy Detective", a device to +measure power consumption. These devices are usually connected to a serial +(RS232) or USB port. The plugin opens a configured device and tries to read the +current energy readings. For more information on TED, visit +L. + +Available configuration options: + +=over 4 + +=item B I + +Path to the device on which TED is connected. collectd will need read and write +permissions on that file. + +Default: B + +=item B I + +Apparently reading from TED is not that reliable. You can therefore configure a +number of retries here. You only configure the I here, to if you +specify zero, one reading will be performed (but no retries if that fails); if +you specify three, a maximum of four readings are performed. Negative values +are illegal. + +Default: B<0> + +=back + =head2 Plugin C The C counts the number of currently established TCP @@ -2733,16 +3534,16 @@ only one such notification is generated until the value appears again. =head1 FILTER CONFIGURATION -TODO: Update this entire section once development is done. - Starting with collectd 4.6 there is a powerful filtering infrastructure -implemented in the daemon. The concept has mostly been copied from I, -the packet filter infrastructure for Linux. We'll use a similar terminology, so -that users that are familiar with iptables feel right at home. +implemented in the daemon. The concept has mostly been copied from +I, the packet filter infrastructure for Linux. We'll use a similar +terminology, so that users that are familiar with iptables feel right at home. =head2 Terminology -The most important terms are: +The following are the terms used in the remainder of the filter configuration +documentation. For an ASCII-art schema of the mechanism, see +L<"General structure"> below. =over 4 @@ -2751,15 +3552,18 @@ The most important terms are: A I is a criteria to select specific values. Examples are, of course, the name of the value or it's current value. +Matches are implemented in plugins which you have to load prior to using the +match. The name of such plugins starts with the "match_" prefix. + =item B A I is some action that is to be performed with data. Such actions could, for example, be to change part of the value's identifier or to ignore -the value completely. Built-in functions are B and B, see below. +the value completely. -Some targets, for example the built-in B target, signal that processing -of a value should be stopped. In that case processing of the current chain will -be aborted. +Some of these targets are built into the daemon, see L<"Built-in targets"> +below. Other targets are implemented in plugins which you have to load prior to +using the target. The name of such plugins starts with the "target_" prefix. =item B @@ -2768,18 +3572,14 @@ I. The target actions will be performed for all values for which B matches apply. If the rule does not have any matches associated with it, the target action will be performed for all values. -If any target returns the stop condition, the processing will stop right away. -This means that any targets following the current one will not be called after -the stop condition has been returned. - =item B A I is a list of rules and possibly default targets. The rules are tried in order and if one matches, the associated target will be called. If a value is handled by a rule, it depends on the target whether or not any subsequent -rules are considered or if traversal of the chain is aborted. After all rules -have been checked and no target returned the stop condition, the default -targets will be executed. +rules are considered or if traversal of the chain is aborted, see +L<"Flow control"> below. After all rules have been checked, the default targets +will be executed. =back @@ -2816,12 +3616,46 @@ The following shows the resulting structure: ! Target ! +---------+ +=head2 Flow control + +There are four ways to control which way a value takes through the filter +mechanism: + +=over 4 + +=item B + +The built-in B target can be used to "call" another chain, i.Ee. +process the value with another chain. When the called chain finishes, usually +the next target or rule after the jump is executed. + +=item B + +The stop condition, signaled for example by the built-in target B, causes +all processing of the value to be stopped immediately. + +=item B + +Causes processing in the current chain to be aborted, but processing of the +value generally will continue. This means that if the chain was called via +B, the next target or rule after the jump will be executed. If the chain +was not called by another chain, control will be returned to the daemon and it +may pass the value to another chain. + +=item B + +Most targets will signal the B condition, meaning that processing +should continue normally. There is no special built-in target for this +condition. + +=back + =head2 Synopsis The configuration reflects this structure directly: - PostCacheChain "main" - + PostCacheChain "PostCache" + Plugin "^mysql$" @@ -2884,7 +3718,7 @@ read-plugins to the write-plugins: : dispatch values : + - - - - - - - - - + -After the values are passed from the read-plugins to the dispatch functions, +After the values are passed from the "read" plugins to the dispatch functions, the pre-cache chain is run first. The values are added to the internal cache afterwards. The post-cache chain is run after the values have been added to the cache. So why is it such a huge deal if chains are run before or after the @@ -2892,10 +3726,10 @@ values have been added to this cache? Targets that change the identifier of a value list should be executed before the values are added to the cache, so that the name in the cache matches the -name that is used in the write-plugins. The C plugin, too, uses this -cache to receive a list of all available values. If you change the identifier -after the value list has been added to the cache, this may easily lead to -confusion, but it's not forbidden of course. +name that is used in the "write" plugins. The C plugin, too, uses +this cache to receive a list of all available values. If you change the +identifier after the value list has been added to the cache, this may easily +lead to confusion, but it's not forbidden of course. The cache is also used to convert counter values to rates. These rates are, for example, used by the C match (see below). If you use the rate stored in @@ -2969,11 +3803,11 @@ plugins to be loaded: =item B -Signals the "return" condition. This causes the current chain to stop -processing the value and returns control to the calling chain. The calling -chain will continue processing targets and rules just after the B target -(see below). This is very similar to the B target of iptables, see -L. +Signals the "return" condition, see the L<"Flow control"> section above. This +causes the current chain to stop processing the value and returns control to +the calling chain. The calling chain will continue processing targets and rules +just after the B target (see below). This is very similar to the +B target of iptables, see L. This target does not have any options. @@ -2983,9 +3817,9 @@ Example: =item B -Signals the "stop" condition, causing processing of the value to be aborted -immediately. This is similar to the B target of iptables, see -L. +Signals the "stop" condition, see the L<"Flow control"> section above. This +causes processing of the value to be aborted immediately. This is similar to +the B target of iptables, see L. This target does not have any options. @@ -2995,7 +3829,7 @@ Example: =item B -Sends the value to write plugins. +Sends the value to "write" plugins. Available options: @@ -3019,11 +3853,11 @@ Example: =item B -Starts processing the rules of another chain. If the end of that chain is -reached, or a stop condition is encountered, processing will continue right -after the B target, i.Ee. with the next target or the next rule. -This is similar to the B<-j> command line option of iptables, see -L. +Starts processing the rules of another chain, see L<"Flow control"> above. If +the end of that chain is reached, or a stop condition is encountered, +processing will continue right after the B target, i.Ee. with the +next target or the next rule. This is similar to the B<-j> command line option +of iptables, see L. Available options: @@ -3078,6 +3912,50 @@ Example: Plugin "^foobar$" +=item B + +Matches values that have a time which differs from the time on the server. + +This match is mainly intended for servers that receive values over the +C plugin and write them to disk using the C plugin. RRDtool +is very sensitive to the timestamp used when updating the RRD files. In +particular, the time must be ever increasing. If a misbehaving client sends one +packet with a timestamp far in the future, all further packets with a correct +time will be ignored because of that one packet. What's worse, such corrupted +RRD files are hard to fix. + +This match lets one match all values B a specified time range +(relative to the server's time), so you can use the B target (see below) +to ignore the value, for example. + +Available options: + +=over 4 + +=item B I + +Matches all values that are I of the server's time by I or more +seconds. Set to zero for no limit. Either B or B must be +non-zero. + +=item B I + +Matches all values that are I of the server's time by I or +more seconds. Set to zero for no limit. Either B or B must be +non-zero. + +=back + +Example: + + + Future 300 + Past 3600 + + +This example matches all values that are five minutes or more ahead of the +server or one hour (or more) lagging behind. + =item B Matches the actual value of data sources against given minimumE/ maximum @@ -3276,22 +4154,20 @@ If you use collectd with an old configuration, i.Ee. one without a B block, it will behave as it used to. This is equivalent to the following configuration: - + Target "write" -If you specify a B block anywhere, the B target will not be added +If you specify a B, the B target will not be added anywhere and you will have to make sure that it is called where appropriate. We -suggest to add the above snippet as default target to your main chain. - -TODO: Notifications will be implemented using chains, too. Describe that here! +suggest to add the above snippet as default target to your "PostCache" chain. =head2 Examples Ignore all values, where the hostname does not contain a dot, i.Ee. can't be an FQDN. - + Host "^[^\.]*$" @@ -3312,7 +4188,6 @@ L, L, L, L, -L, L, L, L,