1COLLECTD.CONF(5) collectd COLLECTD.CONF(5)
2
6 collectd.conf - Configuration for the system statistics collection
7 daemon collectd
8
10 BaseDir "/path/to/data/"
11 PIDFile "/path/to/pidfile/collectd.pid"
12 Server "123.123.123.123" 12345
13 LoadPlugin cpu
15 LoadPlugin load
16 LoadPlugin ping
17 <Plugin ping>
19 Host "example.org"
20 Host "provider.net"
21 </Plugin>
22
24 This config file controls how the system statistics collection daemon
25 collectd behaves. The most significant option is LoadPlugin, which
26 controls which plugins to load. These plugins ultimately define
27 collectd's behavior.
28 The syntax of this config file is similar to the config file of the
30 famous Apache Webserver. Each line contains either a key-value-pair or
31 a section-start or -end. Empty lines and everything after the hash-
32 symbol `#' is ignored. Values are either string, enclosed in double-
33 quotes, (floating-point-)numbers or a boolean expression, i. e. either
34 true or false. String containing of only alphanumeric characters and
35 underscores do not need to be quoted. Lines may be wrapped by using `\'
36 as the last character before the newline. This allows long lines to be
37 split into multiple lines. Quoted strings may be wrapped as well.
38 However, those are treated special in that whitespace at the beginning
39 of the following lines will be ignored, which allows for nicely
40 indenting the wrapped lines.
41 The configuration is read and processed in order, i. e. from top to
43 bottom. So the plugins are loaded in the order listed in this config
44 file. It is a good idea to load any logging plugins first in order to
45 catch messages from plugins during configuration. Also, the
46 "LoadPlugin" option must occur before the "<Plugin ...>" block.
47
49 BaseDir Directory
50 Sets the base directory. This is the directory beneath all RRD-
51 files are created. Possibly more subdirectories are created. This
52 is also the working directory for the daemon.
53 LoadPlugin Plugin
55 Loads the plugin Plugin. There must be at least one such line or
56 collectd will be mostly useless.
57 Starting with collectd 4.9, this may also be a block in which
59 further options affecting the behavior of LoadPlugin may be
60 specified. The following options are allowed inside a LoadPlugin
61 block:
62 <LoadPlugin perl>
64 Globals true
65 </LoadPlugin>
66 Globals true|false
68 If enabled, collectd will export all global symbols of the
69 plugin (and of all libraries loaded as dependencies of the
70 plugin) and, thus, makes those symbols available for resolving
71 unresolved symbols in subsequently loaded plugins if that is
72 supported by your system. By default, this is disabled.
73 This is useful (or possibly even required), e. g., when loading
75 a plugin that embeds some scripting language into the daemon
76 (e. g. the "perl" or "python" plugins). Scripting languages
77 usually provide means to load extensions written in C. Those
78 extensions require symbols provided by the interpreter, which
79 is loaded as a dependency of the respective collectd plugin.
80 See the documentation of those plugins (e. g., collectd-perl(5)
81 or collectd-python(5)) for details.
82 Include Path
84 If Path points to a file, includes that file. If Path points to a
85 directory, recursively includes all files within that directory and
86 its subdirectories. If the "wordexp" function is available on your
87 system, shell-like wildcards are expanded before files are
88 included. This means you can use statements like the following:
89 Include "/etc/collectd.d/*.conf"
91 If more than one files are included by a single Include option, the
93 files will be included in lexicographical order (as defined by the
94 "strcmp" function). Thus, you can e. g. use numbered prefixes to
95 specify the order in which the files are loaded.
96 To prevent loops and shooting yourself in the foot in interesting
98 ways the nesting is limited to a depth of 8 levels, which should be
99 sufficient for most uses. Since symlinks are followed it is still
100 possible to crash the daemon by looping symlinks. In our opinion
101 significant stupidity should result in an appropriate amount of
102 pain.
103 It is no problem to have a block like "<Plugin foo>" in more than
105 one file, but you cannot include files from within blocks.
106 PIDFile File
108 Sets where to write the PID file to. This file is overwritten when
109 it exists and deleted when the program is stopped. Some init-
110 scripts might override this setting using the -P command-line
111 option.
112 PluginDir Directory
114 Path to the plugins (shared objects) of collectd.
115 TypesDB File [File ...]
117 Set one or more files that contain the data-set descriptions. See
118 types.db(5) for a description of the format of this file.
119 Interval Seconds
121 Configures the interval in which to query the read plugins.
122 Obviously smaller values lead to a higher system load produced by
123 collectd, while higher values lead to more coarse statistics.
124 Warning: You should set this once and then never touch it again. If
126 you do, you will have to delete all your RRD files or know some
127 serious RRDtool magic! (Assuming you're using the RRDtool or
128 RRDCacheD plugin.)
129 ReadThreads Num
131 Number of threads to start for reading plugins. The default value
132 is 5, but you may want to increase this if you have more than five
133 plugins that take a long time to read. Mostly those are plugin that
134 do network-IO. Setting this to a value higher than the number of
135 plugins you've loaded is totally useless.
136 Hostname Name
138 Sets the hostname that identifies a host. If you omit this setting,
139 the hostname will be determined using the gethostname(2) system
140 call.
141 FQDNLookup true|false
143 If Hostname is determined automatically this setting controls
144 whether or not the daemon should try to figure out the "fully
145 qualified domain name", FQDN. This is done using a lookup of the
146 name returned by "gethostname".
147 Using this feature (i. e. setting this option to true) is
149 recommended. However, to preserve backwards compatibility the
150 default is set to false. The sample config file that is installed
151 with "make install" includes a line which sets this option, though,
152 so that default installations will have this setting enabled.
153 PreCacheChain ChainName
155 PostCacheChain ChainName
156 Configure the name of the "pre-cache chain" and the "post-cache
157 chain". Please see "FILTER CONFIGURATION" below on information on
158 chains and how these setting change the daemon's behavior.
159
161 Some plugins may register own options. These options must be enclosed
162 in a "Plugin"-Section. Which options exist depends on the plugin used.
163 Some plugins require external configuration, too. The "apache plugin",
164 for example, required "mod_status" to be configured in the webserver
165 you're going to collect data from. These plugins are listed below as
166 well, even if they don't require any configuration within collectd's
167 configfile.
168 A list of all plugins and a short summary for each plugin can be found
170 in the README file shipped with the sourcecode and hopefully binary
171 packets as well.
172 Plugin "apache"
174 To configure the "apache"-plugin you first need to configure the Apache
175 webserver correctly. The Apache-plugin "mod_status" needs to be loaded
176 and working and the "ExtendedStatus" directive needs to be enabled. You
177 can use the following snipped to base your Apache config upon:
178 ExtendedStatus on
180 <IfModule mod_status.c>
181 <Location /mod_status>
182 SetHandler server-status
183 </Location>
184 </IfModule>
185 Since its "mod_status" module is very similar to Apache's, lighttpd is
187 also supported. It introduces a new field, called "BusyServers", to
188 count the number of currently connected clients. This field is also
189 supported.
190 The following options are accepted by the "apache"-plugin:
192 URL http://host/mod_status?auto
194 Sets the URL of the "mod_status" output. This needs to be the
195 output generated by "ExtendedStatus on" and it needs to be the
196 machine readable output generated by appending the "?auto"
197 argument.
198 User Username
200 Optional user name needed for authentication.
201 Password Password
203 Optional password needed for authentication.
204 VerifyPeer true|false
206 Enable or disable peer SSL certificate verification. See
207 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
208 default.
209 VerifyHost true|false
211 Enable or disable peer host name verification. If enabled, the
212 plugin checks if the "Common Name" or a "Subject Alternate Name"
213 field of the SSL certificate matches the host name provided by the
214 URL option. If this identity check fails, the connection is
215 aborted. Obviously, only works when connecting to a SSL enabled
216 server. Enabled by default.
217 CACert File
219 File that holds one or more SSL certificates. If you want to use
220 HTTPS you will possibly need this option. What CA certificates come
221 bundled with "libcurl" and are checked by default depends on the
222 distribution you use.
223 Plugin "apcups"
225 Host Hostname
226 Hostname of the host running apcupsd. Defaults to localhost. Please
227 note that IPv6 support has been disabled unless someone can confirm
228 or decline that apcupsd can handle it.
229 Port Port
231 TCP-Port to connect to. Defaults to 3551.
232 Plugin "ascent"
234 This plugin collects information about an Ascent server, a free server
235 for the "World of Warcraft" game. This plugin gathers the information
236 by fetching the XML status page using "libcurl" and parses it using
237 "libxml2".
238 The configuration options are the same as for the "apache" plugin
240 above:
241 URL http://localhost/ascent/status/
243 Sets the URL of the XML status output.
244 User Username
246 Optional user name needed for authentication.
247 Password Password
249 Optional password needed for authentication.
250 VerifyPeer true|false
252 Enable or disable peer SSL certificate verification. See
253 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
254 default.
255 VerifyHost true|false
257 Enable or disable peer host name verification. If enabled, the
258 plugin checks if the "Common Name" or a "Subject Alternate Name"
259 field of the SSL certificate matches the host name provided by the
260 URL option. If this identity check fails, the connection is
261 aborted. Obviously, only works when connecting to a SSL enabled
262 server. Enabled by default.
263 CACert File
265 File that holds one or more SSL certificates. If you want to use
266 HTTPS you will possibly need this option. What CA certificates come
267 bundled with "libcurl" and are checked by default depends on the
268 distribution you use.
269 Plugin "bind"
271 Starting with BIND 9.5.0, the most widely used DNS server software
272 provides extensive statistics about queries, responses and lots of
273 other information. The bind plugin retrieves this information that's
274 encoded in XML and provided via HTTP and submits the values to
275 collectd.
276 To use this plugin, you first need to tell BIND to make this
278 information available. This is done with the "statistics-channels"
279 configuration option:
280 statistics-channels {
282 inet localhost port 8053;
283 };
284 The configuration follows the grouping that can be seen when looking at
286 the data with an XSLT compatible viewer, such as a modern web browser.
287 It's probably a good idea to make yourself familiar with the provided
288 values, so you can understand what the collected statistics actually
289 mean.
290 Synopsis:
292 <Plugin "bind">
294 URL "http://localhost:8053/"
295 OpCodes true
296 QTypes true
297 ServerStats true
299 ZoneMaintStats true
300 ResolverStats false
301 MemoryStats true
302 <View "_default">
304 QTypes true
305 ResolverStats true
306 CacheRRSets true
307 Zone "127.in-addr.arpa/IN"
309 </View>
310 </Plugin>
311 The bind plugin accepts the following configuration options:
313 URL URL
315 URL from which to retrieve the XML data. If not specified,
316 "http://localhost:8053/" will be used.
317 OpCodes true|false
319 When enabled, statistics about the "OpCodes", for example the
320 number of "QUERY" packets, are collected.
321 Default: Enabled.
323 QTypes true|false
325 When enabled, the number of incoming queries by query types (for
326 example "A", "MX", "AAAA") is collected.
327 Default: Enabled.
329 ServerStats true|false
331 Collect global server statistics, such as requests received over
332 IPv4 and IPv6, successful queries, and failed updates.
333 Default: Enabled.
335 ZoneMaintStats true|false
337 Collect zone maintenance statistics, mostly information about
338 notifications (zone updates) and zone transfers.
339 Default: Enabled.
341 ResolverStats true|false
343 Collect resolver statistics, i. e. statistics about outgoing
344 requests (e. g. queries over IPv4, lame servers). Since the global
345 resolver counters apparently were removed in BIND 9.5.1 and 9.6.0,
346 this is disabled by default. Use the ResolverStats option within a
347 View "_default" block instead for the same functionality.
348 Default: Disabled.
350 MemoryStats
352 Collect global memory statistics.
353 Default: Enabled.
355 View Name
357 Collect statistics about a specific "view". BIND can behave
358 different, mostly depending on the source IP-address of the
359 request. These different configurations are called "views". If you
360 don't use this feature, you most likely are only interested in the
361 "_default" view.
362 Within a <View name> block, you can specify which information you
364 want to collect about a view. If no View block is configured, no
365 detailed view statistics will be collected.
366 QTypes true|false
368 If enabled, the number of outgoing queries by query type (e. g.
369 "A", "MX") is collected.
370 Default: Enabled.
372 ResolverStats true|false
374 Collect resolver statistics, i. e. statistics about outgoing
375 requests (e. g. queries over IPv4, lame servers).
376 Default: Enabled.
378 CacheRRSets true|false
380 If enabled, the number of entries ("RR sets") in the view's
381 cache by query type is collected. Negative entries (queries
382 which resulted in an error, for example names that do not
383 exist) are reported with a leading exclamation mark, e. g.
384 "!A".
385 Default: Enabled.
387 Zone Name
389 When given, collect detailed information about the given zone
390 in the view. The information collected if very similar to the
391 global ServerStats information (see above).
392 You can repeat this option to collect detailed information
394 about multiple zones.
395 By default no detailed zone information is collected.
397 Plugin "cpufreq"
399 This plugin doesn't have any options. It reads
400 /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq (for the first
401 CPU installed) to get the current CPU frequency. If this file does not
402 exist make sure cpufreqd (<http://cpufreqd.sourceforge.net/>) or a
403 similar tool is installed and an "cpu governor" (that's a kernel
404 module) is loaded.
405 Plugin "csv"
407 DataDir Directory
408 Set the directory to store CSV-files under. Per default CSV-files
409 are generated beneath the daemon's working directory, i. e. the
410 BaseDir. The special strings stdout and stderr can be used to
411 write to the standard output and standard error channels,
412 respectively. This, of course, only makes much sense when collectd
413 is running in foreground- or non-daemon-mode.
414 StoreRates true|false
416 If set to true, convert counter values to rates. If set to false
417 (the default) counter values are stored as is, i. e. as an
418 increasing integer number.
419 Plugin "curl"
421 The curl plugin uses the libcurl (<http://curl.haxx.se/>) to read web
422 pages and the match infrastructure (the same code used by the tail
423 plugin) to use regular expressions with the received data.
424 The following example will read the current value of AMD stock from
426 Google's finance page and dispatch the value to collectd.
427 <Plugin curl>
429 <Page "stock_quotes">
430 URL "http://finance.google.com/finance?q=NYSE%3AAMD"
431 User "foo"
432 Password "bar"
433 <Match>
434 Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
435 DSType "GaugeAverage"
436 # Note: `stock_value' is not a standard type.
437 Type "stock_value"
438 Instance "AMD"
439 </Match>
440 </Page>
441 </Plugin>
442 In the Plugin block, there may be one or more Page blocks, each
444 defining a web page and one or more "matches" to be performed on the
445 returned data. The string argument to the Page block is used as plugin
446 instance.
447 The following options are valid within Page blocks:
449 URL URL
451 URL of the web site to retrieve. Since a regular expression will be
452 used to extract information from this data, non-binary data is a
453 big plus here ;)
454 User Name
456 Username to use if authorization is required to read the page.
457 Password Password
459 Password to use if authorization is required to read the page.
460 VerifyPeer true|false
462 Enable or disable peer SSL certificate verification. See
463 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
464 default.
465 VerifyHost true|false
467 Enable or disable peer host name verification. If enabled, the
468 plugin checks if the "Common Name" or a "Subject Alternate Name"
469 field of the SSL certificate matches the host name provided by the
470 URL option. If this identity check fails, the connection is
471 aborted. Obviously, only works when connecting to a SSL enabled
472 server. Enabled by default.
473 CACert file
475 File that holds one or more SSL certificates. If you want to use
476 HTTPS you will possibly need this option. What CA certificates come
477 bundled with "libcurl" and are checked by default depends on the
478 distribution you use.
479 MeasureResponseTime true|false
481 Measure response time for the request. If this setting is enabled,
482 Match blocks (see below) are optional. Disabled by default.
483 <Match>
485 One or more Match blocks that define how to match information in
486 the data returned by "libcurl". The "curl" plugin uses the same
487 infrastructure that's used by the "tail" plugin, so please see the
488 documentation of the "tail" plugin below on how matches are
489 defined. If the MeasureResponseTime option is set to true, Match
490 blocks are optional.
491 Plugin "curl_json"
493 The curl_json plugin uses libcurl (<http://curl.haxx.se/>) and libyajl
494 (<http://www.lloydforge.org/projects/yajl/>) to retrieve JSON data via
495 cURL. This can be used to collect values from CouchDB documents (which
496 are stored JSON notation), for example.
497 The following example will collect several values from the built-in
499 `_stats' runtime statistics module of CouchDB
500 (<http://wiki.apache.org/couchdb/Runtime_Statistics>).
501 <Plugin curl_json>
503 <URL "http://localhost:5984/_stats">
504 Instance "httpd"
505 <Key "httpd/requests/count">
506 Type "http_requests"
507 </Key>
508 <Key "httpd_request_methods/*/count">
510 Type "http_request_methods"
511 </Key>
512 <Key "httpd_status_codes/*/count">
514 Type "http_response_codes"
515 </Key>
516 </URL>
517 </Plugin>
518 Another CouchDB example: The following example will collect the status
520 values from each database:
521 <URL "http://localhost:5984/_all_dbs">
523 Instance "dbs"
524 <Key "*/doc_count">
525 Type "gauge"
526 </Key>
527 <Key "*/doc_del_count">
528 Type "counter"
529 </Key>
530 <Key "*/disk_size">
531 Type "bytes"
532 </Key>
533 </URL>
534 In the Plugin block, there may be one or more URL blocks, each defining
536 a URL to be fetched via HTTP (using libcurl) and one or more Key
537 blocks. The Key string argument must be in a path format, which is
538 used to collect a value from a JSON map object. If a path element of
539 Key is the * wildcard, the values for all keys will be collectd.
540 The following options are valid within URL blocks:
542 Instance Instance
544 Sets the plugin instance to Instance.
545 User Name
547 Username to use if authorization is required to read the page.
548 Password Password
550 Password to use if authorization is required to read the page.
551 VerifyPeer true|false
553 Enable or disable peer SSL certificate verification. See
554 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
555 default.
556 VerifyHost true|false
558 Enable or disable peer host name verification. If enabled, the
559 plugin checks if the "Common Name" or a "Subject Alternate Name"
560 field of the SSL certificate matches the host name provided by the
561 URL option. If this identity check fails, the connection is
562 aborted. Obviously, only works when connecting to a SSL enabled
563 server. Enabled by default.
564 CACert file
566 File that holds one or more SSL certificates. If you want to use
567 HTTPS you will possibly need this option. What CA certificates come
568 bundled with "libcurl" and are checked by default depends on the
569 distribution you use.
570 The following options are valid within Key blocks:
572 Type Type
574 Sets the type used to dispatch the values to the daemon. Detailed
575 information about types and their configuration can be found in
576 types.db(5). This option is mandatory.
577 Instance Instance
579 Type-instance to use. Defaults to the current map key or current
580 string array element value.
581 Plugin "dbi"
583 This plugin uses the dbi library (<http://libdbi.sourceforge.net/>) to
584 connect to various databases, execute SQL statements and read back the
585 results. dbi is an acronym for "database interface" in case you were
586 wondering about the name. You can configure how each column is to be
587 interpreted and the plugin will generate one or more data sets from
588 each row returned according to these rules.
589 Because the plugin is very generic, the configuration is a little more
591 complex than those of other plugins. It usually looks something like
592 this:
593 <Plugin dbi>
595 <Query "out_of_stock">
596 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
597 # Use with MySQL 5.0.0 or later
598 MinVersion 50000
599 <Result>
600 Type "gauge"
601 InstancePrefix "out_of_stock"
602 InstancesFrom "category"
603 ValuesFrom "value"
604 </Result>
605 </Query>
606 <Database "product_information">
607 Driver "mysql"
608 DriverOption "host" "localhost"
609 DriverOption "username" "collectd"
610 DriverOption "password" "aZo6daiw"
611 DriverOption "dbname" "prod_info"
612 SelectDB "prod_info"
613 Query "out_of_stock"
614 </Database>
615 </Plugin>
616 The configuration above defines one query with one result and one
618 database. The query is then linked to the database with the Query
619 option within the <Database> block. You can have any number of queries
620 and databases and you can also use the Include statement to split up
621 the configuration file in multiple, smaller files. However, the <Query>
622 block must precede the <Database> blocks, because the file is
623 interpreted from top to bottom!
624 The following is a complete list of options:
626 Query blocks
628 Query blocks define SQL statements and how the returned data should be
630 interpreted. They are identified by the name that is given in the
631 opening line of the block. Thus the name needs to be unique. Other than
632 that, the name is not used in collectd.
633 In each Query block, there is one or more Result blocks. Result blocks
635 define which column holds which value or instance information. You can
636 use multiple Result blocks to create multiple values from one returned
637 row. This is especially useful, when queries take a long time and
638 sending almost the same query again and again is not desirable.
639 Example:
641 <Query "environment">
643 Statement "select station, temperature, humidity from environment"
644 <Result>
645 Type "temperature"
646 # InstancePrefix "foo"
647 InstancesFrom "station"
648 ValuesFrom "temperature"
649 </Result>
650 <Result>
651 Type "humidity"
652 InstancesFrom "station"
653 ValuesFrom "humidity"
654 </Result>
655 </Query>
656 The following options are accepted:
658 Statement SQL
660 Sets the statement that should be executed on the server. This is
661 not interpreted by collectd, but simply passed to the database
662 server. Therefore, the SQL dialect that's used depends on the
663 server collectd is connected to.
664 The query has to return at least two columns, one for the instance
666 and one value. You cannot omit the instance, even if the statement
667 is guaranteed to always return exactly one line. In that case, you
668 can usually specify something like this:
669 Statement "SELECT \"instance\", COUNT(*) AS value FROM table"
671 (That works with MySQL but may not be valid SQL according to the
673 spec. If you use a more strict database server, you may have to
674 select from a dummy table or something.)
675 Please note that some databases, for example Oracle, will fail if
677 you include a semicolon at the end of the statement.
678 MinVersion Version
680 MaxVersion Value
681 Only use this query for the specified database version. You can use
682 these options to provide multiple queries with the same name but
683 with a slightly different syntax. The plugin will use only those
684 queries, where the specified minimum and maximum versions fit the
685 version of the database in use.
686 The database version is determined by
688 "dbi_conn_get_engine_version", see the libdbi documentation for
689 details. Basically, each part of the version is assumed to be in
690 the range from 00 to 99 and all dots are removed. So version
691 "4.1.2" becomes "40102", version "5.0.42" becomes "50042".
692 Warning: The plugin will use all matching queries, so if you
694 specify multiple queries with the same name and overlapping ranges,
695 weird stuff will happen. Don't to it! A valid example would be
696 something along these lines:
697 MinVersion 40000
699 MaxVersion 49999
700 ...
701 MinVersion 50000
702 MaxVersion 50099
703 ...
704 MinVersion 50100
705 # No maximum
706 In the above example, there are three ranges that don't overlap.
708 The last one goes from version "5.1.0" to infinity, meaning "all
709 later versions". Versions before "4.0.0" are not specified.
710 Type Type
712 The type that's used for each line returned. See types.db(5) for
713 more details on how types are defined. In short: A type is a
714 predefined layout of data and the number of values and type of
715 values has to match the type definition.
716 If you specify "temperature" here, you need exactly one gauge
718 column. If you specify "if_octets", you will need two counter
719 columns. See the ValuesFrom setting below.
720 There must be exactly one Type option inside each Result block.
722 InstancePrefix prefix
724 Prepends prefix to the type instance. If InstancesFrom (see below)
725 is not given, the string is simply copied. If InstancesFrom is
726 given, prefix and all strings returned in the appropriate columns
727 are concatenated together, separated by dashes ("-").
728 InstancesFrom column0 [column1 ...]
730 Specifies the columns whose values will be used to create the
731 "type-instance" for each row. If you specify more than one column,
732 the value of all columns will be joined together with dashes ("-")
733 as separation characters.
734 The plugin itself does not check whether or not all built instances
736 are different. It's your responsibility to assure that each is
737 unique. This is especially true, if you do not specify
738 InstancesFrom: You have to make sure that only one row is returned
739 in this case.
740 If neither InstancePrefix nor InstancesFrom is given, the type-
742 instance will be empty.
743 ValuesFrom column0 [column1 ...]
745 Names the columns whose content is used as the actual data for the
746 data sets that are dispatched to the daemon. How many such columns
747 you need is determined by the Type setting above. If you specify
748 too many or not enough columns, the plugin will complain about that
749 and no data will be submitted to the daemon.
750 The actual data type in the columns is not that important. The
752 plugin will automatically cast the values to the right type if it
753 know how to do that. So it should be able to handle integer an
754 floating point types, as well as strings (if they include a number
755 at the beginning).
756 There must be at least one ValuesFrom option inside each Result
758 block.
759 Database blocks
761 Database blocks define a connection to a database and which queries
763 should be sent to that database. Since the used "dbi" library can
764 handle a wide variety of databases, the configuration is very generic.
765 If in doubt, refer to libdbi's documentation - we stick as close to the
766 terminology used there.
767 Each database needs a "name" as string argument in the starting tag of
769 the block. This name will be used as "PluginInstance" in the values
770 submitted to the daemon. Other than that, that name is not used.
771 Driver Driver
773 Specifies the driver to use to connect to the database. In many
774 cases those drivers are named after the database they can connect
775 to, but this is not a technical necessity. These drivers are
776 sometimes referred to as "DBD", DataBase Driver, and some
777 distributions ship them in separate packages. Drivers for the "dbi"
778 library are developed by the libdbi-drivers project at
779 <http://libdbi-drivers.sourceforge.net/>.
780 You need to give the driver name as expected by the "dbi" library
782 here. You should be able to find that in the documentation for each
783 driver. If you mistype the driver name, the plugin will dump a list
784 of all known driver names to the log.
785 DriverOption Key Value
787 Sets driver-specific options. What option a driver supports can be
788 found in the documentation for each driver, somewhere at
789 <http://libdbi-drivers.sourceforge.net/>. However, the options
790 "host", "username", "password", and "dbname" seem to be de facto
791 standards.
792 Unfortunately, drivers are not too keen to report errors when an
794 unknown option is passed to them, so invalid settings here may go
795 unnoticed. This is not the plugin's fault, it will report errors if
796 it gets them from the library / the driver. If a driver complains
797 about an option, the plugin will dump a complete list of all
798 options understood by that driver to the log.
799 SelectDB Database
801 In some cases, the database name you connect with is not the
802 database name you want to use for querying data. If this option is
803 set, the plugin will "select" (switch to) that database after the
804 connection is established.
805 Query QueryName
807 Associates the query named QueryName with this database connection.
808 The query needs to be defined before this statement, i. e. all
809 query blocks you want to refer to must be placed above the database
810 block you want to refer to them from.
811 Plugin "df"
813 Device Device
814 Select partitions based on the devicename.
815 MountPoint Directory
817 Select partitions based on the mountpoint.
818 FSType FSType
820 Select partitions based on the filesystem type.
821 IgnoreSelected true|false
823 Invert the selection: If set to true, all partitions except the
824 ones that match any one of the criteria are collected. By default
825 only selected partitions are collected if a selection is made. If
826 no selection is configured at all, all partitions are selected.
827 ReportByDevice true|false
829 Report using the device name rather than the mountpoint. i.e. with
830 this false, (the default), it will report a disk as "root", but
831 with it true, it will be "sda1" (or whichever).
832 ReportReserved true|false
834 When enabled, the blocks reserved for root are reported separately.
835 When disabled (the default for backwards compatibility reasons) the
836 reserved space will be included in the "free" space.
837 When disabled, the "df" type will be used to store "free" and
839 "used" space. The mount point or disk name (see option
840 ReportByDevice) is used as type instance in this case (again:
841 backwards compatibility).
842 When enabled, the type "df_complex" is used and three files are
844 created. The mount point or disk name is used as plugin instance
845 and the type instance is set to "free", "reserved" and "used" as
846 appropriate.
847 Enabling this option is recommended.
849 ReportInodes true|false
851 Enables or disables reporting of free, reserved and used inodes.
852 Defaults to inode collection being disabled.
853 Enable this option if inodes are a scarce resource for you, usually
855 because many small files are stored on the disk. This is a usual
856 scenario for mail transfer agents and web caches.
857 Plugin "disk"
859 The "disk" plugin collects information about the usage of physical
860 disks and logical disks (partitions). Values collected are the number
861 of octets written to and read from a disk or partition, the number of
862 read/write operations issued to the disk and a rather complex "time" it
863 took for these commands to be issued.
864 Using the following two options you can ignore some disks or configure
866 the collection only of specific disks.
867 Disk Name
869 Select the disk Name. Whether it is collected or ignored depends on
870 the IgnoreSelected setting, see below. As with other plugins that
871 use the daemon's ignorelist functionality, a string that starts and
872 ends with a slash is interpreted as a regular expression. Examples:
873 Disk "sdd"
875 Disk "/hda[34]/"
876 IgnoreSelected true|false
878 Sets whether selected disks, i. e. the ones matches by any of the
879 Disk statements, are ignored or if all other disks are ignored. The
880 behavior (hopefully) is intuitive: If no Disk option is configured,
881 all disks are collected. If at least one Disk option is given and
882 no IgnoreSelected or set to false, only matching disks will be
883 collected. If IgnoreSelected is set to true, all disks are
884 collected except the ones matched.
885 Plugin "dns"
887 Interface Interface
888 The dns plugin uses libpcap to capture dns traffic and analyzes it.
889 This option sets the interface that should be used. If this option
890 is not set, or set to "any", the plugin will try to get packets
891 from all interfaces. This may not work on certain platforms, such
892 as Mac OS X.
893 IgnoreSource IP-address
895 Ignore packets that originate from this address.
896 SelectNumericQueryTypes true|false
898 Enabled by default, collects unknown (and thus presented as numeric
899 only) query types.
900 Plugin "email"
902 SocketFile Path
903 Sets the socket-file which is to be created.
904 SocketGroup Group
906 If running as root change the group of the UNIX-socket after it has
907 been created. Defaults to collectd.
908 SocketPerms Permissions
910 Change the file permissions of the UNIX-socket after it has been
911 created. The permissions must be given as a numeric, octal value as
912 you would pass to chmod(1). Defaults to 0770.
913 MaxConns Number
915 Sets the maximum number of connections that can be handled in
916 parallel. Since this many threads will be started immediately
917 setting this to a very high value will waste valuable resources.
918 Defaults to 5 and will be forced to be at most 16384 to prevent
919 typos and dumb mistakes.
920 Plugin "exec"
922 Please make sure to read collectd-exec(5) before using this plugin. It
923 contains valuable information on when the executable is executed and
924 the output that is expected from it.
925 Exec User[:[Group]] Executable [<arg> [<arg> ...]]
927 NotificationExec User[:[Group]] Executable [<arg> [<arg> ...]]
928 Execute the executable Executable as user User. If the user name is
929 followed by a colon and a group name, the effective group is set to
930 that group. The real group and saved-set group will be set to the
931 default group of that user. If no group is given the effective
932 group ID will be the same as the real group ID.
933 Please note that in order to change the user and/or group the
935 daemon needs superuser privileges. If the daemon is run as an
936 unprivileged user you must specify the same user/group here. If the
937 daemon is run with superuser privileges, you must supply a non-root
938 user here.
939 The executable may be followed by optional arguments that are
941 passed to the program. Please note that due to the configuration
942 parsing numbers and boolean values may be changed. If you want to
943 be absolutely sure that something is passed as-is please enclose it
944 in quotes.
945 The Exec and NotificationExec statements change the semantics of
947 the programs executed, i. e. the data passed to them and the
948 response expected from them. This is documented in great detail in
949 collectd-exec(5).
950 Plugin "filecount"
952 The "filecount" plugin counts the number of files in a certain
953 directory (and its subdirectories) and their combined size. The
954 configuration is very straight forward:
955 <Plugin "filecount">
957 <Directory "/var/qmail/queue/mess">
958 Instance "qmail-message"
959 </Directory>
960 <Directory "/var/qmail/queue/todo">
961 Instance "qmail-todo"
962 </Directory>
963 <Directory "/var/lib/php5">
964 Instance "php5-sessions"
965 Name "sess_*"
966 </Directory>
967 </Plugin>
968 The example above counts the number of files in QMail's queue
970 directories and the number of PHP5 sessions. Jfiy: The "todo" queue
971 holds the messages that QMail has not yet looked at, the "message"
972 queue holds the messages that were classified into "local" and
973 "remote".
974 As you can see, the configuration consists of one or more "Directory"
976 blocks, each of which specifies a directory in which to count the
977 files. Within those blocks, the following options are recognized:
978 Instance Instance
980 Sets the plugin instance to Instance. That instance name must be
981 unique, but it's your responsibility, the plugin doesn't check for
982 that. If not given, the instance is set to the directory name with
983 all slashes replaced by underscores and all leading underscores
984 removed.
985 Name Pattern
987 Only count files that match Pattern, where Pattern is a shell-like
988 wildcard as understood by fnmatch(3). Only the filename is checked
989 against the pattern, not the entire path. In case this makes it
990 easier for you: This option has been named after the -name
991 parameter to find(1).
992 MTime Age
994 Count only files of a specific age: If Age is greater than zero,
995 only files that haven't been touched in the last Age seconds are
996 counted. If Age is a negative number, this is inversed. For
997 example, if -60 is specified, only files that have been modified in
998 the last minute will be counted.
999 The number can also be followed by a "multiplier" to easily specify
1001 a larger timespan. When given in this notation, the argument must
1002 in quoted, i. e. must be passed as string. So the -60 could also
1003 be written as "-1m" (one minute). Valid multipliers are "s"
1004 (second), "m" (minute), "h" (hour), "d" (day), "w" (week), and "y"
1005 (year). There is no "month" multiplier. You can also specify
1006 fractional numbers, e. g. "0.5d" is identical to "12h".
1007 Size Size
1009 Count only files of a specific size. When Size is a positive
1010 number, only files that are at least this big are counted. If Size
1011 is a negative number, this is inversed, i. e. only files smaller
1012 than the absolute value of Size are counted.
1013 As with the MTime option, a "multiplier" may be added. For a
1015 detailed description see above. Valid multipliers here are "b"
1016 (byte), "k" (kilobyte), "m" (megabyte), "g" (gigabyte), "t"
1017 (terabyte), and "p" (petabyte). Please note that there are 1000
1018 bytes in a kilobyte, not 1024.
1019 Recursive true|false
1021 Controls whether or not to recurse into subdirectories. Enabled by
1022 default.
1023 Plugin "GenericJMX"
1025 The GenericJMX plugin is written in Java and therefore documented in
1026 collectd-java(5).
1027 Plugin "gmond"
1029 The gmond plugin received the multicast traffic sent by gmond, the
1030 statistics collection daemon of Ganglia. Mappings for the standard
1031 "metrics" are built-in, custom mappings may be added via Metric blocks,
1032 see below.
1033 Synopsis:
1035 <Plugin "gmond">
1037 MCReceiveFrom "239.2.11.71" "8649"
1038 <Metric "swap_total">
1039 Type "swap"
1040 TypeInstance "total"
1041 DataSource "value"
1042 </Metric>
1043 <Metric "swap_free">
1044 Type "swap"
1045 TypeInstance "free"
1046 DataSource "value"
1047 </Metric>
1048 </Plugin>
1049 The following metrics are built-in:
1051 · load_one, load_five, load_fifteen
1053 · cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio
1055 · mem_free, mem_shared, mem_buffers, mem_cached, mem_total
1057 · bytes_in, bytes_out
1059 · pkts_in, pkts_out
1061 Available configuration options:
1063 MCReceiveFrom MCGroup [Port]
1065 Sets sets the multicast group and UDP port to which to subscribe.
1066 Default: 239.2.11.71 / 8649
1068 <Metric Name>
1070 These blocks add a new metric conversion to the internal table.
1071 Name, the string argument to the Metric block, is the metric name
1072 as used by Ganglia.
1073 Type Type
1075 Type to map this metric to. Required.
1076 TypeInstance Instance
1078 Type-instance to use. Optional.
1079 DataSource Name
1081 Data source to map this metric to. If the configured type has
1082 exactly one data source, this is optional. Otherwise the option
1083 is required.
1084 Plugin "hddtemp"
1086 To get values from hddtemp collectd connects to localhost (127.0.0.1),
1087 port 7634/tcp. The Host and Port options can be used to change these
1088 default values, see below. "hddtemp" has to be running to work
1089 correctly. If "hddtemp" is not running timeouts may appear which may
1090 interfere with other statistics..
1091 The hddtemp homepage can be found at
1093 <http://www.guzu.net/linux/hddtemp.php>.
1094 Host Hostname
1096 Hostname to connect to. Defaults to 127.0.0.1.
1097 Port Port
1099 TCP-Port to connect to. Defaults to 7634.
1100 TranslateDevicename true|false
1102 If enabled, translate the disk names to major/minor device numbers
1103 (e. g. "8-0" for /dev/sda). For backwards compatibility this
1104 defaults to true but it's recommended to disable it as it will
1105 probably be removed in the next major version.
1106 Plugin "interface"
1108 Interface Interface
1109 Select this interface. By default these interfaces will then be
1110 collected. For a more detailed description see IgnoreSelected
1111 below.
1112 IgnoreSelected true|false
1114 If no configuration if given, the traffic-plugin will collect data
1115 from all interfaces. This may not be practical, especially for
1116 loopback- and similar interfaces. Thus, you can use the
1117 Interface-option to pick the interfaces you're interested in.
1118 Sometimes, however, it's easier/preferred to collect all interfaces
1119 except a few ones. This option enables you to do that: By setting
1120 IgnoreSelected to true the effect of Interface is inverted: All
1121 selected interfaces are ignored and all other interfaces are
1122 collected.
1123 Plugin "ipmi"
1125 Sensor Sensor
1126 Selects sensors to collect or to ignore, depending on
1127 IgnoreSelected.
1128 IgnoreSelected true|false
1130 If no configuration if given, the ipmi plugin will collect data
1131 from all sensors found of type "temperature", "voltage", "current"
1132 and "fanspeed". This option enables you to do that: By setting
1133 IgnoreSelected to true the effect of Sensor is inverted: All
1134 selected sensors are ignored and all other sensors are collected.
1135 NotifySensorAdd true|false
1137 If a sensor appears after initialization time of a minute a
1138 notification is sent.
1139 NotifySensorRemove true|false
1141 If a sensor disappears a notification is sent.
1142 NotifySensorNotPresent true|false
1144 If you have for example dual power supply and one of them is
1145 (un)plugged then a notification is sent.
1146 Plugin "iptables"
1148 Chain Table Chain [Comment|Number [Name]]
1149 Select the rules to count. If only Table and Chain are given, this
1150 plugin will collect the counters of all rules which have a comment-
1151 match. The comment is then used as type-instance.
1152 If Comment or Number is given, only the rule with the matching
1154 comment or the nth rule will be collected. Again, the comment (or
1155 the number) will be used as the type-instance.
1156 If Name is supplied, it will be used as the type-instance instead
1158 of the comment or the number.
1159 Plugin "irq"
1161 Irq Irq
1162 Select this irq. By default these irqs will then be collected. For
1163 a more detailed description see IgnoreSelected below.
1164 IgnoreSelected true|false
1166 If no configuration if given, the irq-plugin will collect data from
1167 all irqs. This may not be practical, especially if no interrupts
1168 happen. Thus, you can use the Irq-option to pick the interrupt
1169 you're interested in. Sometimes, however, it's easier/preferred to
1170 collect all interrupts except a few ones. This option enables you
1171 to do that: By setting IgnoreSelected to true the effect of Irq is
1172 inverted: All selected interrupts are ignored and all other
1173 interrupts are collected.
1174 Plugin "java"
1176 The Java plugin makes it possible to write extensions for collectd in
1177 Java. This section only discusses the syntax and semantic of the
1178 configuration options. For more in-depth information on the Java
1179 plugin, please read collectd-java(5).
1180 Synopsis:
1182 <Plugin "java">
1184 JVMArg "-verbose:jni"
1185 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
1186 LoadPlugin "org.collectd.java.Foobar"
1187 <Plugin "org.collectd.java.Foobar">
1188 # To be parsed by the plugin
1189 </Plugin>
1190 </Plugin>
1191 Available configuration options:
1193 JVMArg Argument
1195 Argument that is to be passed to the Java Virtual Machine (JVM).
1196 This works exactly the way the arguments to the java binary on the
1197 command line work. Execute "java --help" for details.
1198 Please note that all these options must appear before (i. e. above)
1200 any other options! When another option is found, the JVM will be
1201 started and later options will have to be ignored!
1202 LoadPlugin JavaClass
1204 Instantiates a new JavaClass object. The constructor of this object
1205 very likely then registers one or more callback methods with the
1206 server.
1207 See collectd-java(5) for details.
1209 When the first such option is found, the virtual machine (JVM) is
1211 created. This means that all JVMArg options must appear before
1212 (i. e. above) all LoadPlugin options!
1213 Plugin Name
1215 The entire block is passed to the Java plugin as an
1216 org.collectd.api.OConfigItem object.
1217 For this to work, the plugin has to register a configuration
1219 callback first, see "config callback" in collectd-java(5). This
1220 means, that the Plugin block must appear after the appropriate
1221 LoadPlugin block. Also note, that Name depends on the (Java) plugin
1222 registering the callback and is completely independent from the
1223 JavaClass argument passed to LoadPlugin.
1224 Plugin "libvirt"
1226 This plugin allows CPU, disk and network load to be collected for
1227 virtualized guests on the machine. This means that these
1228 characteristics can be collected for guest systems without installing
1229 any software on them - collectd only runs on the hosting system. The
1230 statistics are collected through libvirt (<http://libvirt.org/>).
1231 Only Connection is required.
1233 Connection uri
1235 Connect to the hypervisor given by uri. For example if using Xen
1236 use:
1237 Connection "xen:///"
1239 Details which URIs allowed are given at
1241 <http://libvirt.org/uri.html>.
1242 RefreshInterval seconds
1244 Refresh the list of domains and devices every seconds. The default
1245 is 60 seconds. Setting this to be the same or smaller than the
1246 Interval will cause the list of domains and devices to be refreshed
1247 on every iteration.
1248 Refreshing the devices in particular is quite a costly operation,
1250 so if your virtualization setup is static you might consider
1251 increasing this. If this option is set to 0, refreshing is disabled
1252 completely.
1253 Domain name
1255 BlockDevice name:dev
1256 InterfaceDevice name:dev
1257 IgnoreSelected true|false
1258 Select which domains and devices are collected.
1259 If IgnoreSelected is not given or false then only the listed
1261 domains and disk/network devices are collected.
1262 If IgnoreSelected is true then the test is reversed and the listed
1264 domains and disk/network devices are ignored, while the rest are
1265 collected.
1266 The domain name and device names may use a regular expression, if
1268 the name is surrounded by /.../ and collectd was compiled with
1269 support for regexps.
1270 The default is to collect statistics for all domains and all their
1272 devices.
1273 Example:
1275 BlockDevice "/:hdb/"
1277 IgnoreSelected "true"
1278 Ignore all hdb devices on any domain, but other block devices (eg.
1280 hda) will be collected.
1281 HostnameFormat name|uuid|hostname|...
1283 When the libvirt plugin logs data, it sets the hostname of the
1284 collected data according to this setting. The default is to use the
1285 guest name as provided by the hypervisor, which is equal to setting
1286 name.
1287 uuid means use the guest's UUID. This is useful if you want to
1289 track the same guest across migrations.
1290 hostname means to use the global Hostname setting, which is
1292 probably not useful on its own because all guests will appear to
1293 have the same name.
1294 You can also specify combinations of these fields. For example name
1296 uuid means to concatenate the guest name and UUID (with a literal
1297 colon character between, thus "foo:1234-1234-1234-1234").
1298 Plugin "logfile"
1300 LogLevel debug|info|notice|warning|err
1301 Sets the log-level. If, for example, set to notice, then all events
1302 with severity notice, warning, or err will be written to the
1303 logfile.
1304 Please note that debug is only available if collectd has been
1306 compiled with debugging support.
1307 File File
1309 Sets the file to write log messages to. The special strings stdout
1310 and stderr can be used to write to the standard output and standard
1311 error channels, respectively. This, of course, only makes much
1312 sense when collectd is running in foreground- or non-daemon-mode.
1313 Timestamp true|false
1315 Prefix all lines printed by the current time. Defaults to true.
1316 Note: There is no need to notify the daemon after moving or removing
1318 the log file (e. g. when rotating the logs). The plugin reopens the
1319 file for each line it writes.
1320 Plugin "mbmon"
1322 The "mbmon plugin" uses mbmon to retrieve temperature, voltage, etc.
1323 Be default collectd connects to localhost (127.0.0.1), port 411/tcp.
1325 The Host and Port options can be used to change these values, see
1326 below. "mbmon" has to be running to work correctly. If "mbmon" is not
1327 running timeouts may appear which may interfere with other statistics..
1328 "mbmon" must be run with the -r option ("print TAG and Value format");
1330 Debian's /etc/init.d/mbmon script already does this, other people will
1331 need to ensure that this is the case.
1332 Host Hostname
1334 Hostname to connect to. Defaults to 127.0.0.1.
1335 Port Port
1337 TCP-Port to connect to. Defaults to 411.
1338 Plugin "memcachec"
1340 The "memcachec plugin" connects to a memcached server, queries one or
1341 more given pages and parses the returned data according to user
1342 specification. The matches used are the same as the matches used in
1343 the "curl" and "tail" plugins.
1344 In order to talk to the memcached server, this plugin uses the
1346 libmemcached library. Please note that there is another library with a
1347 very similar name, libmemcache (notice the missing `d'), which is not
1348 applicable.
1349 Synopsis of the configuration:
1351 <Plugin "memcachec">
1353 <Page "plugin_instance">
1354 Server "localhost"
1355 Key "page_key"
1356 <Match>
1357 Regex "(\\d+) bytes sent"
1358 DSType CounterAdd
1359 Type "ipt_octets"
1360 Instance "type_instance"
1361 </Match>
1362 </Page>
1363 </Plugin>
1364 The configuration options are:
1366 <Page Name>
1368 Each Page block defines one page to be queried from the memcached
1369 server. The block requires one string argument which is used as
1370 plugin instance.
1371 Server Address
1373 Sets the server address to connect to when querying the page. Must
1374 be inside a Page block.
1375 Key Key
1377 When connected to the memcached server, asks for the page Key.
1378 <Match>
1380 Match blocks define which strings to look for and how matches
1381 substrings are interpreted. For a description of match blocks,
1382 please see "Plugin tail".
1383 Plugin "memcached"
1385 The "memcached plugin" connects to a memcached server and queries
1386 statistics about cache utilization, memory and bandwidth used.
1387 <http://www.danga.com/memcached/>
1388 Host Hostname
1390 Hostname to connect to. Defaults to 127.0.0.1.
1391 Port Port
1393 TCP-Port to connect to. Defaults to 11211.
1394 Plugin "mysql"
1396 The "mysql plugin" requires mysqlclient to be installed. It connects to
1397 one or more databases when started and keeps the connection up as long
1398 as possible. When the connection is interrupted for whatever reason it
1399 will try to re-connect. The plugin will complaint loudly in case
1400 anything goes wrong.
1401 This plugin issues the MySQL "SHOW STATUS" / "SHOW GLOBAL STATUS"
1403 command and collects information about MySQL network traffic, executed
1404 statements, requests, the query cache and threads by evaluating the
1405 "Bytes_{received,sent}", "Com_*", "Handler_*", "Qcache_*" and
1406 "Threads_*" return values. Please refer to the MySQL reference manual,
1407 5.1.6. Server Status Variables for an explanation of these values.
1408 Optionally, master and slave statistics may be collected in a MySQL
1410 replication setup. In that case, information about the synchronization
1411 state of the nodes are collected by evaluating the "Position" return
1412 value of the "SHOW MASTER STATUS" command and the
1413 "Seconds_Behind_Master", "Read_Master_Log_Pos" and
1414 "Exec_Master_Log_Pos" return values of the "SHOW SLAVE STATUS" command.
1415 See the MySQL reference manual, 12.5.5.21 SHOW MASTER STATUS Syntax and
1416 12.5.5.31 SHOW SLAVE STATUS Syntax for details.
1417 Synopsis:
1419 <Plugin mysql>
1421 <Database foo>
1422 Host "hostname"
1423 User "username"
1424 Password "password"
1425 Port "3306"
1426 MasterStats true
1427 </Database>
1428 <Database bar>
1430 Host "localhost"
1431 Socket "/var/run/mysql/mysqld.sock"
1432 SlaveStats true
1433 SlaveNotifications true
1434 </Database>
1435 </Plugin>
1436 A Database block defines one connection to a MySQL database. It accepts
1438 a single argument which specifies the name of the database. None of the
1439 other options are required. MySQL will use default values as documented
1440 in the section "mysql_real_connect()" in the MySQL reference manual.
1441 Host Hostname
1443 Hostname of the database server. Defaults to localhost.
1444 User Username
1446 Username to use when connecting to the database. The user does not
1447 have to be granted any privileges (which is synonym to granting the
1448 "USAGE" privilege), unless you want to collectd replication
1449 statistics (see MasterStats and SlaveStats below). In this case,
1450 the user needs the "REPLICATION CLIENT" (or "SUPER") privileges.
1451 Else, any existing MySQL user will do.
1452 Password Password
1454 Password needed to log into the database.
1455 Database Database
1457 Select this database. Defaults to no database which is a perfectly
1458 reasonable option for what this plugin does.
1459 Port Port
1461 TCP-port to connect to. The port must be specified in its numeric
1462 form, but it must be passed as a string nonetheless. For example:
1463 Port "3306"
1465 If Host is set to localhost (the default), this setting has no
1467 effect. See the documentation for the "mysql_real_connect"
1468 function for details.
1469 Socket Socket
1471 Specifies the path to the UNIX domain socket of the MySQL server.
1472 This option only has any effect, if Host is set to localhost (the
1473 default). Otherwise, use the Port option above. See the
1474 documentation for the "mysql_real_connect" function for details.
1475 MasterStats true|false
1477 SlaveStats true|false
1478 Enable the collection of master / slave statistics in a replication
1479 setup. In order to be able to get access to these statistics, the
1480 user needs special privileges. See the User documentation above.
1481 SlaveNotifications true|false
1483 If enabled, the plugin sends a notification if the replication
1484 slave I/O and / or SQL threads are not running.
1485 Plugin "netapp"
1487 The netapp plugin can collect various performance and capacity
1488 information from a NetApp filer using the NetApp API.
1489 Please note that NetApp has a wide line of products and a lot of
1491 different software versions for each of these products. This plugin was
1492 developed for a NetApp FAS3040 running OnTap 7.2.3P8 and tested on
1493 FAS2050 7.3.1.1L1, FAS3140 7.2.5.1 and FAS3020 7.2.4P9. It should work
1494 for most combinations of model and software version but it is very hard
1495 to test this. If you have used this plugin with other models and/or
1496 software version, feel free to send us a mail to tell us about the
1497 results, even if it's just a short "It works".
1498 To collect these data collectd will log in to the NetApp via HTTP(S)
1500 and HTTP basic authentication.
1501 Do not use a regular user for this! Create a special collectd user with
1503 just the minimum of capabilities needed. The user only needs the
1504 "login-http-admin" capability as well as a few more depending on which
1505 data will be collected. Required capabilities are documented below.
1506 Synopsis
1508 <Plugin "netapp">
1510 <Host "netapp1.example.com">
1511 Protocol "https"
1512 Address "10.0.0.1"
1513 Port 443
1514 User "username"
1515 Password "aef4Aebe"
1516 Interval 30
1517 <WAFL>
1519 Interval 30
1520 GetNameCache true
1521 GetDirCache true
1522 GetBufferCache true
1523 GetInodeCache true
1524 </WAFL>
1525 <Disks>
1527 Interval 30
1528 GetBusy true
1529 </Disks>
1530 <VolumePerf>
1532 Interval 30
1533 GetIO "volume0"
1534 IgnoreSelectedIO false
1535 GetOps "volume0"
1536 IgnoreSelectedOps false
1537 GetLatency "volume0"
1538 IgnoreSelectedLatency false
1539 </VolumePerf>
1540 <VolumeUsage>
1542 Interval 30
1543 GetCapacity "vol0"
1544 GetCapacity "vol1"
1545 IgnoreSelectedCapacity false
1546 GetSnapshot "vol1"
1547 GetSnapshot "vol3"
1548 IgnoreSelectedSnapshot false
1549 </VolumeUsage>
1550 <System>
1552 Interval 30
1553 GetCPULoad true
1554 GetInterfaces true
1555 GetDiskOps true
1556 GetDiskIO true
1557 </System>
1558 </Host>
1559 </Plugin>
1560 The netapp plugin accepts the following configuration options:
1562 Host Name
1564 A host block defines one NetApp filer. It will appear in collectd
1565 with the name you specify here which does not have to be its real
1566 name nor its hostname.
1567 Protocol httpd|http
1569 The protocol collectd will use to query this host.
1570 Optional
1572 Type: string
1574 Default: https
1576 Valid options: http, https
1578 Address Address
1580 The hostname or IP address of the host.
1581 Optional
1583 Type: string
1585 Default: The "host" block's name.
1587 Port Port
1589 The TCP port to connect to on the host.
1590 Optional
1592 Type: integer
1594 Default: 80 for protocol "http", 443 for protocol "https"
1596 User User
1598 Password Password
1599 The username and password to use to login to the NetApp.
1600 Mandatory
1602 Type: string
1604 Interval Interval
1606 TODO
1607 The following options decide what kind of data will be collected. You
1609 can either use them as a block and fine tune various parameters inside
1610 this block, use them as a single statement to just accept all default
1611 values, or omit it to not collect any data.
1612 The following options are valid inside all blocks:
1614 Interval Seconds
1616 Collect the respective statistics every Seconds seconds. Defaults
1617 to the host specific setting.
1618 The System block
1620 This will collect various performance data about the whole system.
1622 Note: To get this data the collectd user needs the "api-perf-object-
1624 get-instances" capability.
1625 Interval Seconds
1627 Collect disk statistics every Seconds seconds.
1628 GetCPULoad true|false
1630 If you set this option to true the current CPU usage will be read.
1631 This will be the average usage between all CPUs in your NetApp
1632 without any information about individual CPUs.
1633 Note: These are the same values that the NetApp CLI command
1635 "sysstat" returns in the "CPU" field.
1636 Optional
1638 Type: boolean
1640 Default: true
1642 Result: Two value lists of type "cpu", and type instances "idle"
1644 and "system".
1645 GetInterfaces true|false
1647 If you set this option to true the current traffic of the network
1648 interfaces will be read. This will be the total traffic over all
1649 interfaces of your NetApp without any information about individual
1650 interfaces.
1651 Note: This is the same values that the NetApp CLI command "sysstat"
1653 returns in the "Net kB/s" field.
1654 Or is it?
1656 Optional
1658 Type: boolean
1660 Default: true
1662 Result: One value list of type "if_octects".
1664 GetDiskIO true|false
1666 If you set this option to true the current IO throughput will be
1667 read. This will be the total IO of your NetApp without any
1668 information about individual disks, volumes or aggregates.
1669 Note: This is the same values that the NetApp CLI command "sysstat"
1671 returns in the "Disk kB/s" field.
1672 Optional
1674 Type: boolean
1676 Default: true
1678 Result: One value list of type "disk_octets".
1680 GetDiskOps true|false
1682 If you set this option to true the current number of HTTP, NFS,
1683 CIFS, FCP, iSCSI, etc. operations will be read. This will be the
1684 total number of operations on your NetApp without any information
1685 about individual volumes or aggregates.
1686 Note: These are the same values that the NetApp CLI command
1688 "sysstat" returns in the "NFS", "CIFS", "HTTP", "FCP" and "iSCSI"
1689 fields.
1690 Optional
1692 Type: boolean
1694 Default: true
1696 Result: A variable number of value lists of type
1698 "disk_ops_complex". Each type of operation will result in one value
1699 list with the name of the operation as type instance.
1700 The WAFL block
1702 This will collect various performance data about the WAFL file system.
1704 At the moment this just means cache performance.
1705 Note: To get this data the collectd user needs the "api-perf-object-
1707 get-instances" capability.
1708 Note: The interface to get these values is classified as "Diagnostics"
1710 by NetApp. This means that it is not guaranteed to be stable even
1711 between minor releases.
1712 Interval Seconds
1714 Collect disk statistics every Seconds seconds.
1715 GetNameCache true|false
1717 Optional
1718 Type: boolean
1720 Default: true
1722 Result: One value list of type "cache_ratio" and type instance
1724 "name_cache_hit".
1725 GetDirCache true|false
1727 Optional
1728 Type: boolean
1730 Default: true
1732 Result: One value list of type "cache_ratio" and type instance
1734 "find_dir_hit".
1735 GetInodeCache true|false
1737 Optional
1738 Type: boolean
1740 Default: true
1742 Result: One value list of type "cache_ratio" and type instance
1744 "inode_cache_hit".
1745 GetBufferCache true|false
1747 Note: This is the same value that the NetApp CLI command "sysstat"
1748 returns in the "Cache hit" field.
1749 Optional
1751 Type: boolean
1753 Default: true
1755 Result: One value list of type "cache_ratio" and type instance
1757 "buf_hash_hit".
1758 The Disks block
1760 This will collect performance data about the individual disks in the
1762 NetApp.
1763 Note: To get this data the collectd user needs the "api-perf-object-
1765 get-instances" capability.
1766 Interval Seconds
1768 Collect disk statistics every Seconds seconds.
1769 GetBusy true|false
1771 If you set this option to true the busy time of all disks will be
1772 calculated and the value of the busiest disk in the system will be
1773 written.
1774 Note: This is the same values that the NetApp CLI command "sysstat"
1776 returns in the "Disk util" field. Probably.
1777 Optional
1779 Type: boolean
1781 Default: true
1783 Result: One value list of type "percent" and type instance
1785 "disk_busy".
1786 The VolumePerf block
1788 This will collect various performance data about the individual
1790 volumes.
1791 You can select which data to collect about which volume using the
1793 following options. They follow the standard ignorelist semantic.
1794 Note: To get this data the collectd user needs the api-perf-object-get-
1796 instances capability.
1797 Interval Seconds
1799 Collect volume performance data every Seconds seconds.
1800 GetIO Volume
1802 GetOps Volume
1803 GetLatency Volume
1804 Select the given volume for IO, operations or latency statistics
1805 collection. The argument is the name of the volume without the
1806 "/vol/" prefix.
1807 Since the standard ignorelist functionality is used here, you can
1809 use a string starting and ending with a slash to specify regular
1810 expression matching: To match the volumes "vol0", "vol2" and
1811 "vol7", you can use this regular expression:
1812 GetIO "/^vol[027]$/"
1814 If no regular expression is specified, an exact match is required.
1816 Both, regular and exact matching are case sensitive.
1817 If no volume was specified at all for either of the three options,
1819 that data will be collected for all available volumes.
1820 IgnoreSelectedIO true|false
1822 IgnoreSelectedOps true|false
1823 IgnoreSelectedLatency true|false
1824 When set to true, the volumes selected for IO, operations or
1825 latency statistics collection will be ignored and the data will be
1826 collected for all other volumes.
1827 When set to false, data will only be collected for the specified
1829 volumes and all other volumes will be ignored.
1830 If no volumes have been specified with the above Get* options, all
1832 volumes will be collected regardless of the IgnoreSelected* option.
1833 Defaults to false
1835 The VolumeUsage block
1837 This will collect capacity data about the individual volumes.
1839 Note: To get this data the collectd user needs the api-volume-list-info
1841 capability.
1842 Interval Seconds
1844 Collect volume usage statistics every Seconds seconds.
1845 GetCapacity VolumeName
1847 The current capacity of the volume will be collected. This will
1848 result in two to four value lists, depending on the configuration
1849 of the volume. All data sources are of type "df_complex" with the
1850 name of the volume as plugin_instance.
1851 There will be type_instances "used" and "free" for the number of
1853 used and available bytes on the volume. If the volume has some
1854 space reserved for snapshots, a type_instance "snap_reserved" will
1855 be available. If the volume has SIS enabled, a type_instance
1856 "sis_saved" will be available. This is the number of bytes saved by
1857 the SIS feature.
1858 Note: The current NetApp API has a bug that results in this value
1860 being reported as a 32 bit number. This plugin tries to guess the
1861 correct number which works most of the time. If you see strange
1862 values here, bug NetApp support to fix this.
1863 Repeat this option to specify multiple volumes.
1865 IgnoreSelectedCapacity true|false
1867 Specify whether to collect only the volumes selected by the
1868 GetCapacity option or to ignore those volumes.
1869 IgnoreSelectedCapacity defaults to false. However, if no
1870 GetCapacity option is specified at all, all capacities will be
1871 selected anyway.
1872 GetSnapshot VolumeName
1874 Select volumes from which to collect snapshot information.
1875 Usually, the space used for snapshots is included in the space
1877 reported as "used". If snapshot information is collected as well,
1878 the space used for snapshots is subtracted from the used space.
1879 To make things even more interesting, it is possible to reserve
1881 space to be used for snapshots. If the space required for snapshots
1882 is less than that reserved space, there is "reserved free" and
1883 "reserved used" space in addition to "free" and "used". If the
1884 space required for snapshots exceeds the reserved space, that part
1885 allocated in the normal space is subtracted from the "used" space
1886 again.
1887 Repeat this option to specify multiple volumes.
1889 IgnoreSelectedSnapshot
1891 Specify whether to collect only the volumes selected by the
1892 GetSnapshot option or to ignore those volumes.
1893 IgnoreSelectedSnapshot defaults to false. However, if no
1894 GetSnapshot option is specified at all, all capacities will be
1895 selected anyway.
1896 Plugin "netlink"
1898 The "netlink" plugin uses a netlink socket to query the Linux kernel
1899 about statistics of various interface and routing aspects.
1900 Interface Interface
1902 VerboseInterface Interface
1903 Instruct the plugin to collect interface statistics. This is
1904 basically the same as the statistics provided by the "interface"
1905 plugin (see above) but potentially much more detailed.
1906 When configuring with Interface only the basic statistics will be
1908 collected, namely octets, packets, and errors. These statistics are
1909 collected by the "interface" plugin, too, so using both at the same
1910 time is no benefit.
1911 When configured with VerboseInterface all counters except the basic
1913 ones, so that no data needs to be collected twice if you use the
1914 "interface" plugin. This includes dropped packets, received
1915 multicast packets, collisions and a whole zoo of differentiated RX
1916 and TX errors. You can try the following command to get an idea of
1917 what awaits you:
1918 ip -s -s link list
1920 If Interface is All, all interfaces will be selected.
1922 QDisc Interface [QDisc]
1924 Class Interface [Class]
1925 Filter Interface [Filter]
1926 Collect the octets and packets that pass a certain qdisc, class or
1927 filter.
1928 QDiscs and classes are identified by their type and handle (or
1930 classid). Filters don't necessarily have a handle, therefore the
1931 parent's handle is used. The notation used in collectd differs
1932 from that used in tc(1) in that it doesn't skip the major or minor
1933 number if it's zero and doesn't print special ids by their name.
1934 So, for example, a qdisc may be identified by "pfifo_fast-1:0" even
1935 though the minor number of all qdiscs is zero and thus not
1936 displayed by tc(1).
1937 If QDisc, Class, or Filter is given without the second argument,
1939 i. .e. without an identifier, all qdiscs, classes, or filters that
1940 are associated with that interface will be collected.
1941 Since a filter itself doesn't necessarily have a handle, the
1943 parent's handle is used. This may lead to problems when more than
1944 one filter is attached to a qdisc or class. This isn't nice, but we
1945 don't know how this could be done any better. If you have a idea,
1946 please don't hesitate to tell us.
1947 As with the Interface option you can specify All as the interface,
1949 meaning all interfaces.
1950 Here are some examples to help you understand the above text more
1952 easily:
1953 <Plugin netlink>
1955 VerboseInterface "All"
1956 QDisc "eth0" "pfifo_fast-1:0"
1957 QDisc "ppp0"
1958 Class "ppp0" "htb-1:10"
1959 Filter "ppp0" "u32-1:0"
1960 </Plugin>
1961 IgnoreSelected
1963 The behavior is the same as with all other similar plugins: If
1964 nothing is selected at all, everything is collected. If some things
1965 are selected using the options described above, only these
1966 statistics are collected. If you set IgnoreSelected to true, this
1967 behavior is inverted, i. e. the specified statistics will not be
1968 collected.
1969 Plugin "network"
1971 The Network plugin sends data to a remote instance of collectd,
1972 receives data from a remote instance, or both at the same time. Data
1973 which has been received from the network is usually not transmitted
1974 again, but this can be activated, see the Forward option below.
1975 The default IPv6 multicast group is "ff18::efc0:4a42". The default IPv4
1977 multicast group is 239.192.74.66. The default UDP port is 25826.
1978 Both, Server and Listen can be used as single option or as block. When
1980 used as block, given options are valid for this socket only. For
1981 example:
1982 <Plugin "network">
1984 Server "collectd.internal.tld"
1985 <Server "collectd.external.tld">
1986 SecurityLevel "sign"
1987 Username "myhostname"
1988 Password "ohl0eQue"
1989 </Server>
1990 </Plugin>
1991 <Server Host [Port]>
1993 The Server statement/block sets the server to send datagrams to.
1994 The statement may occur multiple times to send each datagram to
1995 multiple destinations.
1996 The argument Host may be a hostname, an IPv4 address or an IPv6
1998 address. The optional second argument specifies a port number or a
1999 service name. If not given, the default, 25826, is used.
2000 The following options are recognized within Server blocks:
2002 SecurityLevel Encrypt|Sign|None
2004 Set the security you require for network communication. When
2005 the security level has been set to Encrypt, data sent over the
2006 network will be encrypted using AES-256. The integrity of
2007 encrypted packets is ensured using SHA-1. When set to Sign,
2008 transmitted data is signed using the HMAC-SHA-256 message
2009 authentication code. When set to None, data is sent without any
2010 security.
2011 This feature is only available if the network plugin was linked
2013 with libgcrypt.
2014 Username Username
2016 Sets the username to transmit. This is used by the server to
2017 lookup the password. See AuthFile below. All security levels
2018 except None require this setting.
2019 This feature is only available if the network plugin was linked
2021 with libgcrypt.
2022 Password Password
2024 Sets a password (shared secret) for this socket. All security
2025 levels except None require this setting.
2026 This feature is only available if the network plugin was linked
2028 with libgcrypt.
2029 <Listen Host [Port]>
2031 The Listen statement sets the interfaces to bind to. When multiple
2032 statements are found the daemon will bind to multiple interfaces.
2033 The argument Host may be a hostname, an IPv4 address or an IPv6
2035 address. If the argument is a multicast address the daemon will
2036 join that multicast group. The optional second argument specifies
2037 a port number or a service name. If not given, the default, 25826,
2038 is used.
2039 The following options are recognized within "<Listen>" blocks:
2041 SecurityLevel Encrypt|Sign|None
2043 Set the security you require for network communication. When
2044 the security level has been set to Encrypt, only encrypted data
2045 will be accepted. The integrity of encrypted packets is ensured
2046 using SHA-1. When set to Sign, only signed and encrypted data
2047 is accepted. When set to None, all data will be accepted. If an
2048 AuthFile option was given (see below), encrypted data is
2049 decrypted if possible.
2050 This feature is only available if the network plugin was linked
2052 with libgcrypt.
2053 AuthFile Filename
2055 Sets a file in which usernames are mapped to passwords. These
2056 passwords are used to verify signatures and to decrypt
2057 encrypted network packets. If SecurityLevel is set to None,
2058 this is optional. If given, signed data is verified and
2059 encrypted packets are decrypted. Otherwise, signed data is
2060 accepted without checking the signature and encrypted data
2061 cannot be decrypted. For the other security levels this option
2062 is mandatory.
2063 The file format is very simple: Each line consists of a
2065 username followed by a colon and any number of spaces followed
2066 by the password. To demonstrate, an example file could look
2067 like this:
2068 user0: foo
2070 user1: bar
2071 Each time a packet is received, the modification time of the
2073 file is checked using stat(2). If the file has been changed,
2074 the contents is re-read. While the file is being read, it is
2075 locked using fcntl(2).
2076 TimeToLive 1-255
2078 Set the time-to-live of sent packets. This applies to all, unicast
2079 and multicast, and IPv4 and IPv6 packets. The default is to not
2080 change this value. That means that multicast packets will be sent
2081 with a TTL of 1 (one) on most operating systems.
2082 MaxPacketSize 1024-65535
2084 Set the maximum size for datagrams received over the network.
2085 Packets larger than this will be truncated.
2086 Forward true|false
2088 If set to true, write packets that were received via the network
2089 plugin to the sending sockets. This should only be activated when
2090 the Listen- and Server-statements differ. Otherwise packets may be
2091 send multiple times to the same multicast group. While this results
2092 in more network traffic than necessary it's not a huge problem
2093 since the plugin has a duplicate detection, so the values will not
2094 loop.
2095 CacheFlush Seconds
2097 For each host/plugin/type combination the "network plugin" caches
2098 the time of the last value being sent or received. Every Seconds
2099 seconds the plugin searches and removes all entries that are older
2100 than Seconds seconds, thus freeing the unused memory again. Since
2101 this process is somewhat expensive and normally doesn't do much,
2102 this value should not be too small. The default is 1800 seconds,
2103 but setting this to 86400 seconds (one day) will not do much harm
2104 either.
2105 ReportStats true|false
2107 The network plugin cannot only receive and send statistics, it can
2108 also create statistics about itself. Collected data included the
2109 number of received and sent octets and packets, the length of the
2110 receive queue and the number of values handled. When set to true,
2111 the Network plugin will make these statistics available. Defaults
2112 to false.
2113 Plugin "nginx"
2115 This plugin collects the number of connections and requests handled by
2116 the "nginx daemon" (speak: engine X), a HTTP and mail server/proxy. It
2117 queries the page provided by the "ngx_http_stub_status_module" module,
2118 which isn't compiled by default. Please refer to
2119 <http://wiki.codemongers.com/NginxStubStatusModule> for more
2120 information on how to compile and configure nginx and this module.
2121 The following options are accepted by the "nginx plugin":
2123 URL http://host/nginx_status
2125 Sets the URL of the "ngx_http_stub_status_module" output.
2126 User Username
2128 Optional user name needed for authentication.
2129 Password Password
2131 Optional password needed for authentication.
2132 VerifyPeer true|false
2134 Enable or disable peer SSL certificate verification. See
2135 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
2136 default.
2137 VerifyHost true|false
2139 Enable or disable peer host name verification. If enabled, the
2140 plugin checks if the "Common Name" or a "Subject Alternate Name"
2141 field of the SSL certificate matches the host name provided by the
2142 URL option. If this identity check fails, the connection is
2143 aborted. Obviously, only works when connecting to a SSL enabled
2144 server. Enabled by default.
2145 CACert File
2147 File that holds one or more SSL certificates. If you want to use
2148 HTTPS you will possibly need this option. What CA certificates come
2149 bundled with "libcurl" and are checked by default depends on the
2150 distribution you use.
2151 Plugin "notify_desktop"
2153 This plugin sends a desktop notification to a notification daemon, as
2154 defined in the Desktop Notification Specification. To actually display
2155 the notifications, notification-daemon is required and collectd has to
2156 be able to access the X server (i. e., the "DISPLAY" and "XAUTHORITY"
2157 environment variables have to be set correctly) and the D-Bus message
2158 bus.
2159 The Desktop Notification Specification can be found at
2161 <http://www.galago-project.org/specs/notification/>.
2162 OkayTimeout timeout
2164 WarningTimeout timeout
2165 FailureTimeout timeout
2166 Set the timeout, in milliseconds, after which to expire the
2167 notification for "OKAY", "WARNING" and "FAILURE" severities
2168 respectively. If zero has been specified, the displayed
2169 notification will not be closed at all - the user has to do so
2170 herself. These options default to 5000. If a negative number has
2171 been specified, the default is used as well.
2172 Plugin "notify_email"
2174 The notify_email plugin uses the ESMTP library to send notifications to
2175 a configured email address.
2176 libESMTP is available from <http://www.stafford.uklinux.net/libesmtp/>.
2178 Available configuration options:
2180 From Address
2182 Email address from which the emails should appear to come from.
2183 Default: "root@localhost"
2185 Recipient Address
2187 Configures the email address(es) to which the notifications should
2188 be mailed. May be repeated to send notifications to multiple
2189 addresses.
2190 At least one Recipient must be present for the plugin to work
2192 correctly.
2193 SMTPServer Hostname
2195 Hostname of the SMTP server to connect to.
2196 Default: "localhost"
2198 SMTPPort Port
2200 TCP port to connect to.
2201 Default: 25
2203 SMTPUser Username
2205 Username for ASMTP authentication. Optional.
2206 SMTPPassword Password
2208 Password for ASMTP authentication. Optional.
2209 Subject Subject
2211 Subject-template to use when sending emails. There must be exactly
2212 two string-placeholders in the subject, given in the standard
2213 printf(3) syntax, i. e. %s. The first will be replaced with the
2214 severity, the second with the hostname.
2215 Default: "Collectd notify: %s@%s"
2217 Plugin "ntpd"
2219 Host Hostname
2220 Hostname of the host running ntpd. Defaults to localhost.
2221 Port Port
2223 UDP-Port to connect to. Defaults to 123.
2224 ReverseLookups true|false
2226 Sets whether or not to perform reverse lookups on peers. Since the
2227 name or IP-address may be used in a filename it is recommended to
2228 disable reverse lookups. The default is to do reverse lookups to
2229 preserve backwards compatibility, though.
2230 Plugin "nut"
2232 UPS upsname@hostname[:port]
2233 Add a UPS to collect data from. The format is identical to the one
2234 accepted by upsc(8).
2235 Plugin "olsrd"
2237 The olsrd plugin connects to the TCP port opened by the txtinfo plugin
2238 of the Optimized Link State Routing daemon and reads information about
2239 the current state of the meshed network.
2240 The following configuration options are understood:
2242 Host Host
2244 Connect to Host. Defaults to "localhost".
2245 Port Port
2247 Specifies the port to connect to. This must be a string, even if
2248 you give the port as a number rather than a service name. Defaults
2249 to "2006".
2250 CollectLinks No|Summary|Detail
2252 Specifies what information to collect about links, i. e. direct
2253 connections of the daemon queried. If set to No, no information is
2254 collected. If set to Summary, the number of links and the average
2255 of all link quality (LQ) and neighbor link quality (NLQ) values is
2256 calculated. If set to Detail LQ and NLQ are collected per link.
2257 Defaults to Detail.
2259 CollectRoutes No|Summary|Detail
2261 Specifies what information to collect about routes of the daemon
2262 queried. If set to No, no information is collected. If set to
2263 Summary, the number of routes and the average metric and ETX is
2264 calculated. If set to Detail metric and ETX are collected per
2265 route.
2266 Defaults to Summary.
2268 CollectTopology No|Summary|Detail
2270 Specifies what information to collect about the global topology. If
2271 set to No, no information is collected. If set to Summary, the
2272 number of links in the entire topology and the average link quality
2273 (LQ) is calculated. If set to Detail LQ and NLQ are collected for
2274 each link in the entire topology.
2275 Defaults to Summary.
2277 Plugin "onewire"
2279 EXPERIMENTAL! See notes below.
2280 The "onewire" plugin uses the owcapi library from the owfs project
2282 <http://owfs.org/> to read sensors connected via the onewire bus.
2283 Currently only temperature sensors (sensors with the family code 10,
2285 e. g. DS1820, DS18S20, DS1920) can be read. If you have other sensors
2286 you would like to have included, please send a sort request to the
2287 mailing list.
2288 Hubs (the DS2409 chips) are working, but read the note, why this plugin
2290 is experimental, below.
2291 Device Device
2293 Sets the device to read the values from. This can either be a
2294 "real" hardware device, such as a serial port or an USB port, or
2295 the address of the owserver(1) socket, usually localhost:4304.
2296 Though the documentation claims to automatically recognize the
2298 given address format, with version 2.7p4 we had to specify the type
2299 explicitly. So with that version, the following configuration
2300 worked for us:
2301 <Plugin onewire>
2303 Device "-s localhost:4304"
2304 </Plugin>
2305 This directive is required and does not have a default value.
2307 Sensor Sensor
2309 Selects sensors to collect or to ignore, depending on
2310 IgnoreSelected, see below. Sensors are specified without the family
2311 byte at the beginning, to you'd use "F10FCA000800", and not include
2312 the leading 10. family byte and point.
2313 IgnoreSelected true|false
2315 If no configuration if given, the onewire plugin will collect data
2316 from all sensors found. This may not be practical, especially if
2317 sensors are added and removed regularly. Sometimes, however, it's
2318 easier/preferred to collect only specific sensors or all sensors
2319 except a few specified ones. This option enables you to do that: By
2320 setting IgnoreSelected to true the effect of Sensor is inverted:
2321 All selected interfaces are ignored and all other interfaces are
2322 collected.
2323 Interval Seconds
2325 Sets the interval in which all sensors should be read. If not
2326 specified, the global Interval setting is used.
2327 EXPERIMENTAL! The "onewire" plugin is experimental, because it doesn't
2329 yet work with big setups. It works with one sensor being attached to
2330 one controller, but as soon as you throw in a couple more senors and
2331 maybe a hub or two, reading all values will take more than ten seconds
2332 (the default interval). We will probably add some separate thread for
2333 reading the sensors and some cache or something like that, but it's not
2334 done yet. We will try to maintain backwards compatibility in the
2335 future, but we can't promise. So in short: If it works for you: Great!
2336 But keep in mind that the config might change, though this is unlikely.
2337 Oh, and if you want to help improving this plugin, just send a short
2338 notice to the mailing list. Thanks :)
2339 Plugin "openvpn"
2341 The OpenVPN plugin reads a status file maintained by OpenVPN and
2342 gathers traffic statistics about connected clients.
2343 To set up OpenVPN to write to the status file periodically, use the
2345 --status option of OpenVPN. Since OpenVPN can write two different
2346 formats, you need to set the required format, too. This is done by
2347 setting --status-version to 2.
2348 So, in a nutshell you need:
2350 openvpn $OTHER_OPTIONS \
2352 --status "/var/run/openvpn-status" 10 \
2353 --status-version 2
2354 Available options:
2356 StatusFile File
2358 Specifies the location of the status file.
2359 ImprovedNamingSchema true|false
2361 When enabled, the filename of the status file will be used as
2362 plugin instance and the client's "common name" will be used as type
2363 instance. This is required when reading multiple status files.
2364 Enabling this option is recommended, but to maintain backwards
2365 compatibility this option is disabled by default.
2366 Compression true|false
2368 Sets whether or not statistics about the compression used by
2369 OpenVPN should be collected. This information is only available in
2370 single mode. Enabled by default.
2371 Plugin "oracle"
2373 The "oracle" plugin uses the OracleAX Call Interface (OCI) to connect
2374 to an OracleAX Database and lets you execute SQL statements there. It
2375 is very similar to the "dbi" plugin, because it was written around the
2376 same time. See the "dbi" plugin's documentation above for details.
2377 <Plugin oracle>
2379 <Query "out_of_stock">
2380 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
2381 <Result>
2382 Type "gauge"
2383 # InstancePrefix "foo"
2384 InstancesFrom "category"
2385 ValuesFrom "value"
2386 </Result>
2387 </Query>
2388 <Database "product_information">
2389 ConnectID "db01"
2390 Username "oracle"
2391 Password "secret"
2392 Query "out_of_stock"
2393 </Database>
2394 </Plugin>
2395 Query blocks
2397 The Query blocks are handled identically to the Query blocks of the
2399 "dbi" plugin. Please see its documentation above for details on how to
2400 specify queries.
2401 Database blocks
2403 Database blocks define a connection to a database and which queries
2405 should be sent to that database. Each database needs a "name" as string
2406 argument in the starting tag of the block. This name will be used as
2407 "PluginInstance" in the values submitted to the daemon. Other than
2408 that, that name is not used.
2409 ConnectID ID
2411 Defines the "database alias" or "service name" to connect to.
2412 Usually, these names are defined in the file named
2413 "$ORACLE_HOME/network/admin/tnsnames.ora".
2414 Username Username
2416 Username used for authentication.
2417 Password Password
2419 Password used for authentication.
2420 Query QueryName
2422 Associates the query named QueryName with this database connection.
2423 The query needs to be defined before this statement, i. e. all
2424 query blocks you want to refer to must be placed above the database
2425 block you want to refer to them from.
2426 Plugin "perl"
2428 This plugin embeds a Perl-interpreter into collectd and provides an
2429 interface to collectd's plugin system. See collectd-perl(5) for its
2430 documentation.
2431 Plugin "ping"
2433 The Ping plugin starts a new thread which sends ICMP "ping" packets to
2434 the configured hosts periodically and measures the network latency.
2435 Whenever the "read" function of the plugin is called, it submits the
2436 average latency, the standard deviation and the drop rate for each
2437 host.
2438 Available configuration options:
2440 Host IP-address
2442 Host to ping periodically. This option may be repeated several
2443 times to ping multiple hosts.
2444 Interval Seconds
2446 Sets the interval in which to send ICMP echo packets to the
2447 configured hosts. This is not the interval in which statistics are
2448 queries from the plugin but the interval in which the hosts are
2449 "pinged". Therefore, the setting here should be smaller than or
2450 equal to the global Interval setting. Fractional times, such as
2451 "1.24" are allowed.
2452 Default: 1.0
2454 Timeout Seconds
2456 Time to wait for a response from the host to which an ICMP packet
2457 had been sent. If a reply was not received after Seconds seconds,
2458 the host is assumed to be down or the packet to be dropped. This
2459 setting must be smaller than the Interval setting above for the
2460 plugin to work correctly. Fractional arguments are accepted.
2461 Default: 0.9
2463 TTL 0-255
2465 Sets the Time-To-Live of generated ICMP packets.
2466 SourceAddress host
2468 Sets the source address to use. host may either be a numerical
2469 network address or a network hostname.
2470 Device name
2472 Sets the outgoing network device to be used. name has to specify an
2473 interface name (e. g. "eth0"). This might not be supported by all
2474 operating systems.
2475 MaxMissed Packets
2477 Trigger a DNS resolv after the host has not replied to Packets
2478 packets. This enables the use of dynamic DNS services (like
2479 dyndns.org) with the ping plugin.
2480 Default: -1 (disabled)
2482 Plugin "postgresql"
2484 The "postgresql" plugin queries statistics from PostgreSQL databases.
2485 It keeps a persistent connection to all configured databases and tries
2486 to reconnect if the connection has been interrupted. A database is
2487 configured by specifying a Database block as described below. The
2488 default statistics are collected from PostgreSQL's statistics collector
2489 which thus has to be enabled for this plugin to work correctly. This
2490 should usually be the case by default. See the section "The Statistics
2491 Collector" of the PostgreSQL Documentation for details.
2492 By specifying custom database queries using a Query block as described
2494 below, you may collect any data that is available from some PostgreSQL
2495 database. This way, you are able to access statistics of external
2496 daemons which are available in a PostgreSQL database or use future or
2497 special statistics provided by PostgreSQL without the need to upgrade
2498 your collectd installation.
2499 The PostgreSQL Documentation manual can be found at
2501 <http://www.postgresql.org/docs/manuals/>.
2502 <Plugin postgresql>
2504 <Query magic>
2505 Statement "SELECT magic FROM wizard WHERE host = $1;"
2506 Param hostname
2507 <Result>
2508 Type gauge
2509 InstancePrefix "magic"
2510 ValuesFrom magic
2511 </Result>
2512 </Query>
2513 <Query rt36_tickets>
2515 Statement "SELECT COUNT(type) AS count, type \
2516 FROM (SELECT CASE \
2517 WHEN resolved = 'epoch' THEN 'open' \
2518 ELSE 'resolved' END AS type \
2519 FROM tickets) type \
2520 GROUP BY type;"
2521 <Result>
2522 Type counter
2523 InstancePrefix "rt36_tickets"
2524 InstancesFrom "type"
2525 ValuesFrom "count"
2526 </Result>
2527 </Query>
2528 <Database foo>
2530 Host "hostname"
2531 Port "5432"
2532 User "username"
2533 Password "secret"
2534 SSLMode "prefer"
2535 KRBSrvName "kerberos_service_name"
2536 Query magic
2537 </Database>
2538 <Database bar>
2540 Service "service_name"
2541 Query backend # predefined
2542 Query rt36_tickets
2543 </Database>
2544 </Plugin>
2545 The Query block defines one database query which may later be used by a
2547 database definition. It accepts a single mandatory argument which
2548 specifies the name of the query. The names of all queries have to be
2549 unique (see the MinVersion and MaxVersion options below for an
2550 exception to this rule). The following configuration options are
2551 available to define the query:
2552 In each Query block, there is one or more Result blocks. Result blocks
2554 define how to handle the values returned from the query. They define
2555 which column holds which value and how to dispatch that value to the
2556 daemon. Multiple Result blocks may be used to extract multiple values
2557 from a single query.
2558 Statement sql query statement
2560 Specify the sql query statement which the plugin should execute.
2561 The string may contain the tokens $1, $2, etc. which are used to
2562 reference the first, second, etc. parameter. The value of the
2563 parameters is specified by the Param configuration option - see
2564 below for details. To include a literal $ character followed by a
2565 number, surround it with single quotes (').
2566 Any SQL command which may return data (such as "SELECT" or "SHOW")
2568 is allowed. Note, however, that only a single command may be used.
2569 Semicolons are allowed as long as a single non-empty command has
2570 been specified only.
2571 The returned lines will be handled separately one after another.
2573 Query sql query statement
2575 This is a deprecated synonym for Statement. It will be removed in
2576 version 5 of collectd.
2577 Param hostname|database|username|interval
2579 Specify the parameters which should be passed to the SQL query. The
2580 parameters are referred to in the SQL query as $1, $2, etc. in the
2581 same order as they appear in the configuration file. The value of
2582 the parameter is determined depending on the value of the Param
2583 option as follows:
2584 hostname
2586 The configured hostname of the database connection. If a UNIX
2587 domain socket is used, the parameter expands to "localhost".
2588 database
2590 The name of the database of the current connection.
2591 username
2593 The username used to connect to the database.
2594 interval
2596 The interval collectd is using (as specified by the Interval
2597 option).
2598 Please note that parameters are only supported by PostgreSQL's
2600 protocol version 3 and above which was introduced in version 7.4 of
2601 PostgreSQL.
2602 Type type
2604 The type name to be used when dispatching the values. The type
2605 describes how to handle the data and where to store it. See
2606 types.db(5) for more details on types and their configuration. The
2607 number and type of values (as selected by the ValuesFrom option)
2608 has to match the type of the given name.
2609 This option is required inside a Result block.
2611 InstancePrefix prefix
2613 InstancesFrom column0 [column1 ...]
2614 Specify how to create the "TypeInstance" for each data set (i. e.
2615 line). InstancePrefix defines a static prefix that will be
2616 prepended to all type instances. InstancesFrom defines the column
2617 names whose values will be used to create the type instance.
2618 Multiple values will be joined together using the hyphen ("-") as
2619 separation character.
2620 The plugin itself does not check whether or not all built instances
2622 are different. It is your responsibility to assure that each is
2623 unique.
2624 Both options are optional. If none is specified, the type instance
2626 will be empty.
2627 ValuesFrom column0 [column1 ...]
2629 Names the columns whose content is used as the actual data for the
2630 data sets that are dispatched to the daemon. How many such columns
2631 you need is determined by the Type setting as explained above. If
2632 you specify too many or not enough columns, the plugin will
2633 complain about that and no data will be submitted to the daemon.
2634 The actual data type, as seen by PostgreSQL, is not that important
2636 as long as it represents numbers. The plugin will automatically
2637 cast the values to the right type if it know how to do that. For
2638 that, it uses the strtoll(3) and strtod(3) functions, so anything
2639 supported by those functions is supported by the plugin as well.
2640 This option is required inside a Result block and may be specified
2642 multiple times. If multiple ValuesFrom options are specified, the
2643 columns are read in the given order.
2644 Column type [type instance]
2646 This is a deprecated alternative to a Result block. It will be
2647 removed in version 5 of collectd. It is equivalent to the following
2648 Result block:
2649 <Result>
2651 Type I<type>
2652 InstancePrefix I<type instance>
2653 ValuesFrom I<name of the x. column>
2654 </Result>
2655 The order of the Column options defines which columns of the query
2657 result should be used. The first option specifies the data found in
2658 the first column, the second option that of the second column, and
2659 so on.
2660 MinVersion version
2662 MaxVersion version
2663 Specify the minimum or maximum version of PostgreSQL that this
2664 query should be used with. Some statistics might only be available
2665 with certain versions of PostgreSQL. This allows you to specify
2666 multiple queries with the same name but which apply to different
2667 versions, thus allowing you to use the same configuration in a
2668 heterogeneous environment.
2669 The version has to be specified as the concatenation of the major,
2671 minor and patch-level versions, each represented as two-decimal-
2672 digit numbers. For example, version 8.2.3 will become 80203.
2673 MinPGVersion version
2675 MaxPGVersion version
2676 These are deprecated synonyms for MinVersion and MaxVersion
2677 respectively. They will be removed in version 5 of collectd.
2678 The following predefined queries are available (the definitions can be
2680 found in the postgresql_default.conf file which, by default, is
2681 available at "prefix/share/collectd/"):
2682 backends
2684 This query collects the number of backends, i. e. the number of
2685 connected clients.
2686 transactions
2688 This query collects the numbers of committed and rolled-back
2689 transactions of the user tables.
2690 queries
2692 This query collects the numbers of various table modifications
2693 (i. e. insertions, updates, deletions) of the user tables.
2694 query_plans
2696 This query collects the numbers of various table scans and returned
2697 tuples of the user tables.
2698 table_states
2700 This query collects the numbers of live and dead rows in the user
2701 tables.
2702 disk_io
2704 This query collects disk block access counts for user tables.
2705 disk_usage
2707 This query collects the on-disk size of the database in bytes.
2708 The Database block defines one PostgreSQL database for which to collect
2710 statistics. It accepts a single mandatory argument which specifies the
2711 database name. None of the other options are required. PostgreSQL will
2712 use default values as documented in the section "CONNECTING TO A
2713 DATABASE" in the psql(1) manpage. However, be aware that those defaults
2714 may be influenced by the user collectd is run as and special
2715 environment variables. See the manpage for details.
2716 Host hostname
2718 Specify the hostname or IP of the PostgreSQL server to connect to.
2719 If the value begins with a slash, it is interpreted as the
2720 directory name in which to look for the UNIX domain socket.
2721 This option is also used to determine the hostname that is
2723 associated with a collected data set. If it has been omitted or
2724 either begins with with a slash or equals localhost it will be
2725 replaced with the global hostname definition of collectd. Any other
2726 value will be passed literally to collectd when dispatching values.
2727 Also see the global Hostname and FQDNLookup options.
2728 Port port
2730 Specify the TCP port or the local UNIX domain socket file extension
2731 of the server.
2732 User username
2734 Specify the username to be used when connecting to the server.
2735 Password password
2737 Specify the password to be used when connecting to the server.
2738 SSLMode disable|allow|prefer|require
2740 Specify whether to use an SSL connection when contacting the
2741 server. The following modes are supported:
2742 disable
2744 Do not use SSL at all.
2745 allow
2747 First, try to connect without using SSL. If that fails, try
2748 using SSL.
2749 prefer (default)
2751 First, try to connect using SSL. If that fails, try without
2752 using SSL.
2753 require
2755 Use SSL only.
2756 KRBSrvName kerberos_service_name
2758 Specify the Kerberos service name to use when authenticating with
2759 Kerberos 5 or GSSAPI. See the sections "Kerberos authentication"
2760 and "GSSAPI" of the PostgreSQL Documentation for details.
2761 Service service_name
2763 Specify the PostgreSQL service name to use for additional
2764 parameters. That service has to be defined in pg_service.conf and
2765 holds additional connection parameters. See the section "The
2766 Connection Service File" in the PostgreSQL Documentation for
2767 details.
2768 Query query
2770 Specify a query which should be executed for the database
2771 connection. This may be any of the predefined or user-defined
2772 queries. If no such option is given, it defaults to "backends",
2773 "transactions", "queries", "query_plans", "table_states", "disk_io"
2774 and "disk_usage". Else, the specified queries are used only.
2775 Plugin "powerdns"
2777 The "powerdns" plugin queries statistics from an authoritative PowerDNS
2778 nameserver and/or a PowerDNS recursor. Since both offer a wide variety
2779 of values, many of which are probably meaningless to most users, but
2780 may be useful for some. So you may chose which values to collect, but
2781 if you don't, some reasonable defaults will be collected.
2782 <Plugin "powerdns">
2784 <Server "server_name">
2785 Collect "latency"
2786 Collect "udp-answers" "udp-queries"
2787 Socket "/var/run/pdns.controlsocket"
2788 </Server>
2789 <Recursor "recursor_name">
2790 Collect "questions"
2791 Collect "cache-hits" "cache-misses"
2792 Socket "/var/run/pdns_recursor.controlsocket"
2793 </Recursor>
2794 LocalSocket "/opt/collectd/var/run/collectd-powerdns"
2795 </Plugin>
2796 Server and Recursor block
2798 The Server block defines one authoritative server to query, the
2799 Recursor does the same for an recursing server. The possible
2800 options in both blocks are the same, though. The argument defines a
2801 name for the server / recursor and is required.
2802 Collect Field
2804 Using the Collect statement you can select which values to
2805 collect. Here, you specify the name of the values as used by
2806 the PowerDNS servers, e. g. "dlg-only-drops", "answers10-100".
2807 The method of getting the values differs for Server and
2809 Recursor blocks: When querying the server a "SHOW *" command is
2810 issued in any case, because that's the only way of getting
2811 multiple values out of the server at once. collectd then picks
2812 out the values you have selected. When querying the recursor, a
2813 command is generated to query exactly these values. So if you
2814 specify invalid fields when querying the recursor, a syntax
2815 error may be returned by the daemon and collectd may not
2816 collect any values at all.
2817 If no Collect statement is given, the following Server values
2819 will be collected:
2820 latency
2822 packetcache-hit
2823 packetcache-miss
2824 packetcache-size
2825 query-cache-hit
2826 query-cache-miss
2827 recursing-answers
2828 recursing-questions
2829 tcp-answers
2830 tcp-queries
2831 udp-answers
2832 udp-queries
2833 The following Recursor values will be collected by default:
2835 noerror-answers
2837 nxdomain-answers
2838 servfail-answers
2839 sys-msec
2840 user-msec
2841 qa-latency
2842 cache-entries
2843 cache-hits
2844 cache-misses
2845 questions
2846 Please note that up to that point collectd doesn't know what
2848 values are available on the server and values that are added do
2849 not need a change of the mechanism so far. However, the values
2850 must be mapped to collectd's naming scheme, which is done using
2851 a lookup table that lists all known values. If values are added
2852 in the future and collectd does not know about them, you will
2853 get an error much like this:
2854 powerdns plugin: submit: Not found in lookup table: foobar = 42
2856 In this case please file a bug report with the collectd team.
2858 Socket Path
2860 Configures the path to the UNIX domain socket to be used when
2861 connecting to the daemon. By default
2862 "${localstatedir}/run/pdns.controlsocket" will be used for an
2863 authoritative server and
2864 "${localstatedir}/run/pdns_recursor.controlsocket" will be used
2865 for the recursor.
2866 LocalSocket Path
2868 Querying the recursor is done using UDP. When using UDP over UNIX
2869 domain sockets, the client socket needs a name in the file system,
2870 too. You can set this local name to Path using the LocalSocket
2871 option. The default is "prefix/var/run/collectd-powerdns".
2872 Plugin "processes"
2874 Process Name
2875 Select more detailed statistics of processes matching this name.
2876 The statistics collected for these selected processes are size of
2877 the resident segment size (RSS), user- and system-time used, number
2878 of processes and number of threads, io data (where available) and
2879 minor and major pagefaults.
2880 ProcessMatch name regex
2882 Similar to the Process option this allows to select more detailed
2883 statistics of processes matching the specified regex (see regex(7)
2884 for details). The statistics of all matching processes are summed
2885 up and dispatched to the daemon using the specified name as an
2886 identifier. This allows to "group" several processes together. name
2887 must not contain slashes.
2888 Plugin "protocols"
2890 Collects a lot of information about various network protocols, such as
2891 IP, TCP, UDP, etc.
2892 Available configuration options:
2894 Value Selector
2896 Selects whether or not to select a specific value. The string being
2897 matched is of the form "Protocol:ValueName", where Protocol will be
2898 used as the plugin instance and ValueName will be used as type
2899 instance. An example of the string being used would be
2900 "Tcp:RetransSegs".
2901 You can use regular expressions to match a large number of values
2903 with just one configuration option. To select all "extended" TCP
2904 values, you could use the following statement:
2905 Value "/^TcpExt:/"
2907 Whether only matched values are selected or all matched values are
2909 ignored depends on the IgnoreSelected. By default, only matched
2910 values are selected. If no value is configured at all, all values
2911 will be selected.
2912 IgnoreSelected true|false
2914 If set to true, inverts the selection made by Value, i. e. all
2915 matching values will be ignored.
2916 Plugin "python"
2918 This plugin embeds a Python-interpreter into collectd and provides an
2919 interface to collectd's plugin system. See collectd-python(5) for its
2920 documentation.
2921 Plugin "routeros"
2923 The "routeros" plugin connects to a device running RouterOS, the Linux-
2924 based operating system for routers by MikroTik. The plugin uses
2925 librouteros to connect and reads information about the interfaces and
2926 wireless connections of the device. The configuration supports querying
2927 multiple routers:
2928 <Plugin "routeros">
2930 <Router>
2931 Host "router0.example.com"
2932 User "collectd"
2933 Password "secr3t"
2934 CollectInterface true
2935 </Router>
2936 <Router>
2937 Host "router1.example.com"
2938 User "collectd"
2939 Password "5ecret"
2940 CollectInterface true
2941 CollectRegistrationTable true
2942 </Router>
2943 </Plugin>
2944 As you can see above, the configuration of the routeros plugin consists
2946 of one or more <Router> blocks. Within each block, the following
2947 options are understood:
2948 Host Host
2950 Hostname or IP-address of the router to connect to.
2951 Port Port
2953 Port name or port number used when connecting. If left unspecified,
2954 the default will be chosen by librouteros, currently "8728". This
2955 option expects a string argument, even when a numeric port number
2956 is given.
2957 User User
2959 Use the user name User to authenticate. Defaults to "admin".
2960 Password Password
2962 Set the password used to authenticate.
2963 CollectInterface true|false
2965 When set to true, interface statistics will be collected for all
2966 interfaces present on the device. Defaults to false.
2967 CollectRegistrationTable true|false
2969 When set to true, information about wireless LAN connections will
2970 be collected. Defaults to false.
2971 Plugin "rrdcached"
2973 The "rrdcached" plugin uses the RRDtool accelerator daemon,
2974 rrdcached(1), to store values to RRD files in an efficient manner. The
2975 combination of the "rrdcached" plugin and the "rrdcached" daemon is
2976 very similar to the way the "rrdtool" plugin works (see below). The
2977 added abstraction layer provides a number of benefits, though: Because
2978 the cache is not within "collectd" anymore, it does not need to be
2979 flushed when "collectd" is to be restarted. This results in much
2980 shorter (if any) gaps in graphs, especially under heavy load. Also, the
2981 "rrdtool" command line utility is aware of the daemon so that it can
2982 flush values to disk automatically when needed. This allows to
2983 integrate automated flushing of values into graphing solutions much
2984 more easily.
2985 There are disadvantages, though: The daemon may reside on a different
2987 host, so it may not be possible for "collectd" to create the
2988 appropriate RRD files anymore. And even if "rrdcached" runs on the same
2989 host, it may run in a different base directory, so relative paths may
2990 do weird stuff if you're not careful.
2991 So the recommended configuration is to let "collectd" and "rrdcached"
2993 run on the same host, communicating via a UNIX domain socket. The
2994 DataDir setting should be set to an absolute path, so that a changed
2995 base directory does not result in RRD files being created / expected in
2996 the wrong place.
2997 DaemonAddress Address
2999 Address of the daemon as understood by the "rrdc_connect" function
3000 of the RRD library. See rrdcached(1) for details. Example:
3001 <Plugin "rrdcached">
3003 DaemonAddress "unix:/var/run/rrdcached.sock"
3004 </Plugin>
3005 DataDir Directory
3007 Set the base directory in which the RRD files reside. If this is a
3008 relative path, it is relative to the working base directory of the
3009 "rrdcached" daemon! Use of an absolute path is recommended.
3010 CreateFiles true|false
3012 Enables or disables the creation of RRD files. If the daemon is not
3013 running locally, or DataDir is set to a relative path, this will
3014 not work as expected. Default is true.
3015 Plugin "rrdtool"
3017 You can use the settings StepSize, HeartBeat, RRARows, and XFF to fine-
3018 tune your RRD-files. Please read rrdcreate(1) if you encounter problems
3019 using these settings. If you don't want to dive into the depths of
3020 RRDtool, you can safely ignore these settings.
3021 DataDir Directory
3023 Set the directory to store RRD-files under. Per default RRD-files
3024 are generated beneath the daemon's working directory, i. e. the
3025 BaseDir.
3026 StepSize Seconds
3028 Force the stepsize of newly created RRD-files. Ideally (and per
3029 default) this setting is unset and the stepsize is set to the
3030 interval in which the data is collected. Do not use this option
3031 unless you absolutely have to for some reason. Setting this option
3032 may cause problems with the "snmp plugin", the "exec plugin" or
3033 when the daemon is set up to receive data from other hosts.
3034 HeartBeat Seconds
3036 Force the heartbeat of newly created RRD-files. This setting should
3037 be unset in which case the heartbeat is set to twice the StepSize
3038 which should equal the interval in which data is collected. Do not
3039 set this option unless you have a very good reason to do so.
3040 RRARows NumRows
3042 The "rrdtool plugin" calculates the number of PDPs per CDP based on
3043 the StepSize, this setting and a timespan. This plugin creates RRD-
3044 files with three times five RRAs, i. e. five RRAs with the CFs MIN,
3045 AVERAGE, and MAX. The five RRAs are optimized for graphs covering
3046 one hour, one day, one week, one month, and one year.
3047 So for each timespan, it calculates how many PDPs need to be
3049 consolidated into one CDP by calculating:
3050 number of PDPs = timespan / (stepsize * rrarows)
3051 Bottom line is, set this no smaller than the width of you graphs in
3053 pixels. The default is 1200.
3054 RRATimespan Seconds
3056 Adds an RRA-timespan, given in seconds. Use this option multiple
3057 times to have more then one RRA. If this option is never used, the
3058 built-in default of (3600, 86400, 604800, 2678400, 31622400) is
3059 used.
3060 For more information on how RRA-sizes are calculated see RRARows
3062 above.
3063 XFF Factor
3065 Set the "XFiles Factor". The default is 0.1. If unsure, don't set
3066 this option.
3067 CacheFlush Seconds
3069 When the "rrdtool" plugin uses a cache (by setting CacheTimeout,
3070 see below) it writes all values for a certain RRD-file if the
3071 oldest value is older than (or equal to) the number of seconds
3072 specified. If some RRD-file is not updated anymore for some reason
3073 (the computer was shut down, the network is broken, etc.) some
3074 values may still be in the cache. If CacheFlush is set, then the
3075 entire cache is searched for entries older than CacheTimeout
3076 seconds and written to disk every Seconds seconds. Since this is
3077 kind of expensive and does nothing under normal circumstances, this
3078 value should not be too small. 900 seconds might be a good value,
3079 though setting this to 7200 seconds doesn't normally do much harm
3080 either.
3081 CacheTimeout Seconds
3083 If this option is set to a value greater than zero, the "rrdtool
3084 plugin" will save values in a cache, as described above. Writing
3085 multiple values at once reduces IO-operations and thus lessens the
3086 load produced by updating the files. The trade off is that the
3087 graphs kind of "drag behind" and that more memory is used.
3088 WritesPerSecond Updates
3090 When collecting many statistics with collectd and the "rrdtool"
3091 plugin, you will run serious performance problems. The CacheFlush
3092 setting and the internal update queue assert that collectd
3093 continues to work just fine even under heavy load, but the system
3094 may become very unresponsive and slow. This is a problem especially
3095 if you create graphs from the RRD files on the same machine, for
3096 example using the "graph.cgi" script included in the
3097 "contrib/collection3/" directory.
3098 This setting is designed for very large setups. Setting this option
3100 to a value between 25 and 80 updates per second, depending on your
3101 hardware, will leave the server responsive enough to draw graphs
3102 even while all the cached values are written to disk. Flushed
3103 values, i. e. values that are forced to disk by the FLUSH command,
3104 are not effected by this limit. They are still written as fast as
3105 possible, so that web frontends have up to date data when
3106 generating graphs.
3107 For example: If you have 100,000 RRD files and set WritesPerSecond
3109 to 30 updates per second, writing all values to disk will take
3110 approximately 56 minutes. Together with the flushing ability that's
3111 integrated into "collection3" you'll end up with a responsive and
3112 fast system, up to date graphs and basically a "backup" of your
3113 values every hour.
3114 RandomTimeout Seconds
3116 When set, the actual timeout for each value is chosen randomly
3117 between CacheTimeout-RandomTimeout and CacheTimeout+RandomTimeout.
3118 The intention is to avoid high load situations that appear when
3119 many values timeout at the same time. This is especially a problem
3120 shortly after the daemon starts, because all values were added to
3121 the internal cache at roughly the same time.
3122 Plugin "sensors"
3124 The "sensors plugin" uses lm_sensors to retrieve sensor-values. This
3125 means that all the needed modules have to be loaded and lm_sensors has
3126 to be configured (most likely by editing /etc/sensors.conf. Read
3127 sensors.conf(5) for details.
3128 The lm_sensors homepage can be found at
3130 <http://secure.netroedge.com/~lm78/>.
3131 Sensor chip-bus-address/type-feature
3133 Selects the name of the sensor which you want to collect or ignore,
3134 depending on the IgnoreSelected below. For example, the option
3135 "Sensor it8712-isa-0290/voltage-in1" will cause collectd to gather
3136 data for the voltage sensor in1 of the it8712 on the isa bus at the
3137 address 0290.
3138 IgnoreSelected true|false
3140 If no configuration if given, the sensors-plugin will collect data
3141 from all sensors. This may not be practical, especially for
3142 uninteresting sensors. Thus, you can use the Sensor-option to pick
3143 the sensors you're interested in. Sometimes, however, it's
3144 easier/preferred to collect all sensors except a few ones. This
3145 option enables you to do that: By setting IgnoreSelected to true
3146 the effect of Sensor is inverted: All selected sensors are ignored
3147 and all other sensors are collected.
3148 Plugin "snmp"
3150 Since the configuration of the "snmp plugin" is a little more
3151 complicated than other plugins, its documentation has been moved to an
3152 own manpage, collectd-snmp(5). Please see there for details.
3153 Plugin "syslog"
3155 LogLevel debug|info|notice|warning|err
3156 Sets the log-level. If, for example, set to notice, then all events
3157 with severity notice, warning, or err will be submitted to the
3158 syslog-daemon.
3159 Please note that debug is only available if collectd has been
3161 compiled with debugging support.
3162 Plugin "table"
3164 The "table plugin" provides generic means to parse tabular data and
3165 dispatch user specified values. Values are selected based on column
3166 numbers. For example, this plugin may be used to get values from the
3167 Linux proc(5) filesystem or CSV (comma separated values) files.
3168 <Plugin table>
3170 <Table "/proc/slabinfo">
3171 Instance "slabinfo"
3172 Separator " "
3173 <Result>
3174 Type gauge
3175 InstancePrefix "active_objs"
3176 InstancesFrom 0
3177 ValuesFrom 1
3178 </Result>
3179 <Result>
3180 Type gauge
3181 InstancePrefix "objperslab"
3182 InstancesFrom 0
3183 ValuesFrom 4
3184 </Result>
3185 </Table>
3186 </Plugin>
3187 The configuration consists of one or more Table blocks, each of which
3189 configures one file to parse. Within each Table block, there are one or
3190 more Result blocks, which configure which data to select and how to
3191 interpret it.
3192 The following options are available inside a Table block:
3194 Instance instance
3196 If specified, instance is used as the plugin instance. So, in the
3197 above example, the plugin name "table-slabinfo" would be used. If
3198 omitted, the filename of the table is used instead, with all
3199 special characters replaced with an underscore ("_").
3200 Separator string
3202 Any character of string is interpreted as a delimiter between the
3203 different columns of the table. A sequence of two or more
3204 contiguous delimiters in the table is considered to be a single
3205 delimiter, i. e. there cannot be any empty columns. The plugin uses
3206 the strtok_r(3) function to parse the lines of a table - see its
3207 documentation for more details. This option is mandatory.
3208 A horizontal tab, newline and carriage return may be specified by
3210 "\\t", "\\n" and "\\r" respectively. Please note that the double
3211 backslashes are required because of collectd's config parsing.
3212 The following options are available inside a Result block:
3214 Type type
3216 Sets the type used to dispatch the values to the daemon. Detailed
3217 information about types and their configuration can be found in
3218 types.db(5). This option is mandatory.
3219 InstancePrefix prefix
3221 If specified, prepend prefix to the type instance. If omitted, only
3222 the InstancesFrom option is considered for the type instance.
3223 InstancesFrom column0 [column1 ...]
3225 If specified, the content of the given columns (identified by the
3226 column number starting at zero) will be used to create the type
3227 instance for each row. Multiple values (and the instance prefix)
3228 will be joined together with dashes (-) as separation character. If
3229 omitted, only the InstancePrefix option is considered for the type
3230 instance.
3231 The plugin itself does not check whether or not all built instances
3233 are different. ItaXXs your responsibility to assure that each is
3234 unique. This is especially true, if you do not specify
3235 InstancesFrom: You have to make sure that the table only contains
3236 one row.
3237 If neither InstancePrefix nor InstancesFrom is given, the type
3239 instance will be empty.
3240 ValuesFrom column0 [column1 ...]
3242 Specifies the columns (identified by the column numbers starting at
3243 zero) whose content is used as the actual data for the data sets
3244 that are dispatched to the daemon. How many such columns you need
3245 is determined by the Type setting above. If you specify too many or
3246 not enough columns, the plugin will complain about that and no data
3247 will be submitted to the daemon. The plugin uses strtoll(3) and
3248 strtod(3) to parse counter and gauge values respectively, so
3249 anything supported by those functions is supported by the plugin as
3250 well. This option is mandatory.
3251 Plugin "tail"
3253 The "tail plugin" follows logfiles, just like tail(1) does, parses each
3254 line and dispatches found values. What is matched can be configured by
3255 the user using (extended) regular expressions, as described in
3256 regex(7).
3257 <Plugin "tail">
3259 <File "/var/log/exim4/mainlog">
3260 Instance "exim"
3261 <Match>
3262 Regex "S=([1-9][0-9]*)"
3263 DSType "CounterAdd"
3264 Type "ipt_bytes"
3265 Instance "total"
3266 </Match>
3267 <Match>
3268 Regex "\\<R=local_user\\>"
3269 DSType "CounterInc"
3270 Type "counter"
3271 Instance "local_user"
3272 </Match>
3273 </File>
3274 </Plugin>
3275 The config consists of one or more File blocks, each of which
3277 configures one logfile to parse. Within each File block, there are one
3278 or more Match blocks, which configure a regular expression to search
3279 for.
3280 The Instance option in the File block may be used to set the plugin
3282 instance. So in the above example the plugin name "tail-foo" would be
3283 used. This plugin instance is for all Match blocks that follow it,
3284 until the next Instance option. This way you can extract several plugin
3285 instances from one logfile, handy when parsing syslog and the like.
3286 Each Match block has the following options to describe how the match
3288 should be performed:
3289 Regex regex
3291 Sets the regular expression to use for matching against a line. The
3292 first subexpression has to match something that can be turned into
3293 a number by strtoll(3) or strtod(3), depending on the value of
3294 "CounterAdd", see below. Because extended regular expressions are
3295 used, you do not need to use backslashes for subexpressions! If in
3296 doubt, please consult regex(7). Due to collectd's config parsing
3297 you need to escape backslashes, though. So if you want to match
3298 literal parentheses you need to do the following:
3299 Regex "SPAM \\(Score: (-?[0-9]+\\.[0-9]+)\\)"
3301 DSType Type
3303 Sets how the values are cumulated. Type is one of:
3304 GaugeAverage
3306 Calculate the average.
3307 GaugeMin
3309 Use the smallest number only.
3310 GaugeMax
3312 Use the greatest number only.
3313 GaugeLast
3315 Use the last number found.
3316 CounterSet
3318 DeriveSet
3319 AbsoluteSet
3320 The matched number is a counter. Simply sets the internal
3321 counter to this value. Variants exist for "COUNTER", "DERIVE",
3322 and "ABSOLUTE" data sources.
3323 CounterAdd
3325 DeriveAdd
3326 Add the matched value to the internal counter. In case of
3327 DeriveAdd, the matched number may be negative, which will
3328 effectively subtract from the internal counter.
3329 CounterInc
3331 DeriveInc
3332 Increase the internal counter by one. These DSType are the only
3333 ones that do not use the matched subexpression, but simply
3334 count the number of matched lines. Thus, you may use a regular
3335 expression without submatch in this case.
3336 As you'd expect the Gauge* types interpret the submatch as a
3338 floating point number, using strtod(3). The Counter* and
3339 AbsoluteSet types interpret the submatch as an unsigned integer
3340 using strtoull(3). The Derive* types interpret the submatch as a
3341 signed integer using strtoll(3). CounterInc and DeriveInc do not
3342 use the submatch at all and it may be omitted in this case.
3343 Type Type
3345 Sets the type used to dispatch this value. Detailed information
3346 about types and their configuration can be found in types.db(5).
3347 Instance TypeInstance
3349 This optional setting sets the type instance to use.
3350 Plugin "teamspeak2"
3352 The "teamspeak2 plugin" connects to the query port of a teamspeak2
3353 server and polls interesting global and virtual server data. The plugin
3354 can query only one physical server but unlimited virtual servers. You
3355 can use the following options to configure it:
3356 Host hostname/ip
3358 The hostname or ip which identifies the physical server. Default:
3359 127.0.0.1
3360 Port port
3362 The query port of the physical server. This needs to be a string.
3363 Default: "51234"
3364 Server port
3366 This option has to be added once for every virtual server the
3367 plugin should query. If you want to query the virtual server on
3368 port 8767 this is what the option would look like:
3369 Server "8767"
3371 This option, although numeric, needs to be a string, i. e. you must
3373 use quotes around it! If no such statement is given only global
3374 information will be collected.
3375 Plugin "ted"
3377 The TED plugin connects to a device of "The Energy Detective", a device
3378 to measure power consumption. These devices are usually connected to a
3379 serial (RS232) or USB port. The plugin opens a configured device and
3380 tries to read the current energy readings. For more information on TED,
3381 visit <http://www.theenergydetective.com/>.
3382 Available configuration options:
3384 Device Path
3386 Path to the device on which TED is connected. collectd will need
3387 read and write permissions on that file.
3388 Default: /dev/ttyUSB0
3390 Retries Num
3392 Apparently reading from TED is not that reliable. You can therefore
3393 configure a number of retries here. You only configure the retries
3394 here, to if you specify zero, one reading will be performed (but no
3395 retries if that fails); if you specify three, a maximum of four
3396 readings are performed. Negative values are illegal.
3397 Default: 0
3399 Plugin "tcpconns"
3401 The "tcpconns plugin" counts the number of currently established TCP
3402 connections based on the local port and/or the remote port. Since there
3403 may be a lot of connections the default if to count all connections
3404 with a local port, for which a listening socket is opened. You can use
3405 the following options to fine-tune the ports you are interested in:
3406 ListeningPorts true|false
3408 If this option is set to true, statistics for all local ports for
3409 which a listening socket exists are collected. The default depends
3410 on LocalPort and RemotePort (see below): If no port at all is
3411 specifically selected, the default is to collect listening ports.
3412 If specific ports (no matter if local or remote ports) are
3413 selected, this option defaults to false, i. e. only the selected
3414 ports will be collected unless this option is set to true
3415 specifically.
3416 LocalPort Port
3418 Count the connections to a specific local port. This can be used to
3419 see how many connections are handled by a specific daemon, e. g.
3420 the mailserver. You have to specify the port in numeric form, so
3421 for the mailserver example you'd need to set 25.
3422 RemotePort Port
3424 Count the connections to a specific remote port. This is useful to
3425 see how much a remote service is used. This is most useful if you
3426 want to know how many connections a local service has opened to
3427 remote services, e. g. how many connections a mail server or news
3428 server has to other mail or news servers, or how many connections a
3429 web proxy holds to web servers. You have to give the port in
3430 numeric form.
3431 Plugin "thermal"
3433 ForceUseProcfs true|false
3434 By default, the "thermal" plugin tries to read the statistics from
3435 the Linux "sysfs" interface. If that is not available, the plugin
3436 falls back to the "procfs" interface. By setting this option to
3437 true, you can force the plugin to use the latter. This option
3438 defaults to false.
3439 Device Device
3441 Selects the name of the thermal device that you want to collect or
3442 ignore, depending on the value of the IgnoreSelected option. This
3443 option may be used multiple times to specify a list of devices.
3444 IgnoreSelected true|false
3446 Invert the selection: If set to true, all devices except the ones
3447 that match the device names specified by the Device option are
3448 collected. By default only selected devices are collected if a
3449 selection is made. If no selection is configured at all, all
3450 devices are selected.
3451 Plugin "tokyotyrant"
3453 The "tokyotyrant plugin" connects to a TokyoTyrant server and collects
3454 a couple metrics: number of records, and database size on disk.
3455 Host Hostname/IP
3457 The hostname or ip which identifies the server. Default: 127.0.0.1
3458 Port Service/Port
3460 The query port of the server. This needs to be a string, even if
3461 the port is given in its numeric form. Default: 1978
3462 Plugin "unixsock"
3464 SocketFile Path
3465 Sets the socket-file which is to be created.
3466 SocketGroup Group
3468 If running as root change the group of the UNIX-socket after it has
3469 been created. Defaults to collectd.
3470 SocketPerms Permissions
3472 Change the file permissions of the UNIX-socket after it has been
3473 created. The permissions must be given as a numeric, octal value as
3474 you would pass to chmod(1). Defaults to 0770.
3475 Plugin "uuid"
3477 This plugin, if loaded, causes the Hostname to be taken from the
3478 machine's UUID. The UUID is a universally unique designation for the
3479 machine, usually taken from the machine's BIOS. This is most useful if
3480 the machine is running in a virtual environment such as Xen, in which
3481 case the UUID is preserved across shutdowns and migration.
3482 The following methods are used to find the machine's UUID, in order:
3484 · Check /etc/uuid (or UUIDFile).
3486 · Check for UUID from HAL
3488 (<http://www.freedesktop.org/wiki/Software/hal>) if present.
3489 · Check for UUID from "dmidecode" / SMBIOS.
3491 · Check for UUID from Xen hypervisor.
3493 If no UUID can be found then the hostname is not modified.
3495 UUIDFile Path
3497 Take the UUID from the given file (default /etc/uuid).
3498 Plugin "vmem"
3500 The "vmem" plugin collects information about the usage of virtual
3501 memory. Since the statistics provided by the Linux kernel are very
3502 detailed, they are collected very detailed. However, to get all the
3503 details, you have to switch them on manually. Most people just want an
3504 overview over, such as the number of pages read from swap space.
3505 Verbose true|false
3507 Enables verbose collection of information. This will start
3508 collecting page "actions", e. g. page allocations, (de)activations,
3509 steals and so on. Part of these statistics are collected on a "per
3510 zone" basis.
3511 Plugin "vserver"
3513 This plugin doesn't have any options. VServer support is only available
3514 for Linux. It cannot yet be found in a vanilla kernel, though. To make
3515 use of this plugin you need a kernel that has VServer support built in,
3516 i. e. you need to apply the patches and compile your own kernel, which
3517 will then provide the /proc/virtual filesystem that is required by this
3518 plugin.
3519 The VServer homepage can be found at <http://linux-vserver.org/>.
3521 Note: The traffic collected by this plugin accounts for the amount of
3523 traffic passing a socket which might be a lot less than the actual on-
3524 wire traffic (e. g. due to headers and retransmission). If you want to
3525 collect on-wire traffic you could, for example, use the logging
3526 facilities of iptables to feed data for the guest IPs into the iptables
3527 plugin.
3528 Plugin "write_http"
3530 This output plugin submits values to an http server by POST them using
3531 the PUTVAL plain-text protocol. Each destination you want to post data
3532 to needs to have one URL block, within which the destination can be
3533 configured further, for example by specifying authentication data.
3534 Synopsis:
3536 <Plugin "write_http">
3538 <URL "http://example.com/post-collectd">
3539 User "collectd"
3540 Password "weCh3ik0"
3541 </URL>
3542 </Plugin>
3543 URL blocks need one string argument which is used as the URL to which
3545 data is posted. The following options are understood within URL blocks.
3546 User Username
3548 Optional user name needed for authentication.
3549 Password Password
3551 Optional password needed for authentication.
3552 VerifyPeer true|false
3554 Enable or disable peer SSL certificate verification. See
3555 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
3556 default.
3557 VerifyHost true|false
3559 Enable or disable peer host name verification. If enabled, the
3560 plugin checks if the "Common Name" or a "Subject Alternate Name"
3561 field of the SSL certificate matches the host name provided by the
3562 URL option. If this identity check fails, the connection is
3563 aborted. Obviously, only works when connecting to a SSL enabled
3564 server. Enabled by default.
3565 CACert File
3567 File that holds one or more SSL certificates. If you want to use
3568 HTTPS you will possibly need this option. What CA certificates come
3569 bundled with "libcurl" and are checked by default depends on the
3570 distribution you use.
3571 Format Command|JSON
3573 Format of the output to generate. If set to Command, will create
3574 output that is understood by the Exec and UnixSock plugins. When
3575 set to JSON, will create output in the JavaScript Object Notation
3576 (JSON).
3577 Defaults to Command.
3579
3581 Starting with version 4.3.0 collectd has support for monitoring. By
3582 that we mean that the values are not only stored or sent somewhere, but
3583 that they are judged and, if a problem is recognized, acted upon. The
3584 only action collectd takes itself is to generate and dispatch a
3585 "notification". Plugins can register to receive notifications and
3586 perform appropriate further actions.
3587 Since systems and what you expect them to do differ a lot, you can
3589 configure thresholds for your values freely. This gives you a lot of
3590 flexibility but also a lot of responsibility.
3591 Every time a value is out of range a notification is dispatched. This
3593 means that the idle percentage of your CPU needs to be less then the
3594 configured threshold only once for a notification to be generated.
3595 There's no such thing as a moving average or similar - at least not
3596 now.
3597 Also, all values that match a threshold are considered to be relevant
3599 or "interesting". As a consequence collectd will issue a notification
3600 if they are not received for twice the last timeout of the values. If,
3601 for example, some hosts sends it's CPU statistics to the server every
3602 60 seconds, a notification will be dispatched after about 120 seconds.
3603 It may take a little longer because the timeout is checked only once
3604 each Interval on the server.
3605 When a value comes within range again or is received after it was
3607 missing, an "OKAY-notification" is dispatched.
3608 Here is a configuration example to get you started. Read below for more
3610 information.
3611 <Threshold>
3613 <Type "foo">
3614 WarningMin 0.00
3615 WarningMax 1000.00
3616 FailureMin 0.00
3617 FailureMax 1200.00
3618 Invert false
3619 Instance "bar"
3620 </Type>
3621 <Plugin "interface">
3623 Instance "eth0"
3624 <Type "if_octets">
3625 FailureMax 10000000
3626 DataSource "rx"
3627 </Type>
3628 </Plugin>
3629 <Host "hostname">
3631 <Type "cpu">
3632 Instance "idle"
3633 FailureMin 10
3634 </Type>
3635 <Plugin "memory">
3637 <Type "memory">
3638 Instance "cached"
3639 WarningMin 100000000
3640 </Type>
3641 </Plugin>
3642 </Host>
3643 </Threshold>
3644 There are basically two types of configuration statements: The "Host",
3646 "Plugin", and "Type" blocks select the value for which a threshold
3647 should be configured. The "Plugin" and "Type" blocks may be specified
3648 further using the "Instance" option. You can combine the block by
3649 nesting the blocks, though they must be nested in the above order,
3650 i. e. "Host" may contain either "Plugin" and "Type" blocks, "Plugin"
3651 may only contain "Type" blocks and "Type" may not contain other blocks.
3652 If multiple blocks apply to the same value the most specific block is
3653 used.
3654 The other statements specify the threshold to configure. They must be
3656 included in a "Type" block. Currently the following statements are
3657 recognized:
3658 FailureMax Value
3660 WarningMax Value
3661 Sets the upper bound of acceptable values. If unset defaults to
3662 positive infinity. If a value is greater than FailureMax a FAILURE
3663 notification will be created. If the value is greater than
3664 WarningMax but less than (or equal to) FailureMax a WARNING
3665 notification will be created.
3666 FailureMin Value
3668 WarningMin Value
3669 Sets the lower bound of acceptable values. If unset defaults to
3670 negative infinity. If a value is less than FailureMin a FAILURE
3671 notification will be created. If the value is less than WarningMin
3672 but greater than (or equal to) FailureMin a WARNING notification
3673 will be created.
3674 DataSource DSName
3676 Some data sets have more than one "data source". Interesting
3677 examples are the "if_octets" data set, which has received ("rx")
3678 and sent ("tx") bytes and the "disk_ops" data set, which holds
3679 "read" and "write" operations. The system load data set, "load",
3680 even has three data sources: "shortterm", "midterm", and
3681 "longterm".
3682 Normally, all data sources are checked against a configured
3684 threshold. If this is undesirable, or if you want to specify
3685 different limits for each data source, you can use the DataSource
3686 option to have a threshold apply only to one data source.
3687 Invert true|false
3689 If set to true the range of acceptable values is inverted, i. e.
3690 values between FailureMin and FailureMax (WarningMin and
3691 WarningMax) are not okay. Defaults to false.
3692 Persist true|false
3694 Sets how often notifications are generated. If set to true one
3695 notification will be generated for each value that is out of the
3696 acceptable range. If set to false (the default) then a notification
3697 is only generated if a value is out of range but the previous value
3698 was okay.
3699 This applies to missing values, too: If set to true a notification
3701 about a missing value is generated once every Interval seconds. If
3702 set to false only one such notification is generated until the
3703 value appears again.
3704 Percentage true|false
3706 If set to true, the minimum and maximum values given are
3707 interpreted as percentage value, relative to the other data
3708 sources. This is helpful for example for the "df" type, where you
3709 may want to issue a warning when less than 5 % of the total space
3710 is available. Defaults to false.
3711
3713 Starting with collectd 4.6 there is a powerful filtering infrastructure
3714 implemented in the daemon. The concept has mostly been copied from
3715 ip_tables, the packet filter infrastructure for Linux. We'll use a
3716 similar terminology, so that users that are familiar with iptables feel
3717 right at home.
3718 Terminology
3720 The following are the terms used in the remainder of the filter
3721 configuration documentation. For an ASCII-art schema of the mechanism,
3722 see "General structure" below.
3723 Match
3725 A match is a criteria to select specific values. Examples are, of
3726 course, the name of the value or it's current value.
3727 Matches are implemented in plugins which you have to load prior to
3729 using the match. The name of such plugins starts with the "match_"
3730 prefix.
3731 Target
3733 A target is some action that is to be performed with data. Such
3734 actions could, for example, be to change part of the value's
3735 identifier or to ignore the value completely.
3736 Some of these targets are built into the daemon, see "Built-in
3738 targets" below. Other targets are implemented in plugins which you
3739 have to load prior to using the target. The name of such plugins
3740 starts with the "target_" prefix.
3741 Rule
3743 The combination of any number of matches and at least one target is
3744 called a rule. The target actions will be performed for all values
3745 for which all matches apply. If the rule does not have any matches
3746 associated with it, the target action will be performed for all
3747 values.
3748 Chain
3750 A chain is a list of rules and possibly default targets. The rules
3751 are tried in order and if one matches, the associated target will
3752 be called. If a value is handled by a rule, it depends on the
3753 target whether or not any subsequent rules are considered or if
3754 traversal of the chain is aborted, see "Flow control" below. After
3755 all rules have been checked, the default targets will be executed.
3756 General structure
3758 The following shows the resulting structure:
3759 +---------+
3761 ! Chain !
3762 +---------+
3763 !
3764 V
3765 +---------+ +---------+ +---------+ +---------+
3766 ! Rule !->! Match !->! Match !->! Target !
3767 +---------+ +---------+ +---------+ +---------+
3768 !
3769 V
3770 +---------+ +---------+ +---------+
3771 ! Rule !->! Target !->! Target !
3772 +---------+ +---------+ +---------+
3773 !
3774 V
3775 :
3776 :
3777 !
3778 V
3779 +---------+ +---------+ +---------+
3780 ! Rule !->! Match !->! Target !
3781 +---------+ +---------+ +---------+
3782 !
3783 V
3784 +---------+
3785 ! Default !
3786 ! Target !
3787 +---------+
3788 Flow control
3790 There are four ways to control which way a value takes through the
3791 filter mechanism:
3792 jump
3794 The built-in jump target can be used to "call" another chain, i. e.
3795 process the value with another chain. When the called chain
3796 finishes, usually the next target or rule after the jump is
3797 executed.
3798 stop
3800 The stop condition, signaled for example by the built-in target
3801 stop, causes all processing of the value to be stopped immediately.
3802 return
3804 Causes processing in the current chain to be aborted, but
3805 processing of the value generally will continue. This means that if
3806 the chain was called via Jump, the next target or rule after the
3807 jump will be executed. If the chain was not called by another
3808 chain, control will be returned to the daemon and it may pass the
3809 value to another chain.
3810 continue
3812 Most targets will signal the continue condition, meaning that
3813 processing should continue normally. There is no special built-in
3814 target for this condition.
3815 Synopsis
3817 The configuration reflects this structure directly:
3818 PostCacheChain "PostCache"
3820 <Chain "PostCache">
3821 <Rule "ignore_mysql_show">
3822 <Match "regex">
3823 Plugin "^mysql$"
3824 Type "^mysql_command$"
3825 TypeInstance "^show_"
3826 </Match>
3827 <Target "stop">
3828 </Target>
3829 </Rule>
3830 <Target "write">
3831 Plugin "rrdtool"
3832 </Target>
3833 </Chain>
3834 The above configuration example will ignore all values where the plugin
3836 field is "mysql", the type is "mysql_command" and the type instance
3837 begins with "show_". All other values will be sent to the "rrdtool"
3838 write plugin via the default target of the chain. Since this chain is
3839 run after the value has been added to the cache, the MySQL "show_*"
3840 command statistics will be available via the "unixsock" plugin.
3841 List of configuration options
3843 PreCacheChain ChainName
3844 PostCacheChain ChainName
3845 Configure the name of the "pre-cache chain" and the "post-cache
3846 chain". The argument is the name of a chain that should be executed
3847 before and/or after the values have been added to the cache.
3848 To understand the implications, it's important you know what is
3850 going on inside collectd. The following diagram shows how values
3851 are passed from the read-plugins to the write-plugins:
3852 +---------------+
3854 ! Read-Plugin !
3855 +-------+-------+
3856 !
3857 + - - - - V - - - - +
3858 : +---------------+ :
3859 : ! Pre-Cache ! :
3860 : ! Chain ! :
3861 : +-------+-------+ :
3862 : ! :
3863 : V :
3864 : +-------+-------+ : +---------------+
3865 : ! Cache !--->! Value Cache !
3866 : ! insert ! : +---+---+-------+
3867 : +-------+-------+ : ! !
3868 : ! ,------------' !
3869 : V V : V
3870 : +-------+---+---+ : +-------+-------+
3871 : ! Post-Cache +--->! Write-Plugins !
3872 : ! Chain ! : +---------------+
3873 : +---------------+ :
3874 : :
3875 : dispatch values :
3876 + - - - - - - - - - +
3877 After the values are passed from the "read" plugins to the dispatch
3879 functions, the pre-cache chain is run first. The values are added
3880 to the internal cache afterwards. The post-cache chain is run after
3881 the values have been added to the cache. So why is it such a huge
3882 deal if chains are run before or after the values have been added
3883 to this cache?
3884 Targets that change the identifier of a value list should be
3886 executed before the values are added to the cache, so that the name
3887 in the cache matches the name that is used in the "write" plugins.
3888 The "unixsock" plugin, too, uses this cache to receive a list of
3889 all available values. If you change the identifier after the value
3890 list has been added to the cache, this may easily lead to
3891 confusion, but it's not forbidden of course.
3892 The cache is also used to convert counter values to rates. These
3894 rates are, for example, used by the "value" match (see below). If
3895 you use the rate stored in the cache before the new value is added,
3896 you will use the old, previous rate. Write plugins may use this
3897 rate, too, see the "csv" plugin, for example. The "unixsock"
3898 plugin uses these rates too, to implement the "GETVAL" command.
3899 Last but not last, the stop target makes a difference: If the pre-
3901 cache chain returns the stop condition, the value will not be added
3902 to the cache and the post-cache chain will not be run.
3903 Chain Name
3905 Adds a new chain with a certain name. This name can be used to
3906 refer to a specific chain, for example to jump to it.
3907 Within the Chain block, there can be Rule blocks and Target blocks.
3909 Rule [Name]
3911 Adds a new rule to the current chain. The name of the rule is
3912 optional and currently has no meaning for the daemon.
3913 Within the Rule block, there may be any number of Match blocks and
3915 there must be at least one Target block.
3916 Match Name
3918 Adds a match to a Rule block. The name specifies what kind of match
3919 should be performed. Available matches depend on the plugins that
3920 have been loaded.
3921 The arguments inside the Match block are passed to the plugin
3923 implementing the match, so which arguments are valid here depends
3924 on the plugin being used. If you do not need any to pass any
3925 arguments to a match, you can use the shorter syntax:
3926 Match "foobar"
3928 Which is equivalent to:
3930 <Match "foobar">
3932 </Match>
3933 Target Name
3935 Add a target to a rule or a default target to a chain. The name
3936 specifies what kind of target is to be added. Which targets are
3937 available depends on the plugins being loaded.
3938 The arguments inside the Target block are passed to the plugin
3940 implementing the target, so which arguments are valid here depends
3941 on the plugin being used. If you do not need any to pass any
3942 arguments to a target, you can use the shorter syntax:
3943 Target "stop"
3945 This is the same as writing:
3947 <Target "stop">
3949 </Target>
3950 Built-in targets
3952 The following targets are built into the core daemon and therefore need
3953 no plugins to be loaded:
3954 return
3956 Signals the "return" condition, see the "Flow control" section
3957 above. This causes the current chain to stop processing the value
3958 and returns control to the calling chain. The calling chain will
3959 continue processing targets and rules just after the jump target
3960 (see below). This is very similar to the RETURN target of iptables,
3961 see iptables(8).
3962 This target does not have any options.
3964 Example:
3966 Target "return"
3968 stop
3970 Signals the "stop" condition, see the "Flow control" section above.
3971 This causes processing of the value to be aborted immediately. This
3972 is similar to the DROP target of iptables, see iptables(8).
3973 This target does not have any options.
3975 Example:
3977 Target "stop"
3979 write
3981 Sends the value to "write" plugins.
3982 Available options:
3984 Plugin Name
3986 Name of the write plugin to which the data should be sent. This
3987 option may be given multiple times to send the data to more
3988 than one write plugin.
3989 If no plugin is explicitly specified, the values will be sent to
3991 all available write plugins.
3992 Example:
3994 <Target "write">
3996 Plugin "rrdtool"
3997 </Target>
3998 jump
4000 Starts processing the rules of another chain, see "Flow control"
4001 above. If the end of that chain is reached, or a stop condition is
4002 encountered, processing will continue right after the jump target,
4003 i. e. with the next target or the next rule. This is similar to the
4004 -j command line option of iptables, see iptables(8).
4005 Available options:
4007 Chain Name
4009 Jumps to the chain Name. This argument is required and may
4010 appear only once.
4011 Example:
4013 <Target "jump">
4015 Chain "foobar"
4016 </Target>
4017 Available matches
4019 regex
4020 Matches a value using regular expressions.
4021 Available options:
4023 Host Regex
4025 Plugin Regex
4026 PluginInstance Regex
4027 Type Regex
4028 TypeInstance Regex
4029 Match values where the given regular expressions match the
4030 various fields of the identifier of a value. If multiple
4031 regular expressions are given, all regexen must match for a
4032 value to match.
4033 Example:
4035 <Match "regex">
4037 Host "customer[0-9]+"
4038 Plugin "^foobar$"
4039 </Match>
4040 timediff
4042 Matches values that have a time which differs from the time on the
4043 server.
4044 This match is mainly intended for servers that receive values over
4046 the "network" plugin and write them to disk using the "rrdtool"
4047 plugin. RRDtool is very sensitive to the timestamp used when
4048 updating the RRD files. In particular, the time must be ever
4049 increasing. If a misbehaving client sends one packet with a
4050 timestamp far in the future, all further packets with a correct
4051 time will be ignored because of that one packet. What's worse, such
4052 corrupted RRD files are hard to fix.
4053 This match lets one match all values outside a specified time range
4055 (relative to the server's time), so you can use the stop target
4056 (see below) to ignore the value, for example.
4057 Available options:
4059 Future Seconds
4061 Matches all values that are ahead of the server's time by
4062 Seconds or more seconds. Set to zero for no limit. Either
4063 Future or Past must be non-zero.
4064 Past Seconds
4066 Matches all values that are behind of the server's time by
4067 Seconds or more seconds. Set to zero for no limit. Either
4068 Future or Past must be non-zero.
4069 Example:
4071 <Match "timediff">
4073 Future 300
4074 Past 3600
4075 </Match>
4076 This example matches all values that are five minutes or more ahead
4078 of the server or one hour (or more) lagging behind.
4079 value
4081 Matches the actual value of data sources against given minimum /
4082 maximum values. If a data-set consists of more than one data-
4083 source, all data-sources must match the specified ranges for a
4084 positive match.
4085 Available options:
4087 Min Value
4089 Sets the smallest value which still results in a match. If
4090 unset, behaves like negative infinity.
4091 Max Value
4093 Sets the largest value which still results in a match. If
4094 unset, behaves like positive infinity.
4095 Invert true|false
4097 Inverts the selection. If the Min and Max settings result in a
4098 match, no-match is returned and vice versa. Please note that
4099 the Invert setting only effects how Min and Max are applied to
4100 a specific value. Especially the DataSource and Satisfy
4101 settings (see below) are not inverted.
4102 DataSource DSName [DSName ...]
4104 Select one or more of the data sources. If no data source is
4105 configured, all data sources will be checked. If the type
4106 handled by the match does not have a data source of the
4107 specified name(s), this will always result in no match
4108 (independent of the Invert setting).
4109 Satisfy Any|All
4111 Specifies how checking with several data sources is performed.
4112 If set to Any, the match succeeds if one of the data sources is
4113 in the configured range. If set to All the match only succeeds
4114 if all data sources are within the configured range. Default is
4115 All.
4116 Usually All is used for positive matches, Any is used for
4118 negative matches. This means that with All you usually check
4119 that all values are in a "good" range, while with Any you check
4120 if any value is within a "bad" range (or outside the "good"
4121 range).
4122 Either Min or Max, but not both, may be unset.
4124 Example:
4126 # Match all values smaller than or equal to 100. Matches only if all data
4128 # sources are below 100.
4129 <Match "value">
4130 Max 100
4131 Satisfy "All"
4132 </Match>
4133 # Match if the value of any data source is outside the range of 0 - 100.
4135 <Match "value">
4136 Min 0
4137 Max 100
4138 Invert true
4139 Satisfy "Any"
4140 </Match>
4141 empty_counter
4143 Matches all values with one or more data sources of type COUNTER
4144 and where all counter values are zero. These counters usually never
4145 increased since they started existing (and are therefore
4146 uninteresting), or got reset recently or overflowed and you had
4147 really, really bad luck.
4148 Please keep in mind that ignoring such counters can result in
4150 confusing behavior: Counters which hardly ever increase will be
4151 zero for long periods of time. If the counter is reset for some
4152 reason (machine or service restarted, usually), the graph will be
4153 empty (NAN) for a long time. People may not understand why.
4154 hashed
4156 Calculates a hash value of the host name and matches values
4157 according to that hash value. This makes it possible to divide all
4158 hosts into groups and match only values that are in a specific
4159 group. The intended use is in load balancing, where you want to
4160 handle only part of all data and leave the rest for other servers.
4161 The hashing function used tries to distribute the hosts evenly.
4163 First, it calculates a 32 bit hash value using the characters of
4164 the hostname:
4165 hash_value = 0;
4167 for (i = 0; host[i] != 0; i++)
4168 hash_value = (hash_value * 251) + host[i];
4169 The constant 251 is a prime number which is supposed to make this
4171 hash value more random. The code then checks the group for this
4172 host according to the Total and Match arguments:
4173 if ((hash_value % Total) == Match)
4175 matches;
4176 else
4177 does not match;
4178 Please note that when you set Total to two (i. e. you have only two
4180 groups), then the least significant bit of the hash value will be
4181 the XOR of all least significant bits in the host name. One
4182 consequence is that when you have two hosts, "server0.example.com"
4183 and "server1.example.com", where the host name differs in one digit
4184 only and the digits differ by one, those hosts will never end up in
4185 the same group.
4186 Available options:
4188 Match Match Total
4190 Divide the data into Total groups and match all hosts in group
4191 Match as described above. The groups are numbered from zero,
4192 i. e. Match must be smaller than Total. Total must be at least
4193 one, although only values greater than one really do make any
4194 sense.
4195 You can repeat this option to match multiple groups, for
4197 example:
4198 Match 3 7
4200 Match 5 7
4201 The above config will divide the data into seven groups and
4203 match groups three and five. One use would be to keep every
4204 value on two hosts so that if one fails the missing data can
4205 later be reconstructed from the second host.
4206 Example:
4208 # Operate on the pre-cache chain, so that ignored values are not even in the
4210 # global cache.
4211 <Chain "PreCache">
4212 <Rule>
4213 <Match "hashed">
4214 # Divide all received hosts in seven groups and accept all hosts in
4215 # group three.
4216 Match 3 7
4217 </Match>
4218 # If matched: Return and continue.
4219 Target "return"
4220 </Rule>
4221 # If not matched: Return and stop.
4222 Target "stop"
4223 </Chain>
4224 Available targets
4226 notification
4227 Creates and dispatches a notification.
4228 Available options:
4230 Message String
4232 This required option sets the message of the notification. The
4233 following placeholders will be replaced by an appropriate
4234 value:
4235 %{host}
4237 %{plugin}
4238 %{plugin_instance}
4239 %{type}
4240 %{type_instance}
4241 These placeholders are replaced by the identifier field of
4242 the same name.
4243 %{ds:name}
4245 These placeholders are replaced by a (hopefully) human
4246 readable representation of the current rate of this data
4247 source. If you changed the instance name (using the set or
4248 replace targets, see below), it may not be possible to
4249 convert counter values to rates.
4250 Please note that these placeholders are case sensitive!
4252 Severity "FATAL"|"WARNING"|"OKAY"
4254 Sets the severity of the message. If omitted, the severity
4255 "WARNING" is used.
4256 Example:
4258 <Target "notification">
4260 Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
4261 Severity "WARNING"
4262 </Target>
4263 replace
4265 Replaces parts of the identifier using regular expressions.
4266 Available options:
4268 Host Regex Replacement
4270 Plugin Regex Replacement
4271 PluginInstance Regex Replacement
4272 TypeInstance Regex Replacement
4273 Match the appropriate field with the given regular expression
4274 Regex. If the regular expression matches, that part that
4275 matches is replaced with Replacement. If multiple places of the
4276 input buffer match a given regular expression, only the first
4277 occurrence will be replaced.
4278 You can specify each option multiple times to use multiple
4280 regular expressions one after another.
4281 Example:
4283 <Target "replace">
4285 # Replace "example.net" with "example.com"
4286 Host "\\<example.net\\>" "example.com"
4287 # Strip "www." from hostnames
4289 Host "\\<www\\." ""
4290 </Target>
4291 set Sets part of the identifier of a value to a given string.
4293 Available options:
4295 Host String
4297 Plugin String
4298 PluginInstance String
4299 TypeInstance String
4300 Set the appropriate field to the given string. The strings for
4301 plugin instance and type instance may be empty, the strings for
4302 host and plugin may not be empty. It's currently not possible
4303 to set the type of a value this way.
4304 Example:
4306 <Target "set">
4308 PluginInstance "coretemp"
4309 TypeInstance "core3"
4310 </Target>
4311 Backwards compatibility
4313 If you use collectd with an old configuration, i. e. one without a
4314 Chain block, it will behave as it used to. This is equivalent to the
4315 following configuration:
4316 <Chain "PostCache">
4318 Target "write"
4319 </Chain>
4320 If you specify a PostCacheChain, the write target will not be added
4322 anywhere and you will have to make sure that it is called where
4323 appropriate. We suggest to add the above snippet as default target to
4324 your "PostCache" chain.
4325 Examples
4327 Ignore all values, where the hostname does not contain a dot, i. e.
4328 can't be an FQDN.
4329 <Chain "PreCache">
4331 <Rule "no_fqdn">
4332 <Match "regex">
4333 Host "^[^\.]*$"
4334 </Match>
4335 Target "stop"
4336 </Rule>
4337 Target "write"
4338 </Chain>
4339
4341 collectd(1), collectd-exec(5), collectd-perl(5), collectd-unixsock(5),
4342 types.db(5), hddtemp(8), iptables(8), kstat(3KSTAT), mbmon(1), psql(1),
4343 regex(7), rrdtool(1), sensors(1)
4344
4346 Florian Forster <octo@verplant.org>
43474.9.5 2011-03-26 COLLECTD.CONF(5)