NAME¶

SYNOPSIS¶

  BaseDir "/path/to/data/"
  PIDFile "/path/to/pidfile/collectd.pid"
  Server  "123.123.123.123" 12345
  LoadPlugin cpu
  LoadPlugin load
  LoadPlugin ping
  <Plugin ping>
    Host "example.org"
    Host "provider.net"
  </Plugin>

DESCRIPTION¶

GLOBAL OPTIONS¶

BaseDir Directory

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.

LoadPlugin Plugin

Loads the plugin Plugin. There must be at least one such line or collectd will be mostly useless.

 

Starting with collectd 4.9, this may also be a block in which further options affecting the behavior of LoadPlugin may be specified. The following options are allowed inside a LoadPlugin block:

 

  <LoadPlugin perl>
    Globals true
  </LoadPlugin>
    

Include Path

If Path points to a file, includes that file. If Path points to a directory, recursively includes all files within that directory and its subdirectories. If the "wordexp" 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"
    

 

If more than one files are included by a single Include option, the files will be included in lexicographical order (as defined by the "strcmp" function). Thus, you can e. g. 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 8 levels, 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 "<Plugin foo>" in more than one file, but you cannot include files from within blocks.

PIDFile File

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 -P command-line option.

PluginDir Directory

Path to the plugins (shared objects) of collectd.

TypesDB File [File ...]

Set one or more files that contain the data-set descriptions. See types.db(5) for a description of the format of this file.

Interval Seconds

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.

 

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

Timeout Iterations

Consider a value list "missing" when no update has been read or received for Iterations iterations. By default, collectd 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 Interval information contained in each value list. This is used in the Threshold configuration to dispatch notifications about missing values, see collectd-threshold(5) for details.

ReadThreads Num

Number of threads to start for reading plugins. The default value is 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 plugin that do network-IO. Setting this to a value higher than the number of plugins you've loaded is totally useless.

Hostname Name

Sets the hostname that identifies a host. If you omit this setting, the hostname will be determined using the gethostname(2) system call.

FQDNLookup true|false

If Hostname 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 "gethostname". This option is enabled by default.

PreCacheChain ChainName

PostCacheChain ChainName

Configure the name of the "pre-cache chain" and the "post-cache chain". Please see "FILTER CONFIGURATION" below on information on chains and how these setting change the daemon's behavior.

PLUGIN OPTIONS¶

Plugin "amqp"¶

 <Plugin "amqp">
   # Send values to an AMQP broker
   <Publish "some_name">
     Host "localhost"
     Port "5672"
     VHost "/"
     User "guest"
     Password "guest"
     Exchange "amq.fanout"
 #   ExchangeType "fanout"
 #   RoutingKey "collectd"
 #   Persistent false
 #   Format "command"
 #   StoreRates false
   </Publish>
   
   # Receive values from an AMQP broker
   <Subscribe "some_name">
     Host "localhost"
     Port "5672"
     VHost "/"
     User "guest"
     Password "guest"
     Exchange "amq.fanout"
 #   ExchangeType "fanout"
 #   Queue "queue_name"
 #   RoutingKey "collectd.#"
   </Subscribe>
 </Plugin>

Host Host

Hostname or IP-address of the AMQP broker. Defaults to the default behavior of the underlying communications library, rabbitmq-c, which is "localhost".

Port Port

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".

VHost VHost

Name of the virtual host on the AMQP broker to use. Defaults to "/".

User User

Password Password

Credentials used to authenticate to the AMQP broker. By default "guest"/"guest" is used.

Exchange Exchange

In Publish blocks, this option specifies the exchange to send values to. By default, "amq.fanout" will be used.

 

In Subscribe blocks this option is optional. If given, a binding between the given exchange and the queue is created, using the routing key if configured. See the Queue and RoutingKey options below.

ExchangeType Type

If given, the plugin will try to create the configured exchange with this type after connecting. When in a Subscribe block, the queue will then be bound to this exchange.

Queue Queue (Subscribe only)

Configures the queue name to subscribe to. If no queue name was configures explicitly, a unique queue name will be created by the broker.

RoutingKey Key

In Publish blocks, this configures the routing key to set on all outgoing messages. If not given, the routing key will be computed from the identifier 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 Subscribe blocks, configures the routing key used when creating a binding between an exchange and the queue. 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.

Persistent true|false (Publish only)

Selects the delivery method to use. If set to true, the persistent mode will be used, i.e. delivery is guaranteed. If set to false (the default), the transient delivery mode will be used, i.e. messages may be lost due to high load, overflowing queues or similar issues.

Format Command|JSON (Publish only)

Selects the format in which messages are sent to the broker. If set to Command (the default), values are sent as "PUTVAL" commands which are identical to the syntax used by the Exec and UnixSock plugins. In this case, the "Content-Type" header field will be set to "text/collectd".

 

If set to JSON, the values are encoded in the JavaScript Object Notation, an easy and straight forward exchange format. The "Content-Type" header field will be set to "application/json".

 

A subscribing client should use the "Content-Type" header field to determine how to decode the values. Currently, the AMQP plugin itself can only decode the Command format.

StoreRates true|false (Publish only)

Determines whether or not "COUNTER", "DERIVE" and "ABSOLUTE" data sources are converted to a rate (i.e. a "GAUGE" value). If set to false (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 Format option has been set to JSON.

Plugin "apache"¶

  ExtendedStatus on
  <IfModule mod_status.c>
    <Location /mod_status>
      SetHandler server-status
    </Location>
  </IfModule>

 <Plugin "apache">
   <Instance "www1">
     URL "http://www1.example.com/mod_status?auto"
   </Instance>
   <Instance "www2">
     URL "http://www2.example.com/mod_status?auto"
   </Instance>
 </Plugin>

URL http://host/mod_status?auto

Sets the URL of the "mod_status" output. This needs to be the output generated by "ExtendedStatus on" and it needs to be the machine readable output generated by appending the "?auto" argument. This option is mandatory.

User Username

Optional user name needed for authentication.

Password Password

Optional password needed for authentication.

VerifyPeer true|false

Enable or disable peer SSL certificate verification. See <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.

VerifyHost true|false

Enable or disable peer host name verification. If enabled, the plugin checks if the "Common Name" or a "Subject Alternate Name" field of the SSL certificate matches the host name provided by the URL option. If this identity check fails, the connection is aborted. Obviously, only works when connecting to a SSL enabled server. Enabled by default.

CACert File

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 "libcurl" and are checked by default depends on the distribution you use.

Plugin "apcups"¶

Host Hostname

Hostname of the host running apcupsd. Defaults to localhost. Please note that IPv6 support has been disabled unless someone can confirm or decline that apcupsd can handle it.

Port Port

TCP-Port to connect to. Defaults to 3551.

Plugin "ascent"¶

URL http://localhost/ascent/status/

Sets the URL of the XML status output.

User Username

Optional user name needed for authentication.

Password Password

Optional password needed for authentication.

VerifyPeer true|false

Enable or disable peer SSL certificate verification. See <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.

VerifyHost true|false

Enable or disable peer host name verification. If enabled, the plugin checks if the "Common Name" or a "Subject Alternate Name" field of the SSL certificate matches the host name provided by the URL option. If this identity check fails, the connection is aborted. Obviously, only works when connecting to a SSL enabled server. Enabled by default.

CACert File

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 "libcurl" and are checked by default depends on the distribution you use.

Plugin "bind"¶

 statistics-channels {
   inet localhost port 8053;
 };

 <Plugin "bind">
   URL "http://localhost:8053/"
   ParseTime       false
   OpCodes         true
   QTypes          true
 
   ServerStats     true
   ZoneMaintStats  true
   ResolverStats   false
   MemoryStats     true
 
   <View "_default">
     QTypes        true
     ResolverStats true
     CacheRRSets   true
 
     Zone "127.in-addr.arpa/IN"
   </View>
 </Plugin>

URL URL

URL from which to retrieve the XML data. If not specified, "http://localhost:8053/" will be used.

ParseTime true|false

When set to true, the time provided by BIND will be parsed and used to dispatch the values. When set to false, the local time source is queried.

 

This setting is set to true by default for backwards compatibility; setting this to false is recommended to avoid problems with timezones and localization.

OpCodes true|false

When enabled, statistics about the "OpCodes", for example the number of "QUERY" packets, are collected.

 

Default: Enabled.

QTypes true|false

When enabled, the number of incoming queries by query types (for example "A", "MX", "AAAA") is collected.

 

Default: Enabled.

ServerStats true|false

Collect global server statistics, such as requests received over IPv4 and IPv6, successful queries, and failed updates.

 

Default: Enabled.

ZoneMaintStats true|false

Collect zone maintenance statistics, mostly information about notifications (zone updates) and zone transfers.

 

Default: Enabled.

ResolverStats true|false

Collect resolver statistics, i. e. statistics about outgoing requests (e. g. 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 ResolverStats option within a View "_default" block instead for the same functionality.

 

Default: Disabled.

MemoryStats

Collect global memory statistics.

 

Default: Enabled.

View Name

Collect statistics about a specific "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 "_default" view.

 

Within a < View name> block, you can specify which information you want to collect about a view. If no View block is configured, no detailed view statistics will be collected.

Plugin "cpufreq"¶

Plugin "csv"¶

DataDir Directory

Set the directory to store CSV-files under. Per default CSV-files are generated beneath the daemon's working directory, i. e. the BaseDir. The special strings stdout and stderr 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.

StoreRates true|false

If set to true, convert counter values to rates. If set to false (the default) counter values are stored as is, i. e. as an increasing integer number.

Plugin "curl"¶

  <Plugin curl>
    <Page "stock_quotes">
      URL "http://finance.google.com/finance?q=NYSE%3AAMD"
      User "foo"
      Password "bar"
      <Match>
        Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
        DSType "GaugeAverage"
        # Note: `stock_value' is not a standard type.
        Type "stock_value"
        Instance "AMD"
      </Match>
    </Page>
  </Plugin>

URL URL

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 ;)

User Name

Username to use if authorization is required to read the page.

Password Password

Password to use if authorization is required to read the page.

VerifyPeer true|false

Enable or disable peer SSL certificate verification. See <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.

VerifyHost true|false

Enable or disable peer host name verification. If enabled, the plugin checks if the "Common Name" or a "Subject Alternate Name" field of the SSL certificate matches the host name provided by the URL option. If this identity check fails, the connection is aborted. Obviously, only works when connecting to a SSL enabled server. Enabled by default.

CACert file

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 "libcurl" and are checked by default depends on the distribution you use.

MeasureResponseTime true|false

Measure response time for the request. If this setting is enabled, Match blocks (see below) are optional. Disabled by default.

<Match>

One or more Match blocks that define how to match information in the data returned by "libcurl". The "curl" plugin uses the same infrastructure that's used by the "tail" plugin, so please see the documentation of the "tail" plugin below on how matches are defined. If the MeasureResponseTime option is set to true, Match blocks are optional.

Plugin "curl_json"¶

  <Plugin curl_json>
    <URL "http://localhost:5984/_stats">
      Instance "httpd"
      <Key "httpd/requests/count">
        Type "http_requests"
      </Key>
      <Key "httpd_request_methods/*/count">
        Type "http_request_methods"
      </Key>
      <Key "httpd_status_codes/*/count">
        Type "http_response_codes"
      </Key>
    </URL>
  </Plugin>

Instance Instance

Sets the plugin instance to Instance.

User Name

Username to use if authorization is required to read the page.

Password Password

Password to use if authorization is required to read the page.

VerifyPeer true|false

Enable or disable peer SSL certificate verification. See <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.

VerifyHost true|false

Enable or disable peer host name verification. If enabled, the plugin checks if the "Common Name" or a "Subject Alternate Name" field of the SSL certificate matches the host name provided by the URL option. If this identity check fails, the connection is aborted. Obviously, only works when connecting to a SSL enabled server. Enabled by default.

CACert file

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 "libcurl" and are checked by default depends on the distribution you use.

Type Type

Sets the type used to dispatch the values to the daemon. Detailed information about types and their configuration can be found in types.db(5). This option is mandatory.

Instance Instance

Type-instance to use. Defaults to the current map key or current string array element value.

Plugin "curl_xml"¶

 <Plugin "curl_xml">
   <URL "http://localhost/stats.xml">
     Host "my_host"
     Instance "some_instance"
     User "collectd"
     Password "thaiNg0I"
     VerifyPeer true
     VerifyHost true
     CACert "/path/to/ca.crt"
     <XPath "table[@id=\"magic_level\"]/tr">
       Type "magic_level"
       #InstancePrefix "prefix-"
       InstanceFrom "td[1]"
       ValuesFrom "td[2]/span[@class=\"level\"]"
     </XPath>
   </URL>
 </Plugin>

Host Name

Use Name as the host name when submitting values. Defaults to the global host name setting.

Instance Instance

Use Instance as the plugin instance when submitting values. Defaults to an empty string (no plugin instance).

User User =item Password Password =item VerifyPeer true|false =item VerifyHost true|false =item CACert CA Cert File

These options behave exactly equivalent to the appropriate options of the cURL and cURL-JSON plugins. Please see there for a detailed description.

<XPath XPath-expression>

Within each URL block, there must be one or more XPath blocks. Each XPath 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 XPath block the following options are accepted:

Plugin "dbi"¶

  <Plugin dbi>
    <Query "out_of_stock">
      Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
      # Use with MySQL 5.0.0 or later
      MinVersion 50000
      <Result>
        Type "gauge"
        InstancePrefix "out_of_stock"
        InstancesFrom "category"
        ValuesFrom "value"
      </Result>
    </Query>
    <Database "product_information">
      Driver "mysql"
      DriverOption "host" "localhost"
      DriverOption "username" "collectd"
      DriverOption "password" "aZo6daiw"
      DriverOption "dbname" "prod_info"
      SelectDB "prod_info"
      Query "out_of_stock"
    </Database>
  </Plugin>

  <Query "environment">
    Statement "select station, temperature, humidity from environment"
    <Result>
      Type "temperature"
      # InstancePrefix "foo"
      InstancesFrom "station"
      ValuesFrom "temperature"
    </Result>
    <Result>
      Type "humidity"
      InstancesFrom "station"
      ValuesFrom "humidity"
    </Result>
  </Query>

Statement SQL

Sets the statement that should be executed on the server. This is not interpreted by collectd, but simply passed to the database server. Therefore, the SQL dialect that's used depends on the server collectd is connected to.

 

The query has to return at least two columns, one for the instance and one value. You cannot omit the instance, even if the statement is guaranteed to always return exactly one line. In that case, you can usually specify something like this:

 

  Statement "SELECT \"instance\", COUNT(*) AS value FROM table"
    

 

(That works with MySQL but may not be valid SQL according to the spec. If you use a more strict database server, you may have to select from a dummy table or something.)

 

Please note that some databases, for example Oracle, will fail if you include a semicolon at the end of the statement.

MinVersion Version

MaxVersion Value

Only use this query for the specified database version. You can use these options to provide multiple queries with the same name but with a slightly different syntax. The plugin will use only those queries, where the specified minimum and maximum versions fit the version of the database in use.

 

The database version is determined by "dbi_conn_get_engine_version", see the libdbi documentation <http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-GET-ENGINE-VERSION> for details. Basically, each part of the version is assumed to be in the range from 00 to 99 and all dots are removed. So version "4.1.2" becomes "40102", version "5.0.42" becomes "50042".

 

Warning: The plugin will use all matching queries, so if you specify multiple queries with the same name and overlapping ranges, weird stuff will happen. Don't to it! A valid example would be something along these lines:

 

  MinVersion 40000
  MaxVersion 49999
  ...
  MinVersion 50000
  MaxVersion 50099
  ...
  MinVersion 50100
  # No maximum
    

 

In the above example, there are three ranges that don't overlap. The last one goes from version "5.1.0" to infinity, meaning "all later versions". Versions before "4.0.0" are not specified.

Type Type

The type that's used for each line returned. See types.db(5) for more details on how types are defined. In short: A type is a predefined layout of data and the number of values and type of values has to match the type definition.

 

If you specify "temperature" here, you need exactly one gauge column. If you specify "if_octets", you will need two counter columns. See the ValuesFrom setting below.

 

There must be exactly one Type option inside each Result block.

InstancePrefix prefix

Prepends prefix to the type instance. If InstancesFrom (see below) is not given, the string is simply copied. If InstancesFrom is given, prefix and all strings returned in the appropriate columns are concatenated together, separated by dashes ("-").

InstancesFrom column0 [column1 ...]

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 ("-") 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. This is especially true, if you do not specify InstancesFrom: You have to make sure that only one row is returned in this case.

 

If neither InstancePrefix nor InstancesFrom is given, the type-instance will be empty.

ValuesFrom column0 [column1 ...]

Names the columns 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 Type 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 actual data type in the columns is not that important. The plugin will automatically cast the values to the right type if it know how to do that. So it should be able to handle integer an floating point types, as well as strings (if they include a number at the beginning).

 

There must be at least one ValuesFrom option inside each Result block.

Driver Driver

Specifies the driver to use to connect to the database. In many cases those drivers are named after the database they can connect to, but this is not a technical necessity. These drivers are sometimes referred to as "DBD", DataBase Driver, and some distributions ship them in separate packages. Drivers for the "dbi" library are developed by the libdbi-drivers project at http://libdbi-drivers.sourceforge.net/ <http://libdbi-drivers.sourceforge.net/>.

 

You need to give the driver name as expected by the "dbi" library here. You should be able to find that in the documentation for each driver. If you mistype the driver name, the plugin will dump a list of all known driver names to the log.

DriverOption Key Value

Sets driver-specific options. What option a driver supports can be found in the documentation for each driver, somewhere at http://libdbi-drivers.sourceforge.net/ <http://libdbi-drivers.sourceforge.net/>. However, the options "host", "username", "password", and "dbname" seem to be de facto standards.

 

Unfortunately, drivers are not too keen to report errors when an unknown option is passed to them, so invalid settings here may go unnoticed. This is not the plugin's fault, it will report errors if it gets them from the library / the driver. If a driver complains about an option, the plugin will dump a complete list of all options understood by that driver to the log.

SelectDB Database

In some cases, the database name you connect with is not the database name you want to use for querying data. If this option is set, the plugin will "select" (switch to) that database after the connection is established.

Query QueryName

Associates the query named QueryName with this database connection. The query needs to be defined before this statement, i. e. all query blocks you want to refer to must be placed above the database block you want to refer to them from.

Plugin "df"¶

Device Device

Select partitions based on the devicename.

MountPoint Directory

Select partitions based on the mountpoint.

FSType FSType

Select partitions based on the filesystem type.

IgnoreSelected true|false

Invert the selection: If set to true, all partitions except the ones that match any one of the criteria are collected. By default only selected partitions are collected if a selection is made. If no selection is configured at all, all partitions are selected.

ReportByDevice true|false

Report using the device name rather than the mountpoint. i.e. with this false, (the default), it will report a disk as "root", but with it true, it will be "sda1" (or whichever).

ReportInodes true|false

Enables or disables reporting of free, reserved and used inodes. Defaults to inode collection being disabled.

 

Enable this option if inodes are a scarce resource for you, usually because many small files are stored on the disk. This is a usual scenario for mail transfer agents and web caches.

Plugin "disk"¶

Disk Name

Select the disk Name. Whether it is collected or ignored depends on the IgnoreSelected setting, see below. As with other plugins that use the daemon's ignorelist functionality, a string that starts and ends with a slash is interpreted as a regular expression. Examples:

 

  Disk "sdd"
  Disk "/hda[34]/"
    

IgnoreSelected true|false

Sets whether selected disks, i. e. the ones matches by any of the Disk statements, are ignored or if all other disks are ignored. The behavior (hopefully) is intuitive: If no Disk option is configured, all disks are collected. If at least one Disk option is given and no IgnoreSelected or set to false, only matching disks will be collected. If IgnoreSelected is set to true, all disks are collected except the ones matched.

Plugin "dns"¶

Interface Interface

The dns plugin uses libpcap to capture dns traffic and analyzes it. This option sets the interface that should be used. If this option is not set, or set to "any", the plugin will try to get packets from all interfaces. This may not work on certain platforms, such as Mac OS X.

IgnoreSource IP-address

Ignore packets that originate from this address.

SelectNumericQueryTypes true|false

Enabled by default, collects unknown (and thus presented as numeric only) query types.

Plugin "email"¶

SocketFile Path

Sets the socket-file which is to be created.

SocketGroup Group

If running as root change the group of the UNIX-socket after it has been created. Defaults to collectd.

SocketPerms Permissions

Change the file permissions of the UNIX-socket after it has been created. The permissions must be given as a numeric, octal value as you would pass to chmod(1). Defaults to 0770.

MaxConns Number

Sets the maximum number of connections that can be handled in parallel. Since this many threads will be started immediately setting this to a very high value will waste valuable resources. Defaults to 5 and will be forced to be at most 16384 to prevent typos and dumb mistakes.

Plugin "ethstat"¶

 <Plugin "ethstat">
   Interface "eth0"
   Map "rx_csum_offload_errors" "if_rx_errors" "checksum_offload"
   Map "multicast" "if_multicast"
 </Plugin>

Interface Name

Collect statistical information about interface Name.

Map Name Type [TypeInstance]

By default, the plugin will submit values as type "derive" and type instance set to Name, the name of the metric as reported by the driver. If an appropriate Map option exists, the given Type and, optionally, TypeInstance will be used.

MappedOnly true|false

When set to true, only metrics that can be mapped to to a type will be collected, all other metrics will be ignored. Defaults to false.

Plugin "exec"¶

Exec User[:[Group]] Executable [ <arg> [<arg> ...]]

NotificationExec User[:[Group]] Executable [ <arg> [<arg> ...]]

Execute the executable Executable as user User. If the user name is followed by a colon and a group name, the effective group is set to that group. The real group and saved-set group will be set to the default group of that user. If no group is given the effective group ID will be the same as the real group ID.

 

Please note that in order to change the user and/or group the daemon needs superuser privileges. If the daemon is run as an unprivileged user you must specify the same user/group here. If the daemon is run with superuser privileges, you must supply a non-root user here.

 

The executable may be followed by optional arguments that are passed to the program. Please note that due to the configuration parsing numbers and boolean values may be changed. If you want to be absolutely sure that something is passed as-is please enclose it in quotes.

 

The Exec and NotificationExec statements change the semantics of the programs executed, i. e. the data passed to them and the response expected from them. This is documented in great detail in collectd-exec(5).

Plugin "filecount"¶

  <Plugin "filecount">
    <Directory "/var/qmail/queue/mess">
      Instance "qmail-message"
    </Directory>
    <Directory "/var/qmail/queue/todo">
      Instance "qmail-todo"
    </Directory>
    <Directory "/var/lib/php5">
      Instance "php5-sessions"
      Name "sess_*"
    </Directory>
  </Plugin>

Instance Instance

Sets the plugin instance to Instance. That instance name must be unique, but it's your responsibility, the plugin doesn't check for that. If not given, the instance is set to the directory name with all slashes replaced by underscores and all leading underscores removed.

Name Pattern

Only count files that match Pattern, where Pattern is a shell-like wildcard as understood by fnmatch(3). Only the filename is checked against the pattern, not the entire path. In case this makes it easier for you: This option has been named after the -name parameter to find(1).

MTime Age

Count only files of a specific age: If Age is greater than zero, only files that haven't been touched in the last Age seconds are counted. If Age is a negative number, this is inversed. For example, if -60 is specified, only files that have been modified in the last minute will be counted.

 

The number can also be followed by a "multiplier" to easily specify a larger timespan. When given in this notation, the argument must in quoted, i. e. must be passed as string. So the -60 could also be written as "-1m" (one minute). Valid multipliers are "s" (second), "m" (minute), "h" (hour), "d" (day), "w" (week), and "y" (year). There is no "month" multiplier. You can also specify fractional numbers, e. g. "0.5d" is identical to "12h".

Size Size

Count only files of a specific size. When Size is a positive number, only files that are at least this big are counted. If Size is a negative number, this is inversed, i. e. only files smaller than the absolute value of Size are counted.

 

As with the MTime option, a "multiplier" may be added. For a detailed description see above. Valid multipliers here are "b" (byte), "k" (kilobyte), "m" (megabyte), "g" (gigabyte), "t" (terabyte), and "p" (petabyte). Please note that there are 1000 bytes in a kilobyte, not 1024.

Recursive true|false

Controls whether or not to recurse into subdirectories. Enabled by default.

IncludeHidden true|false

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 false, i.e. by default hidden files and directories are ignored.

Plugin "GenericJMX"¶

Plugin "gmond"¶

 <Plugin "gmond">
   MCReceiveFrom "239.2.11.71" "8649"
   <Metric "swap_total">
     Type "swap"
     TypeInstance "total"
     DataSource "value"
   </Metric>
   <Metric "swap_free">
     Type "swap"
     TypeInstance "free"
     DataSource "value"
   </Metric>
 </Plugin>

•

load_one, load_five, load_fifteen

•

cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio

•

mem_free, mem_shared, mem_buffers, mem_cached, mem_total

•

bytes_in, bytes_out

•

pkts_in, pkts_out

MCReceiveFrom MCGroup [Port]

Sets sets the multicast group and UDP port to which to subscribe.

 

Default: 239.2.11.71 / 8649

<Metric Name>

These blocks add a new metric conversion to the internal table. Name, the string argument to the Metric block, is the metric name as used by Ganglia.

Plugin "hddtemp"¶

Host Hostname

Hostname to connect to. Defaults to 127.0.0.1.

Port Port

TCP-Port to connect to. Defaults to 7634.

Plugin "interface"¶

Interface Interface

Select this interface. By default these interfaces will then be collected. For a more detailed description see IgnoreSelected below.

IgnoreSelected true|false

If no configuration if given, the traffic-plugin will collect data from all interfaces. This may not be practical, especially for loopback- and similar interfaces. Thus, you can use the Interface-option to pick the interfaces you're interested in. Sometimes, however, it's easier/preferred to collect all interfaces except a few ones. This option enables you to do that: By setting IgnoreSelected to true the effect of Interface is inverted: All selected interfaces are ignored and all other interfaces are collected.

Plugin "ipmi"¶

Sensor Sensor

Selects sensors to collect or to ignore, depending on IgnoreSelected.

IgnoreSelected true|false

If no configuration if given, the ipmi plugin will collect data from all sensors found of type "temperature", "voltage", "current" and "fanspeed". This option enables you to do that: By setting IgnoreSelected to true the effect of Sensor is inverted: All selected sensors are ignored and all other sensors are collected.

NotifySensorAdd true|false

If a sensor appears after initialization time of a minute a notification is sent.

NotifySensorRemove true|false

If a sensor disappears a notification is sent.

NotifySensorNotPresent true|false

If you have for example dual power supply and one of them is (un)plugged then a notification is sent.

Plugin "iptables"¶

Chain Table Chain [Comment|Number [ Name]]

Select the rules to count. If only Table and Chain are given, this plugin will collect the counters of all rules which have a comment-match. The comment is then used as type-instance.

 

If Comment or Number is given, only the rule with the matching comment or the nth rule will be collected. Again, the comment (or the number) will be used as the type-instance.

 

If Name is supplied, it will be used as the type-instance instead of the comment or the number.

Plugin "irq"¶

Irq Irq

Select this irq. By default these irqs will then be collected. For a more detailed description see IgnoreSelected below.

IgnoreSelected true|false

If no configuration if given, the irq-plugin will collect data from all irqs. This may not be practical, especially if no interrupts happen. Thus, you can use the Irq-option to pick the interrupt you're interested in. Sometimes, however, it's easier/preferred to collect all interrupts except a few ones. This option enables you to do that: By setting IgnoreSelected to true the effect of Irq is inverted: All selected interrupts are ignored and all other interrupts are collected.

Plugin "java"¶

 <Plugin "java">
   JVMArg "-verbose:jni"
   JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
   LoadPlugin "org.collectd.java.Foobar"
   <Plugin "org.collectd.java.Foobar">
     # To be parsed by the plugin
   </Plugin>
 </Plugin>

JVMArg Argument

Argument that is to be passed to the Java Virtual Machine (JVM). This works exactly the way the arguments to the java binary on the command line work. Execute "java --help" for details.

 

Please note that all these options must appear before (i. e. above) any other options! When another option is found, the JVM will be started and later options will have to be ignored!

LoadPlugin JavaClass

Instantiates a new JavaClass object. The constructor of this object very likely then registers one or more callback methods with the server.

 

See collectd-java(5) for details.

 

When the first such option is found, the virtual machine (JVM) is created. This means that all JVMArg options must appear before (i. e. above) all LoadPlugin options!

Plugin Name

The entire block is passed to the Java plugin as an org.collectd.api.OConfigItem object.

 

For this to work, the plugin has to register a configuration callback first, see "config callback" in collectd-java(5). This means, that the Plugin block must appear after the appropriate LoadPlugin block. Also note, that Name depends on the (Java) plugin registering the callback and is completely independent from the JavaClass argument passed to LoadPlugin.

Plugin "libvirt"¶

Connection uri

Connect to the hypervisor given by uri. For example if using Xen use:

 

 Connection "xen:///"
    

 

Details which URIs allowed are given at <http://libvirt.org/uri.html>.

RefreshInterval seconds

Refresh the list of domains and devices every seconds. The default is 60 seconds. Setting this to be the same or smaller than the Interval will cause the list of domains and devices to be refreshed on every iteration.

 

Refreshing the devices in particular is quite a costly operation, so if your virtualization setup is static you might consider increasing this. If this option is set to 0, refreshing is disabled completely.

Domain name

BlockDevice name:dev

InterfaceDevice name:dev

IgnoreSelected true|false

Select which domains and devices are collected.

 

If IgnoreSelected is not given or false then only the listed domains and disk/network devices are collected.

 

If IgnoreSelected is true then the test is reversed and the listed domains and disk/network devices are ignored, while the rest are collected.

 

The domain name and device names may use a regular expression, if the name is surrounded by /.../ and collectd was compiled with support for regexps.

 

The default is to collect statistics for all domains and all their devices.

 

Example:

 

 BlockDevice "/:hdb/"
 IgnoreSelected "true"
    

 

Ignore all hdb devices on any domain, but other block devices (eg. hda) will be collected.

HostnameFormat name|uuid|hostname|...

When the libvirt plugin logs data, it sets the hostname of the collected data according to this setting. The default is to use the guest name as provided by the hypervisor, which is equal to setting name.

 

uuid means use the guest's UUID. This is useful if you want to track the same guest across migrations.

 

hostname means to use the global Hostname setting, which is probably not useful on its own because all guests will appear to have the same name.

 

You can also specify combinations of these fields. For example name uuid means to concatenate the guest name and UUID (with a literal colon character between, thus "foo:1234-1234-1234-1234").

InterfaceFormat name|address

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 name.

 

address means use the interface's mac address. This is useful since the interface path might change between reboots of a guest or across migrations.

Plugin "logfile"¶

LogLevel debug|info|notice|warning|err

Sets the log-level. If, for example, set to notice, then all events with severity notice, warning, or err will be written to the logfile.

 

Please note that debug is only available if collectd has been compiled with debugging support.

File File

Sets the file to write log messages to. The special strings stdout and stderr 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.

Timestamp true|false

Prefix all lines printed by the current time. Defaults to true.

PrintSeverity true|false

When enabled, all lines are prefixed by the severity of the log message, for example "warning". Defaults to false.

Plugin "lpar"¶

CpuPoolStats false|true

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.

ReportBySerial false|true

If enabled, the serial of the physical machine the partition is currently running on is reported as hostname and the logical hostname of the machine is reported in the plugin instance. Otherwise, the logical hostname will be used (just like other plugins) and the plugin instance will be empty. Defaults to false.

Plugin "mbmon"¶

Host Hostname

Hostname to connect to. Defaults to 127.0.0.1.

Port Port

TCP-Port to connect to. Defaults to 411.

Plugin "md"¶

Device Device

Select md devices based on device name. The device name is the basename of the device, i.e. the name of the block device without the leading "/dev/". See IgnoreSelected for more details.

IgnoreSelected true|false

Invert device selection: If set to true, all md devices except those listed using Device are collected. If false (the default), only those listed are collected. If no configuration is given, the md plugin will collect data from all md devices.

Plugin "memcachec"¶

 <Plugin "memcachec">
   <Page "plugin_instance">
     Server "localhost"
     Key "page_key"
     <Match>
       Regex "(\\d+) bytes sent"
       DSType CounterAdd
       Type "ipt_octets"
       Instance "type_instance"
     </Match>
   </Page>
 </Plugin>

<Page Name>

Each Page block defines one page to be queried from the memcached server. The block requires one string argument which is used as plugin instance.

Server Address

Sets the server address to connect to when querying the page. Must be inside a Page block.

Key Key

When connected to the memcached server, asks for the page Key.

<Match>

Match blocks define which strings to look for and how matches substrings are interpreted. For a description of match blocks, please see "Plugin tail".

Plugin "memcached"¶

Host Hostname

Hostname to connect to. Defaults to 127.0.0.1.

Port Port

TCP-Port to connect to. Defaults to 11211.

Plugin "modbus"¶

 <Data "voltage-input-1">
   RegisterBase 0
   RegisterType float
   Type voltage
   Instance "input-1"
 </Data>
 
 <Data "voltage-input-2">
   RegisterBase 2
   RegisterType float
   Type voltage
   Instance "input-2"
 </Data>
 
 <Host "modbus.example.com">
   Address "192.168.0.42"
   Port    "502"
   Interval 60
   
   <Slave 1>
     Instance "power-supply"
     Collect  "voltage-input-1"
     Collect  "voltage-input-2"
   </Slave>
 </Host>

<Data Name> blocks

Data blocks define a mapping between register numbers and the "types" used by collectd.

 

Within <Data /> blocks, the following options are allowed:

<Host Name> blocks

Host blocks are used to specify to which hosts to connect and what data to read from their "slaves". The string argument Name is used as hostname when dispatching the values to collectd.

 

Within <Host /> blocks, the following options are allowed:

Plugin "mysql"¶

  <Plugin mysql>
    <Database foo>
      Host "hostname"
      User "username"
      Password "password"
      Port "3306"
      MasterStats true
    </Database>
    <Database bar>
      Host "localhost"
      Socket "/var/run/mysql/mysqld.sock"
      SlaveStats true
      SlaveNotifications true
    </Database>
  </Plugin>

Host Hostname

Hostname of the database server. Defaults to localhost.

User Username

Username to use when connecting to the database. The user does not have to be granted any privileges (which is synonym to granting the "USAGE" privilege), unless you want to collectd replication statistics (see MasterStats and SlaveStats below). In this case, the user needs the "REPLICATION CLIENT" (or "SUPER") privileges. Else, any existing MySQL user will do.

Password Password

Password needed to log into the database.

Database Database

Select this database. Defaults to no database which is a perfectly reasonable option for what this plugin does.

Port Port

TCP-port to connect to. The port must be specified in its numeric form, but it must be passed as a string nonetheless. For example:

 

  Port "3306"
    

 

If Host is set to localhost (the default), this setting has no effect. See the documentation for the "mysql_real_connect" function for details.

Socket Socket

Specifies the path to the UNIX domain socket of the MySQL server. This option only has any effect, if Host is set to localhost (the default). Otherwise, use the Port option above. See the documentation for the "mysql_real_connect" function for details.

MasterStats true|false

SlaveStats true|false

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

SlaveNotifications true|false

If enabled, the plugin sends a notification if the replication slave I/O and / or SQL threads are not running.

Plugin "netapp"¶

 <Plugin "netapp">
   <Host "netapp1.example.com">
    Protocol      "https"
    Address       "10.0.0.1"
    Port          443
    User          "username"
    Password      "aef4Aebe"
    Interval      30
    
    <WAFL>
      Interval 30
      GetNameCache   true
      GetDirCache    true
      GetBufferCache true
      GetInodeCache  true
    </WAFL>
    
    <Disks>
      Interval 30
      GetBusy true
    </Disks>
    
    <VolumePerf>
      Interval 30
      GetIO      "volume0"
      IgnoreSelectedIO      false
      GetOps     "volume0"
      IgnoreSelectedOps     false
      GetLatency "volume0"
      IgnoreSelectedLatency false
    </VolumePerf>
    
    <VolumeUsage>
      Interval 30
      GetCapacity "vol0"
      GetCapacity "vol1"
      IgnoreSelectedCapacity false
      GetSnapshot "vol1"
      GetSnapshot "vol3"
      IgnoreSelectedSnapshot false
    </VolumeUsage>
    
    <System>
      Interval 30
      GetCPULoad     true
      GetInterfaces  true
      GetDiskOps     true
      GetDiskIO      true
    </System>
   </Host>
 </Plugin>

Host Name

A host block defines one NetApp filer. It will appear in collectd with the name you specify here which does not have to be its real name nor its hostname.

Protocol httpd|http

The protocol collectd will use to query this host.

 

Optional

 

Type: string

 

Default: https

 

Valid options: http, https

Address Address

The hostname or IP address of the host.

 

Optional

 

Type: string

 

Default: The "host" block's name.

Port Port

The TCP port to connect to on the host.

 

Optional

 

Type: integer

 

Default: 80 for protocol "http", 443 for protocol "https"

User User

Password Password

The username and password to use to login to the NetApp.

 

Mandatory

 

Type: string

Interval Interval

TODO

Interval Seconds

Collect the respective statistics every Seconds seconds. Defaults to the host specific setting.

Interval Seconds

Collect disk statistics every Seconds seconds.

GetCPULoad true|false

If you set this option to true the current CPU usage will be read. This will be the average usage between all CPUs in your NetApp without any information about individual CPUs.

 

Note: These are the same values that the NetApp CLI command "sysstat" returns in the "CPU" field.

 

Optional

 

Type: boolean

 

Default: true

 

Result: Two value lists of type "cpu", and type instances "idle" and "system".

GetInterfaces true|false

If you set this option to true the current traffic of the network interfaces will be read. This will be the total traffic over all interfaces of your NetApp without any information about individual interfaces.

 

Note: This is the same values that the NetApp CLI command "sysstat" returns in the "Net kB/s" field.

 

Or is it?

 

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "if_octects".

GetDiskIO true|false

If you set this option to true the current IO throughput will be read. This will be the total IO of your NetApp without any information about individual disks, volumes or aggregates.

 

Note: This is the same values that the NetApp CLI command "sysstat" returns in the "Disk kB/s" field.

 

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "disk_octets".

GetDiskOps true|false

If you set this option to true the current number of HTTP, NFS, CIFS, FCP, iSCSI, etc. operations will be read. This will be the total number of operations on your NetApp without any information about individual volumes or aggregates.

 

Note: These are the same values that the NetApp CLI command "sysstat" returns in the "NFS", "CIFS", "HTTP", "FCP" and "iSCSI" fields.

 

Optional

 

Type: boolean

 

Default: true

 

Result: A variable number of value lists of type "disk_ops_complex". Each type of operation will result in one value list with the name of the operation as type instance.

Interval Seconds

Collect disk statistics every Seconds seconds.

GetNameCache true|false

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "cache_ratio" and type instance "name_cache_hit".

GetDirCache true|false

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "cache_ratio" and type instance "find_dir_hit".

GetInodeCache true|false

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "cache_ratio" and type instance "inode_cache_hit".

GetBufferCache true|false

Note: This is the same value that the NetApp CLI command "sysstat" returns in the "Cache hit" field.

 

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "cache_ratio" and type instance "buf_hash_hit".

Interval Seconds

Collect disk statistics every Seconds seconds.

GetBusy true|false

If you set this option to true the busy time of all disks will be calculated and the value of the busiest disk in the system will be written.

 

Note: This is the same values that the NetApp CLI command "sysstat" returns in the "Disk util" field. Probably.

 

Optional

 

Type: boolean

 

Default: true

 

Result: One value list of type "percent" and type instance "disk_busy".

Interval Seconds

Collect volume performance data every Seconds seconds.

GetIO Volume

GetOps Volume

GetLatency Volume

Select the given volume for IO, operations or latency statistics collection. The argument is the name of the volume without the "/vol/" prefix.

 

Since the standard ignorelist functionality is used here, you can use a string starting and ending with a slash to specify regular expression matching: To match the volumes "vol0", "vol2" and "vol7", you can use this regular expression:

 

  GetIO "/^vol[027]$/"
    

 

If no regular expression is specified, an exact match is required. Both, regular and exact matching are case sensitive.

 

If no volume was specified at all for either of the three options, that data will be collected for all available volumes.

IgnoreSelectedIO true|false

IgnoreSelectedOps true|false

IgnoreSelectedLatency true|false

When set to true, the volumes selected for IO, operations or latency statistics collection will be ignored and the data will be collected for all other volumes.

 

When set to false, data will only be collected for the specified volumes and all other volumes will be ignored.

 

If no volumes have been specified with the above Get* options, all volumes will be collected regardless of the IgnoreSelected* option.

 

Defaults to false

Interval Seconds

Collect volume usage statistics every Seconds seconds.

GetCapacity VolumeName

The current capacity of the volume will be collected. This will result in two to four value lists, depending on the configuration of the volume. All data sources are of type "df_complex" with the name of the volume as plugin_instance.

 

There will be type_instances "used" and "free" for the number of used and available bytes on the volume. If the volume has some space reserved for snapshots, a type_instance "snap_reserved" will be available. If the volume has SIS enabled, a type_instance "sis_saved" will be available. This is the number of bytes saved by the SIS feature.

 

Note: The current NetApp API has a bug that results in this value being reported as a 32 bit number. This plugin tries to guess the correct number which works most of the time. If you see strange values here, bug NetApp support to fix this.

 

Repeat this option to specify multiple volumes.

IgnoreSelectedCapacity true|false

Specify whether to collect only the volumes selected by the GetCapacity option or to ignore those volumes. IgnoreSelectedCapacity defaults to false. However, if no GetCapacity option is specified at all, all capacities will be selected anyway.

GetSnapshot VolumeName

Select volumes from which to collect snapshot information.

 

Usually, the space used for snapshots is included in the space reported as "used". If snapshot information is collected as well, the space used for snapshots is subtracted from the used space.

 

To make things even more interesting, it is possible to reserve space to be used for snapshots. If the space required for snapshots is less than that reserved space, there is "reserved free" and "reserved used" space in addition to "free" and "used". If the space required for snapshots exceeds the reserved space, that part allocated in the normal space is subtracted from the "used" space again.

 

Repeat this option to specify multiple volumes.

IgnoreSelectedSnapshot

Specify whether to collect only the volumes selected by the GetSnapshot option or to ignore those volumes. IgnoreSelectedSnapshot defaults to false. However, if no GetSnapshot option is specified at all, all capacities will be selected anyway.

Plugin "netlink"¶

Interface Interface

VerboseInterface Interface

Instruct the plugin to collect interface statistics. This is basically the same as the statistics provided by the "interface" plugin (see above) but potentially much more detailed.

 

When configuring with Interface only the basic statistics will be collected, namely octets, packets, and errors. These statistics are collected by the "interface" plugin, too, so using both at the same time is no benefit.

 

When configured with VerboseInterface all counters except the basic ones, so that no data needs to be collected twice if you use the "interface" plugin. This includes dropped packets, received multicast packets, collisions and a whole zoo of differentiated RX and TX errors. You can try the following command to get an idea of what awaits you:

 

  ip -s -s link list
    

 

If Interface is All, all interfaces will be selected.

QDisc Interface [QDisc]

Class Interface [Class]

Filter Interface [Filter]

Collect the octets and packets that pass a certain qdisc, class or filter.

 

QDiscs and classes are identified by their type and handle (or classid). Filters don't necessarily have a handle, therefore the parent's handle is used. The notation used in collectd differs from that used in tc(1) in that it doesn't skip the major or minor number if it's zero and doesn't print special ids by their name. So, for example, a qdisc may be identified by "pfifo_fast-1:0" even though the minor number of all qdiscs is zero and thus not displayed by tc(1).

 

If QDisc, Class, or Filter is given without the second argument, i. .e. without an identifier, all qdiscs, classes, or filters that are associated with that interface will be collected.

 

Since a filter itself doesn't necessarily have a handle, the parent's handle is used. This may lead to problems when more than one filter is attached to a qdisc or class. This isn't nice, but we don't know how this could be done any better. If you have a idea, please don't hesitate to tell us.

 

As with the Interface option you can specify All as the interface, meaning all interfaces.

 

Here are some examples to help you understand the above text more easily:

 

  <Plugin netlink>
    VerboseInterface "All"
    QDisc "eth0" "pfifo_fast-1:0"
    QDisc "ppp0"
    Class "ppp0" "htb-1:10"
    Filter "ppp0" "u32-1:0"
  </Plugin>
    

IgnoreSelected

The behavior is the same as with all other similar plugins: If nothing is selected at all, everything is collected. If some things are selected using the options described above, only these statistics are collected. If you set IgnoreSelected to true, this behavior is inverted, i. e. the specified statistics will not be collected.

Plugin "network"¶

 <Plugin "network">
   # Export to an internal server
   # (demonstrates usage without additional options)
   Server "collectd.internal.tld"
   
   # Export to an external server
   # (demonstrates usage with signature options)
   <Server "collectd.external.tld">
     SecurityLevel "sign"
     Username "myhostname"
     Password "ohl0eQue"
   </Server>
 </Plugin>

<Server Host [Port]>

The Server statement/block sets the server to send datagrams to. The statement may occur multiple times to send each datagram to multiple destinations.

 

The argument Host 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, 25826, is used.

 

The following options are recognized within Server blocks:

<Listen Host [Port]>

The Listen statement sets the interfaces to bind to. When multiple statements are found the daemon will bind to multiple interfaces.

 

The argument Host 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, 25826, is used.

 

The following options are recognized within "<Listen>" blocks:

TimeToLive 1-255

Set the time-to-live of sent packets. This applies to all, unicast and multicast, and IPv4 and IPv6 packets. The default is to not change this value. That means that multicast packets will be sent with a TTL of 1 (one) on most operating systems.

MaxPacketSize 1024-65535

Set the maximum size for datagrams received over the network. Packets larger than this will be truncated. Defaults to 1452 bytes, which is the maximum payload size that can be transmitted in one Ethernet frame using IPv6 / UDP.

 

On the server side, this limit should be set to the largest value used on any client. Likewise, the value on the client must not be larger than the value on the server, or data will be lost.

 

Compatibility: Versions prior to version 4.8 used a fixed sized buffer of 1024 bytes. Versions 4.8, 4.9 and 4.10 used a default value of 1024 bytes to avoid problems when sending data to an older server.

Forward true|false

If set to true, write packets that were received via the network plugin to the sending sockets. This should only be activated when the Listen- and Server-statements differ. Otherwise packets may be send multiple times to 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.

ReportStats true|false

The network plugin cannot only receive and send statistics, it can also create statistics about itself. Collected data included the number of received and sent octets and packets, the length of the receive queue and the number of values handled. When set to true, the Network plugin will make these statistics available. Defaults to false.

Plugin "nginx"¶

URL http://host/nginx_status

Sets the URL of the "ngx_http_stub_status_module" output.

User Username

Optional user name needed for authentication.

Password Password

Optional password needed for authentication.

VerifyPeer true|false

Enable or disable peer SSL certificate verification. See <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.

VerifyHost true|false

Enable or disable peer host name verification. If enabled, the plugin checks if the "Common Name" or a "Subject Alternate Name" field of the SSL certificate matches the host name provided by the URL option. If this identity check fails, the connection is aborted. Obviously, only works when connecting to a SSL enabled server. Enabled by default.

CACert File

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 "libcurl" and are checked by default depends on the distribution you use.

Plugin "notify_desktop"¶

OkayTimeout timeout

WarningTimeout timeout

FailureTimeout timeout

Set the timeout, in milliseconds, after which to expire the notification for "OKAY", "WARNING" and "FAILURE" severities respectively. If zero has been specified, the displayed notification will not be closed at all - the user has to do so herself. These options default to 5000. If a negative number has been specified, the default is used as well.

Plugin "notify_email"¶

From Address

Email address from which the emails should appear to come from.

 

Default: "root@localhost"

Recipient Address

Configures the email address(es) to which the notifications should be mailed. May be repeated to send notifications to multiple addresses.

 

At least one Recipient must be present for the plugin to work correctly.

SMTPServer Hostname

Hostname of the SMTP server to connect to.

 

Default: "localhost"

SMTPPort Port

TCP port to connect to.

 

Default: 25

SMTPUser Username

Username for ASMTP authentication. Optional.

SMTPPassword Password

Password for ASMTP authentication. Optional.

Subject Subject

Subject-template to use when sending emails. There must be exactly two string-placeholders in the subject, given in the standard printf(3) syntax, i. e. %s. The first will be replaced with the severity, the second with the hostname.

 

Default: "Collectd notify: %s@%s"

Plugin "ntpd"¶

Host Hostname

Hostname of the host running ntpd. Defaults to localhost.

Port Port

UDP-Port to connect to. Defaults to 123.

ReverseLookups true|false

Sets whether or not to perform reverse lookups on peers. Since the name or IP-address may be used in a filename it is recommended to disable reverse lookups. The default is to do reverse lookups to preserve backwards compatibility, though.

Plugin "nut"¶

UPS upsname@hostname[:port]

Add a UPS to collect data from. The format is identical to the one accepted by upsc(8).

Plugin "olsrd"¶

Host Host

Connect to Host. Defaults to "localhost".

Port Port

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 "2006".

CollectLinks No|Summary|Detail

Specifies what information to collect about links, i. e. direct connections of the daemon queried. If set to No, no information is collected. If set to Summary, the number of links and the average of all link quality (LQ) and neighbor link quality (NLQ) values is calculated. If set to Detail LQ and NLQ are collected per link.

 

Defaults to Detail.

CollectRoutes No|Summary|Detail

Specifies what information to collect about routes of the daemon queried. If set to No, no information is collected. If set to Summary, the number of routes and the average metric and ETX is calculated. If set to Detail metric and ETX are collected per route.

 

Defaults to Summary.

CollectTopology No|Summary|Detail

Specifies what information to collect about the global topology. If set to No, no information is collected. If set to Summary, the number of links in the entire topology and the average link quality (LQ) is calculated. If set to Detail LQ and NLQ are collected for each link in the entire topology.

 

Defaults to Summary.

Plugin "onewire"¶

Device Device

Sets the device to read the values from. This can either be a "real" hardware device, such as a serial port or an USB port, or the address of the owserver(1) socket, usually localhost:4304.

 

Though the documentation claims to automatically recognize the given address format, with version 2.7p4 we had to specify the type explicitly. So with that version, the following configuration worked for us:

 

  <Plugin onewire>
    Device "-s localhost:4304"
  </Plugin>
    

 

This directive is required and does not have a default value.

Sensor Sensor

Selects sensors to collect or to ignore, depending on IgnoreSelected, see below. Sensors are specified without the family byte at the beginning, to you'd use "F10FCA000800", and not include the leading 10. family byte and point.

IgnoreSelected true|false

If no configuration if given, the onewire plugin will collect data from all sensors found. This may not be practical, especially if sensors are added and removed regularly. Sometimes, however, it's easier/preferred to collect only specific sensors or all sensors except a few specified ones. This option enables you to do that: By setting IgnoreSelected to true the effect of Sensor is inverted: All selected interfaces are ignored and all other interfaces are collected.

Interval Seconds

Sets the interval in which all sensors should be read. If not specified, the global Interval setting is used.

Plugin "openvpn"¶

  openvpn $OTHER_OPTIONS \
    --status "/var/run/openvpn-status" 10 \
    --status-version 2

StatusFile File

Specifies the location of the status file.

ImprovedNamingSchema true|false

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.

CollectCompression true|false

Sets whether or not statistics about the compression used by OpenVPN should be collected. This information is only available in single mode. Enabled by default.

CollectIndividualUsers true|false

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 true.

CollectUserCount true|false

When enabled, the number of currently connected clients or users is collected. This is especially interesting when CollectIndividualUsers is disabled, but can be configured independently from that option. Defaults to false.

Plugin "oracle"¶

  <Plugin oracle>
    <Query "out_of_stock">
      Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
      <Result>
        Type "gauge"
        # InstancePrefix "foo"
        InstancesFrom "category"
        ValuesFrom "value"
      </Result>
    </Query>
    <Database "product_information">
      ConnectID "db01"
      Username "oracle"
      Password "secret"
      Query "out_of_stock"
    </Database>
  </Plugin>

ConnectID ID

Defines the "database alias" or "service name" to connect to. Usually, these names are defined in the file named "$ORACLE_HOME/network/admin/tnsnames.ora".

Username Username

Username used for authentication.

Password Password

Password used for authentication.

Query QueryName

Associates the query named QueryName with this database connection. The query needs to be defined before this statement, i. e. all query blocks you want to refer to must be placed above the database block you want to refer to them from.

Plugin "perl"¶

Plugin "pinba"¶

 <Plugin pinba>
   Address "::0"
   Port "30002"
   # Overall statistics for the website.
   <View "www-total">
     Server "www.example.com"
   </View>
   # Statistics for www-a only
   <View "www-a">
     Host "www-a.example.com"
     Server "www.example.com"
   </View>
   # Statistics for www-b only
   <View "www-b">
     Host "www-b.example.com"
     Server "www.example.com"
   </View>
 </Plugin>

Address Node

Configures the address used to open a listening socket. By default, plugin will bind to the any address "::0".

Port Service

Configures the port (service) to bind to. By default the default Pinba port "30002" will be used. The option accepts service names in addition to port numbers and thus requires a string argument.

<View Name> 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 View blocks it is possible to separate the data into multiple groups to get more meaningful statistics. Each packet is added to all matching groups, so that a packet may be accounted for more than once.

Plugin "ping"¶

Host IP-address

Host to ping periodically. This option may be repeated several times to ping multiple hosts.

Interval Seconds

Sets the interval in which to send ICMP echo packets to the configured hosts. This is not 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 Interval setting. Fractional times, such as "1.24" are allowed.

 

Default: 1.0

Timeout Seconds

Time to wait for a response from the host to which an ICMP packet had been sent. If a reply was not received after Seconds seconds, the host is assumed to be down or the packet to be dropped. This setting must be smaller than the Interval setting above for the plugin to work correctly. Fractional arguments are accepted.

 

Default: 0.9

TTL 0-255

Sets the Time-To-Live of generated ICMP packets.

SourceAddress host

Sets the source address to use. host may either be a numerical network address or a network hostname.

Device name

Sets the outgoing network device to be used. name has to specify an interface name (e. g. "eth0"). This might not be supported by all operating systems.

MaxMissed Packets

Trigger a DNS resolve after the host has not replied to Packets packets. This enables the use of dynamic DNS services (like dyndns.org) with the ping plugin.

 

Default: -1 (disabled)

Plugin "postgresql"¶

  <Plugin postgresql>
    <Query magic>
      Statement "SELECT magic FROM wizard WHERE host = $1;"
      Param hostname
      <Result>
        Type gauge
        InstancePrefix "magic"
        ValuesFrom magic
      </Result>
    </Query>
    <Query rt36_tickets>
      Statement "SELECT COUNT(type) AS count, type \
                        FROM (SELECT CASE \
                                     WHEN resolved = 'epoch' THEN 'open' \
                                     ELSE 'resolved' END AS type \
                                     FROM tickets) type \
                        GROUP BY type;"
      <Result>
        Type counter
        InstancePrefix "rt36_tickets"
        InstancesFrom "type"
        ValuesFrom "count"
      </Result>
    </Query>
    <Database foo>
      Host "hostname"
      Port "5432"
      User "username"
      Password "secret"
      SSLMode "prefer"
      KRBSrvName "kerberos_service_name"
      Query magic
    </Database>
    <Database bar>
      Interval 300
      Service "service_name"
      Query backend # predefined
      Query rt36_tickets
    </Database>
  </Plugin>

Statement sql query statement

Specify the sql query statement which the plugin should execute. The string may contain the tokens $1, $2, etc. which are used to reference the first, second, etc. parameter. The value of the parameters is specified by the Param configuration option - see below for details. To include a literal $ character followed by a number, surround it with single quotes ( ').

 

Any SQL command which may return data (such as "SELECT" or "SHOW") is allowed. Note, however, that only a single command may be used. Semicolons are allowed as long as a single non-empty command has been specified only.

 

The returned lines will be handled separately one after another.

Param hostname|database|username| interval

Specify the parameters which should be passed to the SQL query. The parameters are referred to in the SQL query as $1, $2, etc. in the same order as they appear in the configuration file. The value of the parameter is determined depending on the value of the Param option as follows:

Type type

The type name to be used when dispatching the values. The type describes how to handle the data and where to store it. See types.db(5) for more details on types and their configuration. The number and type of values (as selected by the ValuesFrom option) has to match the type of the given name.

 

This option is required inside a Result block.

InstancePrefix prefix

InstancesFrom column0 [column1 ...]

Specify how to create the "TypeInstance" for each data set (i. e. line). InstancePrefix defines a static prefix that will be prepended to all type instances. InstancesFrom defines the column names whose values will be used to create the type instance. Multiple values will be joined together using the hyphen ("-") as separation character.

 

The plugin itself does not check whether or not all built instances are different. It is your responsibility to assure that each is unique.

 

Both options are optional. If none is specified, the type instance will be empty.

ValuesFrom column0 [column1 ...]

Names the columns 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 Type setting as explained 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 actual data type, as seen by PostgreSQL, is not that important as long as it represents numbers. The plugin will automatically cast the values to the right type if it know how to do that. For that, it uses the strtoll(3) and strtod(3) functions, so anything supported by those functions is supported by the plugin as well.

 

This option is required inside a Result block and may be specified multiple times. If multiple ValuesFrom options are specified, the columns are read in the given order.

MinVersion version

MaxVersion version

Specify the minimum or maximum version of PostgreSQL that this query should be used with. Some statistics might only be available with certain versions of PostgreSQL. This allows you to specify multiple queries with the same name but which apply to different versions, thus allowing you to use the same configuration in a heterogeneous environment.

 

The version has to be specified as the concatenation of the major, minor and patch-level versions, each represented as two-decimal-digit numbers. For example, version 8.2.3 will become 80203.

backends

This query collects the number of backends, i. e. the number of connected clients.

transactions

This query collects the numbers of committed and rolled-back transactions of the user tables.

queries

This query collects the numbers of various table modifications (i. e. insertions, updates, deletions) of the user tables.

query_plans

This query collects the numbers of various table scans and returned tuples of the user tables.

table_states

This query collects the numbers of live and dead rows in the user tables.

disk_io

This query collects disk block access counts for user tables.

disk_usage

This query collects the on-disk size of the database in bytes.

Interval seconds

Specify the interval with which the database should be queried. The default is to use the global Interval setting.

Host hostname

Specify the hostname or IP of the PostgreSQL server to connect to. If the value begins with a slash, it is interpreted as the directory name in which to look for the UNIX domain socket.

 

This option is also used to determine the hostname that is associated with a collected data set. If it has been omitted or either begins with with a slash or equals localhost it will be replaced with the global hostname definition of collectd. Any other value will be passed literally to collectd when dispatching values. Also see the global Hostname and FQDNLookup options.

Port port

Specify the TCP port or the local UNIX domain socket file extension of the server.

User username

Specify the username to be used when connecting to the server.

Password password

Specify the password to be used when connecting to the server.

SSLMode disable|allow|prefer|require

Specify whether to use an SSL connection when contacting the server. The following modes are supported:

KRBSrvName kerberos_service_name

Specify the Kerberos service name to use when authenticating with Kerberos 5 or GSSAPI. See the sections "Kerberos authentication" and "GSSAPI" of the PostgreSQL Documentation for details.

Service service_name

Specify the PostgreSQL service name to use for additional parameters. That service has to be defined in pg_service.conf and holds additional connection parameters. See the section "The Connection Service File" in the PostgreSQL Documentation for details.

Query query

Specify a query which should be executed for the database connection. This may be any of the predefined or user-defined queries. If no such option is given, it defaults to "backends", "transactions", "queries", "query_plans", "table_states", "disk_io" and "disk_usage". Else, the specified queries are used only.

Plugin "powerdns"¶

  <Plugin "powerdns">
    <Server "server_name">
      Collect "latency"
      Collect "udp-answers" "udp-queries"
      Socket "/var/run/pdns.controlsocket"
    </Server>
    <Recursor "recursor_name">
      Collect "questions"
      Collect "cache-hits" "cache-misses"
      Socket "/var/run/pdns_recursor.controlsocket"
    </Recursor>
    LocalSocket "/opt/collectd/var/run/collectd-powerdns"
  </Plugin>

Server and Recursor block

The Server block defines one authoritative server to query, the Recursor does the same for an recursing server. The possible options in both blocks are the same, though. The argument defines a name for the server / recursor and is required.

  powerdns plugin: submit: Not found in lookup table: foobar = 42

LocalSocket Path

Querying the recursor is done using UDP. When using UDP over UNIX domain sockets, the client socket needs a name in the file system, too. You can set this local name to Path using the LocalSocket option. The default is " prefix/var/run/collectd-powerdns".

Plugin "processes"¶

Process Name

Select more detailed statistics of processes matching this name. The statistics collected for these selected processes are size of the resident segment size (RSS), user- and system-time used, number of processes and number of threads, io data (where available) and minor and major pagefaults.

ProcessMatch name regex

Similar to the Process option this allows to select more detailed statistics of processes matching the specified regex (see regex(7) for details). The statistics of all matching processes are summed up and dispatched to the daemon using the specified name as an identifier. This allows to "group" several processes together. name must not contain slashes.

Plugin "protocols"¶

Value Selector

Selects whether or not to select a specific value. The string being matched is of the form " Protocol:ValueName", where Protocol will be used as the plugin instance and ValueName will be used as type instance. An example of the string being used would be "Tcp:RetransSegs".

 

You can use regular expressions to match a large number of values with just one configuration option. To select all "extended" TCP values, you could use the following statement:

 

  Value "/^TcpExt:/"
    

 

Whether only matched values are selected or all matched values are ignored depends on the IgnoreSelected. By default, only matched values are selected. If no value is configured at all, all values will be selected.

IgnoreSelected true|false

If set to true, inverts the selection made by Value, i. e. all matching values will be ignored.

Plugin "python"¶

Plugin "routeros"¶

  <Plugin "routeros">
    <Router>
      Host "router0.example.com"
      User "collectd"
      Password "secr3t"
      CollectInterface true
      CollectCPULoad true
      CollectMemory true
    </Router>
    <Router>
      Host "router1.example.com"
      User "collectd"
      Password "5ecret"
      CollectInterface true
      CollectRegistrationTable true
      CollectDF true
      CollectDisk true
    </Router>
  </Plugin>

Host Host

Hostname or IP-address of the router to connect to.

Port Port

Port name or port number used when connecting. If left unspecified, the default will be chosen by librouteros, currently "8728". This option expects a string argument, even when a numeric port number is given.

User User

Use the user name User to authenticate. Defaults to "admin".

Password Password

Set the password used to authenticate.

CollectInterface true|false

When set to true, interface statistics will be collected for all interfaces present on the device. Defaults to false.

CollectRegistrationTable true|false

When set to true, information about wireless LAN connections will be collected. Defaults to false.

CollectCPULoad true|false

When set to true, information about the CPU usage will be collected. The number is a dimensionless value where zero indicates no CPU usage at all. Defaults to false.

CollectMemory true|false

When enabled, the amount of used and free memory will be collected. How used memory is calculated is unknown, for example whether or not caches are counted as used space. Defaults to false.

CollectDF true|false

When enabled, the amount of used and free disk space will be collected. Defaults to false.

CollectDisk true|false

When enabled, the number of sectors written and bad blocks will be collected. Defaults to false.

Plugin "redis"¶

  <Plugin redis>
    <Node "example">
        Host "localhost"
        Port "6379"
        Timeout 2000
    </Node>
  </Plugin>

Node Nodename

The Node block identifies a new Redis node, that is a new Redis instance running in an specified host and port. The name for node is a canonical identifier which is used as plugin instance. It is limited to 64 characters in length.

Host Hostname

The Host option is the hostname or IP-address where the Redis instance is running on.

Port Port

The Port option is the TCP port on which the Redis instance accepts connections. Either a service name of a port number may be given. Please note that numerical port numbers must be given as a string, too.

Timeout Timeout in miliseconds

The Timeout option set the socket timeout for node response. Since the Redis read function is blocking, you should keep this value as low as possible. Keep in mind that the sum of all Timeout values for all Nodes should be lower than Interval defined globally.

Plugin "rrdcached"¶

DaemonAddress Address

Address of the daemon as understood by the "rrdc_connect" function of the RRD library. See rrdcached(1) for details. Example:

 

  <Plugin "rrdcached">
    DaemonAddress "unix:/var/run/rrdcached.sock"
  </Plugin>
    

DataDir Directory

Set the base directory in which the RRD files reside. If this is a relative path, it is relative to the working base directory of the "rrdcached" daemon! Use of an absolute path is recommended.

CreateFiles true|false

Enables or disables the creation of RRD files. If the daemon is not running locally, or DataDir is set to a relative path, this will not work as expected. Default is true.

Plugin "rrdtool"¶

DataDir Directory

Set the directory to store RRD-files under. Per default RRD-files are generated beneath the daemon's working directory, i. e. the BaseDir.

StepSize Seconds

Force the stepsize of newly created RRD-files. Ideally (and per default) this setting is unset and the stepsize is set to the interval in which the data is collected. Do not use this option unless you absolutely have to for some reason. Setting this option may cause problems with the "snmp plugin", the "exec plugin" or when the daemon is set up to receive data from other hosts.

HeartBeat Seconds

Force the heartbeat of newly created RRD-files. This setting should be unset in which case the heartbeat is set to twice the StepSize which should equal the interval in which data is collected. Do not set this option unless you have a very good reason to do so.

RRARows NumRows

The "rrdtool plugin" calculates the number of PDPs per CDP based on the StepSize, this setting and a timespan. This plugin creates RRD-files with three times five RRAs, i. e. five RRAs with the CFs MIN, AVERAGE, and MAX. The five RRAs are optimized for graphs covering one hour, one day, one week, one month, and one year.

 

So for each timespan, it calculates how many PDPs need to be consolidated into one CDP by calculating:
number of PDPs = timespan / (stepsize * rrarows)

 

Bottom line is, set this no smaller than the width of you graphs in pixels. The default is 1200.

RRATimespan Seconds

Adds an RRA-timespan, given in seconds. Use this option multiple times to have more then one RRA. If this option is never used, the built-in default of (3600, 86400, 604800, 2678400, 31622400) is used.

 

For more information on how RRA-sizes are calculated see RRARows above.

XFF Factor

Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.

CacheFlush Seconds

When the "rrdtool" plugin uses a cache (by setting CacheTimeout, see below) it writes all values for a certain RRD-file if the oldest value is older than (or equal to) the number of seconds specified. If some RRD-file is not updated anymore for some reason (the computer was shut down, the network is broken, etc.) some values may still be in the cache. If CacheFlush is set, then the entire cache is searched for entries older than CacheTimeout seconds and written to disk every Seconds seconds. Since this is kind of expensive and does nothing under normal circumstances, this value should not be too small. 900 seconds might be a good value, though setting this to 7200 seconds doesn't normally do much harm either.

CacheTimeout Seconds

If this option is set to a value greater than zero, the "rrdtool plugin" will save values in a cache, as described above. Writing multiple values at once 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.

WritesPerSecond Updates

When collecting many statistics with collectd and the "rrdtool" plugin, you will run serious performance problems. The CacheFlush setting and the internal update queue assert that collectd continues to work just fine even under heavy load, but the system may become very unresponsive and slow. This is a problem especially if you create graphs from the RRD files on the same machine, for example using the "graph.cgi" script included in the "contrib/collection3/" directory.

 

This setting is designed for very large setups. Setting this option to a value between 25 and 80 updates per second, depending on your hardware, will leave the server responsive enough to draw graphs even while all the cached values are written to disk. Flushed values, i. e. values that are forced to disk by the FLUSH command, are not effected by this limit. They are still written as fast as possible, so that web frontends have up to date data when generating graphs.

 

For example: If you have 100,000 RRD files and set WritesPerSecond to 30 updates per second, writing all values to disk will take approximately 56 minutes. Together with the flushing ability that's integrated into "collection3" you'll end up with a responsive and fast system, up to date graphs and basically a "backup" of your values every hour.

RandomTimeout Seconds

When set, the actual timeout for each value is chosen randomly between CacheTimeout-RandomTimeout and CacheTimeout+ RandomTimeout. The intention is to avoid high load situations that appear when many values timeout at the same time. This is especially a problem shortly after the daemon starts, because all values were added to the internal cache at roughly the same time.

Plugin "sensors"¶

SensorConfigFile File

Read the lm_sensors configuration from File. When unset (recommended), the library's default will be used.

Sensor chip-bus-address/type-feature

Selects the name of the sensor which you want to collect or ignore, depending on the IgnoreSelected below. For example, the option " Sensor it8712-isa-0290/voltage-in1" will cause collectd to gather data for the voltage sensor in1 of the it8712 on the isa bus at the address 0290.

IgnoreSelected true|false

If no configuration if given, the sensors-plugin will collect data from all sensors. This may not be practical, especially for uninteresting sensors. Thus, you can use the Sensor-option to pick the sensors you're interested in. Sometimes, however, it's easier/preferred to collect all sensors except a few ones. This option enables you to do that: By setting IgnoreSelected to true the effect of Sensor is inverted: All selected sensors are ignored and all other sensors are collected.

Plugin "snmp"¶

Plugin "swap"¶

ReportByDevice false|true

Configures how to report physical swap devices. If set to false (the default), the summary over all swap devices is reported only, i.e. the globally used and available space over all devices. If true is configured, the used and available space of each device will be reported separately.

 

This option is only available if the Swap plugin can read "/proc/swaps" (under Linux) or use the swapctl(2) mechanism (under Solaris).

Plugin "syslog"¶

LogLevel debug|info|notice|warning|err

Sets the log-level. If, for example, set to notice, then all events with severity notice, warning, or err will be submitted to the syslog-daemon.

 

Please note that debug is only available if collectd has been compiled with debugging support.

NotifyLevel OKAY|WARNING|FAILURE

Controls which notifications should be sent to syslog. The default behaviour is not to send any. Less severe notifications always imply logging more severe notifications: Setting this to OKAY means all notifications will be sent to syslog, setting this to WARNING will send WARNING and FAILURE notifications but will dismiss OKAY notifications. Setting this option to FAILURE will only send failures to syslog.

Plugin "table"¶

  <Plugin table>
    <Table "/proc/slabinfo">
      Instance "slabinfo"
      Separator " "
      <Result>
        Type gauge
        InstancePrefix "active_objs"
        InstancesFrom 0
        ValuesFrom 1
      </Result>
      <Result>
        Type gauge
        InstancePrefix "objperslab"
        InstancesFrom 0
        ValuesFrom 4
      </Result>
    </Table>
  </Plugin>

Instance instance

If specified, instance is used as the plugin instance. So, in the above example, the plugin name "table-slabinfo" would be used. If omitted, the filename of the table is used instead, with all special characters replaced with an underscore ("_").

Separator string

Any character of string 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. e. there cannot be any empty columns. The plugin uses the strtok_r(3) 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 "\\t", "\\n" and "\\r" respectively. Please note that the double backslashes are required because of collectd's config parsing.

Type type

Sets the type used to dispatch the values to the daemon. Detailed information about types and their configuration can be found in types.db(5). This option is mandatory.

InstancePrefix prefix

If specified, prepend prefix to the type instance. If omitted, only the InstancesFrom option is considered for the type instance.

InstancesFrom column0 [column1 ...]

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 ( -) as separation character. If omitted, only the InstancePrefix option is considered for the type instance.

 

The plugin itself does not check whether or not all built instances are different. ItaXXs your responsibility to assure that each is unique. This is especially true, if you do not specify InstancesFrom: You have to make sure that the table only contains one row.

 

If neither InstancePrefix nor InstancesFrom is given, the type instance will be empty.

ValuesFrom column0 [column1 ...]

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 Type 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 strtoll(3) and strtod(3) to parse counter and gauge values respectively, so anything supported by those functions is supported by the plugin as well. This option is mandatory.

Plugin "tail"¶

  <Plugin "tail">
    <File "/var/log/exim4/mainlog">
      Instance "exim"
      <Match>
        Regex "S=([1-9][0-9]*)"
        DSType "CounterAdd"
        Type "ipt_bytes"
        Instance "total"
      </Match>
      <Match>
        Regex "\\<R=local_user\\>"
        ExcludeRegex "\\<R=local_user\\>.*mail_spool defer"
        DSType "CounterInc"
        Type "counter"
        Instance "local_user"
      </Match>
    </File>
  </Plugin>

Regex regex

Sets the regular expression to use for matching against a line. The first subexpression has to match something that can be turned into a number by strtoll(3) or strtod(3), depending on the value of "CounterAdd", see below. Because extended regular expressions are used, you do not need to use backslashes for subexpressions! If in doubt, please consult regex(7). Due to collectd's config parsing you need to escape backslashes, though. So if you want to match literal parentheses you need to do the following:

 

  Regex "SPAM \\(Score: (-?[0-9]+\\.[0-9]+)\\)"
    

ExcludeRegex regex

Sets an optional regular expression to use for excluding lines from the match. An example which excludes all connections from localhost from the match:

 

  ExcludeRegex "127\\.0\\.0\\.1"
    

DSType Type

Sets how the values are cumulated. Type is one of:

Type Type

Sets the type used to dispatch this value. Detailed information about types and their configuration can be found in types.db(5).

Instance TypeInstance

This optional setting sets the type instance to use.

Plugin "teamspeak2"¶

Host hostname/ip

The hostname or ip which identifies the physical server. Default: 127.0.0.1

Port port

The query port of the physical server. This needs to be a string. Default: "51234"

Server port

This option has to be added once for every virtual server the plugin should query. If you want to query the virtual server on port 8767 this is what the option would look like:

 

  Server "8767"
    

 

This option, although numeric, needs to be a string, i. e. you must use quotes around it! If no such statement is given only global information will be collected.

Plugin "ted"¶

Device Path

Path to the device on which TED is connected. collectd will need read and write permissions on that file.

 

Default: /dev/ttyUSB0

Retries Num

Apparently reading from TED is not that reliable. You can therefore configure a number of retries here. You only configure the retries 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: 0

Plugin "tcpconns"¶

ListeningPorts true|false

If this option is set to true, statistics for all local ports for which a listening socket exists are collected. The default depends on LocalPort and RemotePort (see below): If no port at all is specifically selected, the default is to collect listening ports. If specific ports (no matter if local or remote ports) are selected, this option defaults to false, i. e. only the selected ports will be collected unless this option is set to true specifically.

LocalPort Port

Count the connections to a specific local port. This can be used to see how many connections are handled by a specific daemon, e. g. the mailserver. You have to specify the port in numeric form, so for the mailserver example you'd need to set 25.

RemotePort Port

Count the connections to a specific remote port. This is useful to see how much a remote service is used. This is most useful if you want to know how many connections a local service has opened to remote services, e. g. how many connections a mail server or news server has to other mail or news servers, or how many connections a web proxy holds to web servers. You have to give the port in numeric form.

Plugin "thermal"¶

ForceUseProcfs true|false

By default, the Thermal plugin tries to read the statistics from the Linux "sysfs" interface. If that is not available, the plugin falls back to the "procfs" interface. By setting this option to true, you can force the plugin to use the latter. This option defaults to false.

Device Device

Selects the name of the thermal device that you want to collect or ignore, depending on the value of the IgnoreSelected option. This option may be used multiple times to specify a list of devices.

IgnoreSelected true|false

Invert the selection: If set to true, all devices except the ones that match the device names specified by the Device option are collected. By default only selected devices are collected if a selection is made. If no selection is configured at all, all devices are selected.

Plugin "threshold"¶

Plugin "tokyotyrant"¶

Host Hostname/IP

The hostname or ip which identifies the server. Default: 127.0.0.1

Port Service/Port

The query port of the server. This needs to be a string, even if the port is given in its numeric form. Default: 1978

Plugin "unixsock"¶

SocketFile Path

Sets the socket-file which is to be created.

SocketGroup Group

If running as root change the group of the UNIX-socket after it has been created. Defaults to collectd.

SocketPerms Permissions

Change the file permissions of the UNIX-socket after it has been created. The permissions must be given as a numeric, octal value as you would pass to chmod(1). Defaults to 0770.

DeleteSocket false|true

If set to true, delete the socket file before calling bind(2), if a file with the given name already exists. If collectd crashes a socket file may be left over, preventing the daemon from opening a new socket when restarted. Since this is potentially dangerous, this defaults to false.

Plugin "uuid"¶

•

Check /etc/uuid (or UUIDFile).

•

Check for UUID from HAL (<http://www.freedesktop.org/wiki/Software/hal>) if present.

•

Check for UUID from "dmidecode" / SMBIOS.

•

Check for UUID from Xen hypervisor.

UUIDFile Path

Take the UUID from the given file (default /etc/uuid).

Plugin "varnish"¶

CollectCache true|false

Cache hits and misses. True by default.

CollectConnections true|false

Number of client connections received, accepted and dropped. True by default.

CollectBackend true|false

Back-end connection statistics, such as successful, reused, and closed connections. True by default.

CollectSHM true|false

Statistics about the shared memory log, a memory region to store log messages which is flushed to disk when full. True by default.

CollectESI true|false

Edge Side Includes (ESI) parse statistics. False by default.

CollectFetch true|false

Statistics about fetches (HTTP requests sent to the backend). False by default.

CollectHCB true|false

Inserts and look-ups in the crit bit tree based hash. Look-ups are divided into locked and unlocked look-ups. False by default.

CollectSMA true|false

malloc or umem (umem_alloc(3MALLOC) based) storage statistics. The umem storage component is Solaris specific. False by default.

CollectSMS true|false

synth (synthetic content) storage statistics. This storage component is used internally only. False by default.

CollectSM true|false

file (memory mapped file) storage statistics. False by default.

CollectTotals true|false

Collects overview counters, such as the number of sessions created, the number of requests and bytes transferred. False by default.

CollectWorkers true|false

Collect statistics about worker threads. False by default.

Plugin "vmem"¶

Verbose true|false

Enables verbose collection of information. This will start collecting page "actions", e. g. page allocations, (de)activations, steals and so on. Part of these statistics are collected on a "per zone" basis.

Plugin "vserver"¶

Plugin "write_graphite"¶

 <Plugin write_graphite>
   <Carbon>
     Host "localhost"
     Port "2003"
     Prefix "collectd"
   </Carbon>
 </Plugin>

Host Address

Hostname or address to connect to. Defaults to "localhost".

Port Service

Service name or port number to connect to. Defaults to 2003.

Prefix String

When set, String is added in front of the host name. Dots and whitespace are not escaped in this string (see EscapeCharacter below).

Postfix String

When set, String is appended to the host name. Dots and whitespace are not escaped in this string (see EscapeCharacter below).

EscapeCharacter Char

Carbon uses the dot (".") as escape character and doesn't allow whitespace in the identifier. The EscapeCharacter option determines which character dots, whitespace and control characters are replaced with. Defaults to underscore ("_").

StoreRates false|true

If set to true (the default), convert counter values to rates. If set to false counter values are stored as is, i. e. as an increasing integer number.

SeparateInstances false|true

If set to true, the plugin instance and type instance will be in their own path component, for example "host.cpu.0.cpu.idle". If set to false (the default), the plugin and plugin instance (and likewise the type and type instance) are put into once component, for example "host.cpu-0.cpu-idle".

AlwaysAppendDS false|true

If set the true, append the name of the Data Source (DS) to the "metric" identifier. If set to false (the default), this is only done when there is more than one DS.

Plugin "write_mongodb"¶

 <Plugin "write_mongodb">
   <Node "default">
     Host "localhost"
     Port "27017"
     Timeout 1000
     StoreRates true
   </Node>
 </Plugin>

Host Address

Hostname or address to connect to. Defaults to "localhost".

Port Service

Service name or port number to connect to. Defaults to 27017.

Timeout Timeout

Set the timeout for each operation on MongoDB to Timeout milliseconds. Setting this option to zero means no timeout, which is the default.

StoreRates false|true

If set to true (the default), convert counter values to rates. If set to false counter values are stored as is, i.e. as an increasing integer number.

Plugin "write_http"¶

 <Plugin "write_http">
   <URL "http://example.com/post-collectd">
     User "collectd"
     Password "weCh3ik0"
   </URL>
 </Plugin>

User Username

Optional user name needed for authentication.

Password Password

Optional password needed for authentication.

VerifyPeer true|false

Enable or disable peer SSL certificate verification. See <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.

VerifyHost true|false

Enable or disable peer host name verification. If enabled, the plugin checks if the "Common Name" or a "Subject Alternate Name" field of the SSL certificate matches the host name provided by the URL option. If this identity check fails, the connection is aborted. Obviously, only works when connecting to a SSL enabled server. Enabled by default.

CACert File

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 "libcurl" and are checked by default depends on the distribution you use.

Format Command|JSON

Format of the output to generate. If set to Command, will create output that is understood by the Exec and UnixSock plugins. When set to JSON, will create output in the JavaScript Object Notation (JSON).

 

Defaults to Command.

StoreRates true|false

If set to true, convert counter values to rates. If set to false (the default) counter values are stored as is, i. e. as an increasing integer number.

THRESHOLD CONFIGURATION¶

 <Threshold>
   <Type "foo">
     WarningMin    0.00
     WarningMax 1000.00
     FailureMin    0.00
     FailureMax 1200.00
     Invert false
     Instance "bar"
   </Type>
   <Plugin "interface">
     Instance "eth0"
     <Type "if_octets">
       FailureMax 10000000
       DataSource "rx"
     </Type>
   </Plugin>
   <Host "hostname">
     <Type "cpu">
       Instance "idle"
       FailureMin 10
     </Type>
     <Plugin "memory">
       <Type "memory">
         Instance "cached"
         WarningMin 100000000
       </Type>
     </Plugin>
   </Host>
 </Threshold>

FailureMax Value

WarningMax Value

Sets the upper bound of acceptable values. If unset defaults to positive infinity. If a value is greater than FailureMax a FAILURE notification will be created. If the value is greater than WarningMax but less than (or equal to) FailureMax a WARNING notification will be created.

FailureMin Value

WarningMin Value

Sets the lower bound of acceptable values. If unset defaults to negative infinity. If a value is less than FailureMin a FAILURE notification will be created. If the value is less than WarningMin but greater than (or equal to) FailureMin a WARNING notification will be created.

DataSource DSName

Some data sets have more than one "data source". Interesting examples are the "if_octets" data set, which has received ("rx") and sent ("tx") bytes and the "disk_ops" data set, which holds "read" and "write" operations. The system load data set, "load", even has three data sources: "shortterm", "midterm", and "longterm".

 

Normally, all data sources are checked against a configured threshold. If this is undesirable, or if you want to specify different limits for each data source, you can use the DataSource option to have a threshold apply only to one data source.

Invert true|false

If set to true the range of acceptable values is inverted, i. e. values between FailureMin and FailureMax ( WarningMin and WarningMax) are not okay. Defaults to false.

Persist true|false

Sets how often notifications are generated. If set to true one notification will be generated for each value that is out of the acceptable range. If set to false (the default) then a notification is only generated if a value is out of range but the previous value was okay.

 

This applies to missing values, too: If set to true a notification about a missing value is generated once every Interval seconds. If set to false only one such notification is generated until the value appears again.

Percentage true|false

If set to true, the minimum and maximum values given are interpreted as percentage value, relative to the other data sources. This is helpful for example for the "df" type, where you may want to issue a warning when less than 5 % of the total space is available. Defaults to false.

Hits Number

Delay creating the notification until the threshold has been passed Number times. When a notification has been generated, or when a subsequent value is inside the threshold, the counter is reset. If, for example, a value is collected once every 10 seconds and Hits is set to 3, a notification will be dispatched at most once every 30 seconds.

 

This is useful when short bursts are not a problem. If, for example, 100% CPU usage for up to a minute is normal (and data is collected every 10 seconds), you could set Hits to 6 to account for this.

Hysteresis Number

When set to non-zero, a hysteresis value is applied when checking minimum and maximum bounds. This is useful for values that increase slowly and fluctuate a bit while doing so. When these values come close to the threshold, they may "flap", i.e. switch between failure / warning case and okay case repeatedly.

 

If, for example, the threshold is configures as

 

  WarningMax 100.0
  Hysteresis 1.0
    

 

then a Warning notification is created when the value exceeds 101 and the corresponding Okay notification is only created once the value falls below 99, thus avoiding the "flapping".

FILTER CONFIGURATION¶

Terminology¶

Match

A match 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.

Target

A target 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.

 

Some of these targets are built into the daemon, see "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.

Rule

The combination of any number of matches and at least one target is called a rule. The target actions will be performed for all values for which all matches apply. If the rule does not have any matches associated with it, the target action will be performed for all values.

Chain

A chain 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, see "Flow control" below. After all rules have been checked, the default targets will be executed.

General structure¶

 +---------+
 ! Chain   !
 +---------+
      !
      V
 +---------+  +---------+  +---------+  +---------+
 ! Rule    !->! Match   !->! Match   !->! Target  !
 +---------+  +---------+  +---------+  +---------+
      !
      V
 +---------+  +---------+  +---------+
 ! Rule    !->! Target  !->! Target  !
 +---------+  +---------+  +---------+
      !
      V
      :
      :
      !
      V
 +---------+  +---------+  +---------+
 ! Rule    !->! Match   !->! Target  !
 +---------+  +---------+  +---------+
      !
      V
 +---------+
 ! Default !
 ! Target  !
 +---------+

Flow control¶

jump

The built-in jump target can be used to "call" another chain, i. e. process the value with another chain. When the called chain finishes, usually the next target or rule after the jump is executed.

stop

The stop condition, signaled for example by the built-in target stop, causes all processing of the value to be stopped immediately.

return

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 Jump, 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.

continue

Most targets will signal the continue condition, meaning that processing should continue normally. There is no special built-in target for this condition.

Synopsis¶

 PostCacheChain "PostCache"
 <Chain "PostCache">
   <Rule "ignore_mysql_show">
     <Match "regex">
       Plugin "^mysql$"
       Type "^mysql_command$"
       TypeInstance "^show_"
     </Match>
     <Target "stop">
     </Target>
   </Rule>
   <Target "write">
     Plugin "rrdtool"
   </Target>
 </Chain>

List of configuration options¶

PreCacheChain ChainName

PostCacheChain ChainName

Configure the name of the "pre-cache chain" and the "post-cache chain". The argument is the name of a chain that should be executed before and/or after the values have been added to the cache.

 

To understand the implications, it's important you know what is going on inside collectd. The following diagram shows how values are passed from the read-plugins to the write-plugins:

 

   +---------------+
   !  Read-Plugin  !
   +-------+-------+
           !
 + - - - - V - - - - +
 : +---------------+ :
 : !   Pre-Cache   ! :
 : !     Chain     ! :
 : +-------+-------+ :
 :         !         :
 :         V         :
 : +-------+-------+ :  +---------------+
 : !     Cache     !--->!  Value Cache  !
 : !     insert    ! :  +---+---+-------+
 : +-------+-------+ :      !   !
 :         !   ,------------'   !
 :         V   V     :          V
 : +-------+---+---+ :  +-------+-------+
 : !  Post-Cache   +--->! Write-Plugins !
 : !     Chain     ! :  +---------------+
 : +---------------+ :
 :                   :
 :  dispatch values  :
 + - - - - - - - - - +
    

 

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 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 "unixsock" 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 "value" match (see below). If you use the rate stored in the cache before the new value is added, you will use the old, previous rate. Write plugins may use this rate, too, see the "csv" plugin, for example. The "unixsock" plugin uses these rates too, to implement the "GETVAL" command.

 

Last but not last, the stop target makes a difference: If the pre-cache chain returns the stop condition, the value will not be added to the cache and the post-cache chain will not be run.

Chain Name

Adds a new chain with a certain name. This name can be used to refer to a specific chain, for example to jump to it.

 

Within the Chain block, there can be Rule blocks and Target blocks.

Rule [Name]

Adds a new rule to the current chain. The name of the rule is optional and currently has no meaning for the daemon.

 

Within the Rule block, there may be any number of Match blocks and there must be at least one Target block.

Match Name

Adds a match to a Rule block. The name specifies what kind of match should be performed. Available matches depend on the plugins that have been loaded.

 

The arguments inside the Match block are passed to the plugin implementing the match, so which arguments are valid here depends on the plugin being used. If you do not need any to pass any arguments to a match, you can use the shorter syntax:

 

 Match "foobar"
    

 

Which is equivalent to:

 

 <Match "foobar">
 </Match>
    

Target Name

Add a target to a rule or a default target to a chain. The name specifies what kind of target is to be added. Which targets are available depends on the plugins being loaded.

 

The arguments inside the Target block are passed to the plugin implementing the target, so which arguments are valid here depends on the plugin being used. If you do not need any to pass any arguments to a target, you can use the shorter syntax:

 

 Target "stop"
    

 

This is the same as writing:

 

 <Target "stop">
 </Target>
    

Built-in targets¶

return

Signals the "return" condition, see the "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 jump target (see below). This is very similar to the RETURN target of iptables, see iptables(8).

 

This target does not have any options.

 

Example:

 

 Target "return"
    

stop

Signals the "stop" condition, see the "Flow control" section above. This causes processing of the value to be aborted immediately. This is similar to the DROP target of iptables, see iptables(8).

 

This target does not have any options.

 

Example:

 

 Target "stop"
    

write

Sends the value to "write" plugins.

 

Available options:

 <Target "write">
   Plugin "rrdtool"
 </Target>

jump

Starts processing the rules of another chain, see "Flow control" above. If the end of that chain is reached, or a stop condition is encountered, processing will continue right after the jump target, i. e. with the next target or the next rule. This is similar to the -j command line option of iptables, see iptables(8).

 

Available options:

 <Target "jump">
   Chain "foobar"
 </Target>

Available matches¶

regex

Matches a value using regular expressions.

 

Available options:

 <Match "regex">
   Host "customer[0-9]+"
   Plugin "^foobar$"
 </Match>

timediff

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 "network" plugin and write them to disk using the "rrdtool" 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 outside a specified time range (relative to the server's time), so you can use the stop target (see below) to ignore the value, for example.

 

Available options:

 <Match "timediff">
   Future  300
   Past   3600
 </Match>

value

Matches the actual value of data sources against given minimum / maximum values. If a data-set consists of more than one data-source, all data-sources must match the specified ranges for a positive match.

 

Available options:

 # Match all values smaller than or equal to 100. Matches only if all data
 # sources are below 100.
 <Match "value">
   Max 100
   Satisfy "All"
 </Match>
 
 # Match if the value of any data source is outside the range of 0 - 100.
 <Match "value">
   Min   0
   Max 100
   Invert true
   Satisfy "Any"
 </Match>

empty_counter

Matches all values with one or more data sources of type COUNTER and where all counter values are zero. These counters usually never increased since they started existing (and are therefore uninteresting), or got reset recently or overflowed and you had really, really bad luck.

 

Please keep in mind that ignoring such counters can result in confusing behavior: Counters which hardly ever increase will be zero for long periods of time. If the counter is reset for some reason (machine or service restarted, usually), the graph will be empty (NAN) for a long time. People may not understand why.

hashed

Calculates a hash value of the host name and matches values according to that hash value. This makes it possible to divide all hosts into groups and match only values that are in a specific group. The intended use is in load balancing, where you want to handle only part of all data and leave the rest for other servers.

 

The hashing function used tries to distribute the hosts evenly. First, it calculates a 32 bit hash value using the characters of the hostname:

 

  hash_value = 0;
  for (i = 0; host[i] != 0; i++)
    hash_value = (hash_value * 251) + host[i];
    

 

The constant 251 is a prime number which is supposed to make this hash value more random. The code then checks the group for this host according to the Total and Match arguments:

 

  if ((hash_value % Total) == Match)
    matches;
  else
    does not match;
    

 

Please note that when you set Total to two (i. e. you have only two groups), then the least significant bit of the hash value will be the XOR of all least significant bits in the host name. One consequence is that when you have two hosts, "server0.example.com" and "server1.example.com", where the host name differs in one digit only and the digits differ by one, those hosts will never end up in the same group.

 

Available options:

 # Operate on the pre-cache chain, so that ignored values are not even in the
 # global cache.
 <Chain "PreCache">
   <Rule>
     <Match "hashed">
       # Divide all received hosts in seven groups and accept all hosts in
       # group three.
       Match 3 7
     </Match>
     # If matched: Return and continue.
     Target "return"
   </Rule>
   # If not matched: Return and stop.
   Target "stop"
 </Chain>

Available targets¶

notification

Creates and dispatches a notification.

 

Available options:

  <Target "notification">
    Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
    Severity "WARNING"
  </Target>

replace

Replaces parts of the identifier using regular expressions.

 

Available options:

 <Target "replace">
   # Replace "example.net" with "example.com"
   Host "\\<example.net\\>" "example.com"
 
   # Strip "www." from hostnames
   Host "\\<www\\." ""
 </Target>

set

Sets part of the identifier of a value to a given string.

 

Available options:

 <Target "set">
   PluginInstance "coretemp"
   TypeInstance "core3"
 </Target>

Backwards compatibility¶

 <Chain "PostCache">
   Target "write"
 </Chain>

Examples¶

 <Chain "PreCache">
   <Rule "no_fqdn">
     <Match "regex">
       Host "^[^\.]*$"
     </Match>
     Target "stop"
   </Rule>
   Target "write"
 </Chain>

SEE ALSO¶

AUTHOR¶