5 collectd.conf - Configuration for the system statistics collection daemon B<collectd>
9 BaseDir "/var/lib/collectd"
10 PIDFile "/run/collectd.pid"
31 This config file controls how the system statistics collection daemon
32 B<collectd> behaves. The most significant option is B<LoadPlugin>, which
33 controls which plugins to load. These plugins ultimately define collectd's
34 behavior. If the B<AutoLoadPlugin> option has been enabled, the explicit
35 B<LoadPlugin> lines may be omitted for all plugins with a configuration block,
36 i.e. a C<E<lt>PluginE<nbsp>...E<gt>> block.
38 The syntax of this config file is similar to the config file of the famous
39 I<Apache> webserver. Each line contains either an option (a key and a list of
40 one or more values) or a section-start or -end. Empty lines and everything
41 after a non-quoted hash-symbol (C<#>) is ignored. I<Keys> are unquoted
42 strings, consisting only of alphanumeric characters and the underscore (C<_>)
43 character. Keys are handled case insensitive by I<collectd> itself and all
44 plugins included with it. I<Values> can either be an I<unquoted string>, a
45 I<quoted string> (enclosed in double-quotes) a I<number> or a I<boolean>
46 expression. I<Unquoted strings> consist of only alphanumeric characters and
47 underscores (C<_>) and do not need to be quoted. I<Quoted strings> are
48 enclosed in double quotes (C<">). You can use the backslash character (C<\>)
49 to include double quotes as part of the string. I<Numbers> can be specified in
50 decimal and floating point format (using a dot C<.> as decimal separator),
51 hexadecimal when using the C<0x> prefix and octal with a leading zero (C<0>).
52 I<Boolean> values are either B<true> or B<false>.
54 Lines may be wrapped by using C<\> as the last character before the newline.
55 This allows long lines to be split into multiple lines. Quoted strings may be
56 wrapped as well. However, those are treated special in that whitespace at the
57 beginning of the following lines will be ignored, which allows for nicely
58 indenting the wrapped lines.
60 The configuration is read and processed in order, i.e. from top to bottom. So
61 the plugins are loaded in the order listed in this config file. It is a good
62 idea to load any logging plugins first in order to catch messages from plugins
63 during configuration. Also, unless B<AutoLoadPlugin> is enabled, the
64 B<LoadPlugin> option I<must> occur I<before> the appropriate
65 C<E<lt>B<Plugin> ...E<gt>> block.
71 =item B<BaseDir> I<Directory>
73 Sets the base directory. This is the directory beneath all RRD-files are
74 created. Possibly more subdirectories are created. This is also the working
75 directory for the daemon.
77 =item B<LoadPlugin> I<Plugin>
79 Loads the plugin I<Plugin>. This is required to load plugins, unless the
80 B<AutoLoadPlugin> option is enabled (see below). Without any loaded plugins,
81 I<collectd> will be mostly useless.
83 Only the first B<LoadPlugin> statement or block for a given plugin name has any
84 effect. This is useful when you want to split up the configuration into smaller
85 files and want each file to be "self contained", i.e. it contains a B<Plugin>
86 block I<and> then appropriate B<LoadPlugin> statement. The downside is that if
87 you have multiple conflicting B<LoadPlugin> blocks, e.g. when they specify
88 different intervals, only one of them (the first one encountered) will take
89 effect and all others will be silently ignored.
91 B<LoadPlugin> may either be a simple configuration I<statement> or a I<block>
92 with additional options, affecting the behavior of B<LoadPlugin>. A simple
93 statement looks like this:
97 Options inside a B<LoadPlugin> block can override default settings and
98 influence the way plugins are loaded, e.g.:
105 The following options are valid inside B<LoadPlugin> blocks:
109 =item B<Globals> B<true|false>
111 If enabled, collectd will export all global symbols of the plugin (and of all
112 libraries loaded as dependencies of the plugin) and, thus, makes those symbols
113 available for resolving unresolved symbols in subsequently loaded plugins if
114 that is supported by your system.
116 This is useful (or possibly even required), e.g., when loading a plugin that
117 embeds some scripting language into the daemon (e.g. the I<Perl> and
118 I<Python plugins>). Scripting languages usually provide means to load
119 extensions written in C. Those extensions require symbols provided by the
120 interpreter, which is loaded as a dependency of the respective collectd plugin.
121 See the documentation of those plugins (e.g., L<collectd-perl(5)> or
122 L<collectd-python(5)>) for details.
124 By default, this is disabled. As a special exception, if the plugin name is
125 either C<perl> or C<python>, the default is changed to enabled in order to keep
126 the average user from ever having to deal with this low level linking stuff.
128 =item B<Interval> I<Seconds>
130 Sets a plugin-specific interval for collecting metrics. This overrides the
131 global B<Interval> setting. If a plugin provides own support for specifying an
132 interval, that setting will take precedence.
136 =item B<AutoLoadPlugin> B<false>|B<true>
138 When set to B<false> (the default), each plugin needs to be loaded explicitly,
139 using the B<LoadPlugin> statement documented above. If a
140 B<E<lt>PluginE<nbsp>...E<gt>> block is encountered and no configuration
141 handling callback for this plugin has been registered, a warning is logged and
142 the block is ignored.
144 When set to B<true>, explicit B<LoadPlugin> statements are not required. Each
145 B<E<lt>PluginE<nbsp>...E<gt>> block acts as if it was immediately preceded by a
146 B<LoadPlugin> statement. B<LoadPlugin> statements are still required for
147 plugins that don't provide any configuration, e.g. the I<Load plugin>.
149 =item B<CollectInternalStats> B<false>|B<true>
151 When set to B<true>, various statistics about the I<collectd> daemon will be
152 collected, with "collectd" as the I<plugin name>. Defaults to B<false>.
154 The "write_queue" I<plugin instance> reports the number of elements currently
155 queued and the number of elements dropped off the queue by the
156 B<WriteQueueLimitLow>/B<WriteQueueLimitHigh> mechanism.
158 The "cache" I<plugin instance> reports the number of elements in the value list
159 cache (the cache you can interact with using L<collectd-unixsock(5)>).
161 =item B<Include> I<Path> [I<pattern>]
163 If I<Path> points to a file, includes that file. If I<Path> points to a
164 directory, recursively includes all files within that directory and its
165 subdirectories. If the C<wordexp> function is available on your system,
166 shell-like wildcards are expanded before files are included. This means you can
167 use statements like the following:
169 Include "/etc/collectd.d/*.conf"
171 Starting with version 5.3, this may also be a block in which further options
172 affecting the behavior of B<Include> may be specified. The following option is
175 <Include "/etc/collectd.d">
181 =item B<Filter> I<pattern>
183 If the C<fnmatch> function is available on your system, a shell-like wildcard
184 I<pattern> may be specified to filter which files to include. This may be used
185 in combination with recursively including a directory to easily be able to
186 arbitrarily mix configuration files and other documents (e.g. README files).
187 The given example is similar to the first example above but includes all files
188 matching C<*.conf> in any subdirectory of C</etc/collectd.d>:
190 Include "/etc/collectd.d" "*.conf"
194 If more than one files are included by a single B<Include> option, the files
195 will be included in lexicographical order (as defined by the C<strcmp>
196 function). Thus, you can e.E<nbsp>g. use numbered prefixes to specify the
197 order in which the files are loaded.
199 To prevent loops and shooting yourself in the foot in interesting ways the
200 nesting is limited to a depth of 8E<nbsp>levels, which should be sufficient for
201 most uses. Since symlinks are followed it is still possible to crash the daemon
202 by looping symlinks. In our opinion significant stupidity should result in an
203 appropriate amount of pain.
205 It is no problem to have a block like C<E<lt>Plugin fooE<gt>> in more than one
206 file, but you cannot include files from within blocks.
208 =item B<PIDFile> I<File>
210 Sets where to write the PID file to. This file is overwritten when it exists
211 and deleted when the program is stopped. Some init-scripts might override this
212 setting using the B<-P> command-line option.
214 =item B<PluginDir> I<Directory>
216 Path to the plugins (shared objects) of collectd.
218 =item B<TypesDB> I<File> [I<File> ...]
220 Set one or more files that contain the data-set descriptions. See
221 L<types.db(5)> for a description of the format of this file.
223 =item B<Interval> I<Seconds>
225 Configures the interval in which to query the read plugins. Obviously smaller
226 values lead to a higher system load produced by collectd, while higher values
227 lead to more coarse statistics.
229 B<Warning:> You should set this once and then never touch it again. If you do,
230 I<you will have to delete all your RRD files> or know some serious RRDtool
231 magic! (Assuming you're using the I<RRDtool> or I<RRDCacheD> plugin.)
233 =item B<MaxReadInterval> I<Seconds>
235 Read plugin doubles interval between queries after each failed attempt
238 This options limits the maximum value of the interval. The default value is
241 =item B<Timeout> I<Iterations>
243 Consider a value list "missing" when no update has been read or received for
244 I<Iterations> iterations. By default, I<collectd> considers a value list
245 missing when no update has been received for twice the update interval. Since
246 this setting uses iterations, the maximum allowed time without update depends
247 on the I<Interval> information contained in each value list. This is used in
248 the I<Threshold> configuration to dispatch notifications about missing values,
249 see L<collectd-threshold(5)> for details.
251 =item B<ReadThreads> I<Num>
253 Number of threads to start for reading plugins. The default value is B<5>, but
254 you may want to increase this if you have more than five plugins that take a
255 long time to read. Mostly those are plugins that do network-IO. Setting this to
256 a value higher than the number of registered read callbacks is not recommended.
258 =item B<WriteThreads> I<Num>
260 Number of threads to start for dispatching value lists to write plugins. The
261 default value is B<5>, but you may want to increase this if you have more than
262 five plugins that may take relatively long to write to.
264 =item B<WriteQueueLimitHigh> I<HighNum>
266 =item B<WriteQueueLimitLow> I<LowNum>
268 Metrics are read by the I<read threads> and then put into a queue to be handled
269 by the I<write threads>. If one of the I<write plugins> is slow (e.g. network
270 timeouts, I/O saturation of the disk) this queue will grow. In order to avoid
271 running into memory issues in such a case, you can limit the size of this
274 By default, there is no limit and memory may grow indefinitely. This is most
275 likely not an issue for clients, i.e. instances that only handle the local
276 metrics. For servers it is recommended to set this to a non-zero value, though.
278 You can set the limits using B<WriteQueueLimitHigh> and B<WriteQueueLimitLow>.
279 Each of them takes a numerical argument which is the number of metrics in the
280 queue. If there are I<HighNum> metrics in the queue, any new metrics I<will> be
281 dropped. If there are less than I<LowNum> metrics in the queue, all new metrics
282 I<will> be enqueued. If the number of metrics currently in the queue is between
283 I<LowNum> and I<HighNum>, the metric is dropped with a probability that is
284 proportional to the number of metrics in the queue (i.e. it increases linearly
285 until it reaches 100%.)
287 If B<WriteQueueLimitHigh> is set to non-zero and B<WriteQueueLimitLow> is
288 unset, the latter will default to half of B<WriteQueueLimitHigh>.
290 If you do not want to randomly drop values when the queue size is between
291 I<LowNum> and I<HighNum>, set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow>
294 Enabling the B<CollectInternalStats> option is of great help to figure out the
295 values to set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow> to.
297 =item B<Hostname> I<Name>
299 Sets the hostname that identifies a host. If you omit this setting, the
300 hostname will be determined using the L<gethostname(2)> system call.
302 =item B<FQDNLookup> B<true|false>
304 If B<Hostname> is determined automatically this setting controls whether or not
305 the daemon should try to figure out the "fully qualified domain name", FQDN.
306 This is done using a lookup of the name returned by C<gethostname>. This option
307 is enabled by default.
309 =item B<PreCacheChain> I<ChainName>
311 =item B<PostCacheChain> I<ChainName>
313 Configure the name of the "pre-cache chain" and the "post-cache chain". Please
314 see L<FILTER CONFIGURATION> below on information on chains and how these
315 setting change the daemon's behavior.
319 =head1 PLUGIN OPTIONS
321 Some plugins may register own options. These options must be enclosed in a
322 C<Plugin>-Section. Which options exist depends on the plugin used. Some plugins
323 require external configuration, too. The C<apache plugin>, for example,
324 required C<mod_status> to be configured in the webserver you're going to
325 collect data from. These plugins are listed below as well, even if they don't
326 require any configuration within collectd's configuration file.
328 A list of all plugins and a short summary for each plugin can be found in the
329 F<README> file shipped with the sourcecode and hopefully binary packets as
332 =head2 Plugin C<aggregation>
334 The I<Aggregation plugin> makes it possible to aggregate several values into
335 one using aggregation functions such as I<sum>, I<average>, I<min> and I<max>.
336 This can be put to a wide variety of uses, e.g. average and total CPU
337 statistics for your entire fleet.
339 The grouping is powerful but, as with many powerful tools, may be a bit
340 difficult to wrap your head around. The grouping will therefore be
341 demonstrated using an example: The average and sum of the CPU usage across
342 all CPUs of each host is to be calculated.
344 To select all the affected values for our example, set C<Plugin cpu> and
345 C<Type cpu>. The other values are left unspecified, meaning "all values". The
346 I<Host>, I<Plugin>, I<PluginInstance>, I<Type> and I<TypeInstance> options
347 work as if they were specified in the C<WHERE> clause of an C<SELECT> SQL
353 Although the I<Host>, I<PluginInstance> (CPU number, i.e. 0, 1, 2, ...) and
354 I<TypeInstance> (idle, user, system, ...) fields are left unspecified in the
355 example, the intention is to have a new value for each host / type instance
356 pair. This is achieved by "grouping" the values using the C<GroupBy> option.
357 It can be specified multiple times to group by more than one field.
360 GroupBy "TypeInstance"
362 We do neither specify nor group by I<plugin instance> (the CPU number), so all
363 metrics that differ in the CPU number only will be aggregated. Each
364 aggregation needs I<at least one> such field, otherwise no aggregation would
367 The full example configuration looks like this:
369 <Plugin "aggregation">
375 GroupBy "TypeInstance"
378 CalculateAverage true
382 There are a couple of limitations you should be aware of:
388 The I<Type> cannot be left unspecified, because it is not reasonable to add
389 apples to oranges. Also, the internal lookup structure won't work if you try
394 There must be at least one unspecified, ungrouped field. Otherwise nothing
399 As you can see in the example above, each aggregation has its own
400 B<Aggregation> block. You can have multiple aggregation blocks and aggregation
401 blocks may match the same values, i.e. one value list can update multiple
402 aggregations. The following options are valid inside B<Aggregation> blocks:
406 =item B<Host> I<Host>
408 =item B<Plugin> I<Plugin>
410 =item B<PluginInstance> I<PluginInstance>
412 =item B<Type> I<Type>
414 =item B<TypeInstance> I<TypeInstance>
416 Selects the value lists to be added to this aggregation. B<Type> must be a
417 valid data set name, see L<types.db(5)> for details.
419 If the string starts with and ends with a slash (C</>), the string is
420 interpreted as a I<regular expression>. The regex flavor used are POSIX
421 extended regular expressions as described in L<regex(7)>. Example usage:
423 Host "/^db[0-9]\\.example\\.com$/"
425 =item B<GroupBy> B<Host>|B<Plugin>|B<PluginInstance>|B<TypeInstance>
427 Group valued by the specified field. The B<GroupBy> option may be repeated to
428 group by multiple fields.
430 =item B<SetHost> I<Host>
432 =item B<SetPlugin> I<Plugin>
434 =item B<SetPluginInstance> I<PluginInstance>
436 =item B<SetTypeInstance> I<TypeInstance>
438 Sets the appropriate part of the identifier to the provided string.
440 The I<PluginInstance> should include the placeholder C<%{aggregation}> which
441 will be replaced with the aggregation function, e.g. "average". Not including
442 the placeholder will result in duplication warnings and/or messed up values if
443 more than one aggregation function are enabled.
445 The following example calculates the average usage of all "even" CPUs:
447 <Plugin "aggregation">
450 PluginInstance "/[0,2,4,6,8]$/"
454 SetPluginInstance "even-%{aggregation}"
457 GroupBy "TypeInstance"
459 CalculateAverage true
463 This will create the files:
469 foo.example.com/cpu-even-average/cpu-idle
473 foo.example.com/cpu-even-average/cpu-system
477 foo.example.com/cpu-even-average/cpu-user
485 =item B<CalculateNum> B<true>|B<false>
487 =item B<CalculateSum> B<true>|B<false>
489 =item B<CalculateAverage> B<true>|B<false>
491 =item B<CalculateMinimum> B<true>|B<false>
493 =item B<CalculateMaximum> B<true>|B<false>
495 =item B<CalculateStddev> B<true>|B<false>
497 Boolean options for enabling calculation of the number of value lists, their
498 sum, average, minimum, maximum andE<nbsp>/ or standard deviation. All options
499 are disabled by default.
503 =head2 Plugin C<amqp>
505 The I<AMQMP plugin> can be used to communicate with other instances of
506 I<collectd> or third party applications using an AMQP message broker. Values
507 are sent to or received from the broker, which handles routing, queueing and
508 possibly filtering or messages.
511 # Send values to an AMQP broker
512 <Publish "some_name">
518 Exchange "amq.fanout"
519 # ExchangeType "fanout"
520 # RoutingKey "collectd"
524 # GraphitePrefix "collectd."
525 # GraphiteEscapeChar "_"
526 # GraphiteSeparateInstances false
527 # GraphiteAlwaysAppendDS false
530 # Receive values from an AMQP broker
531 <Subscribe "some_name">
537 Exchange "amq.fanout"
538 # ExchangeType "fanout"
541 # QueueAutoDelete true
542 # RoutingKey "collectd.#"
546 The plugin's configuration consists of a number of I<Publish> and I<Subscribe>
547 blocks, which configure sending and receiving of values respectively. The two
548 blocks are very similar, so unless otherwise noted, an option can be used in
549 either block. The name given in the blocks starting tag is only used for
550 reporting messages, but may be used to support I<flushing> of certain
551 I<Publish> blocks in the future.
555 =item B<Host> I<Host>
557 Hostname or IP-address of the AMQP broker. Defaults to the default behavior of
558 the underlying communications library, I<rabbitmq-c>, which is "localhost".
560 =item B<Port> I<Port>
562 Service name or port number on which the AMQP broker accepts connections. This
563 argument must be a string, even if the numeric form is used. Defaults to
566 =item B<VHost> I<VHost>
568 Name of the I<virtual host> on the AMQP broker to use. Defaults to "/".
570 =item B<User> I<User>
572 =item B<Password> I<Password>
574 Credentials used to authenticate to the AMQP broker. By default "guest"/"guest"
577 =item B<Exchange> I<Exchange>
579 In I<Publish> blocks, this option specifies the I<exchange> to send values to.
580 By default, "amq.fanout" will be used.
582 In I<Subscribe> blocks this option is optional. If given, a I<binding> between
583 the given exchange and the I<queue> is created, using the I<routing key> if
584 configured. See the B<Queue> and B<RoutingKey> options below.
586 =item B<ExchangeType> I<Type>
588 If given, the plugin will try to create the configured I<exchange> with this
589 I<type> after connecting. When in a I<Subscribe> block, the I<queue> will then
590 be bound to this exchange.
592 =item B<Queue> I<Queue> (Subscribe only)
594 Configures the I<queue> name to subscribe to. If no queue name was configured
595 explicitly, a unique queue name will be created by the broker.
597 =item B<QueueDurable> B<true>|B<false> (Subscribe only)
599 Defines if the I<queue> subscribed to is durable (saved to persistent storage)
600 or transient (will disappear if the AMQP broker is restarted). Defaults to
603 This option should be used in conjunction with the I<Persistent> option on the
606 =item B<QueueAutoDelete> B<true>|B<false> (Subscribe only)
608 Defines if the I<queue> subscribed to will be deleted once the last consumer
609 unsubscribes. Defaults to "true".
611 =item B<RoutingKey> I<Key>
613 In I<Publish> blocks, this configures the routing key to set on all outgoing
614 messages. If not given, the routing key will be computed from the I<identifier>
615 of the value. The host, plugin, type and the two instances are concatenated
616 together using dots as the separator and all containing dots replaced with
617 slashes. For example "collectd.host/example/com.cpu.0.cpu.user". This makes it
618 possible to receive only specific values using a "topic" exchange.
620 In I<Subscribe> blocks, configures the I<routing key> used when creating a
621 I<binding> between an I<exchange> and the I<queue>. The usual wildcards can be
622 used to filter messages when using a "topic" exchange. If you're only
623 interested in CPU statistics, you could use the routing key "collectd.*.cpu.#"
626 =item B<Persistent> B<true>|B<false> (Publish only)
628 Selects the I<delivery method> to use. If set to B<true>, the I<persistent>
629 mode will be used, i.e. delivery is guaranteed. If set to B<false> (the
630 default), the I<transient> delivery mode will be used, i.e. messages may be
631 lost due to high load, overflowing queues or similar issues.
633 =item B<Format> B<Command>|B<JSON>|B<Graphite> (Publish only)
635 Selects the format in which messages are sent to the broker. If set to
636 B<Command> (the default), values are sent as C<PUTVAL> commands which are
637 identical to the syntax used by the I<Exec> and I<UnixSock plugins>. In this
638 case, the C<Content-Type> header field will be set to C<text/collectd>.
640 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
641 an easy and straight forward exchange format. The C<Content-Type> header field
642 will be set to C<application/json>.
644 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
645 "<metric> <value> <timestamp>\n". The C<Content-Type> header field will be set to
648 A subscribing client I<should> use the C<Content-Type> header field to
649 determine how to decode the values. Currently, the I<AMQP plugin> itself can
650 only decode the B<Command> format.
652 =item B<StoreRates> B<true>|B<false> (Publish only)
654 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
655 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
656 default), no conversion is performed. Otherwise the conversion is performed
657 using the internal value cache.
659 Please note that currently this option is only used if the B<Format> option has
662 =item B<GraphitePrefix> (Publish and B<Format>=I<Graphite> only)
664 A prefix can be added in the metric name when outputting in the I<Graphite> format.
665 It's added before the I<Host> name.
666 Metric name will be "<prefix><host><postfix><plugin><type><name>"
668 =item B<GraphitePostfix> (Publish and B<Format>=I<Graphite> only)
670 A postfix can be added in the metric name when outputting in the I<Graphite> format.
671 It's added after the I<Host> name.
672 Metric name will be "<prefix><host><postfix><plugin><type><name>"
674 =item B<GraphiteEscapeChar> (Publish and B<Format>=I<Graphite> only)
676 Specify a character to replace dots (.) in the host part of the metric name.
677 In I<Graphite> metric name, dots are used as separators between different
678 metric parts (host, plugin, type).
679 Default is "_" (I<Underscore>).
681 =item B<GraphiteSeparateInstances> B<true>|B<false>
683 If set to B<true>, the plugin instance and type instance will be in their own
684 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
685 default), the plugin and plugin instance (and likewise the type and type
686 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
688 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
690 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
691 identifier. If set to B<false> (the default), this is only done when there is
696 =head2 Plugin C<apache>
698 To configure the C<apache>-plugin you first need to configure the Apache
699 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
700 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
701 the following snipped to base your Apache config upon:
704 <IfModule mod_status.c>
705 <Location /mod_status>
706 SetHandler server-status
710 Since its C<mod_status> module is very similar to Apache's, B<lighttpd> is
711 also supported. It introduces a new field, called C<BusyServers>, to count the
712 number of currently connected clients. This field is also supported.
714 The configuration of the I<Apache> plugin consists of one or more
715 C<E<lt>InstanceE<nbsp>/E<gt>> blocks. Each block requires one string argument
716 as the instance name. For example:
720 URL "http://www1.example.com/mod_status?auto"
723 URL "http://www2.example.com/mod_status?auto"
727 The instance name will be used as the I<plugin instance>. To emulate the old
728 (versionE<nbsp>4) behavior, you can use an empty string (""). In order for the
729 plugin to work correctly, each instance name must be unique. This is not
730 enforced by the plugin and it is your responsibility to ensure it.
732 The following options are accepted within each I<Instance> block:
736 =item B<URL> I<http://host/mod_status?auto>
738 Sets the URL of the C<mod_status> output. This needs to be the output generated
739 by C<ExtendedStatus on> and it needs to be the machine readable output
740 generated by appending the C<?auto> argument. This option is I<mandatory>.
742 =item B<User> I<Username>
744 Optional user name needed for authentication.
746 =item B<Password> I<Password>
748 Optional password needed for authentication.
750 =item B<VerifyPeer> B<true|false>
752 Enable or disable peer SSL certificate verification. See
753 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
755 =item B<VerifyHost> B<true|false>
757 Enable or disable peer host name verification. If enabled, the plugin checks
758 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
759 certificate matches the host name provided by the B<URL> option. If this
760 identity check fails, the connection is aborted. Obviously, only works when
761 connecting to a SSL enabled server. Enabled by default.
763 =item B<CACert> I<File>
765 File that holds one or more SSL certificates. If you want to use HTTPS you will
766 possibly need this option. What CA certificates come bundled with C<libcurl>
767 and are checked by default depends on the distribution you use.
769 =item B<SSLCiphers> I<list of ciphers>
771 (SSL) Specifies which ciphers to use in the connection. The list of ciphers must
772 specify valid ciphers. Read up on SSL cipher list details on this URL:
773 http://www.openssl.org/docs/apps/ciphers.html
776 =head2 Plugin C<apcups>
780 =item B<Host> I<Hostname>
782 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
783 that IPv6 support has been disabled unless someone can confirm or decline that
784 B<apcupsd> can handle it.
786 =item B<Port> I<Port>
788 TCP-Port to connect to. Defaults to B<3551>.
790 =item B<ReportSeconds> B<true|false>
792 If set to B<true>, the time reported in the C<timeleft> metric will be
793 converted to seconds. This is the recommended setting. If set to B<false>, the
794 default for backwards compatibility, the time will be reported in minutes.
798 =head2 Plugin C<aquaero>
800 This plugin collects the value of the available sensors in an
801 I<AquaeroE<nbsp>5> board. AquaeroE<nbsp>5 is a water-cooling controller board,
802 manufactured by Aqua Computer GmbH L<http://www.aquacomputer.de/>, with a USB2
803 connection for monitoring and configuration. The board can handle multiple
804 temperature sensors, fans, water pumps and water level sensors and adjust the
805 output settings such as fan voltage or power used by the water pump based on
806 the available inputs using a configurable controller included in the board.
807 This plugin collects all the available inputs as well as some of the output
808 values chosen by this controller. The plugin is based on the I<libaquaero5>
809 library provided by I<aquatools-ng>.
813 =item B<Device> I<DevicePath>
815 Device path of the AquaeroE<nbsp>5's USB HID (human interface device), usually
816 in the form C</dev/usb/hiddevX>. If this option is no set the plugin will try
817 to auto-detect the Aquaero 5 USB device based on vendor-ID and product-ID.
821 =head2 Plugin C<ascent>
823 This plugin collects information about an Ascent server, a free server for the
824 "World of Warcraft" game. This plugin gathers the information by fetching the
825 XML status page using C<libcurl> and parses it using C<libxml2>.
827 The configuration options are the same as for the C<apache> plugin above:
831 =item B<URL> I<http://localhost/ascent/status/>
833 Sets the URL of the XML status output.
835 =item B<User> I<Username>
837 Optional user name needed for authentication.
839 =item B<Password> I<Password>
841 Optional password needed for authentication.
843 =item B<VerifyPeer> B<true|false>
845 Enable or disable peer SSL certificate verification. See
846 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
848 =item B<VerifyHost> B<true|false>
850 Enable or disable peer host name verification. If enabled, the plugin checks
851 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
852 certificate matches the host name provided by the B<URL> option. If this
853 identity check fails, the connection is aborted. Obviously, only works when
854 connecting to a SSL enabled server. Enabled by default.
856 =item B<CACert> I<File>
858 File that holds one or more SSL certificates. If you want to use HTTPS you will
859 possibly need this option. What CA certificates come bundled with C<libcurl>
860 and are checked by default depends on the distribution you use.
864 =head2 Plugin C<barometer>
866 This plugin reads absolute air pressure using digital barometer sensor MPL115A2
867 or MPL3115 from Freescale (sensor attached to any I2C bus available in
868 the computer, for HW details see
869 I<http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL115A> or
870 I<http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL3115A2>).
871 The sensor type - one fo these two - is detected automatically by the plugin
872 and indicated in the plugin_instance (typically you will see subdirectory
873 "barometer-mpl115" or "barometer-mpl3115").
875 The plugin provides absolute barometric pressure, air pressure reduced to sea
876 level (several possible approximations) and as an auxiliary value also internal
877 sensor temperature. It uses (expects/provides) typical metric units - pressure
878 in [hPa], temperature in [C], altitude in [m].
880 It was developed and tested under Linux only. The only platform dependency is
881 the standard Linux i2c-dev interface (the particular bus driver has to
882 support the SM Bus command subset).
884 The reduction or normalization to mean sea level pressure requires (depedning on
885 selected method/approximation) also altitude and reference to temperature sensor(s).
886 When multiple temperature sensors are configured the minumum of their values is
887 always used (expecting that the warmer ones are affected by e.g. direct sun light
896 TemperatureOffset 0.0
899 TemperatureSensor "myserver/onewire-F10FCA000800/temperature"
904 =item B<Device> I<device>
906 Device name of the I2C bus to which the sensor is connected. Note that typically
907 you need to have loaded the i2c-dev module.
908 Using i2c-tools you can check/list i2c buses available on your system by:
912 Then you can scan for devices on given bus. E.g. to scan the whole bus 0 use:
916 This way you should be able to verify that the pressure sensor (either type) is
917 connected and detected on address 0x60.
919 =item B<Oversampling> I<value>
921 For MPL115 this is the size of the averaging window. To filter out sensor noise
922 a simple averaging using floating window of configurable size is used. The plugin
923 will use average of the last C<value> measurements (value of 1 means no averaging).
924 Minimal size is 1, maximal 1024.
926 For MPL3115 this is the oversampling value. The actual oversampling is performed
927 by the sensor and the higher value the higher accuracy and longer conversion time
928 (although nothing to worry about in the collectd context). Supported values are:
929 1, 2, 4, 8, 16, 32, 64 and 128. Any other value is adjusted by the plugin to
930 the closest supported one. Default is 128.
932 =item B<PressureOffset> I<offset>
934 You can further calibrate the sensor by supplying pressure and/or temperature offsets.
935 This is added to the measured/caclulated value (i.e. if the measured value is too high
936 then use negative offset).
937 In hPa, default is 0.0.
939 =item B<TemperatureOffset> I<offset>
941 You can further calibrate the sensor by supplying pressure and/or temperature offsets.
942 This is added to the measured/caclulated value (i.e. if the measured value is too high
943 then use negative offset).
944 In C, default is 0.0.
946 =item B<Normalization> I<method>
948 Normalization method - what approximation/model is used to compute mean sea
949 level pressure from the air absolute pressure.
951 Supported values of the C<method> (integer between from 0 to 2) are:
955 =item B<0> - no conversion, absolute pressrure is simply copied over. For this method you
956 do not need to configure C<Altitude> or C<TemperatureSensor>.
958 =item B<1> - international formula for conversion ,
959 See I<http://en.wikipedia.org/wiki/Atmospheric_pressure#Altitude_atmospheric_pressure_variation>.
960 For this method you have to configure C<Altitude> but do not need C<TemperatureSensor>
961 (uses fixed global temperature average instead).
963 =item B<2> - formula as recommended by the Deutsche Wetterdienst (German
964 Meteorological Service).
965 See I<http://de.wikipedia.org/wiki/Barometrische_H%C3%B6henformel#Theorie>
966 For this method you have to configure both C<Altitude> and C<TemperatureSensor>.
971 =item B<Altitude> I<altitude>
973 The altitude (in meters) of the location where you meassure the pressure.
975 =item B<TemperatureSensor> I<reference>
977 Temperature sensor which should be used as a reference when normalizing the pressure.
978 When specified more sensors a minumum is found and uses each time.
979 The temperature reading directly from this pressure sensor/plugin
980 is typically not suitable as the pressure sensor
981 will be probably inside while we want outside temperature.
982 The collectd reference name is something like
983 <hostname>/<plugin_name>-<plugin_instance>/<type>-<type_instance>
984 (<type_instance> is usually omitted when there is just single value type).
985 Or you can figure it out from the path of the output data files.
989 =head2 Plugin C<battery>
991 The I<battery plugin> reports the remaining capacity, power and voltage of
996 =item B<ValuesPercentage> B<false>|B<true>
998 When enabled, remaining capacity is reported as a percentage, e.g. "42%
999 capacity remaining". Otherwise the capacity is stored as reported by the
1000 battery, most likely in "Wh". This option does not work with all input methods,
1001 in particular when only C</proc/pmu> is available on an old Linux system.
1002 Defaults to B<false>.
1004 =item B<ReportDegraded> B<false>|B<true>
1006 Typical laptop batteries degrade over time, meaning the capacity decreases with
1007 recharge cycles. The maximum charge of the previous charge cycle is tracked as
1008 "last full capacity" and used to determine that a battery is "fully charged".
1010 When this option is set to B<false>, the default, the I<battery plugin> will
1011 only report the remaining capacity. If the B<ValuesPercentage> option is
1012 enabled, the relative remaining capacity is calculated as the ratio of the
1013 "remaining capacity" and the "last full capacity". This is what most tools,
1014 such as the status bar of desktop environments, also do.
1016 When set to B<true>, the battery plugin will report three values: B<charged>
1017 (remaining capacity), B<discharged> (difference between "last full capacity"
1018 and "remaining capacity") and B<degraded> (difference between "design capacity"
1019 and "last full capacity").
1023 =head2 Plugin C<bind>
1025 Starting with BIND 9.5.0, the most widely used DNS server software provides
1026 extensive statistics about queries, responses and lots of other information.
1027 The bind plugin retrieves this information that's encoded in XML and provided
1028 via HTTP and submits the values to collectd.
1030 To use this plugin, you first need to tell BIND to make this information
1031 available. This is done with the C<statistics-channels> configuration option:
1033 statistics-channels {
1034 inet localhost port 8053;
1037 The configuration follows the grouping that can be seen when looking at the
1038 data with an XSLT compatible viewer, such as a modern web browser. It's
1039 probably a good idea to make yourself familiar with the provided values, so you
1040 can understand what the collected statistics actually mean.
1045 URL "http://localhost:8053/"
1060 Zone "127.in-addr.arpa/IN"
1064 The bind plugin accepts the following configuration options:
1070 URL from which to retrieve the XML data. If not specified,
1071 C<http://localhost:8053/> will be used.
1073 =item B<ParseTime> B<true>|B<false>
1075 When set to B<true>, the time provided by BIND will be parsed and used to
1076 dispatch the values. When set to B<false>, the local time source is queried.
1078 This setting is set to B<true> by default for backwards compatibility; setting
1079 this to B<false> is I<recommended> to avoid problems with timezones and
1082 =item B<OpCodes> B<true>|B<false>
1084 When enabled, statistics about the I<"OpCodes">, for example the number of
1085 C<QUERY> packets, are collected.
1089 =item B<QTypes> B<true>|B<false>
1091 When enabled, the number of I<incoming> queries by query types (for example
1092 C<A>, C<MX>, C<AAAA>) is collected.
1096 =item B<ServerStats> B<true>|B<false>
1098 Collect global server statistics, such as requests received over IPv4 and IPv6,
1099 successful queries, and failed updates.
1103 =item B<ZoneMaintStats> B<true>|B<false>
1105 Collect zone maintenance statistics, mostly information about notifications
1106 (zone updates) and zone transfers.
1110 =item B<ResolverStats> B<true>|B<false>
1112 Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
1113 (e.E<nbsp>g. queries over IPv4, lame servers). Since the global resolver
1114 counters apparently were removed in BIND 9.5.1 and 9.6.0, this is disabled by
1115 default. Use the B<ResolverStats> option within a B<View "_default"> block
1116 instead for the same functionality.
1120 =item B<MemoryStats>
1122 Collect global memory statistics.
1126 =item B<View> I<Name>
1128 Collect statistics about a specific I<"view">. BIND can behave different,
1129 mostly depending on the source IP-address of the request. These different
1130 configurations are called "views". If you don't use this feature, you most
1131 likely are only interested in the C<_default> view.
1133 Within a E<lt>B<View>E<nbsp>I<name>E<gt> block, you can specify which
1134 information you want to collect about a view. If no B<View> block is
1135 configured, no detailed view statistics will be collected.
1139 =item B<QTypes> B<true>|B<false>
1141 If enabled, the number of I<outgoing> queries by query type (e.E<nbsp>g. C<A>,
1142 C<MX>) is collected.
1146 =item B<ResolverStats> B<true>|B<false>
1148 Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
1149 (e.E<nbsp>g. queries over IPv4, lame servers).
1153 =item B<CacheRRSets> B<true>|B<false>
1155 If enabled, the number of entries (I<"RR sets">) in the view's cache by query
1156 type is collected. Negative entries (queries which resulted in an error, for
1157 example names that do not exist) are reported with a leading exclamation mark,
1162 =item B<Zone> I<Name>
1164 When given, collect detailed information about the given zone in the view. The
1165 information collected if very similar to the global B<ServerStats> information
1168 You can repeat this option to collect detailed information about multiple
1171 By default no detailed zone information is collected.
1177 =head2 Plugin C<cgroups>
1179 This plugin collects the CPU user/system time for each I<cgroup> by reading the
1180 F<cpuacct.stat> files in the first cpuacct-mountpoint (typically
1181 F</sys/fs/cgroup/cpu.cpuacct> on machines using systemd).
1185 =item B<CGroup> I<Directory>
1187 Select I<cgroup> based on the name. Whether only matching I<cgroups> are
1188 collected or if they are ignored is controlled by the B<IgnoreSelected> option;
1191 =item B<IgnoreSelected> B<true>|B<false>
1193 Invert the selection: If set to true, all cgroups I<except> the ones that
1194 match any one of the criteria are collected. By default only selected
1195 cgroups are collected if a selection is made. If no selection is configured
1196 at all, B<all> cgroups are selected.
1200 =head2 Plugin C<conntrack>
1202 This plugin collects IP conntrack statistics.
1208 Assume the B<conntrack_count> and B<conntrack_max> files to be found in
1209 F</proc/sys/net/ipv4/netfilter> instead of F</proc/sys/net/netfilter/>.
1213 =head2 Plugin C<cpu>
1215 The I<CPU plugin> collects CPU usage metrics. By default, CPU usage is reported
1216 as Jiffies, using the C<cpu> type. Two aggregations are available:
1222 Sum, per-state, over all CPUs installed in the system; and
1226 Sum, per-CPU, over all non-idle states of a CPU, creating an "active" state.
1230 The two aggregations can be combined, leading to I<collectd> only emitting a
1231 single "active" metric for the entire system. As soon as one of these
1232 aggregations (or both) is enabled, the I<cpu plugin> will report a percentage,
1233 rather than Jiffies. In addition, you can request individual, per-state,
1234 per-CPU metrics to be reported as percentage.
1236 The following configuration options are available:
1240 =item B<ReportByState> B<true>|B<false>
1242 When set to B<true>, the default, reports per-state metrics, e.g. "system",
1244 When set to B<false>, aggregates (sums) all I<non-idle> states into one
1247 =item B<ReportByCpu> B<true>|B<false>
1249 When set to B<true>, the default, reports per-CPU (per-core) metrics.
1250 When set to B<false>, instead of reporting metrics for individual CPUs, only a
1251 global sum of CPU states is emitted.
1253 =item B<ValuesPercentage> B<false>|B<true>
1255 This option is only considered when both, B<ReportByCpu> and B<ReportByState>
1256 are set to B<true>. In this case, by default, metrics will be reported as
1257 Jiffies. By setting this option to B<true>, you can request percentage values
1258 in the un-aggregated (per-CPU, per-state) mode as well.
1262 =head2 Plugin C<cpufreq>
1264 This plugin doesn't have any options. It reads
1265 F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for the first CPU
1266 installed) to get the current CPU frequency. If this file does not exist make
1267 sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a similar tool is
1268 installed and an "cpu governor" (that's a kernel module) is loaded.
1270 =head2 Plugin C<csv>
1274 =item B<DataDir> I<Directory>
1276 Set the directory to store CSV-files under. Per default CSV-files are generated
1277 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
1278 The special strings B<stdout> and B<stderr> can be used to write to the standard
1279 output and standard error channels, respectively. This, of course, only makes
1280 much sense when collectd is running in foreground- or non-daemon-mode.
1282 =item B<StoreRates> B<true|false>
1284 If set to B<true>, convert counter values to rates. If set to B<false> (the
1285 default) counter values are stored as is, i.E<nbsp>e. as an increasing integer
1290 =head2 Plugin C<curl>
1292 The curl plugin uses the B<libcurl> (L<http://curl.haxx.se/>) to read web pages
1293 and the match infrastructure (the same code used by the tail plugin) to use
1294 regular expressions with the received data.
1296 The following example will read the current value of AMD stock from Google's
1297 finance page and dispatch the value to collectd.
1300 <Page "stock_quotes">
1301 URL "http://finance.google.com/finance?q=NYSE%3AAMD"
1307 CACert "/path/to/ca.crt"
1308 Header "X-Custom-Header: foobar"
1311 MeasureResponseTime false
1312 MeasureResponseCode false
1315 Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
1316 DSType "GaugeAverage"
1317 # Note: `stock_value' is not a standard type.
1324 In the B<Plugin> block, there may be one or more B<Page> blocks, each defining
1325 a web page and one or more "matches" to be performed on the returned data. The
1326 string argument to the B<Page> block is used as plugin instance.
1328 The following options are valid within B<Page> blocks:
1334 URL of the web site to retrieve. Since a regular expression will be used to
1335 extract information from this data, non-binary data is a big plus here ;)
1337 =item B<User> I<Name>
1339 Username to use if authorization is required to read the page.
1341 =item B<Password> I<Password>
1343 Password to use if authorization is required to read the page.
1345 =item B<Digest> B<true>|B<false>
1347 Enable HTTP digest authentication.
1349 =item B<VerifyPeer> B<true>|B<false>
1351 Enable or disable peer SSL certificate verification. See
1352 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
1354 =item B<VerifyHost> B<true>|B<false>
1356 Enable or disable peer host name verification. If enabled, the plugin checks if
1357 the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
1358 matches the host name provided by the B<URL> option. If this identity check
1359 fails, the connection is aborted. Obviously, only works when connecting to a
1360 SSL enabled server. Enabled by default.
1362 =item B<CACert> I<file>
1364 File that holds one or more SSL certificates. If you want to use HTTPS you will
1365 possibly need this option. What CA certificates come bundled with C<libcurl>
1366 and are checked by default depends on the distribution you use.
1368 =item B<Header> I<Header>
1370 A HTTP header to add to the request. Multiple headers are added if this option
1371 is specified more than once.
1373 =item B<Post> I<Body>
1375 Specifies that the HTTP operation should be a POST instead of a GET. The
1376 complete data to be posted is given as the argument. This option will usually
1377 need to be accompanied by a B<Header> option to set an appropriate
1378 C<Content-Type> for the post body (e.g. to
1379 C<application/x-www-form-urlencoded>).
1381 =item B<MeasureResponseTime> B<true>|B<false>
1383 Measure response time for the request. If this setting is enabled, B<Match>
1384 blocks (see below) are optional. Disabled by default.
1386 =item B<MeasureResponseCode> B<true>|B<false>
1388 Measure response code for the request. If this setting is enabled, B<Match>
1389 blocks (see below) are optional. Disabled by default.
1391 =item B<E<lt>MatchE<gt>>
1393 One or more B<Match> blocks that define how to match information in the data
1394 returned by C<libcurl>. The C<curl> plugin uses the same infrastructure that's
1395 used by the C<tail> plugin, so please see the documentation of the C<tail>
1396 plugin below on how matches are defined. If the B<MeasureResponseTime> or
1397 B<MeasureResponseCode> options are set to B<true>, B<Match> blocks are
1402 =head2 Plugin C<curl_json>
1404 The B<curl_json plugin> collects values from JSON data to be parsed by
1405 B<libyajl> (L<http://www.lloydforge.org/projects/yajl/>) retrieved via
1406 either B<libcurl> (L<http://curl.haxx.se/>) or read directly from a
1407 unix socket. The former can be used, for example, to collect values
1408 from CouchDB documents (which are stored JSON notation), and the
1409 latter to collect values from a uWSGI stats socket.
1411 The following example will collect several values from the built-in
1412 C<_stats> runtime statistics module of I<CouchDB>
1413 (L<http://wiki.apache.org/couchdb/Runtime_Statistics>).
1416 <URL "http://localhost:5984/_stats">
1418 <Key "httpd/requests/count">
1419 Type "http_requests"
1422 <Key "httpd_request_methods/*/count">
1423 Type "http_request_methods"
1426 <Key "httpd_status_codes/*/count">
1427 Type "http_response_codes"
1432 This example will collect data directly from a I<uWSGI> "Stats Server" socket.
1435 <Sock "/var/run/uwsgi.stats.sock">
1437 <Key "workers/*/requests">
1438 Type "http_requests"
1441 <Key "workers/*/apps/*/requests">
1442 Type "http_requests"
1447 In the B<Plugin> block, there may be one or more B<URL> blocks, each
1448 defining a URL to be fetched via HTTP (using libcurl) or B<Sock>
1449 blocks defining a unix socket to read JSON from directly. Each of
1450 these blocks may have one or more B<Key> blocks.
1452 The B<Key> string argument must be in a path format. Each component is
1453 used to match the key from a JSON map or the index of an JSON
1454 array. If a path component of a B<Key> is a I<*>E<nbsp>wildcard, the
1455 values for all map keys or array indices will be collectd.
1457 The following options are valid within B<URL> blocks:
1461 =item B<Instance> I<Instance>
1463 Sets the plugin instance to I<Instance>.
1465 =item B<Interval> I<Interval>
1467 Sets the interval (in seconds) in which the values will be collected from this
1468 URL. By default the global B<Interval> setting will be used.
1470 =item B<User> I<Name>
1472 =item B<Password> I<Password>
1474 =item B<Digest> B<true>|B<false>
1476 =item B<VerifyPeer> B<true>|B<false>
1478 =item B<VerifyHost> B<true>|B<false>
1480 =item B<CACert> I<file>
1482 =item B<Header> I<Header>
1484 =item B<Post> I<Body>
1486 These options behave exactly equivalent to the appropriate options of the
1487 I<cURL> plugin. Please see there for a detailed description.
1491 The following options are valid within B<Key> blocks:
1495 =item B<Type> I<Type>
1497 Sets the type used to dispatch the values to the daemon. Detailed information
1498 about types and their configuration can be found in L<types.db(5)>. This
1499 option is mandatory.
1501 =item B<Instance> I<Instance>
1503 Type-instance to use. Defaults to the current map key or current string array element value.
1507 =head2 Plugin C<curl_xml>
1509 The B<curl_xml plugin> uses B<libcurl> (L<http://curl.haxx.se/>) and B<libxml2>
1510 (L<http://xmlsoft.org/>) to retrieve XML data via cURL.
1513 <URL "http://localhost/stats.xml">
1515 Instance "some_instance"
1520 CACert "/path/to/ca.crt"
1521 Header "X-Custom-Header: foobar"
1524 <XPath "table[@id=\"magic_level\"]/tr">
1526 #InstancePrefix "prefix-"
1527 InstanceFrom "td[1]"
1528 ValuesFrom "td[2]/span[@class=\"level\"]"
1533 In the B<Plugin> block, there may be one or more B<URL> blocks, each defining a
1534 URL to be fetched using libcurl. Within each B<URL> block there are
1535 options which specify the connection parameters, for example authentication
1536 information, and one or more B<XPath> blocks.
1538 Each B<XPath> block specifies how to get one type of information. The
1539 string argument must be a valid XPath expression which returns a list
1540 of "base elements". One value is dispatched for each "base element". The
1541 I<type instance> and values are looked up using further I<XPath> expressions
1542 that should be relative to the base element.
1544 Within the B<URL> block the following options are accepted:
1548 =item B<Host> I<Name>
1550 Use I<Name> as the host name when submitting values. Defaults to the global
1553 =item B<Instance> I<Instance>
1555 Use I<Instance> as the plugin instance when submitting values. Defaults to an
1556 empty string (no plugin instance).
1558 =item B<Namespace> I<Prefix> I<URL>
1560 If an XPath expression references namespaces, they must be specified
1561 with this option. I<Prefix> is the "namespace prefix" used in the XML document.
1562 I<URL> is the "namespace name", an URI reference uniquely identifying the
1563 namespace. The option can be repeated to register multiple namespaces.
1567 Namespace "s" "http://schemas.xmlsoap.org/soap/envelope/"
1568 Namespace "m" "http://www.w3.org/1998/Math/MathML"
1570 =item B<User> I<User>
1572 =item B<Password> I<Password>
1574 =item B<Digest> B<true>|B<false>
1576 =item B<VerifyPeer> B<true>|B<false>
1578 =item B<VerifyHost> B<true>|B<false>
1580 =item B<CACert> I<CA Cert File>
1582 =item B<Header> I<Header>
1584 =item B<Post> I<Body>
1586 These options behave exactly equivalent to the appropriate options of the
1587 I<cURL plugin>. Please see there for a detailed description.
1589 =item E<lt>B<XPath> I<XPath-expression>E<gt>
1591 Within each B<URL> block, there must be one or more B<XPath> blocks. Each
1592 B<XPath> block specifies how to get one type of information. The string
1593 argument must be a valid XPath expression which returns a list of "base
1594 elements". One value is dispatched for each "base element".
1596 Within the B<XPath> block the following options are accepted:
1600 =item B<Type> I<Type>
1602 Specifies the I<Type> used for submitting patches. This determines the number
1603 of values that are required / expected and whether the strings are parsed as
1604 signed or unsigned integer or as double values. See L<types.db(5)> for details.
1605 This option is required.
1607 =item B<InstancePrefix> I<InstancePrefix>
1609 Prefix the I<type instance> with I<InstancePrefix>. The values are simply
1610 concatenated together without any separator.
1611 This option is optional.
1613 =item B<InstanceFrom> I<InstanceFrom>
1615 Specifies a XPath expression to use for determining the I<type instance>. The
1616 XPath expression must return exactly one element. The element's value is then
1617 used as I<type instance>, possibly prefixed with I<InstancePrefix> (see above).
1619 This value is required. As a special exception, if the "base XPath expression"
1620 (the argument to the B<XPath> block) returns exactly one argument, then this
1621 option may be omitted.
1623 =item B<ValuesFrom> I<ValuesFrom> [I<ValuesFrom> ...]
1625 Specifies one or more XPath expression to use for reading the values. The
1626 number of XPath expressions must match the number of data sources in the
1627 I<type> specified with B<Type> (see above). Each XPath expression must return
1628 exactly one element. The element's value is then parsed as a number and used as
1629 value for the appropriate value in the value list dispatched to the daemon.
1635 =head2 Plugin C<dbi>
1637 This plugin uses the B<dbi> library (L<http://libdbi.sourceforge.net/>) to
1638 connect to various databases, execute I<SQL> statements and read back the
1639 results. I<dbi> is an acronym for "database interface" in case you were
1640 wondering about the name. You can configure how each column is to be
1641 interpreted and the plugin will generate one or more data sets from each row
1642 returned according to these rules.
1644 Because the plugin is very generic, the configuration is a little more complex
1645 than those of other plugins. It usually looks something like this:
1648 <Query "out_of_stock">
1649 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
1650 # Use with MySQL 5.0.0 or later
1654 InstancePrefix "out_of_stock"
1655 InstancesFrom "category"
1659 <Database "product_information">
1661 DriverOption "host" "localhost"
1662 DriverOption "username" "collectd"
1663 DriverOption "password" "aZo6daiw"
1664 DriverOption "dbname" "prod_info"
1665 SelectDB "prod_info"
1666 Query "out_of_stock"
1670 The configuration above defines one query with one result and one database. The
1671 query is then linked to the database with the B<Query> option I<within> the
1672 B<E<lt>DatabaseE<gt>> block. You can have any number of queries and databases
1673 and you can also use the B<Include> statement to split up the configuration
1674 file in multiple, smaller files. However, the B<E<lt>QueryE<gt>> block I<must>
1675 precede the B<E<lt>DatabaseE<gt>> blocks, because the file is interpreted from
1678 The following is a complete list of options:
1680 =head3 B<Query> blocks
1682 Query blocks define I<SQL> statements and how the returned data should be
1683 interpreted. They are identified by the name that is given in the opening line
1684 of the block. Thus the name needs to be unique. Other than that, the name is
1685 not used in collectd.
1687 In each B<Query> block, there is one or more B<Result> blocks. B<Result> blocks
1688 define which column holds which value or instance information. You can use
1689 multiple B<Result> blocks to create multiple values from one returned row. This
1690 is especially useful, when queries take a long time and sending almost the same
1691 query again and again is not desirable.
1695 <Query "environment">
1696 Statement "select station, temperature, humidity from environment"
1699 # InstancePrefix "foo"
1700 InstancesFrom "station"
1701 ValuesFrom "temperature"
1705 InstancesFrom "station"
1706 ValuesFrom "humidity"
1710 The following options are accepted:
1714 =item B<Statement> I<SQL>
1716 Sets the statement that should be executed on the server. This is B<not>
1717 interpreted by collectd, but simply passed to the database server. Therefore,
1718 the SQL dialect that's used depends on the server collectd is connected to.
1720 The query has to return at least two columns, one for the instance and one
1721 value. You cannot omit the instance, even if the statement is guaranteed to
1722 always return exactly one line. In that case, you can usually specify something
1725 Statement "SELECT \"instance\", COUNT(*) AS value FROM table"
1727 (That works with MySQL but may not be valid SQL according to the spec. If you
1728 use a more strict database server, you may have to select from a dummy table or
1731 Please note that some databases, for example B<Oracle>, will fail if you
1732 include a semicolon at the end of the statement.
1734 =item B<MinVersion> I<Version>
1736 =item B<MaxVersion> I<Value>
1738 Only use this query for the specified database version. You can use these
1739 options to provide multiple queries with the same name but with a slightly
1740 different syntax. The plugin will use only those queries, where the specified
1741 minimum and maximum versions fit the version of the database in use.
1743 The database version is determined by C<dbi_conn_get_engine_version>, see the
1744 L<libdbi documentation|http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-GET-ENGINE-VERSION>
1745 for details. Basically, each part of the version is assumed to be in the range
1746 from B<00> to B<99> and all dots are removed. So version "4.1.2" becomes
1747 "40102", version "5.0.42" becomes "50042".
1749 B<Warning:> The plugin will use B<all> matching queries, so if you specify
1750 multiple queries with the same name and B<overlapping> ranges, weird stuff will
1751 happen. Don't to it! A valid example would be something along these lines:
1762 In the above example, there are three ranges that don't overlap. The last one
1763 goes from version "5.1.0" to infinity, meaning "all later versions". Versions
1764 before "4.0.0" are not specified.
1766 =item B<Type> I<Type>
1768 The B<type> that's used for each line returned. See L<types.db(5)> for more
1769 details on how types are defined. In short: A type is a predefined layout of
1770 data and the number of values and type of values has to match the type
1773 If you specify "temperature" here, you need exactly one gauge column. If you
1774 specify "if_octets", you will need two counter columns. See the B<ValuesFrom>
1777 There must be exactly one B<Type> option inside each B<Result> block.
1779 =item B<InstancePrefix> I<prefix>
1781 Prepends I<prefix> to the type instance. If B<InstancesFrom> (see below) is not
1782 given, the string is simply copied. If B<InstancesFrom> is given, I<prefix> and
1783 all strings returned in the appropriate columns are concatenated together,
1784 separated by dashes I<("-")>.
1786 =item B<InstancesFrom> I<column0> [I<column1> ...]
1788 Specifies the columns whose values will be used to create the "type-instance"
1789 for each row. If you specify more than one column, the value of all columns
1790 will be joined together with dashes I<("-")> as separation characters.
1792 The plugin itself does not check whether or not all built instances are
1793 different. It's your responsibility to assure that each is unique. This is
1794 especially true, if you do not specify B<InstancesFrom>: B<You> have to make
1795 sure that only one row is returned in this case.
1797 If neither B<InstancePrefix> nor B<InstancesFrom> is given, the type-instance
1800 =item B<ValuesFrom> I<column0> [I<column1> ...]
1802 Names the columns whose content is used as the actual data for the data sets
1803 that are dispatched to the daemon. How many such columns you need is determined
1804 by the B<Type> setting above. If you specify too many or not enough columns,
1805 the plugin will complain about that and no data will be submitted to the
1808 The actual data type in the columns is not that important. The plugin will
1809 automatically cast the values to the right type if it know how to do that. So
1810 it should be able to handle integer an floating point types, as well as strings
1811 (if they include a number at the beginning).
1813 There must be at least one B<ValuesFrom> option inside each B<Result> block.
1815 =item B<MetadataFrom> [I<column0> I<column1> ...]
1817 Names the columns whose content is used as metadata for the data sets
1818 that are dispatched to the daemon.
1820 The actual data type in the columns is not that important. The plugin will
1821 automatically cast the values to the right type if it know how to do that. So
1822 it should be able to handle integer an floating point types, as well as strings
1823 (if they include a number at the beginning).
1827 =head3 B<Database> blocks
1829 Database blocks define a connection to a database and which queries should be
1830 sent to that database. Since the used "dbi" library can handle a wide variety
1831 of databases, the configuration is very generic. If in doubt, refer to libdbi's
1832 documentationE<nbsp>- we stick as close to the terminology used there.
1834 Each database needs a "name" as string argument in the starting tag of the
1835 block. This name will be used as "PluginInstance" in the values submitted to
1836 the daemon. Other than that, that name is not used.
1840 =item B<Driver> I<Driver>
1842 Specifies the driver to use to connect to the database. In many cases those
1843 drivers are named after the database they can connect to, but this is not a
1844 technical necessity. These drivers are sometimes referred to as "DBD",
1845 B<D>ataB<B>ase B<D>river, and some distributions ship them in separate
1846 packages. Drivers for the "dbi" library are developed by the B<libdbi-drivers>
1847 project at L<http://libdbi-drivers.sourceforge.net/>.
1849 You need to give the driver name as expected by the "dbi" library here. You
1850 should be able to find that in the documentation for each driver. If you
1851 mistype the driver name, the plugin will dump a list of all known driver names
1854 =item B<DriverOption> I<Key> I<Value>
1856 Sets driver-specific options. What option a driver supports can be found in the
1857 documentation for each driver, somewhere at
1858 L<http://libdbi-drivers.sourceforge.net/>. However, the options "host",
1859 "username", "password", and "dbname" seem to be deE<nbsp>facto standards.
1861 DBDs can register two types of options: String options and numeric options. The
1862 plugin will use the C<dbi_conn_set_option> function when the configuration
1863 provides a string and the C<dbi_conn_require_option_numeric> function when the
1864 configuration provides a number. So these two lines will actually result in
1865 different calls being used:
1867 DriverOption "Port" 1234 # numeric
1868 DriverOption "Port" "1234" # string
1870 Unfortunately, drivers are not too keen to report errors when an unknown option
1871 is passed to them, so invalid settings here may go unnoticed. This is not the
1872 plugin's fault, it will report errors if it gets them from the libraryE<nbsp>/
1873 the driver. If a driver complains about an option, the plugin will dump a
1874 complete list of all options understood by that driver to the log. There is no
1875 way to programatically find out if an option expects a string or a numeric
1876 argument, so you will have to refer to the appropriate DBD's documentation to
1877 find this out. Sorry.
1879 =item B<SelectDB> I<Database>
1881 In some cases, the database name you connect with is not the database name you
1882 want to use for querying data. If this option is set, the plugin will "select"
1883 (switch to) that database after the connection is established.
1885 =item B<Query> I<QueryName>
1887 Associates the query named I<QueryName> with this database connection. The
1888 query needs to be defined I<before> this statement, i.E<nbsp>e. all query
1889 blocks you want to refer to must be placed above the database block you want to
1892 =item B<Host> I<Hostname>
1894 Sets the B<host> field of I<value lists> to I<Hostname> when dispatching
1895 values. Defaults to the global hostname setting.
1903 =item B<Device> I<Device>
1905 Select partitions based on the devicename.
1907 =item B<MountPoint> I<Directory>
1909 Select partitions based on the mountpoint.
1911 =item B<FSType> I<FSType>
1913 Select partitions based on the filesystem type.
1915 =item B<IgnoreSelected> B<true>|B<false>
1917 Invert the selection: If set to true, all partitions B<except> the ones that
1918 match any one of the criteria are collected. By default only selected
1919 partitions are collected if a selection is made. If no selection is configured
1920 at all, B<all> partitions are selected.
1922 =item B<ReportByDevice> B<true>|B<false>
1924 Report using the device name rather than the mountpoint. i.e. with this I<false>,
1925 (the default), it will report a disk as "root", but with it I<true>, it will be
1926 "sda1" (or whichever).
1928 =item B<ReportInodes> B<true>|B<false>
1930 Enables or disables reporting of free, reserved and used inodes. Defaults to
1931 inode collection being disabled.
1933 Enable this option if inodes are a scarce resource for you, usually because
1934 many small files are stored on the disk. This is a usual scenario for mail
1935 transfer agents and web caches.
1937 =item B<ValuesAbsolute> B<true>|B<false>
1939 Enables or disables reporting of free and used disk space in 1K-blocks.
1940 Defaults to B<true>.
1942 =item B<ValuesPercentage> B<false>|B<true>
1944 Enables or disables reporting of free and used disk space in percentage.
1945 Defaults to B<false>.
1947 This is useful for deploying I<collectd> on the cloud, where machines with
1948 different disk size may exist. Then it is more practical to configure
1949 thresholds based on relative disk size.
1953 =head2 Plugin C<disk>
1955 The C<disk> plugin collects information about the usage of physical disks and
1956 logical disks (partitions). Values collected are the number of octets written
1957 to and read from a disk or partition, the number of read/write operations
1958 issued to the disk and a rather complex "time" it took for these commands to be
1961 Using the following two options you can ignore some disks or configure the
1962 collection only of specific disks.
1966 =item B<Disk> I<Name>
1968 Select the disk I<Name>. Whether it is collected or ignored depends on the
1969 B<IgnoreSelected> setting, see below. As with other plugins that use the
1970 daemon's ignorelist functionality, a string that starts and ends with a slash
1971 is interpreted as a regular expression. Examples:
1976 =item B<IgnoreSelected> B<true>|B<false>
1978 Sets whether selected disks, i.E<nbsp>e. the ones matches by any of the B<Disk>
1979 statements, are ignored or if all other disks are ignored. The behavior
1980 (hopefully) is intuitive: If no B<Disk> option is configured, all disks are
1981 collected. If at least one B<Disk> option is given and no B<IgnoreSelected> or
1982 set to B<false>, B<only> matching disks will be collected. If B<IgnoreSelected>
1983 is set to B<true>, all disks are collected B<except> the ones matched.
1985 =item B<UseBSDName> B<true>|B<false>
1987 Whether to use the device's "BSD Name", on MacE<nbsp>OSE<nbsp>X, instead of the
1988 default major/minor numbers. Requires collectd to be built with Apple's
1991 =item B<UdevNameAttr> I<Attribute>
1993 Attempt to override disk instance name with the value of a specified udev
1994 attribute when built with B<libudev>. If the attribute is not defined for the
1995 given device, the default name is used. Example:
1997 UdevNameAttr "DM_NAME"
2001 =head2 Plugin C<dns>
2005 =item B<Interface> I<Interface>
2007 The dns plugin uses B<libpcap> to capture dns traffic and analyzes it. This
2008 option sets the interface that should be used. If this option is not set, or
2009 set to "any", the plugin will try to get packets from B<all> interfaces. This
2010 may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
2012 =item B<IgnoreSource> I<IP-address>
2014 Ignore packets that originate from this address.
2016 =item B<SelectNumericQueryTypes> B<true>|B<false>
2018 Enabled by default, collects unknown (and thus presented as numeric only) query types.
2022 =head2 Plugin C<email>
2026 =item B<SocketFile> I<Path>
2028 Sets the socket-file which is to be created.
2030 =item B<SocketGroup> I<Group>
2032 If running as root change the group of the UNIX-socket after it has been
2033 created. Defaults to B<collectd>.
2035 =item B<SocketPerms> I<Permissions>
2037 Change the file permissions of the UNIX-socket after it has been created. The
2038 permissions must be given as a numeric, octal value as you would pass to
2039 L<chmod(1)>. Defaults to B<0770>.
2041 =item B<MaxConns> I<Number>
2043 Sets the maximum number of connections that can be handled in parallel. Since
2044 this many threads will be started immediately setting this to a very high
2045 value will waste valuable resources. Defaults to B<5> and will be forced to be
2046 at most B<16384> to prevent typos and dumb mistakes.
2050 =head2 Plugin C<ethstat>
2052 The I<ethstat plugin> collects information about network interface cards (NICs)
2053 by talking directly with the underlying kernel driver using L<ioctl(2)>.
2059 Map "rx_csum_offload_errors" "if_rx_errors" "checksum_offload"
2060 Map "multicast" "if_multicast"
2067 =item B<Interface> I<Name>
2069 Collect statistical information about interface I<Name>.
2071 =item B<Map> I<Name> I<Type> [I<TypeInstance>]
2073 By default, the plugin will submit values as type C<derive> and I<type
2074 instance> set to I<Name>, the name of the metric as reported by the driver. If
2075 an appropriate B<Map> option exists, the given I<Type> and, optionally,
2076 I<TypeInstance> will be used.
2078 =item B<MappedOnly> B<true>|B<false>
2080 When set to B<true>, only metrics that can be mapped to to a I<type> will be
2081 collected, all other metrics will be ignored. Defaults to B<false>.
2085 =head2 Plugin C<exec>
2087 Please make sure to read L<collectd-exec(5)> before using this plugin. It
2088 contains valuable information on when the executable is executed and the
2089 output that is expected from it.
2093 =item B<Exec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
2095 =item B<NotificationExec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
2097 Execute the executable I<Executable> as user I<User>. If the user name is
2098 followed by a colon and a group name, the effective group is set to that group.
2099 The real group and saved-set group will be set to the default group of that
2100 user. If no group is given the effective group ID will be the same as the real
2103 Please note that in order to change the user and/or group the daemon needs
2104 superuser privileges. If the daemon is run as an unprivileged user you must
2105 specify the same user/group here. If the daemon is run with superuser
2106 privileges, you must supply a non-root user here.
2108 The executable may be followed by optional arguments that are passed to the
2109 program. Please note that due to the configuration parsing numbers and boolean
2110 values may be changed. If you want to be absolutely sure that something is
2111 passed as-is please enclose it in quotes.
2113 The B<Exec> and B<NotificationExec> statements change the semantics of the
2114 programs executed, i.E<nbsp>e. the data passed to them and the response
2115 expected from them. This is documented in great detail in L<collectd-exec(5)>.
2119 =head2 Plugin C<filecount>
2121 The C<filecount> plugin counts the number of files in a certain directory (and
2122 its subdirectories) and their combined size. The configuration is very straight
2125 <Plugin "filecount">
2126 <Directory "/var/qmail/queue/mess">
2127 Instance "qmail-message"
2129 <Directory "/var/qmail/queue/todo">
2130 Instance "qmail-todo"
2132 <Directory "/var/lib/php5">
2133 Instance "php5-sessions"
2138 The example above counts the number of files in QMail's queue directories and
2139 the number of PHP5 sessions. Jfiy: The "todo" queue holds the messages that
2140 QMail has not yet looked at, the "message" queue holds the messages that were
2141 classified into "local" and "remote".
2143 As you can see, the configuration consists of one or more C<Directory> blocks,
2144 each of which specifies a directory in which to count the files. Within those
2145 blocks, the following options are recognized:
2149 =item B<Instance> I<Instance>
2151 Sets the plugin instance to I<Instance>. That instance name must be unique, but
2152 it's your responsibility, the plugin doesn't check for that. If not given, the
2153 instance is set to the directory name with all slashes replaced by underscores
2154 and all leading underscores removed.
2156 =item B<Name> I<Pattern>
2158 Only count files that match I<Pattern>, where I<Pattern> is a shell-like
2159 wildcard as understood by L<fnmatch(3)>. Only the B<filename> is checked
2160 against the pattern, not the entire path. In case this makes it easier for you:
2161 This option has been named after the B<-name> parameter to L<find(1)>.
2163 =item B<MTime> I<Age>
2165 Count only files of a specific age: If I<Age> is greater than zero, only files
2166 that haven't been touched in the last I<Age> seconds are counted. If I<Age> is
2167 a negative number, this is inversed. For example, if B<-60> is specified, only
2168 files that have been modified in the last minute will be counted.
2170 The number can also be followed by a "multiplier" to easily specify a larger
2171 timespan. When given in this notation, the argument must in quoted, i.E<nbsp>e.
2172 must be passed as string. So the B<-60> could also be written as B<"-1m"> (one
2173 minute). Valid multipliers are C<s> (second), C<m> (minute), C<h> (hour), C<d>
2174 (day), C<w> (week), and C<y> (year). There is no "month" multiplier. You can
2175 also specify fractional numbers, e.E<nbsp>g. B<"0.5d"> is identical to
2178 =item B<Size> I<Size>
2180 Count only files of a specific size. When I<Size> is a positive number, only
2181 files that are at least this big are counted. If I<Size> is a negative number,
2182 this is inversed, i.E<nbsp>e. only files smaller than the absolute value of
2183 I<Size> are counted.
2185 As with the B<MTime> option, a "multiplier" may be added. For a detailed
2186 description see above. Valid multipliers here are C<b> (byte), C<k> (kilobyte),
2187 C<m> (megabyte), C<g> (gigabyte), C<t> (terabyte), and C<p> (petabyte). Please
2188 note that there are 1000 bytes in a kilobyte, not 1024.
2190 =item B<Recursive> I<true>|I<false>
2192 Controls whether or not to recurse into subdirectories. Enabled by default.
2194 =item B<IncludeHidden> I<true>|I<false>
2196 Controls whether or not to include "hidden" files and directories in the count.
2197 "Hidden" files and directories are those, whose name begins with a dot.
2198 Defaults to I<false>, i.e. by default hidden files and directories are ignored.
2202 =head2 Plugin C<GenericJMX>
2204 The I<GenericJMX plugin> is written in I<Java> and therefore documented in
2205 L<collectd-java(5)>.
2207 =head2 Plugin C<gmond>
2209 The I<gmond> plugin received the multicast traffic sent by B<gmond>, the
2210 statistics collection daemon of Ganglia. Mappings for the standard "metrics"
2211 are built-in, custom mappings may be added via B<Metric> blocks, see below.
2216 MCReceiveFrom "239.2.11.71" "8649"
2217 <Metric "swap_total">
2219 TypeInstance "total"
2222 <Metric "swap_free">
2229 The following metrics are built-in:
2235 load_one, load_five, load_fifteen
2239 cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio
2243 mem_free, mem_shared, mem_buffers, mem_cached, mem_total
2255 Available configuration options:
2259 =item B<MCReceiveFrom> I<MCGroup> [I<Port>]
2261 Sets sets the multicast group and UDP port to which to subscribe.
2263 Default: B<239.2.11.71>E<nbsp>/E<nbsp>B<8649>
2265 =item E<lt>B<Metric> I<Name>E<gt>
2267 These blocks add a new metric conversion to the internal table. I<Name>, the
2268 string argument to the B<Metric> block, is the metric name as used by Ganglia.
2272 =item B<Type> I<Type>
2274 Type to map this metric to. Required.
2276 =item B<TypeInstance> I<Instance>
2278 Type-instance to use. Optional.
2280 =item B<DataSource> I<Name>
2282 Data source to map this metric to. If the configured type has exactly one data
2283 source, this is optional. Otherwise the option is required.
2289 =head2 Plugin C<hddtemp>
2291 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
2292 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
2293 default values, see below. C<hddtemp> has to be running to work correctly. If
2294 C<hddtemp> is not running timeouts may appear which may interfere with other
2297 The B<hddtemp> homepage can be found at
2298 L<http://www.guzu.net/linux/hddtemp.php>.
2302 =item B<Host> I<Hostname>
2304 Hostname to connect to. Defaults to B<127.0.0.1>.
2306 =item B<Port> I<Port>
2308 TCP-Port to connect to. Defaults to B<7634>.
2312 =head2 Plugin C<interface>
2316 =item B<Interface> I<Interface>
2318 Select this interface. By default these interfaces will then be collected. For
2319 a more detailed description see B<IgnoreSelected> below.
2321 =item B<IgnoreSelected> I<true>|I<false>
2323 If no configuration if given, the B<traffic>-plugin will collect data from
2324 all interfaces. This may not be practical, especially for loopback- and
2325 similar interfaces. Thus, you can use the B<Interface>-option to pick the
2326 interfaces you're interested in. Sometimes, however, it's easier/preferred
2327 to collect all interfaces I<except> a few ones. This option enables you to
2328 do that: By setting B<IgnoreSelected> to I<true> the effect of
2329 B<Interface> is inverted: All selected interfaces are ignored and all
2330 other interfaces are collected.
2334 =head2 Plugin C<ipmi>
2338 =item B<Sensor> I<Sensor>
2340 Selects sensors to collect or to ignore, depending on B<IgnoreSelected>.
2342 =item B<IgnoreSelected> I<true>|I<false>
2344 If no configuration if given, the B<ipmi> plugin will collect data from all
2345 sensors found of type "temperature", "voltage", "current" and "fanspeed".
2346 This option enables you to do that: By setting B<IgnoreSelected> to I<true>
2347 the effect of B<Sensor> is inverted: All selected sensors are ignored and
2348 all other sensors are collected.
2350 =item B<NotifySensorAdd> I<true>|I<false>
2352 If a sensor appears after initialization time of a minute a notification
2355 =item B<NotifySensorRemove> I<true>|I<false>
2357 If a sensor disappears a notification is sent.
2359 =item B<NotifySensorNotPresent> I<true>|I<false>
2361 If you have for example dual power supply and one of them is (un)plugged then
2362 a notification is sent.
2366 =head2 Plugin C<iptables>
2370 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
2372 Select the rules to count. If only I<Table> and I<Chain> are given, this plugin
2373 will collect the counters of all rules which have a comment-match. The comment
2374 is then used as type-instance.
2376 If I<Comment> or I<Number> is given, only the rule with the matching comment or
2377 the I<n>th rule will be collected. Again, the comment (or the number) will be
2378 used as the type-instance.
2380 If I<Name> is supplied, it will be used as the type-instance instead of the
2381 comment or the number.
2385 =head2 Plugin C<irq>
2391 Select this irq. By default these irqs will then be collected. For a more
2392 detailed description see B<IgnoreSelected> below.
2394 =item B<IgnoreSelected> I<true>|I<false>
2396 If no configuration if given, the B<irq>-plugin will collect data from all
2397 irqs. This may not be practical, especially if no interrupts happen. Thus, you
2398 can use the B<Irq>-option to pick the interrupt you're interested in.
2399 Sometimes, however, it's easier/preferred to collect all interrupts I<except> a
2400 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
2401 I<true> the effect of B<Irq> is inverted: All selected interrupts are ignored
2402 and all other interrupts are collected.
2406 =head2 Plugin C<java>
2408 The I<Java> plugin makes it possible to write extensions for collectd in Java.
2409 This section only discusses the syntax and semantic of the configuration
2410 options. For more in-depth information on the I<Java> plugin, please read
2411 L<collectd-java(5)>.
2416 JVMArg "-verbose:jni"
2417 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
2418 LoadPlugin "org.collectd.java.Foobar"
2419 <Plugin "org.collectd.java.Foobar">
2420 # To be parsed by the plugin
2424 Available configuration options:
2428 =item B<JVMArg> I<Argument>
2430 Argument that is to be passed to the I<Java Virtual Machine> (JVM). This works
2431 exactly the way the arguments to the I<java> binary on the command line work.
2432 Execute C<javaE<nbsp>--help> for details.
2434 Please note that B<all> these options must appear B<before> (i.E<nbsp>e. above)
2435 any other options! When another option is found, the JVM will be started and
2436 later options will have to be ignored!
2438 =item B<LoadPlugin> I<JavaClass>
2440 Instantiates a new I<JavaClass> object. The constructor of this object very
2441 likely then registers one or more callback methods with the server.
2443 See L<collectd-java(5)> for details.
2445 When the first such option is found, the virtual machine (JVM) is created. This
2446 means that all B<JVMArg> options must appear before (i.E<nbsp>e. above) all
2447 B<LoadPlugin> options!
2449 =item B<Plugin> I<Name>
2451 The entire block is passed to the Java plugin as an
2452 I<org.collectd.api.OConfigItem> object.
2454 For this to work, the plugin has to register a configuration callback first,
2455 see L<collectd-java(5)/"config callback">. This means, that the B<Plugin> block
2456 must appear after the appropriate B<LoadPlugin> block. Also note, that I<Name>
2457 depends on the (Java) plugin registering the callback and is completely
2458 independent from the I<JavaClass> argument passed to B<LoadPlugin>.
2462 =head2 Plugin C<load>
2464 The I<Load plugin> collects the system load. These numbers give a rough overview
2465 over the utilization of a machine. The system load is defined as the number of
2466 runnable tasks in the run-queue and is provided by many operating systems as a
2467 one, five or fifteen minute average.
2469 The following configuration options are available:
2473 =item B<ReportRelative> B<false>|B<true>
2475 When enabled, system load divided by number of available CPU cores is reported
2476 for intervals 1 min, 5 min and 15 min. Defaults to false.
2481 =head2 Plugin C<logfile>
2485 =item B<LogLevel> B<debug|info|notice|warning|err>
2487 Sets the log-level. If, for example, set to B<notice>, then all events with
2488 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
2490 Please note that B<debug> is only available if collectd has been compiled with
2493 =item B<File> I<File>
2495 Sets the file to write log messages to. The special strings B<stdout> and
2496 B<stderr> can be used to write to the standard output and standard error
2497 channels, respectively. This, of course, only makes much sense when I<collectd>
2498 is running in foreground- or non-daemon-mode.
2500 =item B<Timestamp> B<true>|B<false>
2502 Prefix all lines printed by the current time. Defaults to B<true>.
2504 =item B<PrintSeverity> B<true>|B<false>
2506 When enabled, all lines are prefixed by the severity of the log message, for
2507 example "warning". Defaults to B<false>.
2511 B<Note>: There is no need to notify the daemon after moving or removing the
2512 log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
2513 for each line it writes.
2515 =head2 Plugin C<log_logstash>
2517 The I<log logstash plugin> behaves like the logfile plugin but formats
2518 messages as JSON events for logstash to parse and input.
2522 =item B<LogLevel> B<debug|info|notice|warning|err>
2524 Sets the log-level. If, for example, set to B<notice>, then all events with
2525 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
2527 Please note that B<debug> is only available if collectd has been compiled with
2530 =item B<File> I<File>
2532 Sets the file to write log messages to. The special strings B<stdout> and
2533 B<stderr> can be used to write to the standard output and standard error
2534 channels, respectively. This, of course, only makes much sense when I<collectd>
2535 is running in foreground- or non-daemon-mode.
2539 B<Note>: There is no need to notify the daemon after moving or removing the
2540 log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
2541 for each line it writes.
2543 =head2 Plugin C<lpar>
2545 The I<LPAR plugin> reads CPU statistics of I<Logical Partitions>, a
2546 virtualization technique for IBM POWER processors. It takes into account CPU
2547 time stolen from or donated to a partition, in addition to the usual user,
2548 system, I/O statistics.
2550 The following configuration options are available:
2554 =item B<CpuPoolStats> B<false>|B<true>
2556 When enabled, statistics about the processor pool are read, too. The partition
2557 needs to have pool authority in order to be able to acquire this information.
2560 =item B<ReportBySerial> B<false>|B<true>
2562 If enabled, the serial of the physical machine the partition is currently
2563 running on is reported as I<hostname> and the logical hostname of the machine
2564 is reported in the I<plugin instance>. Otherwise, the logical hostname will be
2565 used (just like other plugins) and the I<plugin instance> will be empty.
2570 =head2 Plugin C<mbmon>
2572 The C<mbmon plugin> uses mbmon to retrieve temperature, voltage, etc.
2574 Be default collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>. The
2575 B<Host> and B<Port> options can be used to change these values, see below.
2576 C<mbmon> has to be running to work correctly. If C<mbmon> is not running
2577 timeouts may appear which may interfere with other statistics..
2579 C<mbmon> must be run with the -r option ("print TAG and Value format");
2580 Debian's F</etc/init.d/mbmon> script already does this, other people
2581 will need to ensure that this is the case.
2585 =item B<Host> I<Hostname>
2587 Hostname to connect to. Defaults to B<127.0.0.1>.
2589 =item B<Port> I<Port>
2591 TCP-Port to connect to. Defaults to B<411>.
2597 The C<md plugin> collects information from Linux Software-RAID devices (md).
2599 All reported values are of the type C<md_disks>. Reported type instances are
2600 I<active>, I<failed> (present but not operational), I<spare> (hot stand-by) and
2601 I<missing> (physically absent) disks.
2605 =item B<Device> I<Device>
2607 Select md devices based on device name. The I<device name> is the basename of
2608 the device, i.e. the name of the block device without the leading C</dev/>.
2609 See B<IgnoreSelected> for more details.
2611 =item B<IgnoreSelected> B<true>|B<false>
2613 Invert device selection: If set to B<true>, all md devices B<except> those
2614 listed using B<Device> are collected. If B<false> (the default), only those
2615 listed are collected. If no configuration is given, the B<md> plugin will
2616 collect data from all md devices.
2620 =head2 Plugin C<memcachec>
2622 The C<memcachec plugin> connects to a memcached server, queries one or more
2623 given I<pages> and parses the returned data according to user specification.
2624 The I<matches> used are the same as the matches used in the C<curl> and C<tail>
2627 In order to talk to the memcached server, this plugin uses the I<libmemcached>
2628 library. Please note that there is another library with a very similar name,
2629 libmemcache (notice the missing `d'), which is not applicable.
2631 Synopsis of the configuration:
2633 <Plugin "memcachec">
2634 <Page "plugin_instance">
2638 Regex "(\\d+) bytes sent"
2641 Instance "type_instance"
2646 The configuration options are:
2650 =item E<lt>B<Page> I<Name>E<gt>
2652 Each B<Page> block defines one I<page> to be queried from the memcached server.
2653 The block requires one string argument which is used as I<plugin instance>.
2655 =item B<Server> I<Address>
2657 Sets the server address to connect to when querying the page. Must be inside a
2662 When connected to the memcached server, asks for the page I<Key>.
2664 =item E<lt>B<Match>E<gt>
2666 Match blocks define which strings to look for and how matches substrings are
2667 interpreted. For a description of match blocks, please see L<"Plugin tail">.
2671 =head2 Plugin C<memcached>
2673 The B<memcached plugin> connects to a memcached server and queries statistics
2674 about cache utilization, memory and bandwidth used.
2675 L<http://www.danga.com/memcached/>
2677 <Plugin "memcached">
2679 Host "memcache.example.com"
2684 The plugin configuration consists of one or more B<Instance> blocks which
2685 specify one I<memcached> connection each. Within the B<Instance> blocks, the
2686 following options are allowed:
2690 =item B<Host> I<Hostname>
2692 Hostname to connect to. Defaults to B<127.0.0.1>.
2694 =item B<Port> I<Port>
2696 TCP-Port to connect to. Defaults to B<11211>.
2698 =item B<Socket> I<Path>
2700 Connect to I<memcached> using the UNIX domain socket at I<Path>. If this
2701 setting is given, the B<Host> and B<Port> settings are ignored.
2705 =head2 Plugin C<mic>
2707 The B<mic plugin> gathers CPU statistics, memory usage and temperatures from
2708 Intel's Many Integrated Core (MIC) systems.
2717 ShowTemperatures true
2720 IgnoreSelectedTemperature true
2725 IgnoreSelectedPower true
2728 The following options are valid inside the B<PluginE<nbsp>mic> block:
2732 =item B<ShowCPU> B<true>|B<false>
2734 If enabled (the default) a sum of the CPU usage across all cores is reported.
2736 =item B<ShowCPUCores> B<true>|B<false>
2738 If enabled (the default) per-core CPU usage is reported.
2740 =item B<ShowMemory> B<true>|B<false>
2742 If enabled (the default) the physical memory usage of the MIC system is
2745 =item B<ShowTemperatures> B<true>|B<false>
2747 If enabled (the default) various temperatures of the MIC system are reported.
2749 =item B<Temperature> I<Name>
2751 This option controls which temperatures are being reported. Whether matching
2752 temperatures are being ignored or I<only> matching temperatures are reported
2753 depends on the B<IgnoreSelectedTemperature> setting below. By default I<all>
2754 temperatures are reported.
2756 =item B<IgnoreSelectedTemperature> B<false>|B<true>
2758 Controls the behavior of the B<Temperature> setting above. If set to B<false>
2759 (the default) only temperatures matching a B<Temperature> option are reported
2760 or, if no B<Temperature> option is specified, all temperatures are reported. If
2761 set to B<true>, matching temperatures are I<ignored> and all other temperatures
2764 Known temperature names are:
2798 =item B<ShowPower> B<true>|B<false>
2800 If enabled (the default) various temperatures of the MIC system are reported.
2802 =item B<Power> I<Name>
2804 This option controls which power readings are being reported. Whether matching
2805 power readings are being ignored or I<only> matching power readings are reported
2806 depends on the B<IgnoreSelectedPower> setting below. By default I<all>
2807 power readings are reported.
2809 =item B<IgnoreSelectedPower> B<false>|B<true>
2811 Controls the behavior of the B<Power> setting above. If set to B<false>
2812 (the default) only power readings matching a B<Power> option are reported
2813 or, if no B<Power> option is specified, all power readings are reported. If
2814 set to B<true>, matching power readings are I<ignored> and all other power readings
2817 Known power names are:
2823 Total power utilization averaged over Time Window 0 (uWatts).
2827 Total power utilization averaged over Time Window 0 (uWatts).
2831 Instantaneous power (uWatts).
2835 Max instantaneous power (uWatts).
2839 PCI-E connector power (uWatts).
2843 2x3 connector power (uWatts).
2847 2x4 connector power (uWatts).
2855 Uncore rail (uVolts).
2859 Memory subsystem rail (uVolts).
2865 =head2 Plugin C<memory>
2867 The I<memory plugin> provides the following configuration options:
2871 =item B<ValuesAbsolute> B<true>|B<false>
2873 Enables or disables reporting of physical memory usage in absolute numbers,
2874 i.e. bytes. Defaults to B<true>.
2876 =item B<ValuesPercentage> B<false>|B<true>
2878 Enables or disables reporting of physical memory usage in percentages, e.g.
2879 percent of physical memory used. Defaults to B<false>.
2881 This is useful for deploying I<collectd> in a heterogeneous environment in
2882 which the sizes of physical memory vary.
2886 =head2 Plugin C<modbus>
2888 The B<modbus plugin> connects to a Modbus "slave" via Modbus/TCP or Modbus/RTU and
2889 reads register values. It supports reading single registers (unsigned 16E<nbsp>bit
2890 values), large integer values (unsigned 32E<nbsp>bit values) and floating point
2891 values (two registers interpreted as IEEE floats in big endian notation).
2895 <Data "voltage-input-1">
2898 RegisterCmd ReadHolding
2903 <Data "voltage-input-2">
2906 RegisterCmd ReadHolding
2911 <Data "supply-temperature-1">
2914 RegisterCmd ReadHolding
2919 <Host "modbus.example.com">
2920 Address "192.168.0.42"
2925 Instance "power-supply"
2926 Collect "voltage-input-1"
2927 Collect "voltage-input-2"
2932 Device "/dev/ttyUSB0"
2937 Instance "temperature"
2938 Collect "supply-temperature-1"
2944 =item E<lt>B<Data> I<Name>E<gt> blocks
2946 Data blocks define a mapping between register numbers and the "types" used by
2949 Within E<lt>DataE<nbsp>/E<gt> blocks, the following options are allowed:
2953 =item B<RegisterBase> I<Number>
2955 Configures the base register to read from the device. If the option
2956 B<RegisterType> has been set to B<Uint32> or B<Float>, this and the next
2957 register will be read (the register number is increased by one).
2959 =item B<RegisterType> B<Int16>|B<Int32>|B<Uint16>|B<Uint32>|B<Float>
2961 Specifies what kind of data is returned by the device. If the type is B<Int32>,
2962 B<Uint32> or B<Float>, two 16E<nbsp>bit registers will be read and the data is
2963 combined into one value. Defaults to B<Uint16>.
2965 =item B<RegisterCmd> B<ReadHolding>|B<ReadInput>
2967 Specifies register type to be collected from device. Works only with libmodbus
2968 2.9.2 or higher. Defaults to B<ReadHolding>.
2970 =item B<Type> I<Type>
2972 Specifies the "type" (data set) to use when dispatching the value to
2973 I<collectd>. Currently, only data sets with exactly one data source are
2976 =item B<Instance> I<Instance>
2978 Sets the type instance to use when dispatching the value to I<collectd>. If
2979 unset, an empty string (no type instance) is used.
2983 =item E<lt>B<Host> I<Name>E<gt> blocks
2985 Host blocks are used to specify to which hosts to connect and what data to read
2986 from their "slaves". The string argument I<Name> is used as hostname when
2987 dispatching the values to I<collectd>.
2989 Within E<lt>HostE<nbsp>/E<gt> blocks, the following options are allowed:
2993 =item B<Address> I<Hostname>
2995 For Modbus/TCP, specifies the node name (the actual network address) used to
2996 connect to the host. This may be an IP address or a hostname. Please note that
2997 the used I<libmodbus> library only supports IPv4 at the moment.
2999 =item B<Port> I<Service>
3001 for Modbus/TCP, specifies the port used to connect to the host. The port can
3002 either be given as a number or as a service name. Please note that the
3003 I<Service> argument must be a string, even if ports are given in their numerical
3004 form. Defaults to "502".
3006 =item B<Device> I<Devicenode>
3008 For Modbus/RTU, specifies the path to the serial device being used.
3010 =item B<Baudrate> I<Baudrate>
3012 For Modbus/RTU, specifies the baud rate of the serial device.
3013 Note, connections currently support only 8/N/1.
3015 =item B<Interval> I<Interval>
3017 Sets the interval (in seconds) in which the values will be collected from this
3018 host. By default the global B<Interval> setting will be used.
3020 =item E<lt>B<Slave> I<ID>E<gt>
3022 Over each connection, multiple Modbus devices may be reached. The slave ID
3023 is used to specify which device should be addressed. For each device you want
3024 to query, one B<Slave> block must be given.
3026 Within E<lt>SlaveE<nbsp>/E<gt> blocks, the following options are allowed:
3030 =item B<Instance> I<Instance>
3032 Specify the plugin instance to use when dispatching the values to I<collectd>.
3033 By default "slave_I<ID>" is used.
3035 =item B<Collect> I<DataName>
3037 Specifies which data to retrieve from the device. I<DataName> must be the same
3038 string as the I<Name> argument passed to a B<Data> block. You can specify this
3039 option multiple times to collect more than one value from a slave. At least one
3040 B<Collect> option is mandatory.
3048 =head2 Plugin C<mysql>
3050 The C<mysql plugin> requires B<mysqlclient> to be installed. It connects to
3051 one or more databases when started and keeps the connection up as long as
3052 possible. When the connection is interrupted for whatever reason it will try
3053 to re-connect. The plugin will complain loudly in case anything goes wrong.
3055 This plugin issues the MySQL C<SHOW STATUS> / C<SHOW GLOBAL STATUS> command
3056 and collects information about MySQL network traffic, executed statements,
3057 requests, the query cache and threads by evaluating the
3058 C<Bytes_{received,sent}>, C<Com_*>, C<Handler_*>, C<Qcache_*> and C<Threads_*>
3059 return values. Please refer to the B<MySQL reference manual>, I<5.1.6. Server
3060 Status Variables> for an explanation of these values.
3062 Optionally, master and slave statistics may be collected in a MySQL
3063 replication setup. In that case, information about the synchronization state
3064 of the nodes are collected by evaluating the C<Position> return value of the
3065 C<SHOW MASTER STATUS> command and the C<Seconds_Behind_Master>,
3066 C<Read_Master_Log_Pos> and C<Exec_Master_Log_Pos> return values of the
3067 C<SHOW SLAVE STATUS> command. See the B<MySQL reference manual>,
3068 I<12.5.5.21 SHOW MASTER STATUS Syntax> and
3069 I<12.5.5.31 SHOW SLAVE STATUS Syntax> for details.
3086 Socket "/var/run/mysql/mysqld.sock"
3088 SlaveNotifications true
3092 A B<Database> block defines one connection to a MySQL database. It accepts a
3093 single argument which specifies the name of the database. None of the other
3094 options are required. MySQL will use default values as documented in the
3095 section "mysql_real_connect()" in the B<MySQL reference manual>.
3099 =item B<Alias> I<Alias>
3101 Alias to use as sender instead of hostname when reporting. This may be useful
3102 when having cryptic hostnames.
3104 =item B<Host> I<Hostname>
3106 Hostname of the database server. Defaults to B<localhost>.
3108 =item B<User> I<Username>
3110 Username to use when connecting to the database. The user does not have to be
3111 granted any privileges (which is synonym to granting the C<USAGE> privilege),
3112 unless you want to collectd replication statistics (see B<MasterStats> and
3113 B<SlaveStats> below). In this case, the user needs the C<REPLICATION CLIENT>
3114 (or C<SUPER>) privileges. Else, any existing MySQL user will do.
3116 =item B<Password> I<Password>
3118 Password needed to log into the database.
3120 =item B<Database> I<Database>
3122 Select this database. Defaults to I<no database> which is a perfectly reasonable
3123 option for what this plugin does.
3125 =item B<Port> I<Port>
3127 TCP-port to connect to. The port must be specified in its numeric form, but it
3128 must be passed as a string nonetheless. For example:
3132 If B<Host> is set to B<localhost> (the default), this setting has no effect.
3133 See the documentation for the C<mysql_real_connect> function for details.
3135 =item B<Socket> I<Socket>
3137 Specifies the path to the UNIX domain socket of the MySQL server. This option
3138 only has any effect, if B<Host> is set to B<localhost> (the default).
3139 Otherwise, use the B<Port> option above. See the documentation for the
3140 C<mysql_real_connect> function for details.
3142 =item B<InnodbStats> I<true|false>
3144 If enabled, metrics about the InnoDB storage engine are collected.
3145 Disabled by default.
3147 =item B<MasterStats> I<true|false>
3149 =item B<SlaveStats> I<true|false>
3151 Enable the collection of master / slave statistics in a replication setup. In
3152 order to be able to get access to these statistics, the user needs special
3153 privileges. See the B<User> documentation above. Defaults to B<false>.
3155 =item B<SlaveNotifications> I<true|false>
3157 If enabled, the plugin sends a notification if the replication slave I/O and /
3158 or SQL threads are not running. Defaults to B<false>.
3160 =item B<ConnectTimeout> I<Seconds>
3162 Sets the connect timeout for the MySQL client.
3166 =head2 Plugin C<netapp>
3168 The netapp plugin can collect various performance and capacity information
3169 from a NetApp filer using the NetApp API.
3171 Please note that NetApp has a wide line of products and a lot of different
3172 software versions for each of these products. This plugin was developed for a
3173 NetApp FAS3040 running OnTap 7.2.3P8 and tested on FAS2050 7.3.1.1L1,
3174 FAS3140 7.2.5.1 and FAS3020 7.2.4P9. It I<should> work for most combinations of
3175 model and software version but it is very hard to test this.
3176 If you have used this plugin with other models and/or software version, feel
3177 free to send us a mail to tell us about the results, even if it's just a short
3180 To collect these data collectd will log in to the NetApp via HTTP(S) and HTTP
3181 basic authentication.
3183 B<Do not use a regular user for this!> Create a special collectd user with just
3184 the minimum of capabilities needed. The user only needs the "login-http-admin"
3185 capability as well as a few more depending on which data will be collected.
3186 Required capabilities are documented below.
3191 <Host "netapp1.example.com">
3215 IgnoreSelectedIO false
3217 IgnoreSelectedOps false
3218 GetLatency "volume0"
3219 IgnoreSelectedLatency false
3226 IgnoreSelectedCapacity false
3229 IgnoreSelectedSnapshot false
3257 The netapp plugin accepts the following configuration options:
3261 =item B<Host> I<Name>
3263 A host block defines one NetApp filer. It will appear in collectd with the name
3264 you specify here which does not have to be its real name nor its hostname (see
3265 the B<Address> option below).
3267 =item B<VFiler> I<Name>
3269 A B<VFiler> block may only be used inside a host block. It accepts all the
3270 same options as the B<Host> block (except for cascaded B<VFiler> blocks) and
3271 will execute all NetApp API commands in the context of the specified
3272 VFiler(R). It will appear in collectd with the name you specify here which
3273 does not have to be its real name. The VFiler name may be specified using the
3274 B<VFilerName> option. If this is not specified, it will default to the name
3277 The VFiler block inherits all connection related settings from the surrounding
3278 B<Host> block (which appear before the B<VFiler> block) but they may be
3279 overwritten inside the B<VFiler> block.
3281 This feature is useful, for example, when using a VFiler as SnapVault target
3282 (supported since OnTap 8.1). In that case, the SnapVault statistics are not
3283 available in the host filer (vfiler0) but only in the respective VFiler
3286 =item B<Protocol> B<httpd>|B<http>
3288 The protocol collectd will use to query this host.
3296 Valid options: http, https
3298 =item B<Address> I<Address>
3300 The hostname or IP address of the host.
3306 Default: The "host" block's name.
3308 =item B<Port> I<Port>
3310 The TCP port to connect to on the host.
3316 Default: 80 for protocol "http", 443 for protocol "https"
3318 =item B<User> I<User>
3320 =item B<Password> I<Password>
3322 The username and password to use to login to the NetApp.
3328 =item B<VFilerName> I<Name>
3330 The name of the VFiler in which context to execute API commands. If not
3331 specified, the name provided to the B<VFiler> block will be used instead.
3337 Default: name of the B<VFiler> block
3339 B<Note:> This option may only be used inside B<VFiler> blocks.
3341 =item B<Interval> I<Interval>
3347 The following options decide what kind of data will be collected. You can
3348 either use them as a block and fine tune various parameters inside this block,
3349 use them as a single statement to just accept all default values, or omit it to
3350 not collect any data.
3352 The following options are valid inside all blocks:
3356 =item B<Interval> I<Seconds>
3358 Collect the respective statistics every I<Seconds> seconds. Defaults to the
3359 host specific setting.
3363 =head3 The System block
3365 This will collect various performance data about the whole system.
3367 B<Note:> To get this data the collectd user needs the
3368 "api-perf-object-get-instances" capability.
3372 =item B<Interval> I<Seconds>
3374 Collect disk statistics every I<Seconds> seconds.
3376 =item B<GetCPULoad> B<true>|B<false>
3378 If you set this option to true the current CPU usage will be read. This will be
3379 the average usage between all CPUs in your NetApp without any information about
3382 B<Note:> These are the same values that the NetApp CLI command "sysstat"
3383 returns in the "CPU" field.
3391 Result: Two value lists of type "cpu", and type instances "idle" and "system".
3393 =item B<GetInterfaces> B<true>|B<false>
3395 If you set this option to true the current traffic of the network interfaces
3396 will be read. This will be the total traffic over all interfaces of your NetApp
3397 without any information about individual interfaces.
3399 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
3400 in the "Net kB/s" field.
3410 Result: One value list of type "if_octects".
3412 =item B<GetDiskIO> B<true>|B<false>
3414 If you set this option to true the current IO throughput will be read. This
3415 will be the total IO of your NetApp without any information about individual
3416 disks, volumes or aggregates.
3418 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
3419 in the "DiskE<nbsp>kB/s" field.
3427 Result: One value list of type "disk_octets".
3429 =item B<GetDiskOps> B<true>|B<false>
3431 If you set this option to true the current number of HTTP, NFS, CIFS, FCP,
3432 iSCSI, etc. operations will be read. This will be the total number of
3433 operations on your NetApp without any information about individual volumes or
3436 B<Note:> These are the same values that the NetApp CLI command "sysstat"
3437 returns in the "NFS", "CIFS", "HTTP", "FCP" and "iSCSI" fields.
3445 Result: A variable number of value lists of type "disk_ops_complex". Each type
3446 of operation will result in one value list with the name of the operation as
3451 =head3 The WAFL block
3453 This will collect various performance data about the WAFL file system. At the
3454 moment this just means cache performance.
3456 B<Note:> To get this data the collectd user needs the
3457 "api-perf-object-get-instances" capability.
3459 B<Note:> The interface to get these values is classified as "Diagnostics" by
3460 NetApp. This means that it is not guaranteed to be stable even between minor
3465 =item B<Interval> I<Seconds>
3467 Collect disk statistics every I<Seconds> seconds.
3469 =item B<GetNameCache> B<true>|B<false>
3477 Result: One value list of type "cache_ratio" and type instance
3480 =item B<GetDirCache> B<true>|B<false>
3488 Result: One value list of type "cache_ratio" and type instance "find_dir_hit".
3490 =item B<GetInodeCache> B<true>|B<false>
3498 Result: One value list of type "cache_ratio" and type instance
3501 =item B<GetBufferCache> B<true>|B<false>
3503 B<Note:> This is the same value that the NetApp CLI command "sysstat" returns
3504 in the "Cache hit" field.
3512 Result: One value list of type "cache_ratio" and type instance "buf_hash_hit".
3516 =head3 The Disks block
3518 This will collect performance data about the individual disks in the NetApp.
3520 B<Note:> To get this data the collectd user needs the
3521 "api-perf-object-get-instances" capability.
3525 =item B<Interval> I<Seconds>
3527 Collect disk statistics every I<Seconds> seconds.
3529 =item B<GetBusy> B<true>|B<false>
3531 If you set this option to true the busy time of all disks will be calculated
3532 and the value of the busiest disk in the system will be written.
3534 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
3535 in the "Disk util" field. Probably.
3543 Result: One value list of type "percent" and type instance "disk_busy".
3547 =head3 The VolumePerf block
3549 This will collect various performance data about the individual volumes.
3551 You can select which data to collect about which volume using the following
3552 options. They follow the standard ignorelist semantic.
3554 B<Note:> To get this data the collectd user needs the
3555 I<api-perf-object-get-instances> capability.
3559 =item B<Interval> I<Seconds>
3561 Collect volume performance data every I<Seconds> seconds.
3563 =item B<GetIO> I<Volume>
3565 =item B<GetOps> I<Volume>
3567 =item B<GetLatency> I<Volume>
3569 Select the given volume for IO, operations or latency statistics collection.
3570 The argument is the name of the volume without the C</vol/> prefix.
3572 Since the standard ignorelist functionality is used here, you can use a string
3573 starting and ending with a slash to specify regular expression matching: To
3574 match the volumes "vol0", "vol2" and "vol7", you can use this regular
3577 GetIO "/^vol[027]$/"
3579 If no regular expression is specified, an exact match is required. Both,
3580 regular and exact matching are case sensitive.
3582 If no volume was specified at all for either of the three options, that data
3583 will be collected for all available volumes.
3585 =item B<IgnoreSelectedIO> B<true>|B<false>
3587 =item B<IgnoreSelectedOps> B<true>|B<false>
3589 =item B<IgnoreSelectedLatency> B<true>|B<false>
3591 When set to B<true>, the volumes selected for IO, operations or latency
3592 statistics collection will be ignored and the data will be collected for all
3595 When set to B<false>, data will only be collected for the specified volumes and
3596 all other volumes will be ignored.
3598 If no volumes have been specified with the above B<Get*> options, all volumes
3599 will be collected regardless of the B<IgnoreSelected*> option.
3601 Defaults to B<false>
3605 =head3 The VolumeUsage block
3607 This will collect capacity data about the individual volumes.
3609 B<Note:> To get this data the collectd user needs the I<api-volume-list-info>
3614 =item B<Interval> I<Seconds>
3616 Collect volume usage statistics every I<Seconds> seconds.
3618 =item B<GetCapacity> I<VolumeName>
3620 The current capacity of the volume will be collected. This will result in two
3621 to four value lists, depending on the configuration of the volume. All data
3622 sources are of type "df_complex" with the name of the volume as
3625 There will be type_instances "used" and "free" for the number of used and
3626 available bytes on the volume. If the volume has some space reserved for
3627 snapshots, a type_instance "snap_reserved" will be available. If the volume
3628 has SIS enabled, a type_instance "sis_saved" will be available. This is the
3629 number of bytes saved by the SIS feature.
3631 B<Note:> The current NetApp API has a bug that results in this value being
3632 reported as a 32E<nbsp>bit number. This plugin tries to guess the correct
3633 number which works most of the time. If you see strange values here, bug
3634 NetApp support to fix this.
3636 Repeat this option to specify multiple volumes.
3638 =item B<IgnoreSelectedCapacity> B<true>|B<false>
3640 Specify whether to collect only the volumes selected by the B<GetCapacity>
3641 option or to ignore those volumes. B<IgnoreSelectedCapacity> defaults to
3642 B<false>. However, if no B<GetCapacity> option is specified at all, all
3643 capacities will be selected anyway.
3645 =item B<GetSnapshot> I<VolumeName>
3647 Select volumes from which to collect snapshot information.
3649 Usually, the space used for snapshots is included in the space reported as
3650 "used". If snapshot information is collected as well, the space used for
3651 snapshots is subtracted from the used space.
3653 To make things even more interesting, it is possible to reserve space to be
3654 used for snapshots. If the space required for snapshots is less than that
3655 reserved space, there is "reserved free" and "reserved used" space in addition
3656 to "free" and "used". If the space required for snapshots exceeds the reserved
3657 space, that part allocated in the normal space is subtracted from the "used"
3660 Repeat this option to specify multiple volumes.
3662 =item B<IgnoreSelectedSnapshot>
3664 Specify whether to collect only the volumes selected by the B<GetSnapshot>
3665 option or to ignore those volumes. B<IgnoreSelectedSnapshot> defaults to
3666 B<false>. However, if no B<GetSnapshot> option is specified at all, all
3667 capacities will be selected anyway.
3671 =head3 The Quota block
3673 This will collect (tree) quota statistics (used disk space and number of used
3674 files). This mechanism is useful to get usage information for single qtrees.
3675 In case the quotas are not used for any other purpose, an entry similar to the
3676 following in C</etc/quotas> would be sufficient:
3678 /vol/volA/some_qtree tree - - - - -
3680 After adding the entry, issue C<quota on -w volA> on the NetApp filer.
3684 =item B<Interval> I<Seconds>
3686 Collect SnapVault(R) statistics every I<Seconds> seconds.
3690 =head3 The SnapVault block
3692 This will collect statistics about the time and traffic of SnapVault(R)
3697 =item B<Interval> I<Seconds>
3699 Collect SnapVault(R) statistics every I<Seconds> seconds.
3703 =head2 Plugin C<netlink>
3705 The C<netlink> plugin uses a netlink socket to query the Linux kernel about
3706 statistics of various interface and routing aspects.
3710 =item B<Interface> I<Interface>
3712 =item B<VerboseInterface> I<Interface>
3714 Instruct the plugin to collect interface statistics. This is basically the same
3715 as the statistics provided by the C<interface> plugin (see above) but
3716 potentially much more detailed.
3718 When configuring with B<Interface> only the basic statistics will be collected,
3719 namely octets, packets, and errors. These statistics are collected by
3720 the C<interface> plugin, too, so using both at the same time is no benefit.
3722 When configured with B<VerboseInterface> all counters B<except> the basic ones,
3723 so that no data needs to be collected twice if you use the C<interface> plugin.
3724 This includes dropped packets, received multicast packets, collisions and a
3725 whole zoo of differentiated RX and TX errors. You can try the following command
3726 to get an idea of what awaits you:
3730 If I<Interface> is B<All>, all interfaces will be selected.
3732 =item B<QDisc> I<Interface> [I<QDisc>]
3734 =item B<Class> I<Interface> [I<Class>]
3736 =item B<Filter> I<Interface> [I<Filter>]
3738 Collect the octets and packets that pass a certain qdisc, class or filter.
3740 QDiscs and classes are identified by their type and handle (or classid).
3741 Filters don't necessarily have a handle, therefore the parent's handle is used.
3742 The notation used in collectd differs from that used in tc(1) in that it
3743 doesn't skip the major or minor number if it's zero and doesn't print special
3744 ids by their name. So, for example, a qdisc may be identified by
3745 C<pfifo_fast-1:0> even though the minor number of B<all> qdiscs is zero and
3746 thus not displayed by tc(1).
3748 If B<QDisc>, B<Class>, or B<Filter> is given without the second argument,
3749 i.E<nbsp>.e. without an identifier, all qdiscs, classes, or filters that are
3750 associated with that interface will be collected.
3752 Since a filter itself doesn't necessarily have a handle, the parent's handle is
3753 used. This may lead to problems when more than one filter is attached to a
3754 qdisc or class. This isn't nice, but we don't know how this could be done any
3755 better. If you have a idea, please don't hesitate to tell us.
3757 As with the B<Interface> option you can specify B<All> as the interface,
3758 meaning all interfaces.
3760 Here are some examples to help you understand the above text more easily:
3763 VerboseInterface "All"
3764 QDisc "eth0" "pfifo_fast-1:0"
3766 Class "ppp0" "htb-1:10"
3767 Filter "ppp0" "u32-1:0"
3770 =item B<IgnoreSelected>
3772 The behavior is the same as with all other similar plugins: If nothing is
3773 selected at all, everything is collected. If some things are selected using the
3774 options described above, only these statistics are collected. If you set
3775 B<IgnoreSelected> to B<true>, this behavior is inverted, i.E<nbsp>e. the
3776 specified statistics will not be collected.
3780 =head2 Plugin C<network>
3782 The Network plugin sends data to a remote instance of collectd, receives data
3783 from a remote instance, or both at the same time. Data which has been received
3784 from the network is usually not transmitted again, but this can be activated, see
3785 the B<Forward> option below.
3787 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
3788 multicast group is C<239.192.74.66>. The default I<UDP> port is B<25826>.
3790 Both, B<Server> and B<Listen> can be used as single option or as block. When
3791 used as block, given options are valid for this socket only. The following
3792 example will export the metrics twice: Once to an "internal" server (without
3793 encryption and signing) and one to an external server (with cryptographic
3797 # Export to an internal server
3798 # (demonstrates usage without additional options)
3799 Server "collectd.internal.tld"
3801 # Export to an external server
3802 # (demonstrates usage with signature options)
3803 <Server "collectd.external.tld">
3804 SecurityLevel "sign"
3805 Username "myhostname"
3812 =item B<E<lt>Server> I<Host> [I<Port>]B<E<gt>>
3814 The B<Server> statement/block sets the server to send datagrams to. The
3815 statement may occur multiple times to send each datagram to multiple
3818 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. The
3819 optional second argument specifies a port number or a service name. If not
3820 given, the default, B<25826>, is used.
3822 The following options are recognized within B<Server> blocks:
3826 =item B<SecurityLevel> B<Encrypt>|B<Sign>|B<None>
3828 Set the security you require for network communication. When the security level
3829 has been set to B<Encrypt>, data sent over the network will be encrypted using
3830 I<AES-256>. The integrity of encrypted packets is ensured using I<SHA-1>. When
3831 set to B<Sign>, transmitted data is signed using the I<HMAC-SHA-256> message
3832 authentication code. When set to B<None>, data is sent without any security.
3834 This feature is only available if the I<network> plugin was linked with
3837 =item B<Username> I<Username>
3839 Sets the username to transmit. This is used by the server to lookup the
3840 password. See B<AuthFile> below. All security levels except B<None> require
3843 This feature is only available if the I<network> plugin was linked with
3846 =item B<Password> I<Password>
3848 Sets a password (shared secret) for this socket. All security levels except
3849 B<None> require this setting.
3851 This feature is only available if the I<network> plugin was linked with
3854 =item B<Interface> I<Interface name>
3856 Set the outgoing interface for IP packets. This applies at least
3857 to IPv6 packets and if possible to IPv4. If this option is not applicable,
3858 undefined or a non-existent interface name is specified, the default
3859 behavior is to let the kernel choose the appropriate interface. Be warned
3860 that the manual selection of an interface for unicast traffic is only
3861 necessary in rare cases.
3863 =item B<ResolveInterval> I<Seconds>
3865 Sets the interval at which to re-resolve the DNS for the I<Host>. This is
3866 useful to force a regular DNS lookup to support a high availability setup. If
3867 not specified, re-resolves are never attempted.
3871 =item B<E<lt>Listen> I<Host> [I<Port>]B<E<gt>>
3873 The B<Listen> statement sets the interfaces to bind to. When multiple
3874 statements are found the daemon will bind to multiple interfaces.
3876 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
3877 the argument is a multicast address the daemon will join that multicast group.
3878 The optional second argument specifies a port number or a service name. If not
3879 given, the default, B<25826>, is used.
3881 The following options are recognized within C<E<lt>ListenE<gt>> blocks:
3885 =item B<SecurityLevel> B<Encrypt>|B<Sign>|B<None>
3887 Set the security you require for network communication. When the security level
3888 has been set to B<Encrypt>, only encrypted data will be accepted. The integrity
3889 of encrypted packets is ensured using I<SHA-1>. When set to B<Sign>, only
3890 signed and encrypted data is accepted. When set to B<None>, all data will be
3891 accepted. If an B<AuthFile> option was given (see below), encrypted data is
3892 decrypted if possible.
3894 This feature is only available if the I<network> plugin was linked with
3897 =item B<AuthFile> I<Filename>
3899 Sets a file in which usernames are mapped to passwords. These passwords are
3900 used to verify signatures and to decrypt encrypted network packets. If
3901 B<SecurityLevel> is set to B<None>, this is optional. If given, signed data is
3902 verified and encrypted packets are decrypted. Otherwise, signed data is
3903 accepted without checking the signature and encrypted data cannot be decrypted.
3904 For the other security levels this option is mandatory.
3906 The file format is very simple: Each line consists of a username followed by a
3907 colon and any number of spaces followed by the password. To demonstrate, an
3908 example file could look like this:
3913 Each time a packet is received, the modification time of the file is checked
3914 using L<stat(2)>. If the file has been changed, the contents is re-read. While
3915 the file is being read, it is locked using L<fcntl(2)>.
3917 =item B<Interface> I<Interface name>
3919 Set the incoming interface for IP packets explicitly. This applies at least
3920 to IPv6 packets and if possible to IPv4. If this option is not applicable,
3921 undefined or a non-existent interface name is specified, the default
3922 behavior is, to let the kernel choose the appropriate interface. Thus incoming
3923 traffic gets only accepted, if it arrives on the given interface.
3927 =item B<TimeToLive> I<1-255>
3929 Set the time-to-live of sent packets. This applies to all, unicast and
3930 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
3931 That means that multicast packets will be sent with a TTL of C<1> (one) on most
3934 =item B<MaxPacketSize> I<1024-65535>
3936 Set the maximum size for datagrams received over the network. Packets larger
3937 than this will be truncated. Defaults to 1452E<nbsp>bytes, which is the maximum
3938 payload size that can be transmitted in one Ethernet frame using IPv6E<nbsp>/
3941 On the server side, this limit should be set to the largest value used on
3942 I<any> client. Likewise, the value on the client must not be larger than the
3943 value on the server, or data will be lost.
3945 B<Compatibility:> Versions prior to I<versionE<nbsp>4.8> used a fixed sized
3946 buffer of 1024E<nbsp>bytes. Versions I<4.8>, I<4.9> and I<4.10> used a default
3947 value of 1024E<nbsp>bytes to avoid problems when sending data to an older
3950 =item B<Forward> I<true|false>
3952 If set to I<true>, write packets that were received via the network plugin to
3953 the sending sockets. This should only be activated when the B<Listen>- and
3954 B<Server>-statements differ. Otherwise packets may be send multiple times to
3955 the same multicast group. While this results in more network traffic than
3956 necessary it's not a huge problem since the plugin has a duplicate detection,
3957 so the values will not loop.
3959 =item B<ReportStats> B<true>|B<false>
3961 The network plugin cannot only receive and send statistics, it can also create
3962 statistics about itself. Collected data included the number of received and
3963 sent octets and packets, the length of the receive queue and the number of
3964 values handled. When set to B<true>, the I<Network plugin> will make these
3965 statistics available. Defaults to B<false>.
3969 =head2 Plugin C<nginx>
3971 This plugin collects the number of connections and requests handled by the
3972 C<nginx daemon> (speak: engineE<nbsp>X), a HTTP and mail server/proxy. It
3973 queries the page provided by the C<ngx_http_stub_status_module> module, which
3974 isn't compiled by default. Please refer to
3975 L<http://wiki.codemongers.com/NginxStubStatusModule> for more information on
3976 how to compile and configure nginx and this module.
3978 The following options are accepted by the C<nginx plugin>:
3982 =item B<URL> I<http://host/nginx_status>
3984 Sets the URL of the C<ngx_http_stub_status_module> output.
3986 =item B<User> I<Username>
3988 Optional user name needed for authentication.
3990 =item B<Password> I<Password>
3992 Optional password needed for authentication.
3994 =item B<VerifyPeer> B<true|false>
3996 Enable or disable peer SSL certificate verification. See
3997 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
3999 =item B<VerifyHost> B<true|false>
4001 Enable or disable peer host name verification. If enabled, the plugin checks
4002 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
4003 certificate matches the host name provided by the B<URL> option. If this
4004 identity check fails, the connection is aborted. Obviously, only works when
4005 connecting to a SSL enabled server. Enabled by default.
4007 =item B<CACert> I<File>
4009 File that holds one or more SSL certificates. If you want to use HTTPS you will
4010 possibly need this option. What CA certificates come bundled with C<libcurl>
4011 and are checked by default depends on the distribution you use.
4015 =head2 Plugin C<notify_desktop>
4017 This plugin sends a desktop notification to a notification daemon, as defined
4018 in the Desktop Notification Specification. To actually display the
4019 notifications, B<notification-daemon> is required and B<collectd> has to be
4020 able to access the X server (i.E<nbsp>e., the C<DISPLAY> and C<XAUTHORITY>
4021 environment variables have to be set correctly) and the D-Bus message bus.
4023 The Desktop Notification Specification can be found at
4024 L<http://www.galago-project.org/specs/notification/>.
4028 =item B<OkayTimeout> I<timeout>
4030 =item B<WarningTimeout> I<timeout>
4032 =item B<FailureTimeout> I<timeout>
4034 Set the I<timeout>, in milliseconds, after which to expire the notification
4035 for C<OKAY>, C<WARNING> and C<FAILURE> severities respectively. If zero has
4036 been specified, the displayed notification will not be closed at all - the
4037 user has to do so herself. These options default to 5000. If a negative number
4038 has been specified, the default is used as well.
4042 =head2 Plugin C<notify_email>
4044 The I<notify_email> plugin uses the I<ESMTP> library to send notifications to a
4045 configured email address.
4047 I<libESMTP> is available from L<http://www.stafford.uklinux.net/libesmtp/>.
4049 Available configuration options:
4053 =item B<From> I<Address>
4055 Email address from which the emails should appear to come from.
4057 Default: C<root@localhost>
4059 =item B<Recipient> I<Address>
4061 Configures the email address(es) to which the notifications should be mailed.
4062 May be repeated to send notifications to multiple addresses.
4064 At least one B<Recipient> must be present for the plugin to work correctly.
4066 =item B<SMTPServer> I<Hostname>
4068 Hostname of the SMTP server to connect to.
4070 Default: C<localhost>
4072 =item B<SMTPPort> I<Port>
4074 TCP port to connect to.
4078 =item B<SMTPUser> I<Username>
4080 Username for ASMTP authentication. Optional.
4082 =item B<SMTPPassword> I<Password>
4084 Password for ASMTP authentication. Optional.
4086 =item B<Subject> I<Subject>
4088 Subject-template to use when sending emails. There must be exactly two
4089 string-placeholders in the subject, given in the standard I<printf(3)> syntax,
4090 i.E<nbsp>e. C<%s>. The first will be replaced with the severity, the second
4093 Default: C<Collectd notify: %s@%s>
4097 =head2 Plugin C<ntpd>
4101 =item B<Host> I<Hostname>
4103 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
4105 =item B<Port> I<Port>
4107 UDP-Port to connect to. Defaults to B<123>.
4109 =item B<ReverseLookups> B<true>|B<false>
4111 Sets whether or not to perform reverse lookups on peers. Since the name or
4112 IP-address may be used in a filename it is recommended to disable reverse
4113 lookups. The default is to do reverse lookups to preserve backwards
4114 compatibility, though.
4116 =item B<IncludeUnitID> B<true>|B<false>
4118 When a peer is a refclock, include the unit ID in the I<type instance>.
4119 Defaults to B<false> for backward compatibility.
4121 If two refclock peers use the same driver and this is B<false>, the plugin will
4122 try to write simultaneous measurements from both to the same type instance.
4123 This will result in error messages in the log and only one set of measurements
4128 =head2 Plugin C<nut>
4132 =item B<UPS> I<upsname>B<@>I<hostname>[B<:>I<port>]
4134 Add a UPS to collect data from. The format is identical to the one accepted by
4139 =head2 Plugin C<olsrd>
4141 The I<olsrd> plugin connects to the TCP port opened by the I<txtinfo> plugin of
4142 the Optimized Link State Routing daemon and reads information about the current
4143 state of the meshed network.
4145 The following configuration options are understood:
4149 =item B<Host> I<Host>
4151 Connect to I<Host>. Defaults to B<"localhost">.
4153 =item B<Port> I<Port>
4155 Specifies the port to connect to. This must be a string, even if you give the
4156 port as a number rather than a service name. Defaults to B<"2006">.
4158 =item B<CollectLinks> B<No>|B<Summary>|B<Detail>
4160 Specifies what information to collect about links, i.E<nbsp>e. direct
4161 connections of the daemon queried. If set to B<No>, no information is
4162 collected. If set to B<Summary>, the number of links and the average of all
4163 I<link quality> (LQ) and I<neighbor link quality> (NLQ) values is calculated.
4164 If set to B<Detail> LQ and NLQ are collected per link.
4166 Defaults to B<Detail>.
4168 =item B<CollectRoutes> B<No>|B<Summary>|B<Detail>
4170 Specifies what information to collect about routes of the daemon queried. If
4171 set to B<No>, no information is collected. If set to B<Summary>, the number of
4172 routes and the average I<metric> and I<ETX> is calculated. If set to B<Detail>
4173 metric and ETX are collected per route.
4175 Defaults to B<Summary>.
4177 =item B<CollectTopology> B<No>|B<Summary>|B<Detail>
4179 Specifies what information to collect about the global topology. If set to
4180 B<No>, no information is collected. If set to B<Summary>, the number of links
4181 in the entire topology and the average I<link quality> (LQ) is calculated.
4182 If set to B<Detail> LQ and NLQ are collected for each link in the entire topology.
4184 Defaults to B<Summary>.
4188 =head2 Plugin C<onewire>
4190 B<EXPERIMENTAL!> See notes below.
4192 The C<onewire> plugin uses the B<owcapi> library from the B<owfs> project
4193 L<http://owfs.org/> to read sensors connected via the onewire bus.
4195 It can be used in two possible modes - standard or advanced.
4197 In the standard mode only temperature sensors (sensors with the family code
4198 C<10>, C<22> and C<28> - e.g. DS1820, DS18S20, DS1920) can be read. If you have
4199 other sensors you would like to have included, please send a sort request to
4200 the mailing list. You can select sensors to be read or to be ignored depending
4201 on the option B<IgnoreSelected>). When no list is provided the whole bus is
4202 walked and all sensors are read.
4204 Hubs (the DS2409 chips) are working, but read the note, why this plugin is
4205 experimental, below.
4207 In the advanced mode you can configure any sensor to be read (only numerical
4208 value) using full OWFS path (e.g. "/uncached/10.F10FCA000800/temperature").
4209 In this mode you have to list all the sensors. Neither default bus walk nor
4210 B<IgnoreSelected> are used here. Address and type (file) is extracted from
4211 the path automatically and should produce compatible structure with the "standard"
4212 mode (basically the path is expected as for example
4213 "/uncached/10.F10FCA000800/temperature" where it would extract address part
4214 "F10FCA000800" and the rest after the slash is considered the type - here
4216 There are two advantages to this mode - you can access virtually any sensor
4217 (not just temperature), select whether to use cached or directly read values
4218 and it is slighlty faster. The downside is more complex configuration.
4220 The two modes are distinguished automatically by the format of the address.
4221 It is not possible to mix the two modes. Once a full path is detected in any
4222 B<Sensor> then the whole addressing (all sensors) is considered to be this way
4223 (and as standard addresses will fail parsing they will be ignored).
4227 =item B<Device> I<Device>
4229 Sets the device to read the values from. This can either be a "real" hardware
4230 device, such as a serial port or an USB port, or the address of the
4231 L<owserver(1)> socket, usually B<localhost:4304>.
4233 Though the documentation claims to automatically recognize the given address
4234 format, with versionE<nbsp>2.7p4 we had to specify the type explicitly. So
4235 with that version, the following configuration worked for us:
4238 Device "-s localhost:4304"
4241 This directive is B<required> and does not have a default value.
4243 =item B<Sensor> I<Sensor>
4245 In the standard mode selects sensors to collect or to ignore
4246 (depending on B<IgnoreSelected>, see below). Sensors are specified without
4247 the family byte at the beginning, so you have to use for example C<F10FCA000800>,
4248 and B<not> include the leading C<10.> family byte and point.
4249 When no B<Sensor> is configured the whole Onewire bus is walked and all supported
4250 sensors (see above) are read.
4252 In the advanced mode the B<Sensor> specifies full OWFS path - e.g.
4253 C</uncached/10.F10FCA000800/temperature> (or when cached values are OK
4254 C</10.F10FCA000800/temperature>). B<IgnoreSelected> is not used.
4256 As there can be multiple devices on the bus you can list multiple sensor (use
4257 multiple B<Sensor> elements).
4259 =item B<IgnoreSelected> I<true>|I<false>
4261 If no configuration is given, the B<onewire> plugin will collect data from all
4262 sensors found. This may not be practical, especially if sensors are added and
4263 removed regularly. Sometimes, however, it's easier/preferred to collect only
4264 specific sensors or all sensors I<except> a few specified ones. This option
4265 enables you to do that: By setting B<IgnoreSelected> to I<true> the effect of
4266 B<Sensor> is inverted: All selected interfaces are ignored and all other
4267 interfaces are collected.
4269 Used only in the standard mode - see above.
4271 =item B<Interval> I<Seconds>
4273 Sets the interval in which all sensors should be read. If not specified, the
4274 global B<Interval> setting is used.
4278 B<EXPERIMENTAL!> The C<onewire> plugin is experimental, because it doesn't yet
4279 work with big setups. It works with one sensor being attached to one
4280 controller, but as soon as you throw in a couple more senors and maybe a hub
4281 or two, reading all values will take more than ten seconds (the default
4282 interval). We will probably add some separate thread for reading the sensors
4283 and some cache or something like that, but it's not done yet. We will try to
4284 maintain backwards compatibility in the future, but we can't promise. So in
4285 short: If it works for you: Great! But keep in mind that the config I<might>
4286 change, though this is unlikely. Oh, and if you want to help improving this
4287 plugin, just send a short notice to the mailing list. ThanksE<nbsp>:)
4289 =head2 Plugin C<openldap>
4291 To use the C<openldap> plugin you first need to configure the I<OpenLDAP>
4292 server correctly. The backend database C<monitor> needs to be loaded and
4293 working. See slapd-monitor(5) for the details.
4295 The configuration of the C<openldap> plugin consists of one or more B<Instance>
4296 blocks. Each block requires one string argument as the instance name. For
4301 URL "ldap://localhost/"
4304 URL "ldaps://localhost/"
4308 The instance name will be used as the I<plugin instance>. To emulate the old
4309 (versionE<nbsp>4) behavior, you can use an empty string (""). In order for the
4310 plugin to work correctly, each instance name must be unique. This is not
4311 enforced by the plugin and it is your responsibility to ensure it is.
4313 The following options are accepted within each B<Instance> block:
4317 =item B<URL> I<ldap://host/binddn>
4319 Sets the URL to use to connect to the I<OpenLDAP> server. This option is
4322 =item B<StartTLS> B<true|false>
4324 Defines whether TLS must be used when connecting to the I<OpenLDAP> server.
4325 Disabled by default.
4327 =item B<VerifyHost> B<true|false>
4329 Enables or disables peer host name verification. If enabled, the plugin checks
4330 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
4331 certificate matches the host name provided by the B<URL> option. If this
4332 identity check fails, the connection is aborted. Enabled by default.
4334 =item B<CACert> I<File>
4336 File that holds one or more SSL certificates. If you want to use TLS/SSL you
4337 may possibly need this option. What CA certificates are checked by default
4338 depends on the distribution you use and can be changed with the usual ldap
4339 client configuration mechanisms. See ldap.conf(5) for the details.
4341 =item B<Timeout> I<Seconds>
4343 Sets the timeout value for ldap operations. Defaults to B<-1> which results in
4344 an infinite timeout.
4346 =item B<Version> I<Version>
4348 An integer which sets the LDAP protocol version number to use when connecting
4349 to the I<OpenLDAP> server. Defaults to B<3> for using I<LDAPv3>.
4353 =head2 Plugin C<openvpn>
4355 The OpenVPN plugin reads a status file maintained by OpenVPN and gathers
4356 traffic statistics about connected clients.
4358 To set up OpenVPN to write to the status file periodically, use the
4359 B<--status> option of OpenVPN. Since OpenVPN can write two different formats,
4360 you need to set the required format, too. This is done by setting
4361 B<--status-version> to B<2>.
4363 So, in a nutshell you need:
4365 openvpn $OTHER_OPTIONS \
4366 --status "/var/run/openvpn-status" 10 \
4373 =item B<StatusFile> I<File>
4375 Specifies the location of the status file.
4377 =item B<ImprovedNamingSchema> B<true>|B<false>
4379 When enabled, the filename of the status file will be used as plugin instance
4380 and the client's "common name" will be used as type instance. This is required
4381 when reading multiple status files. Enabling this option is recommended, but to
4382 maintain backwards compatibility this option is disabled by default.
4384 =item B<CollectCompression> B<true>|B<false>
4386 Sets whether or not statistics about the compression used by OpenVPN should be
4387 collected. This information is only available in I<single> mode. Enabled by
4390 =item B<CollectIndividualUsers> B<true>|B<false>
4392 Sets whether or not traffic information is collected for each connected client
4393 individually. If set to false, currently no traffic data is collected at all
4394 because aggregating this data in a save manner is tricky. Defaults to B<true>.
4396 =item B<CollectUserCount> B<true>|B<false>
4398 When enabled, the number of currently connected clients or users is collected.
4399 This is especially interesting when B<CollectIndividualUsers> is disabled, but
4400 can be configured independently from that option. Defaults to B<false>.
4404 =head2 Plugin C<oracle>
4406 The "oracle" plugin uses the Oracle® Call Interface I<(OCI)> to connect to an
4407 Oracle® Database and lets you execute SQL statements there. It is very similar
4408 to the "dbi" plugin, because it was written around the same time. See the "dbi"
4409 plugin's documentation above for details.
4412 <Query "out_of_stock">
4413 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
4416 # InstancePrefix "foo"
4417 InstancesFrom "category"
4421 <Database "product_information">
4425 Query "out_of_stock"
4429 =head3 B<Query> blocks
4431 The Query blocks are handled identically to the Query blocks of the "dbi"
4432 plugin. Please see its documentation above for details on how to specify
4435 =head3 B<Database> blocks
4437 Database blocks define a connection to a database and which queries should be
4438 sent to that database. Each database needs a "name" as string argument in the
4439 starting tag of the block. This name will be used as "PluginInstance" in the
4440 values submitted to the daemon. Other than that, that name is not used.
4444 =item B<ConnectID> I<ID>
4446 Defines the "database alias" or "service name" to connect to. Usually, these
4447 names are defined in the file named C<$ORACLE_HOME/network/admin/tnsnames.ora>.
4449 =item B<Host> I<Host>
4451 Hostname to use when dispatching values for this database. Defaults to using
4452 the global hostname of the I<collectd> instance.
4454 =item B<Username> I<Username>
4456 Username used for authentication.
4458 =item B<Password> I<Password>
4460 Password used for authentication.
4462 =item B<Query> I<QueryName>
4464 Associates the query named I<QueryName> with this database connection. The
4465 query needs to be defined I<before> this statement, i.E<nbsp>e. all query
4466 blocks you want to refer to must be placed above the database block you want to
4471 =head2 Plugin C<perl>
4473 This plugin embeds a Perl-interpreter into collectd and provides an interface
4474 to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
4476 =head2 Plugin C<pinba>
4478 The I<Pinba plugin> receives profiling information from I<Pinba>, an extension
4479 for the I<PHP> interpreter. At the end of executing a script, i.e. after a
4480 PHP-based webpage has been delivered, the extension will send a UDP packet
4481 containing timing information, peak memory usage and so on. The plugin will
4482 wait for such packets, parse them and account the provided information, which
4483 is then dispatched to the daemon once per interval.
4490 # Overall statistics for the website.
4492 Server "www.example.com"
4494 # Statistics for www-a only
4496 Host "www-a.example.com"
4497 Server "www.example.com"
4499 # Statistics for www-b only
4501 Host "www-b.example.com"
4502 Server "www.example.com"
4506 The plugin provides the following configuration options:
4510 =item B<Address> I<Node>
4512 Configures the address used to open a listening socket. By default, plugin will
4513 bind to the I<any> address C<::0>.
4515 =item B<Port> I<Service>
4517 Configures the port (service) to bind to. By default the default Pinba port
4518 "30002" will be used. The option accepts service names in addition to port
4519 numbers and thus requires a I<string> argument.
4521 =item E<lt>B<View> I<Name>E<gt> block
4523 The packets sent by the Pinba extension include the hostname of the server, the
4524 server name (the name of the virtual host) and the script that was executed.
4525 Using B<View> blocks it is possible to separate the data into multiple groups
4526 to get more meaningful statistics. Each packet is added to all matching groups,
4527 so that a packet may be accounted for more than once.
4531 =item B<Host> I<Host>
4533 Matches the hostname of the system the webserver / script is running on. This
4534 will contain the result of the L<gethostname(2)> system call. If not
4535 configured, all hostnames will be accepted.
4537 =item B<Server> I<Server>
4539 Matches the name of the I<virtual host>, i.e. the contents of the
4540 C<$_SERVER["SERVER_NAME"]> variable when within PHP. If not configured, all
4541 server names will be accepted.
4543 =item B<Script> I<Script>
4545 Matches the name of the I<script name>, i.e. the contents of the
4546 C<$_SERVER["SCRIPT_NAME"]> variable when within PHP. If not configured, all
4547 script names will be accepted.
4553 =head2 Plugin C<ping>
4555 The I<Ping> plugin starts a new thread which sends ICMP "ping" packets to the
4556 configured hosts periodically and measures the network latency. Whenever the
4557 C<read> function of the plugin is called, it submits the average latency, the
4558 standard deviation and the drop rate for each host.
4560 Available configuration options:
4564 =item B<Host> I<IP-address>
4566 Host to ping periodically. This option may be repeated several times to ping
4569 =item B<Interval> I<Seconds>
4571 Sets the interval in which to send ICMP echo packets to the configured hosts.
4572 This is B<not> the interval in which statistics are queries from the plugin but
4573 the interval in which the hosts are "pinged". Therefore, the setting here
4574 should be smaller than or equal to the global B<Interval> setting. Fractional
4575 times, such as "1.24" are allowed.
4579 =item B<Timeout> I<Seconds>
4581 Time to wait for a response from the host to which an ICMP packet had been
4582 sent. If a reply was not received after I<Seconds> seconds, the host is assumed
4583 to be down or the packet to be dropped. This setting must be smaller than the
4584 B<Interval> setting above for the plugin to work correctly. Fractional
4585 arguments are accepted.
4589 =item B<TTL> I<0-255>
4591 Sets the Time-To-Live of generated ICMP packets.
4593 =item B<SourceAddress> I<host>
4595 Sets the source address to use. I<host> may either be a numerical network
4596 address or a network hostname.
4598 =item B<Device> I<name>
4600 Sets the outgoing network device to be used. I<name> has to specify an
4601 interface name (e.E<nbsp>g. C<eth0>). This might not be supported by all
4604 =item B<MaxMissed> I<Packets>
4606 Trigger a DNS resolve after the host has not replied to I<Packets> packets. This
4607 enables the use of dynamic DNS services (like dyndns.org) with the ping plugin.
4609 Default: B<-1> (disabled)
4613 =head2 Plugin C<postgresql>
4615 The C<postgresql> plugin queries statistics from PostgreSQL databases. It
4616 keeps a persistent connection to all configured databases and tries to
4617 reconnect if the connection has been interrupted. A database is configured by
4618 specifying a B<Database> block as described below. The default statistics are
4619 collected from PostgreSQL's B<statistics collector> which thus has to be
4620 enabled for this plugin to work correctly. This should usually be the case by
4621 default. See the section "The Statistics Collector" of the B<PostgreSQL
4622 Documentation> for details.
4624 By specifying custom database queries using a B<Query> block as described
4625 below, you may collect any data that is available from some PostgreSQL
4626 database. This way, you are able to access statistics of external daemons
4627 which are available in a PostgreSQL database or use future or special
4628 statistics provided by PostgreSQL without the need to upgrade your collectd
4631 Starting with version 5.2, the C<postgresql> plugin supports writing data to
4632 PostgreSQL databases as well. This has been implemented in a generic way. You
4633 need to specify an SQL statement which will then be executed by collectd in
4634 order to write the data (see below for details). The benefit of that approach
4635 is that there is no fixed database layout. Rather, the layout may be optimized
4636 for the current setup.
4638 The B<PostgreSQL Documentation> manual can be found at
4639 L<http://www.postgresql.org/docs/manuals/>.
4643 Statement "SELECT magic FROM wizard WHERE host = $1;"
4647 InstancePrefix "magic"
4652 <Query rt36_tickets>
4653 Statement "SELECT COUNT(type) AS count, type \
4655 WHEN resolved = 'epoch' THEN 'open' \
4656 ELSE 'resolved' END AS type \
4657 FROM tickets) type \
4661 InstancePrefix "rt36_tickets"
4662 InstancesFrom "type"
4668 Statement "SELECT collectd_insert($1, $2, $3, $4, $5, $6, $7, $8, $9);"
4678 KRBSrvName "kerberos_service_name"
4684 Service "service_name"
4685 Query backend # predefined
4696 The B<Query> block defines one database query which may later be used by a
4697 database definition. It accepts a single mandatory argument which specifies
4698 the name of the query. The names of all queries have to be unique (see the
4699 B<MinVersion> and B<MaxVersion> options below for an exception to this
4700 rule). The following configuration options are available to define the query:
4702 In each B<Query> block, there is one or more B<Result> blocks. B<Result>
4703 blocks define how to handle the values returned from the query. They define
4704 which column holds which value and how to dispatch that value to the daemon.
4705 Multiple B<Result> blocks may be used to extract multiple values from a single
4710 =item B<Statement> I<sql query statement>
4712 Specify the I<sql query statement> which the plugin should execute. The string
4713 may contain the tokens B<$1>, B<$2>, etc. which are used to reference the
4714 first, second, etc. parameter. The value of the parameters is specified by the
4715 B<Param> configuration option - see below for details. To include a literal
4716 B<$> character followed by a number, surround it with single quotes (B<'>).
4718 Any SQL command which may return data (such as C<SELECT> or C<SHOW>) is
4719 allowed. Note, however, that only a single command may be used. Semicolons are
4720 allowed as long as a single non-empty command has been specified only.
4722 The returned lines will be handled separately one after another.
4724 =item B<Param> I<hostname>|I<database>|I<username>|I<interval>
4726 Specify the parameters which should be passed to the SQL query. The parameters
4727 are referred to in the SQL query as B<$1>, B<$2>, etc. in the same order as
4728 they appear in the configuration file. The value of the parameter is
4729 determined depending on the value of the B<Param> option as follows:
4735 The configured hostname of the database connection. If a UNIX domain socket is
4736 used, the parameter expands to "localhost".
4740 The name of the database of the current connection.
4744 The name of the database plugin instance. See the B<Instance> option of the
4745 database specification below for details.
4749 The username used to connect to the database.
4753 The interval with which this database is queried (as specified by the database
4754 specific or global B<Interval> options).
4758 Please note that parameters are only supported by PostgreSQL's protocol
4759 version 3 and above which was introduced in version 7.4 of PostgreSQL.
4761 =item B<Type> I<type>
4763 The I<type> name to be used when dispatching the values. The type describes
4764 how to handle the data and where to store it. See L<types.db(5)> for more
4765 details on types and their configuration. The number and type of values (as
4766 selected by the B<ValuesFrom> option) has to match the type of the given name.
4768 This option is required inside a B<Result> block.
4770 =item B<InstancePrefix> I<prefix>
4772 =item B<InstancesFrom> I<column0> [I<column1> ...]
4774 Specify how to create the "TypeInstance" for each data set (i.E<nbsp>e. line).
4775 B<InstancePrefix> defines a static prefix that will be prepended to all type
4776 instances. B<InstancesFrom> defines the column names whose values will be used
4777 to create the type instance. Multiple values will be joined together using the
4778 hyphen (C<->) as separation character.
4780 The plugin itself does not check whether or not all built instances are
4781 different. It is your responsibility to assure that each is unique.
4783 Both options are optional. If none is specified, the type instance will be
4786 =item B<ValuesFrom> I<column0> [I<column1> ...]
4788 Names the columns whose content is used as the actual data for the data sets
4789 that are dispatched to the daemon. How many such columns you need is
4790 determined by the B<Type> setting as explained above. If you specify too many
4791 or not enough columns, the plugin will complain about that and no data will be
4792 submitted to the daemon.
4794 The actual data type, as seen by PostgreSQL, is not that important as long as
4795 it represents numbers. The plugin will automatically cast the values to the
4796 right type if it know how to do that. For that, it uses the L<strtoll(3)> and
4797 L<strtod(3)> functions, so anything supported by those functions is supported
4798 by the plugin as well.
4800 This option is required inside a B<Result> block and may be specified multiple
4801 times. If multiple B<ValuesFrom> options are specified, the columns are read
4804 =item B<MinVersion> I<version>
4806 =item B<MaxVersion> I<version>
4808 Specify the minimum or maximum version of PostgreSQL that this query should be
4809 used with. Some statistics might only be available with certain versions of
4810 PostgreSQL. This allows you to specify multiple queries with the same name but
4811 which apply to different versions, thus allowing you to use the same
4812 configuration in a heterogeneous environment.
4814 The I<version> has to be specified as the concatenation of the major, minor
4815 and patch-level versions, each represented as two-decimal-digit numbers. For
4816 example, version 8.2.3 will become 80203.
4820 The following predefined queries are available (the definitions can be found
4821 in the F<postgresql_default.conf> file which, by default, is available at
4822 C<I<prefix>/share/collectd/>):
4828 This query collects the number of backends, i.E<nbsp>e. the number of
4831 =item B<transactions>
4833 This query collects the numbers of committed and rolled-back transactions of
4838 This query collects the numbers of various table modifications (i.E<nbsp>e.
4839 insertions, updates, deletions) of the user tables.
4841 =item B<query_plans>
4843 This query collects the numbers of various table scans and returned tuples of
4846 =item B<table_states>
4848 This query collects the numbers of live and dead rows in the user tables.
4852 This query collects disk block access counts for user tables.
4856 This query collects the on-disk size of the database in bytes.
4860 In addition, the following detailed queries are available by default. Please
4861 note that each of those queries collects information B<by table>, thus,
4862 potentially producing B<a lot> of data. For details see the description of the
4863 non-by_table queries above.
4867 =item B<queries_by_table>
4869 =item B<query_plans_by_table>
4871 =item B<table_states_by_table>
4873 =item B<disk_io_by_table>
4877 The B<Writer> block defines a PostgreSQL writer backend. It accepts a single
4878 mandatory argument specifying the name of the writer. This will then be used
4879 in the B<Database> specification in order to activate the writer instance. The
4880 names of all writers have to be unique. The following options may be
4885 =item B<Statement> I<sql statement>
4887 This mandatory option specifies the SQL statement that will be executed for
4888 each submitted value. A single SQL statement is allowed only. Anything after
4889 the first semicolon will be ignored.
4891 Nine parameters will be passed to the statement and should be specified as
4892 tokens B<$1>, B<$2>, through B<$9> in the statement string. The following
4893 values are made available through those parameters:
4899 The timestamp of the queried value as a floating point number.
4903 The hostname of the queried value.
4907 The plugin name of the queried value.
4911 The plugin instance of the queried value. This value may be B<NULL> if there
4912 is no plugin instance.
4916 The type of the queried value (cf. L<types.db(5)>).
4920 The type instance of the queried value. This value may be B<NULL> if there is
4925 An array of names for the submitted values (i.E<nbsp>e., the name of the data
4926 sources of the submitted value-list).
4930 An array of types for the submitted values (i.E<nbsp>e., the type of the data
4931 sources of the submitted value-list; C<counter>, C<gauge>, ...). Note, that if
4932 B<StoreRates> is enabled (which is the default, see below), all types will be
4937 An array of the submitted values. The dimensions of the value name and value
4942 In general, it is advisable to create and call a custom function in the
4943 PostgreSQL database for this purpose. Any procedural language supported by
4944 PostgreSQL will do (see chapter "Server Programming" in the PostgreSQL manual
4947 =item B<StoreRates> B<false>|B<true>
4949 If set to B<true> (the default), convert counter values to rates. If set to
4950 B<false> counter values are stored as is, i.E<nbsp>e. as an increasing integer
4955 The B<Database> block defines one PostgreSQL database for which to collect
4956 statistics. It accepts a single mandatory argument which specifies the
4957 database name. None of the other options are required. PostgreSQL will use
4958 default values as documented in the section "CONNECTING TO A DATABASE" in the
4959 L<psql(1)> manpage. However, be aware that those defaults may be influenced by
4960 the user collectd is run as and special environment variables. See the manpage
4965 =item B<Interval> I<seconds>
4967 Specify the interval with which the database should be queried. The default is
4968 to use the global B<Interval> setting.
4970 =item B<CommitInterval> I<seconds>
4972 This option may be used for database connections which have "writers" assigned
4973 (see above). If specified, it causes a writer to put several updates into a
4974 single transaction. This transaction will last for the specified amount of
4975 time. By default, each update will be executed in a separate transaction. Each
4976 transaction generates a fair amount of overhead which can, thus, be reduced by
4977 activating this option. The draw-back is, that data covering the specified
4978 amount of time will be lost, for example, if a single statement within the
4979 transaction fails or if the database server crashes.
4981 =item B<Host> I<hostname>
4983 Specify the hostname or IP of the PostgreSQL server to connect to. If the
4984 value begins with a slash, it is interpreted as the directory name in which to
4985 look for the UNIX domain socket.
4987 This option is also used to determine the hostname that is associated with a
4988 collected data set. If it has been omitted or either begins with with a slash
4989 or equals B<localhost> it will be replaced with the global hostname definition
4990 of collectd. Any other value will be passed literally to collectd when
4991 dispatching values. Also see the global B<Hostname> and B<FQDNLookup> options.
4993 =item B<Port> I<port>
4995 Specify the TCP port or the local UNIX domain socket file extension of the
4998 =item B<User> I<username>
5000 Specify the username to be used when connecting to the server.
5002 =item B<Password> I<password>
5004 Specify the password to be used when connecting to the server.
5006 =item B<ExpireDelay> I<delay>
5008 Skip expired values in query output.
5010 =item B<SSLMode> I<disable>|I<allow>|I<prefer>|I<require>
5012 Specify whether to use an SSL connection when contacting the server. The
5013 following modes are supported:
5019 Do not use SSL at all.
5023 First, try to connect without using SSL. If that fails, try using SSL.
5025 =item I<prefer> (default)
5027 First, try to connect using SSL. If that fails, try without using SSL.
5035 =item B<Instance> I<name>
5037 Specify the plugin instance name that should be used instead of the database
5038 name (which is the default, if this option has not been specified). This
5039 allows to query multiple databases of the same name on the same host (e.g.
5040 when running multiple database server versions in parallel).
5042 =item B<KRBSrvName> I<kerberos_service_name>
5044 Specify the Kerberos service name to use when authenticating with Kerberos 5
5045 or GSSAPI. See the sections "Kerberos authentication" and "GSSAPI" of the
5046 B<PostgreSQL Documentation> for details.
5048 =item B<Service> I<service_name>
5050 Specify the PostgreSQL service name to use for additional parameters. That
5051 service has to be defined in F<pg_service.conf> and holds additional
5052 connection parameters. See the section "The Connection Service File" in the
5053 B<PostgreSQL Documentation> for details.
5055 =item B<Query> I<query>
5057 Specifies a I<query> which should be executed in the context of the database
5058 connection. This may be any of the predefined or user-defined queries. If no
5059 such option is given, it defaults to "backends", "transactions", "queries",
5060 "query_plans", "table_states", "disk_io" and "disk_usage" (unless a B<Writer>
5061 has been specified). Else, the specified queries are used only.
5063 =item B<Writer> I<writer>
5065 Assigns the specified I<writer> backend to the database connection. This
5066 causes all collected data to be send to the database using the settings
5067 defined in the writer configuration (see the section "FILTER CONFIGURATION"
5068 below for details on how to selectively send data to certain plugins).
5070 Each writer will register a flush callback which may be used when having long
5071 transactions enabled (see the B<CommitInterval> option above). When issuing
5072 the B<FLUSH> command (see L<collectd-unixsock(5)> for details) the current
5073 transaction will be committed right away. Two different kinds of flush
5074 callbacks are available with the C<postgresql> plugin:
5080 Flush all writer backends.
5082 =item B<postgresql->I<database>
5084 Flush all writers of the specified I<database> only.
5090 =head2 Plugin C<powerdns>
5092 The C<powerdns> plugin queries statistics from an authoritative PowerDNS
5093 nameserver and/or a PowerDNS recursor. Since both offer a wide variety of
5094 values, many of which are probably meaningless to most users, but may be useful
5095 for some. So you may chose which values to collect, but if you don't, some
5096 reasonable defaults will be collected.
5099 <Server "server_name">
5101 Collect "udp-answers" "udp-queries"
5102 Socket "/var/run/pdns.controlsocket"
5104 <Recursor "recursor_name">
5106 Collect "cache-hits" "cache-misses"
5107 Socket "/var/run/pdns_recursor.controlsocket"
5109 LocalSocket "/opt/collectd/var/run/collectd-powerdns"
5114 =item B<Server> and B<Recursor> block
5116 The B<Server> block defines one authoritative server to query, the B<Recursor>
5117 does the same for an recursing server. The possible options in both blocks are
5118 the same, though. The argument defines a name for the serverE<nbsp>/ recursor
5123 =item B<Collect> I<Field>
5125 Using the B<Collect> statement you can select which values to collect. Here,
5126 you specify the name of the values as used by the PowerDNS servers, e.E<nbsp>g.
5127 C<dlg-only-drops>, C<answers10-100>.
5129 The method of getting the values differs for B<Server> and B<Recursor> blocks:
5130 When querying the server a C<SHOW *> command is issued in any case, because
5131 that's the only way of getting multiple values out of the server at once.
5132 collectd then picks out the values you have selected. When querying the
5133 recursor, a command is generated to query exactly these values. So if you
5134 specify invalid fields when querying the recursor, a syntax error may be
5135 returned by the daemon and collectd may not collect any values at all.
5137 If no B<Collect> statement is given, the following B<Server> values will be
5144 =item packetcache-hit
5146 =item packetcache-miss
5148 =item packetcache-size
5150 =item query-cache-hit
5152 =item query-cache-miss
5154 =item recursing-answers
5156 =item recursing-questions
5168 The following B<Recursor> values will be collected by default:
5172 =item noerror-answers
5174 =item nxdomain-answers
5176 =item servfail-answers
5194 Please note that up to that point collectd doesn't know what values are
5195 available on the server and values that are added do not need a change of the
5196 mechanism so far. However, the values must be mapped to collectd's naming
5197 scheme, which is done using a lookup table that lists all known values. If
5198 values are added in the future and collectd does not know about them, you will
5199 get an error much like this:
5201 powerdns plugin: submit: Not found in lookup table: foobar = 42
5203 In this case please file a bug report with the collectd team.
5205 =item B<Socket> I<Path>
5207 Configures the path to the UNIX domain socket to be used when connecting to the
5208 daemon. By default C<${localstatedir}/run/pdns.controlsocket> will be used for
5209 an authoritative server and C<${localstatedir}/run/pdns_recursor.controlsocket>
5210 will be used for the recursor.
5214 =item B<LocalSocket> I<Path>
5216 Querying the recursor is done using UDP. When using UDP over UNIX domain
5217 sockets, the client socket needs a name in the file system, too. You can set
5218 this local name to I<Path> using the B<LocalSocket> option. The default is
5219 C<I<prefix>/var/run/collectd-powerdns>.
5223 =head2 Plugin C<processes>
5227 =item B<Process> I<Name>
5229 Select more detailed statistics of processes matching this name. The statistics
5230 collected for these selected processes are size of the resident segment size
5231 (RSS), user- and system-time used, number of processes and number of threads,
5232 io data (where available) and minor and major pagefaults.
5234 =item B<ProcessMatch> I<name> I<regex>
5236 Similar to the B<Process> option this allows to select more detailed
5237 statistics of processes matching the specified I<regex> (see L<regex(7)> for
5238 details). The statistics of all matching processes are summed up and
5239 dispatched to the daemon using the specified I<name> as an identifier. This
5240 allows to "group" several processes together. I<name> must not contain
5245 =head2 Plugin C<protocols>
5247 Collects a lot of information about various network protocols, such as I<IP>,
5248 I<TCP>, I<UDP>, etc.
5250 Available configuration options:
5254 =item B<Value> I<Selector>
5256 Selects whether or not to select a specific value. The string being matched is
5257 of the form "I<Protocol>:I<ValueName>", where I<Protocol> will be used as the
5258 plugin instance and I<ValueName> will be used as type instance. An example of
5259 the string being used would be C<Tcp:RetransSegs>.
5261 You can use regular expressions to match a large number of values with just one
5262 configuration option. To select all "extended" I<TCP> values, you could use the
5263 following statement:
5267 Whether only matched values are selected or all matched values are ignored
5268 depends on the B<IgnoreSelected>. By default, only matched values are selected.
5269 If no value is configured at all, all values will be selected.
5271 =item B<IgnoreSelected> B<true>|B<false>
5273 If set to B<true>, inverts the selection made by B<Value>, i.E<nbsp>e. all
5274 matching values will be ignored.
5278 =head2 Plugin C<python>
5280 This plugin embeds a Python-interpreter into collectd and provides an interface
5281 to collectd's plugin system. See L<collectd-python(5)> for its documentation.
5283 =head2 Plugin C<routeros>
5285 The C<routeros> plugin connects to a device running I<RouterOS>, the
5286 Linux-based operating system for routers by I<MikroTik>. The plugin uses
5287 I<librouteros> to connect and reads information about the interfaces and
5288 wireless connections of the device. The configuration supports querying
5293 Host "router0.example.com"
5296 CollectInterface true
5301 Host "router1.example.com"
5304 CollectInterface true
5305 CollectRegistrationTable true
5311 As you can see above, the configuration of the I<routeros> plugin consists of
5312 one or more B<E<lt>RouterE<gt>> blocks. Within each block, the following
5313 options are understood:
5317 =item B<Host> I<Host>
5319 Hostname or IP-address of the router to connect to.
5321 =item B<Port> I<Port>
5323 Port name or port number used when connecting. If left unspecified, the default
5324 will be chosen by I<librouteros>, currently "8728". This option expects a
5325 string argument, even when a numeric port number is given.
5327 =item B<User> I<User>
5329 Use the user name I<User> to authenticate. Defaults to "admin".
5331 =item B<Password> I<Password>
5333 Set the password used to authenticate.
5335 =item B<CollectInterface> B<true>|B<false>
5337 When set to B<true>, interface statistics will be collected for all interfaces
5338 present on the device. Defaults to B<false>.
5340 =item B<CollectRegistrationTable> B<true>|B<false>
5342 When set to B<true>, information about wireless LAN connections will be
5343 collected. Defaults to B<false>.
5345 =item B<CollectCPULoad> B<true>|B<false>
5347 When set to B<true>, information about the CPU usage will be collected. The
5348 number is a dimensionless value where zero indicates no CPU usage at all.
5349 Defaults to B<false>.
5351 =item B<CollectMemory> B<true>|B<false>
5353 When enabled, the amount of used and free memory will be collected. How used
5354 memory is calculated is unknown, for example whether or not caches are counted
5356 Defaults to B<false>.
5358 =item B<CollectDF> B<true>|B<false>
5360 When enabled, the amount of used and free disk space will be collected.
5361 Defaults to B<false>.
5363 =item B<CollectDisk> B<true>|B<false>
5365 When enabled, the number of sectors written and bad blocks will be collected.
5366 Defaults to B<false>.
5370 =head2 Plugin C<redis>
5372 The I<Redis plugin> connects to one or more Redis servers and gathers
5373 information about each server's state. For each server there is a I<Node> block
5374 which configures the connection parameters for this node.
5381 <Query "LLEN myqueue">
5388 The information shown in the synopsis above is the I<default configuration>
5389 which is used by the plugin if no configuration is present.
5393 =item B<Node> I<Nodename>
5395 The B<Node> block identifies a new Redis node, that is a new Redis instance
5396 running in an specified host and port. The name for node is a canonical
5397 identifier which is used as I<plugin instance>. It is limited to
5398 64E<nbsp>characters in length.
5400 =item B<Host> I<Hostname>
5402 The B<Host> option is the hostname or IP-address where the Redis instance is
5405 =item B<Port> I<Port>
5407 The B<Port> option is the TCP port on which the Redis instance accepts
5408 connections. Either a service name of a port number may be given. Please note
5409 that numerical port numbers must be given as a string, too.
5411 =item B<Password> I<Password>
5413 Use I<Password> to authenticate when connecting to I<Redis>.
5415 =item B<Timeout> I<Timeout in miliseconds>
5417 The B<Timeout> option set the socket timeout for node response. Since the Redis
5418 read function is blocking, you should keep this value as low as possible. Keep
5419 in mind that the sum of all B<Timeout> values for all B<Nodes> should be lower
5420 than B<Interval> defined globally.
5422 =item B<Query> I<Querystring>
5424 The B<Query> block identifies a query to execute against the redis server.
5425 There may be an arbitrary number of queries to execute.
5427 =item B<Type> I<Collectd type>
5429 Within a query definition, a valid collectd type to use as when submitting
5430 the result of the query. When not supplied, will default to B<gauge>.
5432 =item B<Instance> I<Type instance>
5434 Within a query definition, an optional type instance to use when submitting
5435 the result of the query. When not supplied will default to the escaped
5436 command, up to 64 chars.
5440 =head2 Plugin C<rrdcached>
5442 The C<rrdcached> plugin uses the RRDtool accelerator daemon, L<rrdcached(1)>,
5443 to store values to RRD files in an efficient manner. The combination of the
5444 C<rrdcached> B<plugin> and the C<rrdcached> B<daemon> is very similar to the
5445 way the C<rrdtool> plugin works (see below). The added abstraction layer
5446 provides a number of benefits, though: Because the cache is not within
5447 C<collectd> anymore, it does not need to be flushed when C<collectd> is to be
5448 restarted. This results in much shorter (if any) gaps in graphs, especially
5449 under heavy load. Also, the C<rrdtool> command line utility is aware of the
5450 daemon so that it can flush values to disk automatically when needed. This
5451 allows to integrate automated flushing of values into graphing solutions much
5454 There are disadvantages, though: The daemon may reside on a different host, so
5455 it may not be possible for C<collectd> to create the appropriate RRD files
5456 anymore. And even if C<rrdcached> runs on the same host, it may run in a
5457 different base directory, so relative paths may do weird stuff if you're not
5460 So the B<recommended configuration> is to let C<collectd> and C<rrdcached> run
5461 on the same host, communicating via a UNIX domain socket. The B<DataDir>
5462 setting should be set to an absolute path, so that a changed base directory
5463 does not result in RRD files being createdE<nbsp>/ expected in the wrong place.
5467 =item B<DaemonAddress> I<Address>
5469 Address of the daemon as understood by the C<rrdc_connect> function of the RRD
5470 library. See L<rrdcached(1)> for details. Example:
5472 <Plugin "rrdcached">
5473 DaemonAddress "unix:/var/run/rrdcached.sock"
5476 =item B<DataDir> I<Directory>
5478 Set the base directory in which the RRD files reside. If this is a relative
5479 path, it is relative to the working base directory of the C<rrdcached> daemon!
5480 Use of an absolute path is recommended.
5482 =item B<CreateFiles> B<true>|B<false>
5484 Enables or disables the creation of RRD files. If the daemon is not running
5485 locally, or B<DataDir> is set to a relative path, this will not work as
5486 expected. Default is B<true>.
5488 =item B<CreateFilesAsync> B<false>|B<true>
5490 When enabled, new RRD files are enabled asynchronously, using a separate thread
5491 that runs in the background. This prevents writes to block, which is a problem
5492 especially when many hundreds of files need to be created at once. However,
5493 since the purpose of creating the files asynchronously is I<not> to block until
5494 the file is available, values before the file is available will be discarded.
5495 When disabled (the default) files are created synchronously, blocking for a
5496 short while, while the file is being written.
5498 =item B<StepSize> I<Seconds>
5500 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
5501 this setting is unset and the stepsize is set to the interval in which the data
5502 is collected. Do not use this option unless you absolutely have to for some
5503 reason. Setting this option may cause problems with the C<snmp plugin>, the
5504 C<exec plugin> or when the daemon is set up to receive data from other hosts.
5506 =item B<HeartBeat> I<Seconds>
5508 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
5509 in which case the heartbeat is set to twice the B<StepSize> which should equal
5510 the interval in which data is collected. Do not set this option unless you have
5511 a very good reason to do so.
5513 =item B<RRARows> I<NumRows>
5515 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
5516 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
5517 three times five RRAs, i. e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
5518 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
5519 week, one month, and one year.
5521 So for each timespan, it calculates how many PDPs need to be consolidated into
5522 one CDP by calculating:
5523 number of PDPs = timespan / (stepsize * rrarows)
5525 Bottom line is, set this no smaller than the width of you graphs in pixels. The
5528 =item B<RRATimespan> I<Seconds>
5530 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
5531 more then one RRA. If this option is never used, the built-in default of (3600,
5532 86400, 604800, 2678400, 31622400) is used.
5534 For more information on how RRA-sizes are calculated see B<RRARows> above.
5536 =item B<XFF> I<Factor>
5538 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
5539 I<Factor> must be in the range C<[0.0-1.0)>, i.e. between zero (inclusive) and
5542 =item B<CollectStatistics> B<false>|B<true>
5544 When set to B<true>, various statistics about the I<rrdcached> daemon will be
5545 collected, with "rrdcached" as the I<plugin name>. Defaults to B<false>.
5547 Statistics are read via I<rrdcached>s socket using the STATS command.
5548 See L<rrdcached(1)> for details.
5552 =head2 Plugin C<rrdtool>
5554 You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
5555 fine-tune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
5556 using these settings. If you don't want to dive into the depths of RRDtool, you
5557 can safely ignore these settings.
5561 =item B<DataDir> I<Directory>
5563 Set the directory to store RRD files under. By default RRD files are generated
5564 beneath the daemon's working directory, i.e. the B<BaseDir>.
5566 =item B<CreateFilesAsync> B<false>|B<true>
5568 When enabled, new RRD files are enabled asynchronously, using a separate thread
5569 that runs in the background. This prevents writes to block, which is a problem
5570 especially when many hundreds of files need to be created at once. However,
5571 since the purpose of creating the files asynchronously is I<not> to block until
5572 the file is available, values before the file is available will be discarded.
5573 When disabled (the default) files are created synchronously, blocking for a
5574 short while, while the file is being written.
5576 =item B<StepSize> I<Seconds>
5578 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
5579 this setting is unset and the stepsize is set to the interval in which the data
5580 is collected. Do not use this option unless you absolutely have to for some
5581 reason. Setting this option may cause problems with the C<snmp plugin>, the
5582 C<exec plugin> or when the daemon is set up to receive data from other hosts.
5584 =item B<HeartBeat> I<Seconds>
5586 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
5587 in which case the heartbeat is set to twice the B<StepSize> which should equal
5588 the interval in which data is collected. Do not set this option unless you have
5589 a very good reason to do so.
5591 =item B<RRARows> I<NumRows>
5593 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
5594 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
5595 three times five RRAs, i.e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
5596 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
5597 week, one month, and one year.
5599 So for each timespan, it calculates how many PDPs need to be consolidated into
5600 one CDP by calculating:
5601 number of PDPs = timespan / (stepsize * rrarows)
5603 Bottom line is, set this no smaller than the width of you graphs in pixels. The
5606 =item B<RRATimespan> I<Seconds>
5608 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
5609 more then one RRA. If this option is never used, the built-in default of (3600,
5610 86400, 604800, 2678400, 31622400) is used.
5612 For more information on how RRA-sizes are calculated see B<RRARows> above.
5614 =item B<XFF> I<Factor>
5616 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
5617 I<Factor> must be in the range C<[0.0-1.0)>, i.e. between zero (inclusive) and
5620 =item B<CacheFlush> I<Seconds>
5622 When the C<rrdtool> plugin uses a cache (by setting B<CacheTimeout>, see below)
5623 it writes all values for a certain RRD-file if the oldest value is older than
5624 (or equal to) the number of seconds specified. If some RRD-file is not updated
5625 anymore for some reason (the computer was shut down, the network is broken,
5626 etc.) some values may still be in the cache. If B<CacheFlush> is set, then the
5627 entire cache is searched for entries older than B<CacheTimeout> seconds and
5628 written to disk every I<Seconds> seconds. Since this is kind of expensive and
5629 does nothing under normal circumstances, this value should not be too small.
5630 900 seconds might be a good value, though setting this to 7200 seconds doesn't
5631 normally do much harm either.
5633 =item B<CacheTimeout> I<Seconds>
5635 If this option is set to a value greater than zero, the C<rrdtool plugin> will
5636 save values in a cache, as described above. Writing multiple values at once
5637 reduces IO-operations and thus lessens the load produced by updating the files.
5638 The trade off is that the graphs kind of "drag behind" and that more memory is
5641 =item B<WritesPerSecond> I<Updates>
5643 When collecting many statistics with collectd and the C<rrdtool> plugin, you
5644 will run serious performance problems. The B<CacheFlush> setting and the
5645 internal update queue assert that collectd continues to work just fine even
5646 under heavy load, but the system may become very unresponsive and slow. This is
5647 a problem especially if you create graphs from the RRD files on the same
5648 machine, for example using the C<graph.cgi> script included in the
5649 C<contrib/collection3/> directory.
5651 This setting is designed for very large setups. Setting this option to a value
5652 between 25 and 80 updates per second, depending on your hardware, will leave
5653 the server responsive enough to draw graphs even while all the cached values
5654 are written to disk. Flushed values, i.E<nbsp>e. values that are forced to disk
5655 by the B<FLUSH> command, are B<not> effected by this limit. They are still
5656 written as fast as possible, so that web frontends have up to date data when
5659 For example: If you have 100,000 RRD files and set B<WritesPerSecond> to 30
5660 updates per second, writing all values to disk will take approximately
5661 56E<nbsp>minutes. Together with the flushing ability that's integrated into
5662 "collection3" you'll end up with a responsive and fast system, up to date
5663 graphs and basically a "backup" of your values every hour.
5665 =item B<RandomTimeout> I<Seconds>
5667 When set, the actual timeout for each value is chosen randomly between
5668 I<CacheTimeout>-I<RandomTimeout> and I<CacheTimeout>+I<RandomTimeout>. The
5669 intention is to avoid high load situations that appear when many values timeout
5670 at the same time. This is especially a problem shortly after the daemon starts,
5671 because all values were added to the internal cache at roughly the same time.
5675 =head2 Plugin C<sensors>
5677 The I<Sensors plugin> uses B<lm_sensors> to retrieve sensor-values. This means
5678 that all the needed modules have to be loaded and lm_sensors has to be
5679 configured (most likely by editing F</etc/sensors.conf>. Read
5680 L<sensors.conf(5)> for details.
5682 The B<lm_sensors> homepage can be found at
5683 L<http://secure.netroedge.com/~lm78/>.
5687 =item B<SensorConfigFile> I<File>
5689 Read the I<lm_sensors> configuration from I<File>. When unset (recommended),
5690 the library's default will be used.
5692 =item B<Sensor> I<chip-bus-address/type-feature>
5694 Selects the name of the sensor which you want to collect or ignore, depending
5695 on the B<IgnoreSelected> below. For example, the option "B<Sensor>
5696 I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
5697 voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
5699 =item B<IgnoreSelected> I<true>|I<false>
5701 If no configuration if given, the B<sensors>-plugin will collect data from all
5702 sensors. This may not be practical, especially for uninteresting sensors.
5703 Thus, you can use the B<Sensor>-option to pick the sensors you're interested
5704 in. Sometimes, however, it's easier/preferred to collect all sensors I<except> a
5705 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
5706 I<true> the effect of B<Sensor> is inverted: All selected sensors are ignored
5707 and all other sensors are collected.
5711 =head2 Plugin C<sigrok>
5713 The I<sigrok plugin> uses I<libsigrok> to retrieve measurements from any device
5714 supported by the L<sigrok|http://sigrok.org/> project.
5720 <Device "AC Voltage">
5725 <Device "Sound Level">
5726 Driver "cem-dt-885x"
5733 =item B<LogLevel> B<0-5>
5735 The I<sigrok> logging level to pass on to the I<collectd> log, as a number
5736 between B<0> and B<5> (inclusive). These levels correspond to C<None>,
5737 C<Errors>, C<Warnings>, C<Informational>, C<Debug >and C<Spew>, respectively.
5738 The default is B<2> (C<Warnings>). The I<sigrok> log messages, regardless of
5739 their level, are always submitted to I<collectd> at its INFO log level.
5741 =item E<lt>B<Device> I<Name>E<gt>
5743 A sigrok-supported device, uniquely identified by this section's options. The
5744 I<Name> is passed to I<collectd> as the I<plugin instance>.
5746 =item B<Driver> I<DriverName>
5748 The sigrok driver to use for this device.
5750 =item B<Conn> I<ConnectionSpec>
5752 If the device cannot be auto-discovered, or more than one might be discovered
5753 by the driver, I<ConnectionSpec> specifies the connection string to the device.
5754 It can be of the form of a device path (e.g.E<nbsp>C</dev/ttyUSB2>), or, in
5755 case of a non-serial USB-connected device, the USB I<VendorID>B<.>I<ProductID>
5756 separated by a period (e.g.E<nbsp>C<0403.6001>). A USB device can also be
5757 specified as I<Bus>B<.>I<Address> (e.g.E<nbsp>C<1.41>).
5759 =item B<SerialComm> I<SerialSpec>
5761 For serial devices with non-standard port settings, this option can be used
5762 to specify them in a form understood by I<sigrok>, e.g.E<nbsp>C<9600/8n1>.
5763 This should not be necessary; drivers know how to communicate with devices they
5766 =item B<MinimumInterval> I<Seconds>
5768 Specifies the minimum time between measurement dispatches to I<collectd>, in
5769 seconds. Since some I<sigrok> supported devices can acquire measurements many
5770 times per second, it may be necessary to throttle these. For example, the
5771 I<RRD plugin> cannot process writes more than once per second.
5773 The default B<MinimumInterval> is B<0>, meaning measurements received from the
5774 device are always dispatched to I<collectd>. When throttled, unused
5775 measurements are discarded.
5779 =head2 Plugin C<smart>
5781 The C<smart> plugin collects SMART information from physical
5782 disks. Values collectd include temperature, power cycle count, poweron
5783 time and bad sectors. Also, all SMART attributes are collected along
5784 with the normalized current value, the worst value, the threshold and
5785 a human readable value.
5787 Using the following two options you can ignore some disks or configure the
5788 collection only of specific disks.
5792 =item B<Disk> I<Name>
5794 Select the disk I<Name>. Whether it is collected or ignored depends on the
5795 B<IgnoreSelected> setting, see below. As with other plugins that use the
5796 daemon's ignorelist functionality, a string that starts and ends with a slash
5797 is interpreted as a regular expression. Examples:
5802 =item B<IgnoreSelected> B<true>|B<false>
5804 Sets whether selected disks, i.E<nbsp>e. the ones matches by any of the B<Disk>
5805 statements, are ignored or if all other disks are ignored. The behavior
5806 (hopefully) is intuitive: If no B<Disk> option is configured, all disks are
5807 collected. If at least one B<Disk> option is given and no B<IgnoreSelected> or
5808 set to B<false>, B<only> matching disks will be collected. If B<IgnoreSelected>
5809 is set to B<true>, all disks are collected B<except> the ones matched.
5813 =head2 Plugin C<snmp>
5815 Since the configuration of the C<snmp plugin> is a little more complicated than
5816 other plugins, its documentation has been moved to an own manpage,
5817 L<collectd-snmp(5)>. Please see there for details.
5819 =head2 Plugin C<statsd>
5821 The I<statsd plugin> listens to a UDP socket, reads "events" in the statsd
5822 protocol and dispatches rates or other aggregates of these numbers
5825 The plugin implements the I<Counter>, I<Timer>, I<Gauge> and I<Set> types which
5826 are dispatched as the I<collectd> types C<derive>, C<latency>, C<gauge> and
5827 C<objects> respectively.
5829 The following configuration options are valid:
5833 =item B<Host> I<Host>
5835 Bind to the hostname / address I<Host>. By default, the plugin will bind to the
5836 "any" address, i.e. accept packets sent to any of the hosts addresses.
5838 =item B<Port> I<Port>
5840 UDP port to listen to. This can be either a service name or a port number.
5841 Defaults to C<8125>.
5843 =item B<DeleteCounters> B<false>|B<true>
5845 =item B<DeleteTimers> B<false>|B<true>
5847 =item B<DeleteGauges> B<false>|B<true>
5849 =item B<DeleteSets> B<false>|B<true>
5851 These options control what happens if metrics are not updated in an interval.
5852 If set to B<False>, the default, metrics are dispatched unchanged, i.e. the
5853 rate of counters and size of sets will be zero, timers report C<NaN> and gauges
5854 are unchanged. If set to B<True>, the such metrics are not dispatched and
5855 removed from the internal cache.
5857 =item B<TimerPercentile> I<Percent>
5859 Calculate and dispatch the configured percentile, i.e. compute the latency, so
5860 that I<Percent> of all reported timers are smaller than or equal to the
5861 computed latency. This is useful for cutting off the long tail latency, as it's
5862 often done in I<Service Level Agreements> (SLAs).
5864 Different percentiles can be calculated by setting this option several times.
5865 If none are specified, no percentiles are calculated / dispatched.
5867 =item B<TimerLower> B<false>|B<true>
5869 =item B<TimerUpper> B<false>|B<true>
5871 =item B<TimerSum> B<false>|B<true>
5873 =item B<TimerCount> B<false>|B<true>
5875 Calculate and dispatch various values out of I<Timer> metrics received during
5876 an interval. If set to B<False>, the default, these values aren't calculated /
5881 =head2 Plugin C<swap>
5883 The I<Swap plugin> collects information about used and available swap space. On
5884 I<Linux> and I<Solaris>, the following options are available:
5888 =item B<ReportByDevice> B<false>|B<true>
5890 Configures how to report physical swap devices. If set to B<false> (the
5891 default), the summary over all swap devices is reported only, i.e. the globally
5892 used and available space over all devices. If B<true> is configured, the used
5893 and available space of each device will be reported separately.
5895 This option is only available if the I<Swap plugin> can read C</proc/swaps>
5896 (under Linux) or use the L<swapctl(2)> mechanism (under I<Solaris>).
5898 =item B<ReportBytes> B<false>|B<true>
5900 When enabled, the I<swap I/O> is reported in bytes. When disabled, the default,
5901 I<swap I/O> is reported in pages. This option is available under Linux only.
5903 =item B<ValuesAbsolute> B<true>|B<false>
5905 Enables or disables reporting of absolute swap metrics, i.e. number of I<bytes>
5906 available and used. Defaults to B<true>.
5908 =item B<ValuesPercentage> B<false>|B<true>
5910 Enables or disables reporting of relative swap metrics, i.e. I<percent>
5911 available and free. Defaults to B<false>.
5913 This is useful for deploying I<collectd> in a heterogeneous environment, where
5914 swap sizes differ and you want to specify generic thresholds or similar.
5918 =head2 Plugin C<syslog>
5922 =item B<LogLevel> B<debug|info|notice|warning|err>
5924 Sets the log-level. If, for example, set to B<notice>, then all events with
5925 severity B<notice>, B<warning>, or B<err> will be submitted to the
5928 Please note that B<debug> is only available if collectd has been compiled with
5931 =item B<NotifyLevel> B<OKAY>|B<WARNING>|B<FAILURE>
5933 Controls which notifications should be sent to syslog. The default behaviour is
5934 not to send any. Less severe notifications always imply logging more severe
5935 notifications: Setting this to B<OKAY> means all notifications will be sent to
5936 syslog, setting this to B<WARNING> will send B<WARNING> and B<FAILURE>
5937 notifications but will dismiss B<OKAY> notifications. Setting this option to
5938 B<FAILURE> will only send failures to syslog.
5942 =head2 Plugin C<table>
5944 The C<table plugin> provides generic means to parse tabular data and dispatch
5945 user specified values. Values are selected based on column numbers. For
5946 example, this plugin may be used to get values from the Linux L<proc(5)>
5947 filesystem or CSV (comma separated values) files.
5950 <Table "/proc/slabinfo">
5955 InstancePrefix "active_objs"
5961 InstancePrefix "objperslab"
5968 The configuration consists of one or more B<Table> blocks, each of which
5969 configures one file to parse. Within each B<Table> block, there are one or
5970 more B<Result> blocks, which configure which data to select and how to
5973 The following options are available inside a B<Table> block:
5977 =item B<Instance> I<instance>
5979 If specified, I<instance> is used as the plugin instance. So, in the above
5980 example, the plugin name C<table-slabinfo> would be used. If omitted, the
5981 filename of the table is used instead, with all special characters replaced
5982 with an underscore (C<_>).
5984 =item B<Separator> I<string>
5986 Any character of I<string> is interpreted as a delimiter between the different
5987 columns of the table. A sequence of two or more contiguous delimiters in the
5988 table is considered to be a single delimiter, i.E<nbsp>e. there cannot be any
5989 empty columns. The plugin uses the L<strtok_r(3)> function to parse the lines
5990 of a table - see its documentation for more details. This option is mandatory.
5992 A horizontal tab, newline and carriage return may be specified by C<\\t>,
5993 C<\\n> and C<\\r> respectively. Please note that the double backslashes are
5994 required because of collectd's config parsing.
5998 The following options are available inside a B<Result> block:
6002 =item B<Type> I<type>
6004 Sets the type used to dispatch the values to the daemon. Detailed information
6005 about types and their configuration can be found in L<types.db(5)>. This
6006 option is mandatory.
6008 =item B<InstancePrefix> I<prefix>
6010 If specified, prepend I<prefix> to the type instance. If omitted, only the
6011 B<InstancesFrom> option is considered for the type instance.
6013 =item B<InstancesFrom> I<column0> [I<column1> ...]
6015 If specified, the content of the given columns (identified by the column
6016 number starting at zero) will be used to create the type instance for each
6017 row. Multiple values (and the instance prefix) will be joined together with
6018 dashes (I<->) as separation character. If omitted, only the B<InstancePrefix>
6019 option is considered for the type instance.
6021 The plugin itself does not check whether or not all built instances are
6022 different. It’s your responsibility to assure that each is unique. This is
6023 especially true, if you do not specify B<InstancesFrom>: B<You> have to make
6024 sure that the table only contains one row.
6026 If neither B<InstancePrefix> nor B<InstancesFrom> is given, the type instance
6029 =item B<ValuesFrom> I<column0> [I<column1> ...]
6031 Specifies the columns (identified by the column numbers starting at zero)
6032 whose content is used as the actual data for the data sets that are dispatched
6033 to the daemon. How many such columns you need is determined by the B<Type>
6034 setting above. If you specify too many or not enough columns, the plugin will
6035 complain about that and no data will be submitted to the daemon. The plugin
6036 uses L<strtoll(3)> and L<strtod(3)> to parse counter and gauge values
6037 respectively, so anything supported by those functions is supported by the
6038 plugin as well. This option is mandatory.
6042 =head2 Plugin C<tail>
6044 The C<tail plugin> follows logfiles, just like L<tail(1)> does, parses
6045 each line and dispatches found values. What is matched can be configured by the
6046 user using (extended) regular expressions, as described in L<regex(7)>.
6049 <File "/var/log/exim4/mainlog">
6053 Regex "S=([1-9][0-9]*)"
6059 Regex "\\<R=local_user\\>"
6060 ExcludeRegex "\\<R=local_user\\>.*mail_spool defer"
6063 Instance "local_user"
6068 The config consists of one or more B<File> blocks, each of which configures one
6069 logfile to parse. Within each B<File> block, there are one or more B<Match>
6070 blocks, which configure a regular expression to search for.
6072 The B<Instance> option in the B<File> block may be used to set the plugin
6073 instance. So in the above example the plugin name C<tail-foo> would be used.
6074 This plugin instance is for all B<Match> blocks that B<follow> it, until the
6075 next B<Instance> option. This way you can extract several plugin instances from
6076 one logfile, handy when parsing syslog and the like.
6078 The B<Interval> option allows you to define the length of time between reads. If
6079 this is not set, the default Interval will be used.
6081 Each B<Match> block has the following options to describe how the match should
6086 =item B<Regex> I<regex>
6088 Sets the regular expression to use for matching against a line. The first
6089 subexpression has to match something that can be turned into a number by
6090 L<strtoll(3)> or L<strtod(3)>, depending on the value of C<CounterAdd>, see
6091 below. Because B<extended> regular expressions are used, you do not need to use
6092 backslashes for subexpressions! If in doubt, please consult L<regex(7)>. Due to
6093 collectd's config parsing you need to escape backslashes, though. So if you
6094 want to match literal parentheses you need to do the following:
6096 Regex "SPAM \\(Score: (-?[0-9]+\\.[0-9]+)\\)"
6098 =item B<ExcludeRegex> I<regex>
6100 Sets an optional regular expression to use for excluding lines from the match.
6101 An example which excludes all connections from localhost from the match:
6103 ExcludeRegex "127\\.0\\.0\\.1"
6105 =item B<DSType> I<Type>
6107 Sets how the values are cumulated. I<Type> is one of:
6111 =item B<GaugeAverage>
6113 Calculate the average.
6117 Use the smallest number only.
6121 Use the greatest number only.
6125 Use the last number found.
6131 =item B<AbsoluteSet>
6133 The matched number is a counter. Simply I<sets> the internal counter to this
6134 value. Variants exist for C<COUNTER>, C<DERIVE>, and C<ABSOLUTE> data sources.
6142 Add the matched value to the internal counter. In case of B<DeriveAdd>, the
6143 matched number may be negative, which will effectively subtract from the
6152 Increase the internal counter by one. These B<DSType> are the only ones that do
6153 not use the matched subexpression, but simply count the number of matched
6154 lines. Thus, you may use a regular expression without submatch in this case.
6158 As you'd expect the B<Gauge*> types interpret the submatch as a floating point
6159 number, using L<strtod(3)>. The B<Counter*> and B<AbsoluteSet> types interpret
6160 the submatch as an unsigned integer using L<strtoull(3)>. The B<Derive*> types
6161 interpret the submatch as a signed integer using L<strtoll(3)>. B<CounterInc>
6162 and B<DeriveInc> do not use the submatch at all and it may be omitted in this
6165 =item B<Type> I<Type>
6167 Sets the type used to dispatch this value. Detailed information about types and
6168 their configuration can be found in L<types.db(5)>.
6170 =item B<Instance> I<TypeInstance>
6172 This optional setting sets the type instance to use.
6176 =head2 Plugin C<tail_csv>
6178 The I<tail_csv plugin> reads files in the CSV format, e.g. the statistics file
6179 written by I<Snort>.
6184 <Metric "snort-dropped">
6189 <File "/var/log/snort/snort.stats">
6190 Instance "snort-eth0"
6192 Collect "snort-dropped"
6196 The configuration consists of one or more B<Metric> blocks that define an index
6197 into the line of the CSV file and how this value is mapped to I<collectd's>
6198 internal representation. These are followed by one or more B<Instance> blocks
6199 which configure which file to read, in which interval and which metrics to
6204 =item E<lt>B<Metric> I<Name>E<gt>
6206 The B<Metric> block configures a new metric to be extracted from the statistics
6207 file and how it is mapped on I<collectd's> data model. The string I<Name> is
6208 only used inside the B<Instance> blocks to refer to this block, so you can use
6209 one B<Metric> block for multiple CSV files.
6213 =item B<Type> I<Type>
6215 Configures which I<Type> to use when dispatching this metric. Types are defined
6216 in the L<types.db(5)> file, see the appropriate manual page for more
6217 information on specifying types. Only types with a single I<data source> are
6218 supported by the I<tail_csv plugin>. The information whether the value is an
6219 absolute value (i.e. a C<GAUGE>) or a rate (i.e. a C<DERIVE>) is taken from the
6220 I<Type's> definition.
6222 =item B<Instance> I<TypeInstance>
6224 If set, I<TypeInstance> is used to populate the type instance field of the
6225 created value lists. Otherwise, no type instance is used.
6227 =item B<ValueFrom> I<Index>
6229 Configure to read the value from the field with the zero-based index I<Index>.
6230 If the value is parsed as signed integer, unsigned integer or double depends on
6231 the B<Type> setting, see above.
6235 =item E<lt>B<File> I<Path>E<gt>
6237 Each B<File> block represents one CSV file to read. There must be at least one
6238 I<File> block but there can be multiple if you have multiple CSV files.
6242 =item B<Instance> I<PluginInstance>
6244 Sets the I<plugin instance> used when dispatching the values.
6246 =item B<Collect> I<Metric>
6248 Specifies which I<Metric> to collect. This option must be specified at least
6249 once, and you can use this option multiple times to specify more than one
6250 metric to be extracted from this statistic file.
6252 =item B<Interval> I<Seconds>
6254 Configures the interval in which to read values from this instance / file.
6255 Defaults to the plugin's default interval.
6257 =item B<TimeFrom> I<Index>
6259 Rather than using the local time when dispatching a value, read the timestamp
6260 from the field with the zero-based index I<Index>. The value is interpreted as
6261 seconds since epoch. The value is parsed as a double and may be factional.
6267 =head2 Plugin C<teamspeak2>
6269 The C<teamspeak2 plugin> connects to the query port of a teamspeak2 server and
6270 polls interesting global and virtual server data. The plugin can query only one
6271 physical server but unlimited virtual servers. You can use the following
6272 options to configure it:
6276 =item B<Host> I<hostname/ip>
6278 The hostname or ip which identifies the physical server.
6281 =item B<Port> I<port>
6283 The query port of the physical server. This needs to be a string.
6286 =item B<Server> I<port>
6288 This option has to be added once for every virtual server the plugin should
6289 query. If you want to query the virtual server on port 8767 this is what the
6290 option would look like:
6294 This option, although numeric, needs to be a string, i.E<nbsp>e. you B<must>
6295 use quotes around it! If no such statement is given only global information
6300 =head2 Plugin C<ted>
6302 The I<TED> plugin connects to a device of "The Energy Detective", a device to
6303 measure power consumption. These devices are usually connected to a serial
6304 (RS232) or USB port. The plugin opens a configured device and tries to read the
6305 current energy readings. For more information on TED, visit
6306 L<http://www.theenergydetective.com/>.
6308 Available configuration options:
6312 =item B<Device> I<Path>
6314 Path to the device on which TED is connected. collectd will need read and write
6315 permissions on that file.
6317 Default: B</dev/ttyUSB0>
6319 =item B<Retries> I<Num>
6321 Apparently reading from TED is not that reliable. You can therefore configure a
6322 number of retries here. You only configure the I<retries> here, to if you
6323 specify zero, one reading will be performed (but no retries if that fails); if
6324 you specify three, a maximum of four readings are performed. Negative values
6331 =head2 Plugin C<tcpconns>
6333 The C<tcpconns plugin> counts the number of currently established TCP
6334 connections based on the local port and/or the remote port. Since there may be
6335 a lot of connections the default if to count all connections with a local port,
6336 for which a listening socket is opened. You can use the following options to
6337 fine-tune the ports you are interested in:
6341 =item B<ListeningPorts> I<true>|I<false>
6343 If this option is set to I<true>, statistics for all local ports for which a
6344 listening socket exists are collected. The default depends on B<LocalPort> and
6345 B<RemotePort> (see below): If no port at all is specifically selected, the
6346 default is to collect listening ports. If specific ports (no matter if local or
6347 remote ports) are selected, this option defaults to I<false>, i.E<nbsp>e. only
6348 the selected ports will be collected unless this option is set to I<true>
6351 =item B<LocalPort> I<Port>
6353 Count the connections to a specific local port. This can be used to see how
6354 many connections are handled by a specific daemon, e.E<nbsp>g. the mailserver.
6355 You have to specify the port in numeric form, so for the mailserver example
6356 you'd need to set B<25>.
6358 =item B<RemotePort> I<Port>
6360 Count the connections to a specific remote port. This is useful to see how
6361 much a remote service is used. This is most useful if you want to know how many
6362 connections a local service has opened to remote services, e.E<nbsp>g. how many
6363 connections a mail server or news server has to other mail or news servers, or
6364 how many connections a web proxy holds to web servers. You have to give the
6365 port in numeric form.
6367 =item B<AllPortsSummary> I<true>|I<false>
6369 If this option is set to I<true> a summary of statistics from all connections
6370 are collectd. This option defaults to I<false>.
6374 =head2 Plugin C<thermal>
6378 =item B<ForceUseProcfs> I<true>|I<false>
6380 By default, the I<Thermal plugin> tries to read the statistics from the Linux
6381 C<sysfs> interface. If that is not available, the plugin falls back to the
6382 C<procfs> interface. By setting this option to I<true>, you can force the
6383 plugin to use the latter. This option defaults to I<false>.
6385 =item B<Device> I<Device>
6387 Selects the name of the thermal device that you want to collect or ignore,
6388 depending on the value of the B<IgnoreSelected> option. This option may be
6389 used multiple times to specify a list of devices.
6391 =item B<IgnoreSelected> I<true>|I<false>
6393 Invert the selection: If set to true, all devices B<except> the ones that
6394 match the device names specified by the B<Device> option are collected. By
6395 default only selected devices are collected if a selection is made. If no
6396 selection is configured at all, B<all> devices are selected.
6400 =head2 Plugin C<threshold>
6402 The I<Threshold plugin> checks values collected or received by I<collectd>
6403 against a configurable I<threshold> and issues I<notifications> if values are
6406 Documentation for this plugin is available in the L<collectd-threshold(5)>
6409 =head2 Plugin C<tokyotyrant>
6411 The I<TokyoTyrant plugin> connects to a TokyoTyrant server and collects a
6412 couple metrics: number of records, and database size on disk.
6416 =item B<Host> I<Hostname/IP>
6418 The hostname or ip which identifies the server.
6419 Default: B<127.0.0.1>
6421 =item B<Port> I<Service/Port>
6423 The query port of the server. This needs to be a string, even if the port is
6424 given in its numeric form.
6429 =head2 Plugin C<unixsock>
6433 =item B<SocketFile> I<Path>
6435 Sets the socket-file which is to be created.
6437 =item B<SocketGroup> I<Group>
6439 If running as root change the group of the UNIX-socket after it has been
6440 created. Defaults to B<collectd>.
6442 =item B<SocketPerms> I<Permissions>
6444 Change the file permissions of the UNIX-socket after it has been created. The
6445 permissions must be given as a numeric, octal value as you would pass to
6446 L<chmod(1)>. Defaults to B<0770>.
6448 =item B<DeleteSocket> B<false>|B<true>
6450 If set to B<true>, delete the socket file before calling L<bind(2)>, if a file
6451 with the given name already exists. If I<collectd> crashes a socket file may be
6452 left over, preventing the daemon from opening a new socket when restarted.
6453 Since this is potentially dangerous, this defaults to B<false>.
6457 =head2 Plugin C<uuid>
6459 This plugin, if loaded, causes the Hostname to be taken from the machine's
6460 UUID. The UUID is a universally unique designation for the machine, usually
6461 taken from the machine's BIOS. This is most useful if the machine is running in
6462 a virtual environment such as Xen, in which case the UUID is preserved across
6463 shutdowns and migration.
6465 The following methods are used to find the machine's UUID, in order:
6471 Check I</etc/uuid> (or I<UUIDFile>).
6475 Check for UUID from HAL (L<http://www.freedesktop.org/wiki/Software/hal>) if
6480 Check for UUID from C<dmidecode> / SMBIOS.
6484 Check for UUID from Xen hypervisor.
6488 If no UUID can be found then the hostname is not modified.
6492 =item B<UUIDFile> I<Path>
6494 Take the UUID from the given file (default I</etc/uuid>).
6498 =head2 Plugin C<varnish>
6500 The I<varnish plugin> collects information about Varnish, an HTTP accelerator.
6501 It collects a subset of the values displayed by L<varnishstat(1)>, and
6502 organizes them in categories which can be enabled or disabled. Currently only
6503 metrics shown in L<varnishstat(1)>'s I<MAIN> section are collected. The exact
6504 meaning of each metric can be found in L<varnish-counters(7)>.
6509 <Instance "example">
6513 CollectConnections true
6514 CollectDirectorDNS false
6518 CollectObjects false
6520 CollectSession false
6530 CollectWorkers false
6534 The configuration consists of one or more E<lt>B<Instance>E<nbsp>I<Name>E<gt>
6535 blocks. I<Name> is the parameter passed to "varnishd -n". If left empty, it
6536 will collectd statistics from the default "varnishd" instance (this should work
6537 fine in most cases).
6539 Inside each E<lt>B<Instance>E<gt> blocks, the following options are recognized:
6543 =item B<CollectBackend> B<true>|B<false>
6545 Back-end connection statistics, such as successful, reused,
6546 and closed connections. True by default.
6548 =item B<CollectBan> B<true>|B<false>
6550 Statistics about ban operations, such as number of bans added, retired, and
6551 number of objects tested against ban operations. Only available with Varnish
6552 3.x and above. False by default.
6554 =item B<CollectCache> B<true>|B<false>
6556 Cache hits and misses. True by default.
6558 =item B<CollectConnections> B<true>|B<false>
6560 Number of client connections received, accepted and dropped. True by default.
6562 =item B<CollectDirectorDNS> B<true>|B<false>
6564 DNS director lookup cache statistics. Only available with Varnish 3.x. False by
6567 =item B<CollectESI> B<true>|B<false>
6569 Edge Side Includes (ESI) parse statistics. False by default.
6571 =item B<CollectFetch> B<true>|B<false>
6573 Statistics about fetches (HTTP requests sent to the backend). False by default.
6575 =item B<CollectHCB> B<true>|B<false>
6577 Inserts and look-ups in the crit bit tree based hash. Look-ups are
6578 divided into locked and unlocked look-ups. False by default.
6580 =item B<CollectObjects> B<true>|B<false>
6582 Statistics on cached objects: number of objects expired, nuked (prematurely
6583 expired), saved, moved, etc. False by default.
6585 =item B<CollectPurge> B<true>|B<false>
6587 Statistics about purge operations, such as number of purges added, retired, and
6588 number of objects tested against purge operations. Only available with Varnish
6589 2.x. False by default.
6591 =item B<CollectSession> B<true>|B<false>
6593 Client session statistics. Number of past and current sessions, session herd and
6594 linger counters, etc. False by default. Note that if using Varnish 4.x, some
6595 metrics found in the Connections and Threads sections with previous versions of
6596 Varnish have been moved here.
6598 =item B<CollectSHM> B<true>|B<false>
6600 Statistics about the shared memory log, a memory region to store
6601 log messages which is flushed to disk when full. True by default.
6603 =item B<CollectSMA> B<true>|B<false>
6605 malloc or umem (umem_alloc(3MALLOC) based) storage statistics. The umem storage
6606 component is Solaris specific. Only available with Varnish 2.x. False by
6609 =item B<CollectSMS> B<true>|B<false>
6611 synth (synthetic content) storage statistics. This storage
6612 component is used internally only. False by default.
6614 =item B<CollectSM> B<true>|B<false>
6616 file (memory mapped file) storage statistics. Only available with Varnish 2.x.
6619 =item B<CollectStruct> B<true>|B<false>
6621 Current varnish internal state statistics. Number of current sessions, objects
6622 in cache store, open connections to backends (with Varnish 2.x), etc. False by
6625 =item B<CollectTotals> B<true>|B<false>
6627 Collects overview counters, such as the number of sessions created,
6628 the number of requests and bytes transferred. False by default.
6630 =item B<CollectUptime> B<true>|B<false>
6632 Varnish uptime. Only available with Varnish 3.x and above. False by default.
6634 =item B<CollectVCL> B<true>|B<false>
6636 Number of total (available + discarded) VCL (config files). False by default.
6638 =item B<CollectVSM> B<true>|B<false>
6640 Collect statistics about Varnish's shared memory usage (used by the logging and
6641 statistics subsystems). Only available with Varnish 4.x. False by default.
6643 =item B<CollectWorkers> B<true>|B<false>
6645 Collect statistics about worker threads. False by default.
6649 =head2 Plugin C<virt>
6651 This plugin allows CPU, disk and network load to be collected for virtualized
6652 guests on the machine. This means that these metrics can be collected for guest
6653 systems without installing any software on them - I<collectd> only runs on the
6654 host system. The statistics are collected through libvirt
6655 (L<http://libvirt.org/>).
6657 Only I<Connection> is required.
6661 =item B<Connection> I<uri>
6663 Connect to the hypervisor given by I<uri>. For example if using Xen use:
6665 Connection "xen:///"
6667 Details which URIs allowed are given at L<http://libvirt.org/uri.html>.
6669 =item B<RefreshInterval> I<seconds>
6671 Refresh the list of domains and devices every I<seconds>. The default is 60
6672 seconds. Setting this to be the same or smaller than the I<Interval> will cause
6673 the list of domains and devices to be refreshed on every iteration.
6675 Refreshing the devices in particular is quite a costly operation, so if your
6676 virtualization setup is static you might consider increasing this. If this
6677 option is set to 0, refreshing is disabled completely.
6679 =item B<Domain> I<name>
6681 =item B<BlockDevice> I<name:dev>
6683 =item B<InterfaceDevice> I<name:dev>
6685 =item B<IgnoreSelected> B<true>|B<false>
6687 Select which domains and devices are collected.
6689 If I<IgnoreSelected> is not given or B<false> then only the listed domains and
6690 disk/network devices are collected.
6692 If I<IgnoreSelected> is B<true> then the test is reversed and the listed
6693 domains and disk/network devices are ignored, while the rest are collected.
6695 The domain name and device names may use a regular expression, if the name is
6696 surrounded by I</.../> and collectd was compiled with support for regexps.
6698 The default is to collect statistics for all domains and all their devices.
6702 BlockDevice "/:hdb/"
6703 IgnoreSelected "true"
6705 Ignore all I<hdb> devices on any domain, but other block devices (eg. I<hda>)
6708 =item B<HostnameFormat> B<name|uuid|hostname|...>
6710 When the virt plugin logs data, it sets the hostname of the collected data
6711 according to this setting. The default is to use the guest name as provided by
6712 the hypervisor, which is equal to setting B<name>.
6714 B<uuid> means use the guest's UUID. This is useful if you want to track the
6715 same guest across migrations.
6717 B<hostname> means to use the global B<Hostname> setting, which is probably not
6718 useful on its own because all guests will appear to have the same name.
6720 You can also specify combinations of these fields. For example B<name uuid>
6721 means to concatenate the guest name and UUID (with a literal colon character
6722 between, thus I<"foo:1234-1234-1234-1234">).
6724 =item B<InterfaceFormat> B<name>|B<address>
6726 When the virt plugin logs interface data, it sets the name of the collected
6727 data according to this setting. The default is to use the path as provided by
6728 the hypervisor (the "dev" property of the target node), which is equal to
6731 B<address> means use the interface's mac address. This is useful since the
6732 interface path might change between reboots of a guest or across migrations.
6734 =item B<PluginInstanceFormat> B<name|uuid>
6736 When the virt plugin logs data, it sets the plugin_instance of the collected
6737 data according to this setting. The default is to use the guest name as provided
6738 by the hypervisor, which is equal to setting B<name>.
6740 B<uuid> means use the guest's UUID.
6744 =head2 Plugin C<vmem>
6746 The C<vmem> plugin collects information about the usage of virtual memory.
6747 Since the statistics provided by the Linux kernel are very detailed, they are
6748 collected very detailed. However, to get all the details, you have to switch
6749 them on manually. Most people just want an overview over, such as the number of
6750 pages read from swap space.
6754 =item B<Verbose> B<true>|B<false>
6756 Enables verbose collection of information. This will start collecting page
6757 "actions", e.E<nbsp>g. page allocations, (de)activations, steals and so on.
6758 Part of these statistics are collected on a "per zone" basis.
6762 =head2 Plugin C<vserver>
6764 This plugin doesn't have any options. B<VServer> support is only available for
6765 Linux. It cannot yet be found in a vanilla kernel, though. To make use of this
6766 plugin you need a kernel that has B<VServer> support built in, i.E<nbsp>e. you
6767 need to apply the patches and compile your own kernel, which will then provide
6768 the F</proc/virtual> filesystem that is required by this plugin.
6770 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
6772 B<Note>: The traffic collected by this plugin accounts for the amount of
6773 traffic passing a socket which might be a lot less than the actual on-wire
6774 traffic (e.E<nbsp>g. due to headers and retransmission). If you want to
6775 collect on-wire traffic you could, for example, use the logging facilities of
6776 iptables to feed data for the guest IPs into the iptables plugin.
6778 =head2 Plugin C<write_graphite>
6780 The C<write_graphite> plugin writes data to I<Graphite>, an open-source metrics
6781 storage and graphing project. The plugin connects to I<Carbon>, the data layer
6782 of I<Graphite>, via I<TCP> or I<UDP> and sends data via the "line based"
6783 protocol (per default using portE<nbsp>2003). The data will be sent in blocks
6784 of at most 1428 bytes to minimize the number of network packets.
6788 <Plugin write_graphite>
6798 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
6799 blocks. Inside the B<Node> blocks, the following options are recognized:
6803 =item B<Host> I<Address>
6805 Hostname or address to connect to. Defaults to C<localhost>.
6807 =item B<Port> I<Service>
6809 Service name or port number to connect to. Defaults to C<2003>.
6811 =item B<Protocol> I<String>
6813 Protocol to use when connecting to I<Graphite>. Defaults to C<tcp>.
6815 =item B<LogSendErrors> B<false>|B<true>
6817 If set to B<true> (the default), logs errors when sending data to I<Graphite>.
6818 If set to B<false>, it will not log the errors. This is especially useful when
6819 using Protocol UDP since many times we want to use the "fire-and-forget"
6820 approach and logging errors fills syslog with unneeded messages.
6822 =item B<Prefix> I<String>
6824 When set, I<String> is added in front of the host name. Dots and whitespace are
6825 I<not> escaped in this string (see B<EscapeCharacter> below).
6827 =item B<Postfix> I<String>
6829 When set, I<String> is appended to the host name. Dots and whitespace are
6830 I<not> escaped in this string (see B<EscapeCharacter> below).
6832 =item B<EscapeCharacter> I<Char>
6834 I<Carbon> uses the dot (C<.>) as escape character and doesn't allow whitespace
6835 in the identifier. The B<EscapeCharacter> option determines which character
6836 dots, whitespace and control characters are replaced with. Defaults to
6839 =item B<StoreRates> B<false>|B<true>
6841 If set to B<true> (the default), convert counter values to rates. If set to
6842 B<false> counter values are stored as is, i.E<nbsp>e. as an increasing integer
6845 =item B<SeparateInstances> B<false>|B<true>
6847 If set to B<true>, the plugin instance and type instance will be in their own
6848 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
6849 default), the plugin and plugin instance (and likewise the type and type
6850 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
6852 =item B<AlwaysAppendDS> B<false>|B<true>
6854 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
6855 identifier. If set to B<false> (the default), this is only done when there is
6860 =head2 Plugin C<write_tsdb>
6862 The C<write_tsdb> plugin writes data to I<OpenTSDB>, a scalable open-source
6863 time series database. The plugin connects to a I<TSD>, a masterless, no shared
6864 state daemon that ingests metrics and stores them in HBase. The plugin uses
6865 I<TCP> over the "line based" protocol with a default port 4242. The data will
6866 be sent in blocks of at most 1428 bytes to minimize the number of network
6873 Host "tsd-1.my.domain"
6875 HostTags "status=production"
6879 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
6880 blocks. Inside the B<Node> blocks, the following options are recognized:
6884 =item B<Host> I<Address>
6886 Hostname or address to connect to. Defaults to C<localhost>.
6888 =item B<Port> I<Service>
6890 Service name or port number to connect to. Defaults to C<4242>.
6893 =item B<HostTags> I<String>
6895 When set, I<HostTags> is added to the end of the metric. It is intended to be
6896 used for name=value pairs that the TSD will tag the metric with. Dots and
6897 whitespace are I<not> escaped in this string.
6899 =item B<StoreRates> B<false>|B<true>
6901 If set to B<true>, convert counter values to rates. If set to B<false>
6902 (the default) counter values are stored as is, as an increasing
6905 =item B<AlwaysAppendDS> B<false>|B<true>
6907 If set the B<true>, append the name of the I<Data Source> (DS) to the "metric"
6908 identifier. If set to B<false> (the default), this is only done when there is
6913 =head2 Plugin C<write_mongodb>
6915 The I<write_mongodb plugin> will send values to I<MongoDB>, a schema-less
6920 <Plugin "write_mongodb">
6929 The plugin can send values to multiple instances of I<MongoDB> by specifying
6930 one B<Node> block for each instance. Within the B<Node> blocks, the following
6931 options are available:
6935 =item B<Host> I<Address>
6937 Hostname or address to connect to. Defaults to C<localhost>.
6939 =item B<Port> I<Service>
6941 Service name or port number to connect to. Defaults to C<27017>.
6943 =item B<Timeout> I<Timeout>
6945 Set the timeout for each operation on I<MongoDB> to I<Timeout> milliseconds.
6946 Setting this option to zero means no timeout, which is the default.
6948 =item B<StoreRates> B<false>|B<true>
6950 If set to B<true> (the default), convert counter values to rates. If set to
6951 B<false> counter values are stored as is, i.e. as an increasing integer
6954 =item B<Database> I<Database>
6956 =item B<User> I<User>
6958 =item B<Password> I<Password>
6960 Sets the information used when authenticating to a I<MongoDB> database. The
6961 fields are optional (in which case no authentication is attempted), but if you
6962 want to use authentication all three fields must be set.
6966 =head2 Plugin C<write_http>
6968 This output plugin submits values to an HTTP server using POST requests and
6969 encoding metrics with JSON or using the C<PUTVAL> command described in
6970 L<collectd-unixsock(5)>.
6974 <Plugin "write_http">
6976 URL "http://example.com/post-collectd"
6983 The plugin can send values to multiple HTTP servers by specifying one
6984 E<lt>B<Node>E<nbsp>I<Name>E<gt> block for each server. Within each B<Node>
6985 block, the following options are available:
6991 URL to which the values are submitted to. Mandatory.
6993 =item B<User> I<Username>
6995 Optional user name needed for authentication.
6997 =item B<Password> I<Password>
6999 Optional password needed for authentication.
7001 =item B<VerifyPeer> B<true>|B<false>
7003 Enable or disable peer SSL certificate verification. See
7004 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
7006 =item B<VerifyHost> B<true|false>
7008 Enable or disable peer host name verification. If enabled, the plugin checks if
7009 the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
7010 matches the host name provided by the B<URL> option. If this identity check
7011 fails, the connection is aborted. Obviously, only works when connecting to a
7012 SSL enabled server. Enabled by default.
7014 =item B<CACert> I<File>
7016 File that holds one or more SSL certificates. If you want to use HTTPS you will
7017 possibly need this option. What CA certificates come bundled with C<libcurl>
7018 and are checked by default depends on the distribution you use.
7020 =item B<CAPath> I<Directory>
7022 Directory holding one or more CA certificate files. You can use this if for
7023 some reason all the needed CA certificates aren't in the same file and can't be
7024 pointed to using the B<CACert> option. Requires C<libcurl> to be built against
7027 =item B<ClientKey> I<File>
7029 File that holds the private key in PEM format to be used for certificate-based
7032 =item B<ClientCert> I<File>
7034 File that holds the SSL certificate to be used for certificate-based
7037 =item B<ClientKeyPass> I<Password>
7039 Password required to load the private key in B<ClientKey>.
7041 =item B<SSLVersion> B<SSLv2>|B<SSLv3>|B<TLSv1>|B<TLSv1_0>|B<TLSv1_1>|B<TLSv1_2>
7043 Define which SSL protocol version must be used. By default C<libcurl> will
7044 attempt to figure out the remote SSL protocol version. See
7045 L<curl_easy_setopt(3)> for more details.
7047 =item B<Format> B<Command>|B<JSON>
7049 Format of the output to generate. If set to B<Command>, will create output that
7050 is understood by the I<Exec> and I<UnixSock> plugins. When set to B<JSON>, will
7051 create output in the I<JavaScript Object Notation> (JSON).
7053 Defaults to B<Command>.
7055 =item B<StoreRates> B<true|false>
7057 If set to B<true>, convert counter values to rates. If set to B<false> (the
7058 default) counter values are stored as is, i.e. as an increasing integer number.
7060 =item B<BufferSize> I<Bytes>
7062 Sets the send buffer size to I<Bytes>. By increasing this buffer, less HTTP
7063 requests will be generated, but more metrics will be batched / metrics are
7064 cached for longer before being sent, introducing additional delay until they
7065 are available on the server side. I<Bytes> must be at least 1024 and cannot
7066 exceed the size of an C<int>, i.e. 2E<nbsp>GByte.
7067 Defaults to C<4096>.
7071 =head2 Plugin C<write_kafka>
7073 The I<write_kafka plugin> will send values to a I<Kafka> topic, a distributed
7077 <Plugin "write_kafka">
7078 Property "metadata.broker.list" "broker1:9092,broker2:9092"
7084 The following options are understood by the I<write_kafka plugin>:
7088 =item E<lt>B<Topic> I<Name>E<gt>
7090 The plugin's configuration consists of one or more B<Topic> blocks. Each block
7091 is given a unique I<Name> and specifies one kafka producer.
7092 Inside the B<Topic> block, the following per-topic options are
7097 =item B<Property> I<String> I<String>
7099 Configure the named property for the current topic. Properties are
7100 forwarded to the kafka producer library B<librdkafka>.
7102 =item B<Key> I<String>
7104 Use the specified string as a partioning key for the topic. Kafka breaks
7105 topic into partitions and guarantees that for a given topology, the same
7106 consumer will be used for a specific key. The special (case insensitive)
7107 string B<Random> can be used to specify that an arbitrary partition should
7110 =item B<Format> B<Command>|B<JSON>|B<Graphite>
7112 Selects the format in which messages are sent to the broker. If set to
7113 B<Command> (the default), values are sent as C<PUTVAL> commands which are
7114 identical to the syntax used by the I<Exec> and I<UnixSock plugins>.
7116 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
7117 an easy and straight forward exchange format.
7119 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
7120 C<E<lt>metricE<gt> E<lt>valueE<gt> E<lt>timestampE<gt>\n>.
7122 =item B<StoreRates> B<true>|B<false>
7124 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
7125 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
7126 default), no conversion is performed. Otherwise the conversion is performed
7127 using the internal value cache.
7129 Please note that currently this option is only used if the B<Format> option has
7130 been set to B<JSON>.
7132 =item B<GraphitePrefix> (B<Format>=I<Graphite> only)
7134 A prefix can be added in the metric name when outputting in the I<Graphite>
7135 format. It's added before the I<Host> name.
7137 C<E<lt>prefixE<gt>E<lt>hostE<gt>E<lt>postfixE<gt>E<lt>pluginE<gt>E<lt>typeE<gt>E<lt>nameE<gt>>
7139 =item B<GraphitePostfix> (B<Format>=I<Graphite> only)
7141 A postfix can be added in the metric name when outputting in the I<Graphite>
7142 format. It's added after the I<Host> name.
7144 C<E<lt>prefixE<gt>E<lt>hostE<gt>E<lt>postfixE<gt>E<lt>pluginE<gt>E<lt>typeE<gt>E<lt>nameE<gt>>
7146 =item B<GraphiteEscapeChar> (B<Format>=I<Graphite> only)
7148 Specify a character to replace dots (.) in the host part of the metric name.
7149 In I<Graphite> metric name, dots are used as separators between different
7150 metric parts (host, plugin, type).
7151 Default is C<_> (I<Underscore>).
7153 =item B<GraphiteSeparateInstances> B<false>|B<true>
7155 If set to B<true>, the plugin instance and type instance will be in their own
7156 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
7157 default), the plugin and plugin instance (and likewise the type and type
7158 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
7160 =item B<StoreRates> B<true>|B<false>
7162 If set to B<true> (the default), convert counter values to rates. If set to
7163 B<false> counter values are stored as is, i.e. as an increasing integer number.
7165 This will be reflected in the C<ds_type> tag: If B<StoreRates> is enabled,
7166 converted values will have "rate" appended to the data source type, e.g.
7167 C<ds_type:derive:rate>.
7171 =item B<Property> I<String> I<String>
7173 Configure the kafka producer through properties, you almost always will
7174 want to set B<metadata.broker.list> to your Kafka broker list.
7178 =head2 Plugin C<write_redis>
7180 The I<write_redis plugin> submits values to I<Redis>, a data structure server.
7184 <Plugin "write_redis">
7192 Values are submitted to I<Sorted Sets>, using the metric name as the key, and
7193 the timestamp as the score. Retrieving a date range can then be done using the
7194 C<ZRANGEBYSCORE> I<Redis> command. Additionnally, all the identifiers of these
7195 I<Sorted Sets> are kept in a I<Set> called C<collectd/values> and can be
7196 retrieved using the C<SMEMBERS> I<Redis> command. See
7197 L<http://redis.io/commands#sorted_set> and L<http://redis.io/commands#set> for
7200 The information shown in the synopsis above is the I<default configuration>
7201 which is used by the plugin if no configuration is present.
7203 The plugin can send values to multiple instances of I<Redis> by specifying
7204 one B<Node> block for each instance. Within the B<Node> blocks, the following
7205 options are available:
7209 =item B<Node> I<Nodename>
7211 The B<Node> block identifies a new I<Redis> node, that is a new I<Redis>
7212 instance running in an specified host and port. The name for node is a
7213 canonical identifier which is used as I<plugin instance>. It is limited to
7214 64E<nbsp>characters in length.
7216 =item B<Host> I<Hostname>
7218 The B<Host> option is the hostname or IP-address where the I<Redis> instance is
7221 =item B<Port> I<Port>
7223 The B<Port> option is the TCP port on which the Redis instance accepts
7224 connections. Either a service name of a port number may be given. Please note
7225 that numerical port numbers must be given as a string, too.
7227 =item B<Timeout> I<Timeout in miliseconds>
7229 The B<Timeout> option sets the socket connection timeout, in milliseconds.
7233 =head2 Plugin C<write_riemann>
7235 The I<write_riemann plugin> will send values to I<Riemann>, a powerful stream
7236 aggregation and monitoring system. The plugin sends I<Protobuf> encoded data to
7237 I<Riemann> using UDP packets.
7241 <Plugin "write_riemann">
7247 AlwaysAppendDS false
7251 Attribute "foo" "bar"
7254 The following options are understood by the I<write_riemann plugin>:
7258 =item E<lt>B<Node> I<Name>E<gt>
7260 The plugin's configuration consists of one or more B<Node> blocks. Each block
7261 is given a unique I<Name> and specifies one connection to an instance of
7262 I<Riemann>. Indise the B<Node> block, the following per-connection options are
7267 =item B<Host> I<Address>
7269 Hostname or address to connect to. Defaults to C<localhost>.
7271 =item B<Port> I<Service>
7273 Service name or port number to connect to. Defaults to C<5555>.
7275 =item B<Protocol> B<UDP>|B<TCP>
7277 Specify the protocol to use when communicating with I<Riemann>. Defaults to
7280 =item B<Batch> B<true>|B<false>
7282 If set to B<true> and B<Protocol> is set to B<TCP>,
7283 events will be batched in memory and flushed at
7284 regular intervals or when B<BatchMaxSize> is exceeded.
7286 Notifications are not batched and sent as soon as possible.
7288 When enabled, it can occur that events get processed by the Riemann server
7289 close to or after their expiration time. Tune the B<TTLFactor> and
7290 B<BatchMaxSize> settings according to the amount of values collected, if this
7295 =item B<BatchMaxSize> I<size>
7297 Maximum payload size for a riemann packet. Defaults to 8192
7299 =item B<StoreRates> B<true>|B<false>
7301 If set to B<true> (the default), convert counter values to rates. If set to
7302 B<false> counter values are stored as is, i.e. as an increasing integer number.
7304 This will be reflected in the C<ds_type> tag: If B<StoreRates> is enabled,
7305 converted values will have "rate" appended to the data source type, e.g.
7306 C<ds_type:derive:rate>.
7308 =item B<AlwaysAppendDS> B<false>|B<true>
7310 If set the B<true>, append the name of the I<Data Source> (DS) to the
7311 "service", i.e. the field that, together with the "host" field, uniquely
7312 identifies a metric in I<Riemann>. If set to B<false> (the default), this is
7313 only done when there is more than one DS.
7315 =item B<TTLFactor> I<Factor>
7317 I<Riemann> events have a I<Time to Live> (TTL) which specifies how long each
7318 event is considered active. I<collectd> populates this field based on the
7319 metrics interval setting. This setting controls the factor with which the
7320 interval is multiplied to set the TTL. The default value is B<2.0>. Unless you
7321 know exactly what you're doing, you should only increase this setting from its
7324 =item B<Notifications> B<false>|B<true>
7326 If set to B<true>, create riemann events for notifications. This is B<true>
7327 by default. When processing thresholds from write_riemann, it might prove
7328 useful to avoid getting notification events.
7330 =item B<CheckThresholds> B<false>|B<true>
7332 If set to B<true>, attach state to events based on thresholds defined
7333 in the B<Threshold> plugin. Defaults to B<false>.
7335 =item B<EventServicePrefix> I<String>
7337 Add the given string as a prefix to the event service name.
7338 If B<EventServicePrefix> not set or set to an empty string (""),
7339 no prefix will be used.
7343 =item B<Tag> I<String>
7345 Add the given string as an additional tag to the metric being sent to
7348 =item B<Attribute> I<String> I<String>
7350 Consider the two given strings to be the key and value of an additional
7351 attribute for each metric being sent out to I<Riemann>.
7355 =head2 Plugin C<zookeeper>
7357 The I<zookeeper plugin> will collect statistics from a I<Zookeeper> server
7358 using the mntr command. It requires Zookeeper 3.4.0+ and access to the
7363 <Plugin "zookeeper">
7370 =item B<Host> I<Address>
7372 Hostname or address to connect to. Defaults to C<localhost>.
7374 =item B<Port> I<Service>
7376 Service name or port number to connect to. Defaults to C<2181>.
7380 =head1 THRESHOLD CONFIGURATION
7382 Starting with version C<4.3.0> collectd has support for B<monitoring>. By that
7383 we mean that the values are not only stored or sent somewhere, but that they
7384 are judged and, if a problem is recognized, acted upon. The only action
7385 collectd takes itself is to generate and dispatch a "notification". Plugins can
7386 register to receive notifications and perform appropriate further actions.
7388 Since systems and what you expect them to do differ a lot, you can configure
7389 B<thresholds> for your values freely. This gives you a lot of flexibility but
7390 also a lot of responsibility.
7392 Every time a value is out of range a notification is dispatched. This means
7393 that the idle percentage of your CPU needs to be less then the configured
7394 threshold only once for a notification to be generated. There's no such thing
7395 as a moving average or similar - at least not now.
7397 Also, all values that match a threshold are considered to be relevant or
7398 "interesting". As a consequence collectd will issue a notification if they are
7399 not received for B<Timeout> iterations. The B<Timeout> configuration option is
7400 explained in section L<"GLOBAL OPTIONS">. If, for example, B<Timeout> is set to
7401 "2" (the default) and some hosts sends it's CPU statistics to the server every
7402 60 seconds, a notification will be dispatched after about 120 seconds. It may
7403 take a little longer because the timeout is checked only once each B<Interval>
7406 When a value comes within range again or is received after it was missing, an
7407 "OKAY-notification" is dispatched.
7409 Here is a configuration example to get you started. Read below for more
7422 <Plugin "interface">
7439 WarningMin 100000000
7445 There are basically two types of configuration statements: The C<Host>,
7446 C<Plugin>, and C<Type> blocks select the value for which a threshold should be
7447 configured. The C<Plugin> and C<Type> blocks may be specified further using the
7448 C<Instance> option. You can combine the block by nesting the blocks, though
7449 they must be nested in the above order, i.E<nbsp>e. C<Host> may contain either
7450 C<Plugin> and C<Type> blocks, C<Plugin> may only contain C<Type> blocks and
7451 C<Type> may not contain other blocks. If multiple blocks apply to the same
7452 value the most specific block is used.
7454 The other statements specify the threshold to configure. They B<must> be
7455 included in a C<Type> block. Currently the following statements are recognized:
7459 =item B<FailureMax> I<Value>
7461 =item B<WarningMax> I<Value>
7463 Sets the upper bound of acceptable values. If unset defaults to positive
7464 infinity. If a value is greater than B<FailureMax> a B<FAILURE> notification
7465 will be created. If the value is greater than B<WarningMax> but less than (or
7466 equal to) B<FailureMax> a B<WARNING> notification will be created.
7468 =item B<FailureMin> I<Value>
7470 =item B<WarningMin> I<Value>
7472 Sets the lower bound of acceptable values. If unset defaults to negative
7473 infinity. If a value is less than B<FailureMin> a B<FAILURE> notification will
7474 be created. If the value is less than B<WarningMin> but greater than (or equal
7475 to) B<FailureMin> a B<WARNING> notification will be created.
7477 =item B<DataSource> I<DSName>
7479 Some data sets have more than one "data source". Interesting examples are the
7480 C<if_octets> data set, which has received (C<rx>) and sent (C<tx>) bytes and
7481 the C<disk_ops> data set, which holds C<read> and C<write> operations. The
7482 system load data set, C<load>, even has three data sources: C<shortterm>,
7483 C<midterm>, and C<longterm>.
7485 Normally, all data sources are checked against a configured threshold. If this
7486 is undesirable, or if you want to specify different limits for each data
7487 source, you can use the B<DataSource> option to have a threshold apply only to
7490 =item B<Invert> B<true>|B<false>
7492 If set to B<true> the range of acceptable values is inverted, i.E<nbsp>e.
7493 values between B<FailureMin> and B<FailureMax> (B<WarningMin> and
7494 B<WarningMax>) are not okay. Defaults to B<false>.
7496 =item B<Persist> B<true>|B<false>
7498 Sets how often notifications are generated. If set to B<true> one notification
7499 will be generated for each value that is out of the acceptable range. If set to
7500 B<false> (the default) then a notification is only generated if a value is out
7501 of range but the previous value was okay.
7503 This applies to missing values, too: If set to B<true> a notification about a
7504 missing value is generated once every B<Interval> seconds. If set to B<false>
7505 only one such notification is generated until the value appears again.
7507 =item B<Percentage> B<true>|B<false>
7509 If set to B<true>, the minimum and maximum values given are interpreted as
7510 percentage value, relative to the other data sources. This is helpful for
7511 example for the "df" type, where you may want to issue a warning when less than
7512 5E<nbsp>% of the total space is available. Defaults to B<false>.
7514 =item B<Hits> I<Number>
7516 Delay creating the notification until the threshold has been passed I<Number>
7517 times. When a notification has been generated, or when a subsequent value is
7518 inside the threshold, the counter is reset. If, for example, a value is
7519 collected once every 10E<nbsp>seconds and B<Hits> is set to 3, a notification
7520 will be dispatched at most once every 30E<nbsp>seconds.
7522 This is useful when short bursts are not a problem. If, for example, 100% CPU
7523 usage for up to a minute is normal (and data is collected every
7524 10E<nbsp>seconds), you could set B<Hits> to B<6> to account for this.
7526 =item B<Hysteresis> I<Number>
7528 When set to non-zero, a hysteresis value is applied when checking minimum and
7529 maximum bounds. This is useful for values that increase slowly and fluctuate a
7530 bit while doing so. When these values come close to the threshold, they may
7531 "flap", i.e. switch between failure / warning case and okay case repeatedly.
7533 If, for example, the threshold is configures as
7538 then a I<Warning> notification is created when the value exceeds I<101> and the
7539 corresponding I<Okay> notification is only created once the value falls below
7540 I<99>, thus avoiding the "flapping".
7544 =head1 FILTER CONFIGURATION
7546 Starting with collectd 4.6 there is a powerful filtering infrastructure
7547 implemented in the daemon. The concept has mostly been copied from
7548 I<ip_tables>, the packet filter infrastructure for Linux. We'll use a similar
7549 terminology, so that users that are familiar with iptables feel right at home.
7553 The following are the terms used in the remainder of the filter configuration
7554 documentation. For an ASCII-art schema of the mechanism, see
7555 L<"General structure"> below.
7561 A I<match> is a criteria to select specific values. Examples are, of course, the
7562 name of the value or it's current value.
7564 Matches are implemented in plugins which you have to load prior to using the
7565 match. The name of such plugins starts with the "match_" prefix.
7569 A I<target> is some action that is to be performed with data. Such actions
7570 could, for example, be to change part of the value's identifier or to ignore
7571 the value completely.
7573 Some of these targets are built into the daemon, see L<"Built-in targets">
7574 below. Other targets are implemented in plugins which you have to load prior to
7575 using the target. The name of such plugins starts with the "target_" prefix.
7579 The combination of any number of matches and at least one target is called a
7580 I<rule>. The target actions will be performed for all values for which B<all>
7581 matches apply. If the rule does not have any matches associated with it, the
7582 target action will be performed for all values.
7586 A I<chain> is a list of rules and possibly default targets. The rules are tried
7587 in order and if one matches, the associated target will be called. If a value
7588 is handled by a rule, it depends on the target whether or not any subsequent
7589 rules are considered or if traversal of the chain is aborted, see
7590 L<"Flow control"> below. After all rules have been checked, the default targets
7595 =head2 General structure
7597 The following shows the resulting structure:
7604 +---------+ +---------+ +---------+ +---------+
7605 ! Rule !->! Match !->! Match !->! Target !
7606 +---------+ +---------+ +---------+ +---------+
7609 +---------+ +---------+ +---------+
7610 ! Rule !->! Target !->! Target !
7611 +---------+ +---------+ +---------+
7618 +---------+ +---------+ +---------+
7619 ! Rule !->! Match !->! Target !
7620 +---------+ +---------+ +---------+
7630 There are four ways to control which way a value takes through the filter
7637 The built-in B<jump> target can be used to "call" another chain, i.E<nbsp>e.
7638 process the value with another chain. When the called chain finishes, usually
7639 the next target or rule after the jump is executed.
7643 The stop condition, signaled for example by the built-in target B<stop>, causes
7644 all processing of the value to be stopped immediately.
7648 Causes processing in the current chain to be aborted, but processing of the
7649 value generally will continue. This means that if the chain was called via
7650 B<Jump>, the next target or rule after the jump will be executed. If the chain
7651 was not called by another chain, control will be returned to the daemon and it
7652 may pass the value to another chain.
7656 Most targets will signal the B<continue> condition, meaning that processing
7657 should continue normally. There is no special built-in target for this
7664 The configuration reflects this structure directly:
7666 PostCacheChain "PostCache"
7668 <Rule "ignore_mysql_show">
7671 Type "^mysql_command$"
7672 TypeInstance "^show_"
7682 The above configuration example will ignore all values where the plugin field
7683 is "mysql", the type is "mysql_command" and the type instance begins with
7684 "show_". All other values will be sent to the C<rrdtool> write plugin via the
7685 default target of the chain. Since this chain is run after the value has been
7686 added to the cache, the MySQL C<show_*> command statistics will be available
7687 via the C<unixsock> plugin.
7689 =head2 List of configuration options
7693 =item B<PreCacheChain> I<ChainName>
7695 =item B<PostCacheChain> I<ChainName>
7697 Configure the name of the "pre-cache chain" and the "post-cache chain". The
7698 argument is the name of a I<chain> that should be executed before and/or after
7699 the values have been added to the cache.
7701 To understand the implications, it's important you know what is going on inside
7702 I<collectd>. The following diagram shows how values are passed from the
7703 read-plugins to the write-plugins:
7709 + - - - - V - - - - +
7710 : +---------------+ :
7713 : +-------+-------+ :
7716 : +-------+-------+ : +---------------+
7717 : ! Cache !--->! Value Cache !
7718 : ! insert ! : +---+---+-------+
7719 : +-------+-------+ : ! !
7720 : ! ,------------' !
7722 : +-------+---+---+ : +-------+-------+
7723 : ! Post-Cache +--->! Write-Plugins !
7724 : ! Chain ! : +---------------+
7725 : +---------------+ :
7728 + - - - - - - - - - +
7730 After the values are passed from the "read" plugins to the dispatch functions,
7731 the pre-cache chain is run first. The values are added to the internal cache
7732 afterwards. The post-cache chain is run after the values have been added to the
7733 cache. So why is it such a huge deal if chains are run before or after the
7734 values have been added to this cache?
7736 Targets that change the identifier of a value list should be executed before
7737 the values are added to the cache, so that the name in the cache matches the
7738 name that is used in the "write" plugins. The C<unixsock> plugin, too, uses
7739 this cache to receive a list of all available values. If you change the
7740 identifier after the value list has been added to the cache, this may easily
7741 lead to confusion, but it's not forbidden of course.
7743 The cache is also used to convert counter values to rates. These rates are, for
7744 example, used by the C<value> match (see below). If you use the rate stored in
7745 the cache B<before> the new value is added, you will use the old, B<previous>
7746 rate. Write plugins may use this rate, too, see the C<csv> plugin, for example.
7747 The C<unixsock> plugin uses these rates too, to implement the C<GETVAL>
7750 Last but not last, the B<stop> target makes a difference: If the pre-cache
7751 chain returns the stop condition, the value will not be added to the cache and
7752 the post-cache chain will not be run.
7754 =item B<Chain> I<Name>
7756 Adds a new chain with a certain name. This name can be used to refer to a
7757 specific chain, for example to jump to it.
7759 Within the B<Chain> block, there can be B<Rule> blocks and B<Target> blocks.
7761 =item B<Rule> [I<Name>]
7763 Adds a new rule to the current chain. The name of the rule is optional and
7764 currently has no meaning for the daemon.
7766 Within the B<Rule> block, there may be any number of B<Match> blocks and there
7767 must be at least one B<Target> block.
7769 =item B<Match> I<Name>
7771 Adds a match to a B<Rule> block. The name specifies what kind of match should
7772 be performed. Available matches depend on the plugins that have been loaded.
7774 The arguments inside the B<Match> block are passed to the plugin implementing
7775 the match, so which arguments are valid here depends on the plugin being used.
7776 If you do not need any to pass any arguments to a match, you can use the
7781 Which is equivalent to:
7786 =item B<Target> I<Name>
7788 Add a target to a rule or a default target to a chain. The name specifies what
7789 kind of target is to be added. Which targets are available depends on the
7790 plugins being loaded.
7792 The arguments inside the B<Target> block are passed to the plugin implementing
7793 the target, so which arguments are valid here depends on the plugin being used.
7794 If you do not need any to pass any arguments to a target, you can use the
7799 This is the same as writing:
7806 =head2 Built-in targets
7808 The following targets are built into the core daemon and therefore need no
7809 plugins to be loaded:
7815 Signals the "return" condition, see the L<"Flow control"> section above. This
7816 causes the current chain to stop processing the value and returns control to
7817 the calling chain. The calling chain will continue processing targets and rules
7818 just after the B<jump> target (see below). This is very similar to the
7819 B<RETURN> target of iptables, see L<iptables(8)>.
7821 This target does not have any options.
7829 Signals the "stop" condition, see the L<"Flow control"> section above. This
7830 causes processing of the value to be aborted immediately. This is similar to
7831 the B<DROP> target of iptables, see L<iptables(8)>.
7833 This target does not have any options.
7841 Sends the value to "write" plugins.
7847 =item B<Plugin> I<Name>
7849 Name of the write plugin to which the data should be sent. This option may be
7850 given multiple times to send the data to more than one write plugin. If the
7851 plugin supports multiple instances, the plugin's instance(s) must also be
7856 If no plugin is explicitly specified, the values will be sent to all available
7859 Single-instance plugin example:
7865 Multi-instance plugin example:
7867 <Plugin "write_graphite">
7877 Plugin "write_graphite/foo"
7882 Starts processing the rules of another chain, see L<"Flow control"> above. If
7883 the end of that chain is reached, or a stop condition is encountered,
7884 processing will continue right after the B<jump> target, i.E<nbsp>e. with the
7885 next target or the next rule. This is similar to the B<-j> command line option
7886 of iptables, see L<iptables(8)>.
7892 =item B<Chain> I<Name>
7894 Jumps to the chain I<Name>. This argument is required and may appear only once.
7906 =head2 Available matches
7912 Matches a value using regular expressions.
7918 =item B<Host> I<Regex>
7920 =item B<Plugin> I<Regex>
7922 =item B<PluginInstance> I<Regex>
7924 =item B<Type> I<Regex>
7926 =item B<TypeInstance> I<Regex>
7928 Match values where the given regular expressions match the various fields of
7929 the identifier of a value. If multiple regular expressions are given, B<all>
7930 regexen must match for a value to match.
7932 =item B<Invert> B<false>|B<true>
7934 When set to B<true>, the result of the match is inverted, i.e. all value lists
7935 where all regular expressions apply are not matched, all other value lists are
7936 matched. Defaults to B<false>.
7943 Host "customer[0-9]+"
7949 Matches values that have a time which differs from the time on the server.
7951 This match is mainly intended for servers that receive values over the
7952 C<network> plugin and write them to disk using the C<rrdtool> plugin. RRDtool
7953 is very sensitive to the timestamp used when updating the RRD files. In
7954 particular, the time must be ever increasing. If a misbehaving client sends one
7955 packet with a timestamp far in the future, all further packets with a correct
7956 time will be ignored because of that one packet. What's worse, such corrupted
7957 RRD files are hard to fix.
7959 This match lets one match all values B<outside> a specified time range
7960 (relative to the server's time), so you can use the B<stop> target (see below)
7961 to ignore the value, for example.
7967 =item B<Future> I<Seconds>
7969 Matches all values that are I<ahead> of the server's time by I<Seconds> or more
7970 seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
7973 =item B<Past> I<Seconds>
7975 Matches all values that are I<behind> of the server's time by I<Seconds> or
7976 more seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
7988 This example matches all values that are five minutes or more ahead of the
7989 server or one hour (or more) lagging behind.
7993 Matches the actual value of data sources against given minimumE<nbsp>/ maximum
7994 values. If a data-set consists of more than one data-source, all data-sources
7995 must match the specified ranges for a positive match.
8001 =item B<Min> I<Value>
8003 Sets the smallest value which still results in a match. If unset, behaves like
8006 =item B<Max> I<Value>
8008 Sets the largest value which still results in a match. If unset, behaves like
8011 =item B<Invert> B<true>|B<false>
8013 Inverts the selection. If the B<Min> and B<Max> settings result in a match,
8014 no-match is returned and vice versa. Please note that the B<Invert> setting
8015 only effects how B<Min> and B<Max> are applied to a specific value. Especially
8016 the B<DataSource> and B<Satisfy> settings (see below) are not inverted.
8018 =item B<DataSource> I<DSName> [I<DSName> ...]
8020 Select one or more of the data sources. If no data source is configured, all
8021 data sources will be checked. If the type handled by the match does not have a
8022 data source of the specified name(s), this will always result in no match
8023 (independent of the B<Invert> setting).
8025 =item B<Satisfy> B<Any>|B<All>
8027 Specifies how checking with several data sources is performed. If set to
8028 B<Any>, the match succeeds if one of the data sources is in the configured
8029 range. If set to B<All> the match only succeeds if all data sources are within
8030 the configured range. Default is B<All>.
8032 Usually B<All> is used for positive matches, B<Any> is used for negative
8033 matches. This means that with B<All> you usually check that all values are in a
8034 "good" range, while with B<Any> you check if any value is within a "bad" range
8035 (or outside the "good" range).
8039 Either B<Min> or B<Max>, but not both, may be unset.
8043 # Match all values smaller than or equal to 100. Matches only if all data
8044 # sources are below 100.
8050 # Match if the value of any data source is outside the range of 0 - 100.
8058 =item B<empty_counter>
8060 Matches all values with one or more data sources of type B<COUNTER> and where
8061 all counter values are zero. These counters usually I<never> increased since
8062 they started existing (and are therefore uninteresting), or got reset recently
8063 or overflowed and you had really, I<really> bad luck.
8065 Please keep in mind that ignoring such counters can result in confusing
8066 behavior: Counters which hardly ever increase will be zero for long periods of
8067 time. If the counter is reset for some reason (machine or service restarted,
8068 usually), the graph will be empty (NAN) for a long time. People may not
8073 Calculates a hash value of the host name and matches values according to that
8074 hash value. This makes it possible to divide all hosts into groups and match
8075 only values that are in a specific group. The intended use is in load
8076 balancing, where you want to handle only part of all data and leave the rest
8079 The hashing function used tries to distribute the hosts evenly. First, it
8080 calculates a 32E<nbsp>bit hash value using the characters of the hostname:
8083 for (i = 0; host[i] != 0; i++)
8084 hash_value = (hash_value * 251) + host[i];
8086 The constant 251 is a prime number which is supposed to make this hash value
8087 more random. The code then checks the group for this host according to the
8088 I<Total> and I<Match> arguments:
8090 if ((hash_value % Total) == Match)
8095 Please note that when you set I<Total> to two (i.E<nbsp>e. you have only two
8096 groups), then the least significant bit of the hash value will be the XOR of
8097 all least significant bits in the host name. One consequence is that when you
8098 have two hosts, "server0.example.com" and "server1.example.com", where the host
8099 name differs in one digit only and the digits differ by one, those hosts will
8100 never end up in the same group.
8106 =item B<Match> I<Match> I<Total>
8108 Divide the data into I<Total> groups and match all hosts in group I<Match> as
8109 described above. The groups are numbered from zero, i.E<nbsp>e. I<Match> must
8110 be smaller than I<Total>. I<Total> must be at least one, although only values
8111 greater than one really do make any sense.
8113 You can repeat this option to match multiple groups, for example:
8118 The above config will divide the data into seven groups and match groups three
8119 and five. One use would be to keep every value on two hosts so that if one
8120 fails the missing data can later be reconstructed from the second host.
8126 # Operate on the pre-cache chain, so that ignored values are not even in the
8131 # Divide all received hosts in seven groups and accept all hosts in
8135 # If matched: Return and continue.
8138 # If not matched: Return and stop.
8144 =head2 Available targets
8148 =item B<notification>
8150 Creates and dispatches a notification.
8156 =item B<Message> I<String>
8158 This required option sets the message of the notification. The following
8159 placeholders will be replaced by an appropriate value:
8167 =item B<%{plugin_instance}>
8171 =item B<%{type_instance}>
8173 These placeholders are replaced by the identifier field of the same name.
8175 =item B<%{ds:>I<name>B<}>
8177 These placeholders are replaced by a (hopefully) human readable representation
8178 of the current rate of this data source. If you changed the instance name
8179 (using the B<set> or B<replace> targets, see below), it may not be possible to
8180 convert counter values to rates.
8184 Please note that these placeholders are B<case sensitive>!
8186 =item B<Severity> B<"FAILURE">|B<"WARNING">|B<"OKAY">
8188 Sets the severity of the message. If omitted, the severity B<"WARNING"> is
8195 <Target "notification">
8196 Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
8202 Replaces parts of the identifier using regular expressions.
8208 =item B<Host> I<Regex> I<Replacement>
8210 =item B<Plugin> I<Regex> I<Replacement>
8212 =item B<PluginInstance> I<Regex> I<Replacement>
8214 =item B<TypeInstance> I<Regex> I<Replacement>
8216 Match the appropriate field with the given regular expression I<Regex>. If the
8217 regular expression matches, that part that matches is replaced with
8218 I<Replacement>. If multiple places of the input buffer match a given regular
8219 expression, only the first occurrence will be replaced.
8221 You can specify each option multiple times to use multiple regular expressions
8229 # Replace "example.net" with "example.com"
8230 Host "\\<example.net\\>" "example.com"
8232 # Strip "www." from hostnames
8238 Sets part of the identifier of a value to a given string.
8244 =item B<Host> I<String>
8246 =item B<Plugin> I<String>
8248 =item B<PluginInstance> I<String>
8250 =item B<TypeInstance> I<String>
8252 Set the appropriate field to the given string. The strings for plugin instance
8253 and type instance may be empty, the strings for host and plugin may not be
8254 empty. It's currently not possible to set the type of a value this way.
8261 PluginInstance "coretemp"
8262 TypeInstance "core3"
8267 =head2 Backwards compatibility
8269 If you use collectd with an old configuration, i.E<nbsp>e. one without a
8270 B<Chain> block, it will behave as it used to. This is equivalent to the
8271 following configuration:
8277 If you specify a B<PostCacheChain>, the B<write> target will not be added
8278 anywhere and you will have to make sure that it is called where appropriate. We
8279 suggest to add the above snippet as default target to your "PostCache" chain.
8283 Ignore all values, where the hostname does not contain a dot, i.E<nbsp>e. can't
8299 L<collectd-exec(5)>,
8300 L<collectd-perl(5)>,
8301 L<collectd-unixsock(5)>,
8314 Florian Forster E<lt>octo@collectd.orgE<gt>