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<#>) are 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 which 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> the 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.:
104 The following options are valid inside B<LoadPlugin> blocks:
108 =item B<Globals> B<true|false>
110 If enabled, collectd will export all global symbols of the plugin (and of all
111 libraries loaded as dependencies of the plugin) and, thus, makes those symbols
112 available for resolving unresolved symbols in subsequently loaded plugins if
113 that is supported by your system.
115 This is useful (or possibly even required), e.g., when loading a plugin that
116 embeds some scripting language into the daemon (e.g. the I<Perl> and
117 I<Python plugins>). Scripting languages usually provide means to load
118 extensions written in C. Those extensions require symbols provided by the
119 interpreter, which is loaded as a dependency of the respective collectd plugin.
120 See the documentation of those plugins (e.g., L<collectd-perl(5)> or
121 L<collectd-python(5)>) for details.
123 By default, this is disabled. As a special exception, if the plugin name is
124 either C<perl> or C<python>, the default is changed to enabled in order to keep
125 the average user from ever having to deal with this low level linking stuff.
127 =item B<Interval> I<Seconds>
129 Sets a plugin-specific interval for collecting metrics. This overrides the
130 global B<Interval> setting. If a plugin provides its own support for specifying
131 an interval, that setting will take precedence.
133 =item B<FlushInterval> I<Seconds>
135 Specifies the interval, in seconds, to call the flush callback if it's
136 defined in this plugin. By default, this is disabled.
138 =item B<FlushTimeout> I<Seconds>
140 Specifies the value of the timeout argument of the flush callback.
144 =item B<AutoLoadPlugin> B<false>|B<true>
146 When set to B<false> (the default), each plugin needs to be loaded explicitly,
147 using the B<LoadPlugin> statement documented above. If a
148 B<E<lt>PluginE<nbsp>...E<gt>> block is encountered and no configuration
149 handling callback for this plugin has been registered, a warning is logged and
150 the block is ignored.
152 When set to B<true>, explicit B<LoadPlugin> statements are not required. Each
153 B<E<lt>PluginE<nbsp>...E<gt>> block acts as if it was immediately preceded by a
154 B<LoadPlugin> statement. B<LoadPlugin> statements are still required for
155 plugins that don't provide any configuration, e.g. the I<Load plugin>.
157 =item B<CollectInternalStats> B<false>|B<true>
159 When set to B<true>, various statistics about the I<collectd> daemon will be
160 collected, with "collectd" as the I<plugin name>. Defaults to B<false>.
162 The following metrics are reported:
166 =item C<collectd-write_queue/queue_length>
168 The number of metrics currently in the write queue. You can limit the queue
169 length with the B<WriteQueueLimitLow> and B<WriteQueueLimitHigh> options.
171 =item C<collectd-write_queue/derive-dropped>
173 The number of metrics dropped due to a queue length limitation.
174 If this value is non-zero, your system can't handle all incoming metrics and
175 protects itself against overload by dropping metrics.
177 =item C<collectd-cache/cache_size>
179 The number of elements in the metric cache (the cache you can interact with
180 using L<collectd-unixsock(5)>).
184 =item B<Include> I<Path> [I<pattern>]
186 If I<Path> points to a file, includes that file. If I<Path> points to a
187 directory, recursively includes all files within that directory and its
188 subdirectories. If the C<wordexp> function is available on your system,
189 shell-like wildcards are expanded before files are included. This means you can
190 use statements like the following:
192 Include "/etc/collectd.d/*.conf"
194 Starting with version 5.3, this may also be a block in which further options
195 affecting the behavior of B<Include> may be specified. The following option is
198 <Include "/etc/collectd.d">
204 =item B<Filter> I<pattern>
206 If the C<fnmatch> function is available on your system, a shell-like wildcard
207 I<pattern> may be specified to filter which files to include. This may be used
208 in combination with recursively including a directory to easily be able to
209 arbitrarily mix configuration files and other documents (e.g. README files).
210 The given example is similar to the first example above but includes all files
211 matching C<*.conf> in any subdirectory of C</etc/collectd.d>.
215 If more than one file is included by a single B<Include> option, the files
216 will be included in lexicographical order (as defined by the C<strcmp>
217 function). Thus, you can e.E<nbsp>g. use numbered prefixes to specify the
218 order in which the files are loaded.
220 To prevent loops and shooting yourself in the foot in interesting ways the
221 nesting is limited to a depth of 8E<nbsp>levels, which should be sufficient for
222 most uses. Since symlinks are followed it is still possible to crash the daemon
223 by looping symlinks. In our opinion significant stupidity should result in an
224 appropriate amount of pain.
226 It is no problem to have a block like C<E<lt>Plugin fooE<gt>> in more than one
227 file, but you cannot include files from within blocks.
229 =item B<PIDFile> I<File>
231 Sets where to write the PID file to. This file is overwritten when it exists
232 and deleted when the program is stopped. Some init-scripts might override this
233 setting using the B<-P> command-line option.
235 =item B<PluginDir> I<Directory>
237 Path to the plugins (shared objects) of collectd.
239 =item B<TypesDB> I<File> [I<File> ...]
241 Set one or more files that contain the data-set descriptions. See
242 L<types.db(5)> for a description of the format of this file.
244 If this option is not specified, a default file is read. If you need to define
245 custom types in addition to the types defined in the default file, you need to
246 explicitly load both. In other words, if the B<TypesDB> option is encountered
247 the default behavior is disabled and if you need the default types you have to
248 also explicitly load them.
250 =item B<Interval> I<Seconds>
252 Configures the interval in which to query the read plugins. Obviously smaller
253 values lead to a higher system load produced by collectd, while higher values
254 lead to more coarse statistics.
256 B<Warning:> You should set this once and then never touch it again. If you do,
257 I<you will have to delete all your RRD files> or know some serious RRDtool
258 magic! (Assuming you're using the I<RRDtool> or I<RRDCacheD> plugin.)
260 =item B<MaxReadInterval> I<Seconds>
262 A read plugin doubles the interval between queries after each failed attempt
265 This options limits the maximum value of the interval. The default value is
268 =item B<Timeout> I<Iterations>
270 Consider a value list "missing" when no update has been read or received for
271 I<Iterations> iterations. By default, I<collectd> considers a value list
272 missing when no update has been received for twice the update interval. Since
273 this setting uses iterations, the maximum allowed time without update depends
274 on the I<Interval> information contained in each value list. This is used in
275 the I<Threshold> configuration to dispatch notifications about missing values,
276 see L<collectd-threshold(5)> for details.
278 =item B<ReadThreads> I<Num>
280 Number of threads to start for reading plugins. The default value is B<5>, but
281 you may want to increase this if you have more than five plugins that take a
282 long time to read. Mostly those are plugins that do network-IO. Setting this to
283 a value higher than the number of registered read callbacks is not recommended.
285 =item B<WriteThreads> I<Num>
287 Number of threads to start for dispatching value lists to write plugins. The
288 default value is B<5>, but you may want to increase this if you have more than
289 five plugins that may take relatively long to write to.
291 =item B<WriteQueueLimitHigh> I<HighNum>
293 =item B<WriteQueueLimitLow> I<LowNum>
295 Metrics are read by the I<read threads> and then put into a queue to be handled
296 by the I<write threads>. If one of the I<write plugins> is slow (e.g. network
297 timeouts, I/O saturation of the disk) this queue will grow. In order to avoid
298 running into memory issues in such a case, you can limit the size of this
301 By default, there is no limit and memory may grow indefinitely. This is most
302 likely not an issue for clients, i.e. instances that only handle the local
303 metrics. For servers it is recommended to set this to a non-zero value, though.
305 You can set the limits using B<WriteQueueLimitHigh> and B<WriteQueueLimitLow>.
306 Each of them takes a numerical argument which is the number of metrics in the
307 queue. If there are I<HighNum> metrics in the queue, any new metrics I<will> be
308 dropped. If there are less than I<LowNum> metrics in the queue, all new metrics
309 I<will> be enqueued. If the number of metrics currently in the queue is between
310 I<LowNum> and I<HighNum>, the metric is dropped with a probability that is
311 proportional to the number of metrics in the queue (i.e. it increases linearly
312 until it reaches 100%.)
314 If B<WriteQueueLimitHigh> is set to non-zero and B<WriteQueueLimitLow> is
315 unset, the latter will default to half of B<WriteQueueLimitHigh>.
317 If you do not want to randomly drop values when the queue size is between
318 I<LowNum> and I<HighNum>, set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow>
321 Enabling the B<CollectInternalStats> option is of great help to figure out the
322 values to set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow> to.
324 =item B<Hostname> I<Name>
326 Sets the hostname that identifies a host. If you omit this setting, the
327 hostname will be determined using the L<gethostname(2)> system call.
329 =item B<FQDNLookup> B<true|false>
331 If B<Hostname> is determined automatically this setting controls whether or not
332 the daemon should try to figure out the "fully qualified domain name", FQDN.
333 This is done using a lookup of the name returned by C<gethostname>. This option
334 is enabled by default.
336 =item B<PreCacheChain> I<ChainName>
338 =item B<PostCacheChain> I<ChainName>
340 Configure the name of the "pre-cache chain" and the "post-cache chain". Please
341 see L</"FILTER CONFIGURATION"> below on information on chains and how these
342 setting change the daemon's behavior.
346 =head1 PLUGIN OPTIONS
348 Some plugins may register own options. These options must be enclosed in a
349 C<Plugin>-Section. Which options exist depends on the plugin used. Some plugins
350 require external configuration, too. The C<apache plugin>, for example,
351 required C<mod_status> to be configured in the webserver you're going to
352 collect data from. These plugins are listed below as well, even if they don't
353 require any configuration within collectd's configuration file.
355 A list of all plugins and a short summary for each plugin can be found in the
356 F<README> file shipped with the sourcecode and hopefully binary packets as
359 =head2 Plugin C<aggregation>
361 The I<Aggregation plugin> makes it possible to aggregate several values into
362 one using aggregation functions such as I<sum>, I<average>, I<min> and I<max>.
363 This can be put to a wide variety of uses, e.g. average and total CPU
364 statistics for your entire fleet.
366 The grouping is powerful but, as with many powerful tools, may be a bit
367 difficult to wrap your head around. The grouping will therefore be
368 demonstrated using an example: The average and sum of the CPU usage across
369 all CPUs of each host is to be calculated.
371 To select all the affected values for our example, set C<Plugin cpu> and
372 C<Type cpu>. The other values are left unspecified, meaning "all values". The
373 I<Host>, I<Plugin>, I<PluginInstance>, I<Type> and I<TypeInstance> options
374 work as if they were specified in the C<WHERE> clause of an C<SELECT> SQL
380 Although the I<Host>, I<PluginInstance> (CPU number, i.e. 0, 1, 2, ...) and
381 I<TypeInstance> (idle, user, system, ...) fields are left unspecified in the
382 example, the intention is to have a new value for each host / type instance
383 pair. This is achieved by "grouping" the values using the C<GroupBy> option.
384 It can be specified multiple times to group by more than one field.
387 GroupBy "TypeInstance"
389 We do neither specify nor group by I<plugin instance> (the CPU number), so all
390 metrics that differ in the CPU number only will be aggregated. Each
391 aggregation needs I<at least one> such field, otherwise no aggregation would
394 The full example configuration looks like this:
396 <Plugin "aggregation">
402 GroupBy "TypeInstance"
405 CalculateAverage true
409 There are a couple of limitations you should be aware of:
415 The I<Type> cannot be left unspecified, because it is not reasonable to add
416 apples to oranges. Also, the internal lookup structure won't work if you try
421 There must be at least one unspecified, ungrouped field. Otherwise nothing
426 As you can see in the example above, each aggregation has its own
427 B<Aggregation> block. You can have multiple aggregation blocks and aggregation
428 blocks may match the same values, i.e. one value list can update multiple
429 aggregations. The following options are valid inside B<Aggregation> blocks:
433 =item B<Host> I<Host>
435 =item B<Plugin> I<Plugin>
437 =item B<PluginInstance> I<PluginInstance>
439 =item B<Type> I<Type>
441 =item B<TypeInstance> I<TypeInstance>
443 Selects the value lists to be added to this aggregation. B<Type> must be a
444 valid data set name, see L<types.db(5)> for details.
446 If the string starts with and ends with a slash (C</>), the string is
447 interpreted as a I<regular expression>. The regex flavor used are POSIX
448 extended regular expressions as described in L<regex(7)>. Example usage:
450 Host "/^db[0-9]\\.example\\.com$/"
452 =item B<GroupBy> B<Host>|B<Plugin>|B<PluginInstance>|B<TypeInstance>
454 Group valued by the specified field. The B<GroupBy> option may be repeated to
455 group by multiple fields.
457 =item B<SetHost> I<Host>
459 =item B<SetPlugin> I<Plugin>
461 =item B<SetPluginInstance> I<PluginInstance>
463 =item B<SetTypeInstance> I<TypeInstance>
465 Sets the appropriate part of the identifier to the provided string.
467 The I<PluginInstance> should include the placeholder C<%{aggregation}> which
468 will be replaced with the aggregation function, e.g. "average". Not including
469 the placeholder will result in duplication warnings and/or messed up values if
470 more than one aggregation function are enabled.
472 The following example calculates the average usage of all "even" CPUs:
474 <Plugin "aggregation">
477 PluginInstance "/[0,2,4,6,8]$/"
481 SetPluginInstance "even-%{aggregation}"
484 GroupBy "TypeInstance"
486 CalculateAverage true
490 This will create the files:
496 foo.example.com/cpu-even-average/cpu-idle
500 foo.example.com/cpu-even-average/cpu-system
504 foo.example.com/cpu-even-average/cpu-user
512 =item B<CalculateNum> B<true>|B<false>
514 =item B<CalculateSum> B<true>|B<false>
516 =item B<CalculateAverage> B<true>|B<false>
518 =item B<CalculateMinimum> B<true>|B<false>
520 =item B<CalculateMaximum> B<true>|B<false>
522 =item B<CalculateStddev> B<true>|B<false>
524 Boolean options for enabling calculation of the number of value lists, their
525 sum, average, minimum, maximum andE<nbsp>/ or standard deviation. All options
526 are disabled by default.
530 =head2 Plugin C<amqp>
532 The I<AMQP plugin> can be used to communicate with other instances of
533 I<collectd> or third party applications using an AMQP 0.9.1 message broker.
534 Values are sent to or received from the broker, which handles routing,
535 queueing and possibly filtering out messages.
540 # Send values to an AMQP broker
541 <Publish "some_name">
547 Exchange "amq.fanout"
548 # ExchangeType "fanout"
549 # RoutingKey "collectd"
551 # ConnectionRetryDelay 0
554 # GraphitePrefix "collectd."
555 # GraphiteEscapeChar "_"
556 # GraphiteSeparateInstances false
557 # GraphiteAlwaysAppendDS false
558 # GraphitePreserveSeparator false
561 # Receive values from an AMQP broker
562 <Subscribe "some_name">
568 Exchange "amq.fanout"
569 # ExchangeType "fanout"
572 # QueueAutoDelete true
573 # RoutingKey "collectd.#"
574 # ConnectionRetryDelay 0
578 The plugin's configuration consists of a number of I<Publish> and I<Subscribe>
579 blocks, which configure sending and receiving of values respectively. The two
580 blocks are very similar, so unless otherwise noted, an option can be used in
581 either block. The name given in the blocks starting tag is only used for
582 reporting messages, but may be used to support I<flushing> of certain
583 I<Publish> blocks in the future.
587 =item B<Host> I<Host>
589 Hostname or IP-address of the AMQP broker. Defaults to the default behavior of
590 the underlying communications library, I<rabbitmq-c>, which is "localhost".
592 =item B<Port> I<Port>
594 Service name or port number on which the AMQP broker accepts connections. This
595 argument must be a string, even if the numeric form is used. Defaults to
598 =item B<VHost> I<VHost>
600 Name of the I<virtual host> on the AMQP broker to use. Defaults to "/".
602 =item B<User> I<User>
604 =item B<Password> I<Password>
606 Credentials used to authenticate to the AMQP broker. By default "guest"/"guest"
609 =item B<Exchange> I<Exchange>
611 In I<Publish> blocks, this option specifies the I<exchange> to send values to.
612 By default, "amq.fanout" will be used.
614 In I<Subscribe> blocks this option is optional. If given, a I<binding> between
615 the given exchange and the I<queue> is created, using the I<routing key> if
616 configured. See the B<Queue> and B<RoutingKey> options below.
618 =item B<ExchangeType> I<Type>
620 If given, the plugin will try to create the configured I<exchange> with this
621 I<type> after connecting. When in a I<Subscribe> block, the I<queue> will then
622 be bound to this exchange.
624 =item B<Queue> I<Queue> (Subscribe only)
626 Configures the I<queue> name to subscribe to. If no queue name was configured
627 explicitly, a unique queue name will be created by the broker.
629 =item B<QueueDurable> B<true>|B<false> (Subscribe only)
631 Defines if the I<queue> subscribed to is durable (saved to persistent storage)
632 or transient (will disappear if the AMQP broker is restarted). Defaults to
635 This option should be used in conjunction with the I<Persistent> option on the
638 =item B<QueueAutoDelete> B<true>|B<false> (Subscribe only)
640 Defines if the I<queue> subscribed to will be deleted once the last consumer
641 unsubscribes. Defaults to "true".
643 =item B<RoutingKey> I<Key>
645 In I<Publish> blocks, this configures the routing key to set on all outgoing
646 messages. If not given, the routing key will be computed from the I<identifier>
647 of the value. The host, plugin, type and the two instances are concatenated
648 together using dots as the separator and all containing dots replaced with
649 slashes. For example "collectd.host/example/com.cpu.0.cpu.user". This makes it
650 possible to receive only specific values using a "topic" exchange.
652 In I<Subscribe> blocks, configures the I<routing key> used when creating a
653 I<binding> between an I<exchange> and the I<queue>. The usual wildcards can be
654 used to filter messages when using a "topic" exchange. If you're only
655 interested in CPU statistics, you could use the routing key "collectd.*.cpu.#"
658 =item B<Persistent> B<true>|B<false> (Publish only)
660 Selects the I<delivery method> to use. If set to B<true>, the I<persistent>
661 mode will be used, i.e. delivery is guaranteed. If set to B<false> (the
662 default), the I<transient> delivery mode will be used, i.e. messages may be
663 lost due to high load, overflowing queues or similar issues.
665 =item B<ConnectionRetryDelay> I<Delay>
667 When the connection to the AMQP broker is lost, defines the time in seconds to
668 wait before attempting to reconnect. Defaults to 0, which implies collectd will
669 attempt to reconnect at each read interval (in Subscribe mode) or each time
670 values are ready for submission (in Publish mode).
672 =item B<Format> B<Command>|B<JSON>|B<Graphite> (Publish only)
674 Selects the format in which messages are sent to the broker. If set to
675 B<Command> (the default), values are sent as C<PUTVAL> commands which are
676 identical to the syntax used by the I<Exec> and I<UnixSock plugins>. In this
677 case, the C<Content-Type> header field will be set to C<text/collectd>.
679 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
680 an easy and straight forward exchange format. The C<Content-Type> header field
681 will be set to C<application/json>.
683 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
684 "<metric> <value> <timestamp>\n". The C<Content-Type> header field will be set to
687 A subscribing client I<should> use the C<Content-Type> header field to
688 determine how to decode the values. Currently, the I<AMQP plugin> itself can
689 only decode the B<Command> format.
691 =item B<StoreRates> B<true>|B<false> (Publish only)
693 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
694 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
695 default), no conversion is performed. Otherwise the conversion is performed
696 using the internal value cache.
698 Please note that currently this option is only used if the B<Format> option has
701 =item B<GraphitePrefix> (Publish and B<Format>=I<Graphite> only)
703 A prefix can be added in the metric name when outputting in the I<Graphite> format.
704 It's added before the I<Host> name.
705 Metric name will be "<prefix><host><postfix><plugin><type><name>"
707 =item B<GraphitePostfix> (Publish and B<Format>=I<Graphite> only)
709 A postfix can be added in the metric name when outputting in the I<Graphite> format.
710 It's added after the I<Host> name.
711 Metric name will be "<prefix><host><postfix><plugin><type><name>"
713 =item B<GraphiteEscapeChar> (Publish and B<Format>=I<Graphite> only)
715 Specify a character to replace dots (.) in the host part of the metric name.
716 In I<Graphite> metric name, dots are used as separators between different
717 metric parts (host, plugin, type).
718 Default is "_" (I<Underscore>).
720 =item B<GraphiteSeparateInstances> B<true>|B<false>
722 If set to B<true>, the plugin instance and type instance will be in their own
723 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
724 default), the plugin and plugin instance (and likewise the type and type
725 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
727 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
729 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
730 identifier. If set to B<false> (the default), this is only done when there is
733 =item B<GraphitePreserveSeparator> B<false>|B<true>
735 If set to B<false> (the default) the C<.> (dot) character is replaced with
736 I<GraphiteEscapeChar>. Otherwise, if set to B<true>, the C<.> (dot) character
737 is preserved, i.e. passed through.
741 =head2 Plugin C<amqp1>
743 The I<AMQP1 plugin> can be used to communicate with other instances of
744 I<collectd> or third party applications using an AMQP 1.0 message
745 intermediary. Metric values or notifications are sent to the
746 messaging intermediary which may handle direct messaging or
747 queue based transfer.
752 # Send values to an AMQP 1.0 intermediary
759 <Instance "some_name">
764 # GraphitePrefix "collectd."
765 # GraphiteEscapeChar "_"
766 # GraphiteSeparateInstances false
767 # GraphiteAlwaysAppendDS false
768 # GraphitePreserveSeparator false
773 The plugin's configuration consists of a I<Transport> that configures
774 communications to the AMQP 1.0 messaging bus and one or more I<Instance>
775 corresponding to metric or event publishers to the messaging system.
777 The address in the I<Transport> block concatenated with the name given in the
778 I<Instance> block starting tag will be used as the send-to address for
779 communications over the messaging link.
781 The following options are accepted within each I<Transport> block:
785 =item B<Host> I<Host>
787 Hostname or IP-address of the AMQP 1.0 intermediary. Defaults to the
788 default behavior of the underlying communications library,
789 I<libqpid-proton>, which is "localhost".
791 =item B<Port> I<Port>
793 Service name or port number on which the AMQP 1.0 intermediary accepts
794 connections. This argument must be a string, even if the numeric form
795 is used. Defaults to "5672".
797 =item B<User> I<User>
799 =item B<Password> I<Password>
801 Credentials used to authenticate to the AMQP 1.0 intermediary. By
802 default "guest"/"guest" is used.
804 =item B<Address> I<Address>
806 This option specifies the prefix for the send-to value in the message.
807 By default, "collectd" will be used.
811 The following options are accepted within each I<Instance> block:
815 =item B<Format> B<Command>|B<JSON>|B<Graphite>
817 Selects the format in which messages are sent to the intermediary. If set to
818 B<Command> (the default), values are sent as C<PUTVAL> commands which are
819 identical to the syntax used by the I<Exec> and I<UnixSock plugins>. In this
820 case, the C<Content-Type> header field will be set to C<text/collectd>.
822 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
823 an easy and straight forward exchange format. The C<Content-Type> header field
824 will be set to C<application/json>.
826 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
827 "<metric> <value> <timestamp>\n". The C<Content-Type> header field will be set to
830 A subscribing client I<should> use the C<Content-Type> header field to
831 determine how to decode the values.
833 =item B<PreSettle> B<true>|B<false>
835 If set to B<false> (the default), the plugin will wait for a message
836 acknowledgement from the messaging bus before sending the next
837 message. This indicates transfer of ownership to the messaging
838 system. If set to B<true>, the plugin will not wait for a message
839 acknowledgement and the message may be dropped prior to transfer of
842 =item B<Notify> B<true>|B<false>
844 If set to B<false> (the default), the plugin will service the
845 instance write call back as a value list. If set to B<true> the
846 plugin will service the instance as a write notification callback
847 for alert formatting.
849 =item B<StoreRates> B<true>|B<false>
851 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
852 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
853 default), no conversion is performed. Otherwise the conversion is performed
854 using the internal value cache.
856 Please note that currently this option is only used if the B<Format> option has
859 =item B<GraphitePrefix>
861 A prefix can be added in the metric name when outputting in the I<Graphite> format.
862 It's added before the I<Host> name.
863 Metric name will be "<prefix><host><postfix><plugin><type><name>"
865 =item B<GraphitePostfix>
867 A postfix can be added in the metric name when outputting in the I<Graphite> format.
868 It's added after the I<Host> name.
869 Metric name will be "<prefix><host><postfix><plugin><type><name>"
871 =item B<GraphiteEscapeChar>
873 Specify a character to replace dots (.) in the host part of the metric name.
874 In I<Graphite> metric name, dots are used as separators between different
875 metric parts (host, plugin, type).
876 Default is "_" (I<Underscore>).
878 =item B<GraphiteSeparateInstances> B<true>|B<false>
880 If set to B<true>, the plugin instance and type instance will be in their own
881 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
882 default), the plugin and plugin instance (and likewise the type and type
883 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
885 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
887 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
888 identifier. If set to B<false> (the default), this is only done when there is
891 =item B<GraphitePreserveSeparator> B<false>|B<true>
893 If set to B<false> (the default) the C<.> (dot) character is replaced with
894 I<GraphiteEscapeChar>. Otherwise, if set to B<true>, the C<.> (dot) character
895 is preserved, i.e. passed through.
899 =head2 Plugin C<apache>
901 To configure the C<apache>-plugin you first need to configure the Apache
902 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
903 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
904 the following snipped to base your Apache config upon:
907 <IfModule mod_status.c>
908 <Location /mod_status>
909 SetHandler server-status
913 Since its C<mod_status> module is very similar to Apache's, B<lighttpd> is
914 also supported. It introduces a new field, called C<BusyServers>, to count the
915 number of currently connected clients. This field is also supported.
917 The configuration of the I<Apache> plugin consists of one or more
918 C<E<lt>InstanceE<nbsp>/E<gt>> blocks. Each block requires one string argument
919 as the instance name. For example:
923 URL "http://www1.example.com/mod_status?auto"
926 URL "http://www2.example.com/mod_status?auto"
930 The instance name will be used as the I<plugin instance>. To emulate the old
931 (versionE<nbsp>4) behavior, you can use an empty string (""). In order for the
932 plugin to work correctly, each instance name must be unique. This is not
933 enforced by the plugin and it is your responsibility to ensure it.
935 The following options are accepted within each I<Instance> block:
939 =item B<URL> I<http://host/mod_status?auto>
941 Sets the URL of the C<mod_status> output. This needs to be the output generated
942 by C<ExtendedStatus on> and it needs to be the machine readable output
943 generated by appending the C<?auto> argument. This option is I<mandatory>.
945 =item B<User> I<Username>
947 Optional user name needed for authentication.
949 =item B<Password> I<Password>
951 Optional password needed for authentication.
953 =item B<VerifyPeer> B<true|false>
955 Enable or disable peer SSL certificate verification. See
956 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
958 =item B<VerifyHost> B<true|false>
960 Enable or disable peer host name verification. If enabled, the plugin checks
961 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
962 certificate matches the host name provided by the B<URL> option. If this
963 identity check fails, the connection is aborted. Obviously, only works when
964 connecting to a SSL enabled server. Enabled by default.
966 =item B<CACert> I<File>
968 File that holds one or more SSL certificates. If you want to use HTTPS you will
969 possibly need this option. What CA certificates come bundled with C<libcurl>
970 and are checked by default depends on the distribution you use.
972 =item B<SSLCiphers> I<list of ciphers>
974 Specifies which ciphers to use in the connection. The list of ciphers
975 must specify valid ciphers. See
976 L<http://www.openssl.org/docs/apps/ciphers.html> for details.
978 =item B<Timeout> I<Milliseconds>
980 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
981 milliseconds. By default, the configured B<Interval> is used to set the
986 =head2 Plugin C<apcups>
990 =item B<Host> I<Hostname>
992 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
993 that IPv6 support has been disabled unless someone can confirm or decline that
994 B<apcupsd> can handle it.
996 =item B<Port> I<Port>
998 TCP-Port to connect to. Defaults to B<3551>.
1000 =item B<ReportSeconds> B<true>|B<false>
1002 If set to B<true>, the time reported in the C<timeleft> metric will be
1003 converted to seconds. This is the recommended setting. If set to B<false>, the
1004 default for backwards compatibility, the time will be reported in minutes.
1006 =item B<PersistentConnection> B<true>|B<false>
1008 The plugin is designed to keep the connection to I<apcupsd> open between reads.
1009 If plugin poll interval is greater than 15 seconds (hardcoded socket close
1010 timeout in I<apcupsd> NIS), then this option is B<false> by default.
1012 You can instruct the plugin to close the connection after each read by setting
1013 this option to B<false> or force keeping the connection by setting it to B<true>.
1015 If I<apcupsd> appears to close the connection due to inactivity quite quickly,
1016 the plugin will try to detect this problem and switch to an open-read-close mode.
1020 =head2 Plugin C<aquaero>
1022 This plugin collects the value of the available sensors in an
1023 I<AquaeroE<nbsp>5> board. AquaeroE<nbsp>5 is a water-cooling controller board,
1024 manufactured by Aqua Computer GmbH L<http://www.aquacomputer.de/>, with a USB2
1025 connection for monitoring and configuration. The board can handle multiple
1026 temperature sensors, fans, water pumps and water level sensors and adjust the
1027 output settings such as fan voltage or power used by the water pump based on
1028 the available inputs using a configurable controller included in the board.
1029 This plugin collects all the available inputs as well as some of the output
1030 values chosen by this controller. The plugin is based on the I<libaquaero5>
1031 library provided by I<aquatools-ng>.
1035 =item B<Device> I<DevicePath>
1037 Device path of the AquaeroE<nbsp>5's USB HID (human interface device), usually
1038 in the form C</dev/usb/hiddevX>. If this option is no set the plugin will try
1039 to auto-detect the Aquaero 5 USB device based on vendor-ID and product-ID.
1043 =head2 Plugin C<ascent>
1045 This plugin collects information about an Ascent server, a free server for the
1046 "World of Warcraft" game. This plugin gathers the information by fetching the
1047 XML status page using C<libcurl> and parses it using C<libxml2>.
1049 The configuration options are the same as for the C<apache> plugin above:
1053 =item B<URL> I<http://localhost/ascent/status/>
1055 Sets the URL of the XML status output.
1057 =item B<User> I<Username>
1059 Optional user name needed for authentication.
1061 =item B<Password> I<Password>
1063 Optional password needed for authentication.
1065 =item B<VerifyPeer> B<true|false>
1067 Enable or disable peer SSL certificate verification. See
1068 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
1070 =item B<VerifyHost> B<true|false>
1072 Enable or disable peer host name verification. If enabled, the plugin checks
1073 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
1074 certificate matches the host name provided by the B<URL> option. If this
1075 identity check fails, the connection is aborted. Obviously, only works when
1076 connecting to a SSL enabled server. Enabled by default.
1078 =item B<CACert> I<File>
1080 File that holds one or more SSL certificates. If you want to use HTTPS you will
1081 possibly need this option. What CA certificates come bundled with C<libcurl>
1082 and are checked by default depends on the distribution you use.
1084 =item B<Timeout> I<Milliseconds>
1086 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
1087 milliseconds. By default, the configured B<Interval> is used to set the
1092 =head2 Plugin C<barometer>
1094 This plugin reads absolute air pressure using digital barometer sensor on a I2C
1095 bus. Supported sensors are:
1099 =item I<MPL115A2> from Freescale,
1100 see L<http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL115A>.
1103 =item I<MPL3115> from Freescale
1104 see L<http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL3115A2>.
1107 =item I<BMP085> from Bosch Sensortec
1111 The sensor type - one of the above - is detected automatically by the plugin
1112 and indicated in the plugin_instance (you will see subdirectory
1113 "barometer-mpl115" or "barometer-mpl3115", or "barometer-bmp085"). The order of
1114 detection is BMP085 -> MPL3115 -> MPL115A2, the first one found will be used
1115 (only one sensor can be used by the plugin).
1117 The plugin provides absolute barometric pressure, air pressure reduced to sea
1118 level (several possible approximations) and as an auxiliary value also internal
1119 sensor temperature. It uses (expects/provides) typical metric units - pressure
1120 in [hPa], temperature in [C], altitude in [m].
1122 It was developed and tested under Linux only. The only platform dependency is
1123 the standard Linux i2c-dev interface (the particular bus driver has to
1124 support the SM Bus command subset).
1126 The reduction or normalization to mean sea level pressure requires (depending
1127 on selected method/approximation) also altitude and reference to temperature
1128 sensor(s). When multiple temperature sensors are configured the minimum of
1129 their values is always used (expecting that the warmer ones are affected by
1130 e.g. direct sun light at that moment).
1134 <Plugin "barometer">
1135 Device "/dev/i2c-0";
1138 TemperatureOffset 0.0
1141 TemperatureSensor "myserver/onewire-F10FCA000800/temperature"
1146 =item B<Device> I<device>
1148 The only mandatory configuration parameter.
1150 Device name of the I2C bus to which the sensor is connected. Note that
1151 typically you need to have loaded the i2c-dev module.
1152 Using i2c-tools you can check/list i2c buses available on your system by:
1156 Then you can scan for devices on given bus. E.g. to scan the whole bus 0 use:
1160 This way you should be able to verify that the pressure sensor (either type) is
1161 connected and detected on address 0x60.
1163 =item B<Oversampling> I<value>
1165 Optional parameter controlling the oversampling/accuracy. Default value
1166 is 1 providing fastest and least accurate reading.
1168 For I<MPL115> this is the size of the averaging window. To filter out sensor
1169 noise a simple averaging using floating window of this configurable size is
1170 used. The plugin will use average of the last C<value> measurements (value of 1
1171 means no averaging). Minimal size is 1, maximal 1024.
1173 For I<MPL3115> this is the oversampling value. The actual oversampling is
1174 performed by the sensor and the higher value the higher accuracy and longer
1175 conversion time (although nothing to worry about in the collectd context).
1176 Supported values are: 1, 2, 4, 8, 16, 32, 64 and 128. Any other value is
1177 adjusted by the plugin to the closest supported one.
1179 For I<BMP085> this is the oversampling value. The actual oversampling is
1180 performed by the sensor and the higher value the higher accuracy and longer
1181 conversion time (although nothing to worry about in the collectd context).
1182 Supported values are: 1, 2, 4, 8. Any other value is adjusted by the plugin to
1183 the closest supported one.
1185 =item B<PressureOffset> I<offset>
1187 Optional parameter for MPL3115 only.
1189 You can further calibrate the sensor by supplying pressure and/or temperature
1190 offsets. This is added to the measured/caclulated value (i.e. if the measured
1191 value is too high then use negative offset).
1192 In hPa, default is 0.0.
1194 =item B<TemperatureOffset> I<offset>
1196 Optional parameter for MPL3115 only.
1198 You can further calibrate the sensor by supplying pressure and/or temperature
1199 offsets. This is added to the measured/caclulated value (i.e. if the measured
1200 value is too high then use negative offset).
1201 In C, default is 0.0.
1203 =item B<Normalization> I<method>
1205 Optional parameter, default value is 0.
1207 Normalization method - what approximation/model is used to compute the mean sea
1208 level pressure from the air absolute pressure.
1210 Supported values of the C<method> (integer between from 0 to 2) are:
1214 =item B<0> - no conversion, absolute pressure is simply copied over. For this method you
1215 do not need to configure C<Altitude> or C<TemperatureSensor>.
1217 =item B<1> - international formula for conversion ,
1219 L<http://en.wikipedia.org/wiki/Atmospheric_pressure#Altitude_atmospheric_pressure_variation>.
1220 For this method you have to configure C<Altitude> but do not need
1221 C<TemperatureSensor> (uses fixed global temperature average instead).
1223 =item B<2> - formula as recommended by the Deutsche Wetterdienst (German
1224 Meteorological Service).
1225 See L<http://de.wikipedia.org/wiki/Barometrische_H%C3%B6henformel#Theorie>
1226 For this method you have to configure both C<Altitude> and
1227 C<TemperatureSensor>.
1232 =item B<Altitude> I<altitude>
1234 The altitude (in meters) of the location where you meassure the pressure.
1236 =item B<TemperatureSensor> I<reference>
1238 Temperature sensor(s) which should be used as a reference when normalizing the
1239 pressure using C<Normalization> method 2.
1240 When specified more sensors a minimum is found and used each time. The
1241 temperature reading directly from this pressure sensor/plugin is typically not
1242 suitable as the pressure sensor will be probably inside while we want outside
1243 temperature. The collectd reference name is something like
1244 <hostname>/<plugin_name>-<plugin_instance>/<type>-<type_instance>
1245 (<type_instance> is usually omitted when there is just single value type). Or
1246 you can figure it out from the path of the output data files.
1250 =head2 Plugin C<battery>
1252 The I<battery plugin> reports the remaining capacity, power and voltage of
1257 =item B<ValuesPercentage> B<false>|B<true>
1259 When enabled, remaining capacity is reported as a percentage, e.g. "42%
1260 capacity remaining". Otherwise the capacity is stored as reported by the
1261 battery, most likely in "Wh". This option does not work with all input methods,
1262 in particular when only C</proc/pmu> is available on an old Linux system.
1263 Defaults to B<false>.
1265 =item B<ReportDegraded> B<false>|B<true>
1267 Typical laptop batteries degrade over time, meaning the capacity decreases with
1268 recharge cycles. The maximum charge of the previous charge cycle is tracked as
1269 "last full capacity" and used to determine that a battery is "fully charged".
1271 When this option is set to B<false>, the default, the I<battery plugin> will
1272 only report the remaining capacity. If the B<ValuesPercentage> option is
1273 enabled, the relative remaining capacity is calculated as the ratio of the
1274 "remaining capacity" and the "last full capacity". This is what most tools,
1275 such as the status bar of desktop environments, also do.
1277 When set to B<true>, the battery plugin will report three values: B<charged>
1278 (remaining capacity), B<discharged> (difference between "last full capacity"
1279 and "remaining capacity") and B<degraded> (difference between "design capacity"
1280 and "last full capacity").
1282 =item B<QueryStateFS> B<false>|B<true>
1284 When set to B<true>, the battery plugin will only read statistics
1285 related to battery performance as exposed by StateFS at
1286 /run/state. StateFS is used in Mer-based Sailfish OS, for
1291 =head2 Plugin C<bind>
1293 Starting with BIND 9.5.0, the most widely used DNS server software provides
1294 extensive statistics about queries, responses and lots of other information.
1295 The bind plugin retrieves this information that's encoded in XML and provided
1296 via HTTP and submits the values to collectd.
1298 To use this plugin, you first need to tell BIND to make this information
1299 available. This is done with the C<statistics-channels> configuration option:
1301 statistics-channels {
1302 inet localhost port 8053;
1305 The configuration follows the grouping that can be seen when looking at the
1306 data with an XSLT compatible viewer, such as a modern web browser. It's
1307 probably a good idea to make yourself familiar with the provided values, so you
1308 can understand what the collected statistics actually mean.
1313 URL "http://localhost:8053/"
1328 Zone "127.in-addr.arpa/IN"
1332 The bind plugin accepts the following configuration options:
1338 URL from which to retrieve the XML data. If not specified,
1339 C<http://localhost:8053/> will be used.
1341 =item B<ParseTime> B<true>|B<false>
1343 When set to B<true>, the time provided by BIND will be parsed and used to
1344 dispatch the values. When set to B<false>, the local time source is queried.
1346 This setting is set to B<true> by default for backwards compatibility; setting
1347 this to B<false> is I<recommended> to avoid problems with timezones and
1350 =item B<OpCodes> B<true>|B<false>
1352 When enabled, statistics about the I<"OpCodes">, for example the number of
1353 C<QUERY> packets, are collected.
1357 =item B<QTypes> B<true>|B<false>
1359 When enabled, the number of I<incoming> queries by query types (for example
1360 C<A>, C<MX>, C<AAAA>) is collected.
1364 =item B<ServerStats> B<true>|B<false>
1366 Collect global server statistics, such as requests received over IPv4 and IPv6,
1367 successful queries, and failed updates.
1371 =item B<ZoneMaintStats> B<true>|B<false>
1373 Collect zone maintenance statistics, mostly information about notifications
1374 (zone updates) and zone transfers.
1378 =item B<ResolverStats> B<true>|B<false>
1380 Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
1381 (e.E<nbsp>g. queries over IPv4, lame servers). Since the global resolver
1382 counters apparently were removed in BIND 9.5.1 and 9.6.0, this is disabled by
1383 default. Use the B<ResolverStats> option within a B<View "_default"> block
1384 instead for the same functionality.
1388 =item B<MemoryStats>
1390 Collect global memory statistics.
1394 =item B<Timeout> I<Milliseconds>
1396 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
1397 milliseconds. By default, the configured B<Interval> is used to set the
1400 =item B<View> I<Name>
1402 Collect statistics about a specific I<"view">. BIND can behave different,
1403 mostly depending on the source IP-address of the request. These different
1404 configurations are called "views". If you don't use this feature, you most
1405 likely are only interested in the C<_default> view.
1407 Within a E<lt>B<View>E<nbsp>I<name>E<gt> block, you can specify which
1408 information you want to collect about a view. If no B<View> block is
1409 configured, no detailed view statistics will be collected.
1413 =item B<QTypes> B<true>|B<false>
1415 If enabled, the number of I<outgoing> queries by query type (e.E<nbsp>g. C<A>,
1416 C<MX>) is collected.
1420 =item B<ResolverStats> B<true>|B<false>
1422 Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
1423 (e.E<nbsp>g. queries over IPv4, lame servers).
1427 =item B<CacheRRSets> B<true>|B<false>
1429 If enabled, the number of entries (I<"RR sets">) in the view's cache by query
1430 type is collected. Negative entries (queries which resulted in an error, for
1431 example names that do not exist) are reported with a leading exclamation mark,
1436 =item B<Zone> I<Name>
1438 When given, collect detailed information about the given zone in the view. The
1439 information collected if very similar to the global B<ServerStats> information
1442 You can repeat this option to collect detailed information about multiple
1445 By default no detailed zone information is collected.
1451 =head2 Plugin C<ceph>
1453 The ceph plugin collects values from JSON data to be parsed by B<libyajl>
1454 (L<https://lloyd.github.io/yajl/>) retrieved from ceph daemon admin sockets.
1456 A separate B<Daemon> block must be configured for each ceph daemon to be
1457 monitored. The following example will read daemon statistics from four
1458 separate ceph daemons running on the same device (two OSDs, one MON, one MDS) :
1461 LongRunAvgLatency false
1462 ConvertSpecialMetricTypes true
1464 SocketPath "/var/run/ceph/ceph-osd.0.asok"
1467 SocketPath "/var/run/ceph/ceph-osd.1.asok"
1470 SocketPath "/var/run/ceph/ceph-mon.ceph1.asok"
1473 SocketPath "/var/run/ceph/ceph-mds.ceph1.asok"
1477 The ceph plugin accepts the following configuration options:
1481 =item B<LongRunAvgLatency> B<true>|B<false>
1483 If enabled, latency values(sum,count pairs) are calculated as the long run
1484 average - average since the ceph daemon was started = (sum / count).
1485 When disabled, latency values are calculated as the average since the last
1486 collection = (sum_now - sum_last) / (count_now - count_last).
1490 =item B<ConvertSpecialMetricTypes> B<true>|B<false>
1492 If enabled, special metrics (metrics that differ in type from similar counters)
1493 are converted to the type of those similar counters. This currently only
1494 applies to filestore.journal_wr_bytes which is a counter for OSD daemons. The
1495 ceph schema reports this metric type as a sum,count pair while similar counters
1496 are treated as derive types. When converted, the sum is used as the counter
1497 value and is treated as a derive type.
1498 When disabled, all metrics are treated as the types received from the ceph schema.
1504 Each B<Daemon> block must have a string argument for the plugin instance name.
1505 A B<SocketPath> is also required for each B<Daemon> block:
1509 =item B<Daemon> I<DaemonName>
1511 Name to be used as the instance name for this daemon.
1513 =item B<SocketPath> I<SocketPath>
1515 Specifies the path to the UNIX admin socket of the ceph daemon.
1519 =head2 Plugin C<cgroups>
1521 This plugin collects the CPU user/system time for each I<cgroup> by reading the
1522 F<cpuacct.stat> files in the first cpuacct-mountpoint (typically
1523 F</sys/fs/cgroup/cpu.cpuacct> on machines using systemd).
1527 =item B<CGroup> I<Directory>
1529 Select I<cgroup> based on the name. Whether only matching I<cgroups> are
1530 collected or if they are ignored is controlled by the B<IgnoreSelected> option;
1533 See F</"IGNORELISTS"> for details.
1535 =item B<IgnoreSelected> B<true>|B<false>
1537 Invert the selection: If set to true, all cgroups I<except> the ones that
1538 match any one of the criteria are collected. By default only selected
1539 cgroups are collected if a selection is made. If no selection is configured
1540 at all, B<all> cgroups are selected.
1544 =head2 Plugin C<chrony>
1546 The C<chrony> plugin collects ntp data from a B<chronyd> server, such as clock
1547 skew and per-peer stratum.
1549 For talking to B<chronyd>, it mimics what the B<chronyc> control program does
1552 Available configuration options for the C<chrony> plugin:
1556 =item B<Host> I<Hostname>
1558 Hostname of the host running B<chronyd>. Defaults to B<localhost>.
1560 =item B<Port> I<Port>
1562 UDP-Port to connect to. Defaults to B<323>.
1564 =item B<Timeout> I<Timeout>
1566 Connection timeout in seconds. Defaults to B<2>.
1570 =head2 Plugin C<conntrack>
1572 This plugin collects IP conntrack statistics.
1578 Assume the B<conntrack_count> and B<conntrack_max> files to be found in
1579 F</proc/sys/net/ipv4/netfilter> instead of F</proc/sys/net/netfilter/>.
1583 =head2 Plugin C<cpu>
1585 The I<CPU plugin> collects CPU usage metrics. By default, CPU usage is reported
1586 as Jiffies, using the C<cpu> type. Two aggregations are available:
1592 Sum, per-state, over all CPUs installed in the system; and
1596 Sum, per-CPU, over all non-idle states of a CPU, creating an "active" state.
1600 The two aggregations can be combined, leading to I<collectd> only emitting a
1601 single "active" metric for the entire system. As soon as one of these
1602 aggregations (or both) is enabled, the I<cpu plugin> will report a percentage,
1603 rather than Jiffies. In addition, you can request individual, per-state,
1604 per-CPU metrics to be reported as percentage.
1606 The following configuration options are available:
1610 =item B<ReportByState> B<true>|B<false>
1612 When set to B<true>, the default, reports per-state metrics, e.g. "system",
1614 When set to B<false>, aggregates (sums) all I<non-idle> states into one
1617 =item B<ReportByCpu> B<true>|B<false>
1619 When set to B<true>, the default, reports per-CPU (per-core) metrics.
1620 When set to B<false>, instead of reporting metrics for individual CPUs, only a
1621 global sum of CPU states is emitted.
1623 =item B<ValuesPercentage> B<false>|B<true>
1625 This option is only considered when both, B<ReportByCpu> and B<ReportByState>
1626 are set to B<true>. In this case, by default, metrics will be reported as
1627 Jiffies. By setting this option to B<true>, you can request percentage values
1628 in the un-aggregated (per-CPU, per-state) mode as well.
1630 =item B<ReportNumCpu> B<false>|B<true>
1632 When set to B<true>, reports the number of available CPUs.
1633 Defaults to B<false>.
1635 =item B<ReportGuestState> B<false>|B<true>
1637 When set to B<true>, reports the "guest" and "guest_nice" CPU states.
1638 Defaults to B<false>.
1640 =item B<SubtractGuestState> B<false>|B<true>
1642 This option is only considered when B<ReportGuestState> is set to B<true>.
1643 "guest" and "guest_nice" are included in respectively "user" and "nice".
1644 If set to B<true>, "guest" will be subtracted from "user" and "guest_nice"
1645 will be subtracted from "nice".
1646 Defaults to B<true>.
1650 =head2 Plugin C<cpufreq>
1652 This plugin doesn't have any options. It reads
1653 F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for the first CPU
1654 installed) to get the current CPU frequency. If this file does not exist make
1655 sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a similar tool is
1656 installed and an "cpu governor" (that's a kernel module) is loaded.
1658 =head2 Plugin C<cpusleep>
1660 This plugin doesn't have any options. It reads CLOCK_BOOTTIME and
1661 CLOCK_MONOTONIC and reports the difference between these clocks. Since
1662 BOOTTIME clock increments while device is suspended and MONOTONIC
1663 clock does not, the derivative of the difference between these clocks
1664 gives the relative amount of time the device has spent in suspend
1665 state. The recorded value is in milliseconds of sleep per seconds of
1668 =head2 Plugin C<csv>
1672 =item B<DataDir> I<Directory>
1674 Set the directory to store CSV-files under. Per default CSV-files are generated
1675 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
1676 The special strings B<stdout> and B<stderr> can be used to write to the standard
1677 output and standard error channels, respectively. This, of course, only makes
1678 much sense when collectd is running in foreground- or non-daemon-mode.
1680 =item B<StoreRates> B<true|false>
1682 If set to B<true>, convert counter values to rates. If set to B<false> (the
1683 default) counter values are stored as is, i.E<nbsp>e. as an increasing integer
1688 =head2 cURL Statistics
1690 All cURL-based plugins support collection of generic, request-based
1691 statistics. These are disabled by default and can be enabled selectively for
1692 each page or URL queried from the curl, curl_json, or curl_xml plugins. See
1693 the documentation of those plugins for specific information. This section
1694 describes the available metrics that can be configured for each plugin. All
1695 options are disabled by default.
1697 See L<http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html> for more details.
1701 =item B<TotalTime> B<true|false>
1703 Total time of the transfer, including name resolving, TCP connect, etc.
1705 =item B<NamelookupTime> B<true|false>
1707 Time it took from the start until name resolving was completed.
1709 =item B<ConnectTime> B<true|false>
1711 Time it took from the start until the connect to the remote host (or proxy)
1714 =item B<AppconnectTime> B<true|false>
1716 Time it took from the start until the SSL/SSH connect/handshake to the remote
1719 =item B<PretransferTime> B<true|false>
1721 Time it took from the start until just before the transfer begins.
1723 =item B<StarttransferTime> B<true|false>
1725 Time it took from the start until the first byte was received.
1727 =item B<RedirectTime> B<true|false>
1729 Time it took for all redirection steps include name lookup, connect,
1730 pre-transfer and transfer before final transaction was started.
1732 =item B<RedirectCount> B<true|false>
1734 The total number of redirections that were actually followed.
1736 =item B<SizeUpload> B<true|false>
1738 The total amount of bytes that were uploaded.
1740 =item B<SizeDownload> B<true|false>
1742 The total amount of bytes that were downloaded.
1744 =item B<SpeedDownload> B<true|false>
1746 The average download speed that curl measured for the complete download.
1748 =item B<SpeedUpload> B<true|false>
1750 The average upload speed that curl measured for the complete upload.
1752 =item B<HeaderSize> B<true|false>
1754 The total size of all the headers received.
1756 =item B<RequestSize> B<true|false>
1758 The total size of the issued requests.
1760 =item B<ContentLengthDownload> B<true|false>
1762 The content-length of the download.
1764 =item B<ContentLengthUpload> B<true|false>
1766 The specified size of the upload.
1768 =item B<NumConnects> B<true|false>
1770 The number of new connections that were created to achieve the transfer.
1774 =head2 Plugin C<curl>
1776 The curl plugin uses the B<libcurl> (L<http://curl.haxx.se/>) to read web pages
1777 and the match infrastructure (the same code used by the tail plugin) to use
1778 regular expressions with the received data.
1780 The following example will read the current value of AMD stock from Google's
1781 finance page and dispatch the value to collectd.
1784 <Page "stock_quotes">
1786 URL "http://finance.google.com/finance?q=NYSE%3AAMD"
1792 CACert "/path/to/ca.crt"
1793 Header "X-Custom-Header: foobar"
1796 MeasureResponseTime false
1797 MeasureResponseCode false
1800 Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
1801 DSType "GaugeAverage"
1802 # Note: `stock_value' is not a standard type.
1809 In the B<Plugin> block, there may be one or more B<Page> blocks, each defining
1810 a web page and one or more "matches" to be performed on the returned data. The
1811 string argument to the B<Page> block is used as plugin instance.
1813 The following options are valid within B<Page> blocks:
1817 =item B<Plugin> I<Plugin>
1819 Use I<Plugin> as the plugin name when submitting values.
1820 Defaults to C<curl>.
1824 URL of the web site to retrieve. Since a regular expression will be used to
1825 extract information from this data, non-binary data is a big plus here ;)
1827 =item B<User> I<Name>
1829 Username to use if authorization is required to read the page.
1831 =item B<Password> I<Password>
1833 Password to use if authorization is required to read the page.
1835 =item B<Digest> B<true>|B<false>
1837 Enable HTTP digest authentication.
1839 =item B<VerifyPeer> B<true>|B<false>
1841 Enable or disable peer SSL certificate verification. See
1842 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
1844 =item B<VerifyHost> B<true>|B<false>
1846 Enable or disable peer host name verification. If enabled, the plugin checks if
1847 the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
1848 matches the host name provided by the B<URL> option. If this identity check
1849 fails, the connection is aborted. Obviously, only works when connecting to a
1850 SSL enabled server. Enabled by default.
1852 =item B<CACert> I<file>
1854 File that holds one or more SSL certificates. If you want to use HTTPS you will
1855 possibly need this option. What CA certificates come bundled with C<libcurl>
1856 and are checked by default depends on the distribution you use.
1858 =item B<Header> I<Header>
1860 A HTTP header to add to the request. Multiple headers are added if this option
1861 is specified more than once.
1863 =item B<Post> I<Body>
1865 Specifies that the HTTP operation should be a POST instead of a GET. The
1866 complete data to be posted is given as the argument. This option will usually
1867 need to be accompanied by a B<Header> option to set an appropriate
1868 C<Content-Type> for the post body (e.g. to
1869 C<application/x-www-form-urlencoded>).
1871 =item B<MeasureResponseTime> B<true>|B<false>
1873 Measure response time for the request. If this setting is enabled, B<Match>
1874 blocks (see below) are optional. Disabled by default.
1876 Beware that requests will get aborted if they take too long to complete. Adjust
1877 B<Timeout> accordingly if you expect B<MeasureResponseTime> to report such slow
1880 This option is similar to enabling the B<TotalTime> statistic but it's
1881 measured by collectd instead of cURL.
1883 =item B<MeasureResponseCode> B<true>|B<false>
1885 Measure response code for the request. If this setting is enabled, B<Match>
1886 blocks (see below) are optional. Disabled by default.
1888 =item B<E<lt>StatisticsE<gt>>
1890 One B<Statistics> block can be used to specify cURL statistics to be collected
1891 for each request to the remote web site. See the section "cURL Statistics"
1892 above for details. If this setting is enabled, B<Match> blocks (see below) are
1895 =item B<E<lt>MatchE<gt>>
1897 One or more B<Match> blocks that define how to match information in the data
1898 returned by C<libcurl>. The C<curl> plugin uses the same infrastructure that's
1899 used by the C<tail> plugin, so please see the documentation of the C<tail>
1900 plugin below on how matches are defined. If the B<MeasureResponseTime> or
1901 B<MeasureResponseCode> options are set to B<true>, B<Match> blocks are
1904 =item B<Timeout> I<Milliseconds>
1906 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
1907 milliseconds. By default, the configured B<Interval> is used to set the
1908 timeout. Prior to version 5.5.0, there was no timeout and requests could hang
1909 indefinitely. This legacy behaviour can be achieved by setting the value of
1912 If B<Timeout> is 0 or bigger than the B<Interval>, keep in mind that each slow
1913 network connection will stall one read thread. Adjust the B<ReadThreads> global
1914 setting accordingly to prevent this from blocking other plugins.
1918 =head2 Plugin C<curl_json>
1920 The B<curl_json plugin> collects values from JSON data to be parsed by
1921 B<libyajl> (L<https://lloyd.github.io/yajl/>) retrieved via
1922 either B<libcurl> (L<http://curl.haxx.se/>) or read directly from a
1923 unix socket. The former can be used, for example, to collect values
1924 from CouchDB documents (which are stored JSON notation), and the
1925 latter to collect values from a uWSGI stats socket.
1927 The following example will collect several values from the built-in
1928 C<_stats> runtime statistics module of I<CouchDB>
1929 (L<http://wiki.apache.org/couchdb/Runtime_Statistics>).
1932 <URL "http://localhost:5984/_stats">
1934 <Key "httpd/requests/count">
1935 Type "http_requests"
1938 <Key "httpd_request_methods/*/count">
1939 Type "http_request_methods"
1942 <Key "httpd_status_codes/*/count">
1943 Type "http_response_codes"
1948 This example will collect data directly from a I<uWSGI> "Stats Server" socket.
1951 <Sock "/var/run/uwsgi.stats.sock">
1953 <Key "workers/*/requests">
1954 Type "http_requests"
1957 <Key "workers/*/apps/*/requests">
1958 Type "http_requests"
1963 In the B<Plugin> block, there may be one or more B<URL> blocks, each
1964 defining a URL to be fetched via HTTP (using libcurl) or B<Sock>
1965 blocks defining a unix socket to read JSON from directly. Each of
1966 these blocks may have one or more B<Key> blocks.
1968 The B<Key> string argument must be in a path format. Each component is
1969 used to match the key from a JSON map or the index of an JSON
1970 array. If a path component of a B<Key> is a I<*>E<nbsp>wildcard, the
1971 values for all map keys or array indices will be collectd.
1973 The following options are valid within B<URL> blocks:
1977 =item B<Host> I<Name>
1979 Use I<Name> as the host name when submitting values. Defaults to the global
1982 =item B<Plugin> I<Plugin>
1984 Use I<Plugin> as the plugin name when submitting values.
1985 Defaults to C<curl_json>.
1987 =item B<Instance> I<Instance>
1989 Sets the plugin instance to I<Instance>.
1991 =item B<Interval> I<Interval>
1993 Sets the interval (in seconds) in which the values will be collected from this
1994 URL. By default the global B<Interval> setting will be used.
1996 =item B<User> I<Name>
1998 =item B<Password> I<Password>
2000 =item B<Digest> B<true>|B<false>
2002 =item B<VerifyPeer> B<true>|B<false>
2004 =item B<VerifyHost> B<true>|B<false>
2006 =item B<CACert> I<file>
2008 =item B<Header> I<Header>
2010 =item B<Post> I<Body>
2012 =item B<Timeout> I<Milliseconds>
2014 These options behave exactly equivalent to the appropriate options of the
2015 I<cURL> plugin. Please see there for a detailed description.
2017 =item B<E<lt>StatisticsE<gt>>
2019 One B<Statistics> block can be used to specify cURL statistics to be collected
2020 for each request to the remote URL. See the section "cURL Statistics" above
2025 The following options are valid within B<Key> blocks:
2029 =item B<Type> I<Type>
2031 Sets the type used to dispatch the values to the daemon. Detailed information
2032 about types and their configuration can be found in L<types.db(5)>. This
2033 option is mandatory.
2035 =item B<Instance> I<Instance>
2037 Type-instance to use. Defaults to the current map key or current string array element value.
2041 =head2 Plugin C<curl_xml>
2043 The B<curl_xml plugin> uses B<libcurl> (L<http://curl.haxx.se/>) and B<libxml2>
2044 (L<http://xmlsoft.org/>) to retrieve XML data via cURL.
2047 <URL "http://localhost/stats.xml">
2050 Instance "some_instance"
2055 CACert "/path/to/ca.crt"
2056 Header "X-Custom-Header: foobar"
2059 <XPath "table[@id=\"magic_level\"]/tr">
2061 #InstancePrefix "prefix-"
2062 InstanceFrom "td[1]"
2063 #PluginInstanceFrom "td[1]"
2064 ValuesFrom "td[2]/span[@class=\"level\"]"
2069 In the B<Plugin> block, there may be one or more B<URL> blocks, each defining a
2070 URL to be fetched using libcurl. Within each B<URL> block there are
2071 options which specify the connection parameters, for example authentication
2072 information, and one or more B<XPath> blocks.
2074 Each B<XPath> block specifies how to get one type of information. The
2075 string argument must be a valid XPath expression which returns a list
2076 of "base elements". One value is dispatched for each "base element". The
2077 I<type instance> and values are looked up using further I<XPath> expressions
2078 that should be relative to the base element.
2080 Within the B<URL> block the following options are accepted:
2084 =item B<Host> I<Name>
2086 Use I<Name> as the host name when submitting values. Defaults to the global
2089 =item B<Plugin> I<Plugin>
2091 Use I<Plugin> as the plugin name when submitting values.
2092 Defaults to 'curl_xml'.
2094 =item B<Instance> I<Instance>
2096 Use I<Instance> as the plugin instance when submitting values.
2097 May be overridden by B<PluginInstanceFrom> option inside B<XPath> blocks.
2098 Defaults to an empty string (no plugin instance).
2100 =item B<Namespace> I<Prefix> I<URL>
2102 If an XPath expression references namespaces, they must be specified
2103 with this option. I<Prefix> is the "namespace prefix" used in the XML document.
2104 I<URL> is the "namespace name", an URI reference uniquely identifying the
2105 namespace. The option can be repeated to register multiple namespaces.
2109 Namespace "s" "http://schemas.xmlsoap.org/soap/envelope/"
2110 Namespace "m" "http://www.w3.org/1998/Math/MathML"
2112 =item B<User> I<User>
2114 =item B<Password> I<Password>
2116 =item B<Digest> B<true>|B<false>
2118 =item B<VerifyPeer> B<true>|B<false>
2120 =item B<VerifyHost> B<true>|B<false>
2122 =item B<CACert> I<CA Cert File>
2124 =item B<Header> I<Header>
2126 =item B<Post> I<Body>
2128 =item B<Timeout> I<Milliseconds>
2130 These options behave exactly equivalent to the appropriate options of the
2131 I<cURL plugin>. Please see there for a detailed description.
2133 =item B<E<lt>StatisticsE<gt>>
2135 One B<Statistics> block can be used to specify cURL statistics to be collected
2136 for each request to the remote URL. See the section "cURL Statistics" above
2139 =item E<lt>B<XPath> I<XPath-expression>E<gt>
2141 Within each B<URL> block, there must be one or more B<XPath> blocks. Each
2142 B<XPath> block specifies how to get one type of information. The string
2143 argument must be a valid XPath expression which returns a list of "base
2144 elements". One value is dispatched for each "base element".
2146 Within the B<XPath> block the following options are accepted:
2150 =item B<Type> I<Type>
2152 Specifies the I<Type> used for submitting patches. This determines the number
2153 of values that are required / expected and whether the strings are parsed as
2154 signed or unsigned integer or as double values. See L<types.db(5)> for details.
2155 This option is required.
2157 =item B<InstancePrefix> I<InstancePrefix>
2159 Prefix the I<type instance> with I<InstancePrefix>. The values are simply
2160 concatenated together without any separator.
2161 This option is optional.
2163 =item B<InstanceFrom> I<InstanceFrom>
2165 Specifies a XPath expression to use for determining the I<type instance>. The
2166 XPath expression must return exactly one element. The element's value is then
2167 used as I<type instance>, possibly prefixed with I<InstancePrefix> (see above).
2169 =item B<PluginInstanceFrom> I<PluginInstanceFrom>
2171 Specifies a XPath expression to use for determining the I<plugin instance>. The
2172 XPath expression must return exactly one element. The element's value is then
2173 used as I<plugin instance>.
2177 If the "base XPath expression" (the argument to the B<XPath> block) returns
2178 exactly one argument, then I<InstanceFrom> and I<PluginInstanceFrom> may be omitted.
2179 Otherwise, at least one of I<InstanceFrom> or I<PluginInstanceFrom> is required.
2183 =item B<ValuesFrom> I<ValuesFrom> [I<ValuesFrom> ...]
2185 Specifies one or more XPath expression to use for reading the values. The
2186 number of XPath expressions must match the number of data sources in the
2187 I<type> specified with B<Type> (see above). Each XPath expression must return
2188 exactly one element. The element's value is then parsed as a number and used as
2189 value for the appropriate value in the value list dispatched to the daemon.
2190 This option is required.
2196 =head2 Plugin C<dbi>
2198 This plugin uses the B<dbi> library (L<http://libdbi.sourceforge.net/>) to
2199 connect to various databases, execute I<SQL> statements and read back the
2200 results. I<dbi> is an acronym for "database interface" in case you were
2201 wondering about the name. You can configure how each column is to be
2202 interpreted and the plugin will generate one or more data sets from each row
2203 returned according to these rules.
2205 Because the plugin is very generic, the configuration is a little more complex
2206 than those of other plugins. It usually looks something like this:
2209 <Query "out_of_stock">
2210 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
2211 # Use with MySQL 5.0.0 or later
2215 InstancePrefix "out_of_stock"
2216 InstancesFrom "category"
2220 <Database "product_information">
2224 DriverOption "host" "localhost"
2225 DriverOption "username" "collectd"
2226 DriverOption "password" "aZo6daiw"
2227 DriverOption "dbname" "prod_info"
2228 SelectDB "prod_info"
2229 Query "out_of_stock"
2233 The configuration above defines one query with one result and one database. The
2234 query is then linked to the database with the B<Query> option I<within> the
2235 B<E<lt>DatabaseE<gt>> block. You can have any number of queries and databases
2236 and you can also use the B<Include> statement to split up the configuration
2237 file in multiple, smaller files. However, the B<E<lt>QueryE<gt>> block I<must>
2238 precede the B<E<lt>DatabaseE<gt>> blocks, because the file is interpreted from
2241 The following is a complete list of options:
2243 =head3 B<Query> blocks
2245 Query blocks define I<SQL> statements and how the returned data should be
2246 interpreted. They are identified by the name that is given in the opening line
2247 of the block. Thus the name needs to be unique. Other than that, the name is
2248 not used in collectd.
2250 In each B<Query> block, there is one or more B<Result> blocks. B<Result> blocks
2251 define which column holds which value or instance information. You can use
2252 multiple B<Result> blocks to create multiple values from one returned row. This
2253 is especially useful, when queries take a long time and sending almost the same
2254 query again and again is not desirable.
2258 <Query "environment">
2259 Statement "select station, temperature, humidity from environment"
2262 # InstancePrefix "foo"
2263 InstancesFrom "station"
2264 ValuesFrom "temperature"
2268 InstancesFrom "station"
2269 ValuesFrom "humidity"
2273 The following options are accepted:
2277 =item B<Statement> I<SQL>
2279 Sets the statement that should be executed on the server. This is B<not>
2280 interpreted by collectd, but simply passed to the database server. Therefore,
2281 the SQL dialect that's used depends on the server collectd is connected to.
2283 The query has to return at least two columns, one for the instance and one
2284 value. You cannot omit the instance, even if the statement is guaranteed to
2285 always return exactly one line. In that case, you can usually specify something
2288 Statement "SELECT \"instance\", COUNT(*) AS value FROM table"
2290 (That works with MySQL but may not be valid SQL according to the spec. If you
2291 use a more strict database server, you may have to select from a dummy table or
2294 Please note that some databases, for example B<Oracle>, will fail if you
2295 include a semicolon at the end of the statement.
2297 =item B<MinVersion> I<Version>
2299 =item B<MaxVersion> I<Value>
2301 Only use this query for the specified database version. You can use these
2302 options to provide multiple queries with the same name but with a slightly
2303 different syntax. The plugin will use only those queries, where the specified
2304 minimum and maximum versions fit the version of the database in use.
2306 The database version is determined by C<dbi_conn_get_engine_version>, see the
2307 L<libdbi documentation|http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-GET-ENGINE-VERSION>
2308 for details. Basically, each part of the version is assumed to be in the range
2309 from B<00> to B<99> and all dots are removed. So version "4.1.2" becomes
2310 "40102", version "5.0.42" becomes "50042".
2312 B<Warning:> The plugin will use B<all> matching queries, so if you specify
2313 multiple queries with the same name and B<overlapping> ranges, weird stuff will
2314 happen. Don't to it! A valid example would be something along these lines:
2325 In the above example, there are three ranges that don't overlap. The last one
2326 goes from version "5.1.0" to infinity, meaning "all later versions". Versions
2327 before "4.0.0" are not specified.
2329 =item B<Type> I<Type>
2331 The B<type> that's used for each line returned. See L<types.db(5)> for more
2332 details on how types are defined. In short: A type is a predefined layout of
2333 data and the number of values and type of values has to match the type
2336 If you specify "temperature" here, you need exactly one gauge column. If you
2337 specify "if_octets", you will need two counter columns. See the B<ValuesFrom>
2340 There must be exactly one B<Type> option inside each B<Result> block.
2342 =item B<InstancePrefix> I<prefix>
2344 Prepends I<prefix> to the type instance. If B<InstancesFrom> (see below) is not
2345 given, the string is simply copied. If B<InstancesFrom> is given, I<prefix> and
2346 all strings returned in the appropriate columns are concatenated together,
2347 separated by dashes I<("-")>.
2349 =item B<InstancesFrom> I<column0> [I<column1> ...]
2351 Specifies the columns whose values will be used to create the "type-instance"
2352 for each row. If you specify more than one column, the value of all columns
2353 will be joined together with dashes I<("-")> as separation characters.
2355 The plugin itself does not check whether or not all built instances are
2356 different. It's your responsibility to assure that each is unique. This is
2357 especially true, if you do not specify B<InstancesFrom>: B<You> have to make
2358 sure that only one row is returned in this case.
2360 If neither B<InstancePrefix> nor B<InstancesFrom> is given, the type-instance
2363 =item B<ValuesFrom> I<column0> [I<column1> ...]
2365 Names the columns whose content is used as the actual data for the data sets
2366 that are dispatched to the daemon. How many such columns you need is determined
2367 by the B<Type> setting above. If you specify too many or not enough columns,
2368 the plugin will complain about that and no data will be submitted to the
2371 The actual data type in the columns is not that important. The plugin will
2372 automatically cast the values to the right type if it know how to do that. So
2373 it should be able to handle integer an floating point types, as well as strings
2374 (if they include a number at the beginning).
2376 There must be at least one B<ValuesFrom> option inside each B<Result> block.
2378 =item B<MetadataFrom> [I<column0> I<column1> ...]
2380 Names the columns whose content is used as metadata for the data sets
2381 that are dispatched to the daemon.
2383 The actual data type in the columns is not that important. The plugin will
2384 automatically cast the values to the right type if it know how to do that. So
2385 it should be able to handle integer an floating point types, as well as strings
2386 (if they include a number at the beginning).
2390 =head3 B<Database> blocks
2392 Database blocks define a connection to a database and which queries should be
2393 sent to that database. Since the used "dbi" library can handle a wide variety
2394 of databases, the configuration is very generic. If in doubt, refer to libdbi's
2395 documentationE<nbsp>- we stick as close to the terminology used there.
2397 Each database needs a "name" as string argument in the starting tag of the
2398 block. This name will be used as "PluginInstance" in the values submitted to
2399 the daemon. Other than that, that name is not used.
2403 =item B<Plugin> I<Plugin>
2405 Use I<Plugin> as the plugin name when submitting query results from
2406 this B<Database>. Defaults to C<dbi>.
2408 =item B<Interval> I<Interval>
2410 Sets the interval (in seconds) in which the values will be collected from this
2411 database. By default the global B<Interval> setting will be used.
2413 =item B<Driver> I<Driver>
2415 Specifies the driver to use to connect to the database. In many cases those
2416 drivers are named after the database they can connect to, but this is not a
2417 technical necessity. These drivers are sometimes referred to as "DBD",
2418 B<D>ataB<B>ase B<D>river, and some distributions ship them in separate
2419 packages. Drivers for the "dbi" library are developed by the B<libdbi-drivers>
2420 project at L<http://libdbi-drivers.sourceforge.net/>.
2422 You need to give the driver name as expected by the "dbi" library here. You
2423 should be able to find that in the documentation for each driver. If you
2424 mistype the driver name, the plugin will dump a list of all known driver names
2427 =item B<DriverOption> I<Key> I<Value>
2429 Sets driver-specific options. What option a driver supports can be found in the
2430 documentation for each driver, somewhere at
2431 L<http://libdbi-drivers.sourceforge.net/>. However, the options "host",
2432 "username", "password", and "dbname" seem to be deE<nbsp>facto standards.
2434 DBDs can register two types of options: String options and numeric options. The
2435 plugin will use the C<dbi_conn_set_option> function when the configuration
2436 provides a string and the C<dbi_conn_require_option_numeric> function when the
2437 configuration provides a number. So these two lines will actually result in
2438 different calls being used:
2440 DriverOption "Port" 1234 # numeric
2441 DriverOption "Port" "1234" # string
2443 Unfortunately, drivers are not too keen to report errors when an unknown option
2444 is passed to them, so invalid settings here may go unnoticed. This is not the
2445 plugin's fault, it will report errors if it gets them from the libraryE<nbsp>/
2446 the driver. If a driver complains about an option, the plugin will dump a
2447 complete list of all options understood by that driver to the log. There is no
2448 way to programmatically find out if an option expects a string or a numeric
2449 argument, so you will have to refer to the appropriate DBD's documentation to
2450 find this out. Sorry.
2452 =item B<SelectDB> I<Database>
2454 In some cases, the database name you connect with is not the database name you
2455 want to use for querying data. If this option is set, the plugin will "select"
2456 (switch to) that database after the connection is established.
2458 =item B<Query> I<QueryName>
2460 Associates the query named I<QueryName> with this database connection. The
2461 query needs to be defined I<before> this statement, i.E<nbsp>e. all query
2462 blocks you want to refer to must be placed above the database block you want to
2465 =item B<Host> I<Hostname>
2467 Sets the B<host> field of I<value lists> to I<Hostname> when dispatching
2468 values. Defaults to the global hostname setting.
2476 =item B<Device> I<Device>
2478 Select partitions based on the devicename.
2480 See F</"IGNORELISTS"> for details.
2482 =item B<MountPoint> I<Directory>
2484 Select partitions based on the mountpoint.
2486 See F</"IGNORELISTS"> for details.
2488 =item B<FSType> I<FSType>
2490 Select partitions based on the filesystem type.
2492 See F</"IGNORELISTS"> for details.
2494 =item B<IgnoreSelected> B<true>|B<false>
2496 Invert the selection: If set to true, all partitions B<except> the ones that
2497 match any one of the criteria are collected. By default only selected
2498 partitions are collected if a selection is made. If no selection is configured
2499 at all, B<all> partitions are selected.
2501 =item B<ReportByDevice> B<true>|B<false>
2503 Report using the device name rather than the mountpoint. i.e. with this I<false>,
2504 (the default), it will report a disk as "root", but with it I<true>, it will be
2505 "sda1" (or whichever).
2507 =item B<ReportInodes> B<true>|B<false>
2509 Enables or disables reporting of free, reserved and used inodes. Defaults to
2510 inode collection being disabled.
2512 Enable this option if inodes are a scarce resource for you, usually because
2513 many small files are stored on the disk. This is a usual scenario for mail
2514 transfer agents and web caches.
2516 =item B<ValuesAbsolute> B<true>|B<false>
2518 Enables or disables reporting of free and used disk space in 1K-blocks.
2519 Defaults to B<true>.
2521 =item B<ValuesPercentage> B<false>|B<true>
2523 Enables or disables reporting of free and used disk space in percentage.
2524 Defaults to B<false>.
2526 This is useful for deploying I<collectd> on the cloud, where machines with
2527 different disk size may exist. Then it is more practical to configure
2528 thresholds based on relative disk size.
2532 =head2 Plugin C<disk>
2534 The C<disk> plugin collects information about the usage of physical disks and
2535 logical disks (partitions). Values collected are the number of octets written
2536 to and read from a disk or partition, the number of read/write operations
2537 issued to the disk and a rather complex "time" it took for these commands to be
2540 Using the following two options you can ignore some disks or configure the
2541 collection only of specific disks.
2545 =item B<Disk> I<Name>
2547 Select the disk I<Name>. Whether it is collected or ignored depends on the
2548 B<IgnoreSelected> setting, see below. As with other plugins that use the
2549 daemon's ignorelist functionality, a string that starts and ends with a slash
2550 is interpreted as a regular expression. Examples:
2555 See F</"IGNORELISTS"> for details.
2557 =item B<IgnoreSelected> B<true>|B<false>
2559 Sets whether selected disks, i.E<nbsp>e. the ones matches by any of the B<Disk>
2560 statements, are ignored or if all other disks are ignored. The behavior
2561 (hopefully) is intuitive: If no B<Disk> option is configured, all disks are
2562 collected. If at least one B<Disk> option is given and no B<IgnoreSelected> or
2563 set to B<false>, B<only> matching disks will be collected. If B<IgnoreSelected>
2564 is set to B<true>, all disks are collected B<except> the ones matched.
2566 =item B<UseBSDName> B<true>|B<false>
2568 Whether to use the device's "BSD Name", on MacE<nbsp>OSE<nbsp>X, instead of the
2569 default major/minor numbers. Requires collectd to be built with Apple's
2572 =item B<UdevNameAttr> I<Attribute>
2574 Attempt to override disk instance name with the value of a specified udev
2575 attribute when built with B<libudev>. If the attribute is not defined for the
2576 given device, the default name is used. Example:
2578 UdevNameAttr "DM_NAME"
2582 =head2 Plugin C<dns>
2586 =item B<Interface> I<Interface>
2588 The dns plugin uses B<libpcap> to capture dns traffic and analyzes it. This
2589 option sets the interface that should be used. If this option is not set, or
2590 set to "any", the plugin will try to get packets from B<all> interfaces. This
2591 may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
2593 =item B<IgnoreSource> I<IP-address>
2595 Ignore packets that originate from this address.
2597 =item B<SelectNumericQueryTypes> B<true>|B<false>
2599 Enabled by default, collects unknown (and thus presented as numeric only) query types.
2603 =head2 Plugin C<dpdkevents>
2605 The I<dpdkevents plugin> collects events from DPDK such as link status of
2606 network ports and Keep Alive status of DPDK logical cores.
2607 In order to get Keep Alive events following requirements must be met:
2609 - support for Keep Alive implemented in DPDK application. More details can
2610 be found here: http://dpdk.org/doc/guides/sample_app_ug/keep_alive.html
2614 <Plugin "dpdkevents">
2620 <Event "link_status">
2621 SendEventsOnUpdate true
2622 EnabledPortMask 0xffff
2623 PortName "interface1"
2624 PortName "interface2"
2625 SendNotification false
2627 <Event "keep_alive">
2628 SendEventsOnUpdate true
2630 KeepAliveShmName "/dpdk_keepalive_shm_name"
2631 SendNotification false
2638 =head3 The EAL block
2642 =item B<Coremask> I<Mask>
2644 =item B<Memorychannels> I<Channels>
2646 Number of memory channels per processor socket.
2648 =item B<FilePrefix> I<File>
2650 The prefix text used for hugepage filenames. The filename will be set to
2651 /var/run/.<prefix>_config where prefix is what is passed in by the user.
2655 =head3 The Event block
2657 The B<Event> block defines configuration for specific event. It accepts a
2658 single argument which specifies the name of the event.
2660 =head4 Link Status event
2664 =item B<SendEventOnUpdate> I<true|false>
2666 If set to true link status value will be dispatched only when it is
2667 different from previously read value. This is an optional argument - default
2670 =item B<EnabledPortMask> I<Mask>
2672 A hexidecimal bit mask of the DPDK ports which should be enabled. A mask
2673 of 0x0 means that all ports will be disabled. A bitmask of all F's means
2674 that all ports will be enabled. This is an optional argument - by default
2675 all ports are enabled.
2677 =item B<PortName> I<Name>
2679 A string containing an optional name for the enabled DPDK ports. Each PortName
2680 option should contain only one port name; specify as many PortName options as
2681 desired. Default naming convention will be used if PortName is blank. If there
2682 are less PortName options than there are enabled ports, the default naming
2683 convention will be used for the additional ports.
2685 =item B<SendNotification> I<true|false>
2687 If set to true, link status notifications are sent, instead of link status
2688 being collected as a statistic. This is an optional argument - default
2693 =head4 Keep Alive event
2697 =item B<SendEventOnUpdate> I<true|false>
2699 If set to true keep alive value will be dispatched only when it is
2700 different from previously read value. This is an optional argument - default
2703 =item B<LCoreMask> I<Mask>
2705 An hexadecimal bit mask of the logical cores to monitor keep alive state.
2707 =item B<KeepAliveShmName> I<Name>
2709 Shared memory name identifier that is used by secondary process to monitor
2710 the keep alive cores state.
2712 =item B<SendNotification> I<true|false>
2714 If set to true, keep alive notifications are sent, instead of keep alive
2715 information being collected as a statistic. This is an optional
2716 argument - default value is false.
2720 =head2 Plugin C<dpdkstat>
2722 The I<dpdkstat plugin> collects information about DPDK interfaces using the
2723 extended NIC stats API in DPDK.
2734 RteDriverLibPath "/usr/lib/dpdk-pmd"
2736 SharedMemObj "dpdk_collectd_stats_0"
2737 EnabledPortMask 0xffff
2738 PortName "interface1"
2739 PortName "interface2"
2744 =head3 The EAL block
2748 =item B<Coremask> I<Mask>
2750 A string containing an hexadecimal bit mask of the cores to run on. Note that
2751 core numbering can change between platforms and should be determined beforehand.
2753 =item B<Memorychannels> I<Channels>
2755 A string containing a number of memory channels per processor socket.
2757 =item B<FilePrefix> I<File>
2759 The prefix text used for hugepage filenames. The filename will be set to
2760 /var/run/.<prefix>_config where prefix is what is passed in by the user.
2762 =item B<SocketMemory> I<MB>
2764 A string containing amount of Memory to allocate from hugepages on specific
2765 sockets in MB. This is an optional value.
2767 =item B<LogLevel> I<LogLevel_number>
2769 A string containing log level number. This parameter is optional.
2770 If parameter is not present then default value "7" - (INFO) is used.
2771 Value "8" - (DEBUG) can be set to enable debug traces.
2773 =item B<RteDriverLibPath> I<Path>
2775 A string containing path to shared pmd driver lib or path to directory,
2776 where shared pmd driver libs are available. This parameter is optional.
2777 This parameter enable loading of shared pmd driver libs from defined path.
2778 E.g.: "/usr/lib/dpdk-pmd/librte_pmd_i40e.so"
2779 or "/usr/lib/dpdk-pmd"
2785 =item B<SharedMemObj> I<Mask>
2787 A string containing the name of the shared memory object that should be used to
2788 share stats from the DPDK secondary process to the collectd dpdkstat plugin.
2789 Defaults to dpdk_collectd_stats if no other value is configured.
2791 =item B<EnabledPortMask> I<Mask>
2793 A hexidecimal bit mask of the DPDK ports which should be enabled. A mask
2794 of 0x0 means that all ports will be disabled. A bitmask of all Fs means
2795 that all ports will be enabled. This is an optional argument - default
2796 is all ports enabled.
2798 =item B<PortName> I<Name>
2800 A string containing an optional name for the enabled DPDK ports. Each PortName
2801 option should contain only one port name; specify as many PortName options as
2802 desired. Default naming convention will be used if PortName is blank. If there
2803 are less PortName options than there are enabled ports, the default naming
2804 convention will be used for the additional ports.
2808 =head2 Plugin C<email>
2812 =item B<SocketFile> I<Path>
2814 Sets the socket-file which is to be created.
2816 =item B<SocketGroup> I<Group>
2818 If running as root change the group of the UNIX-socket after it has been
2819 created. Defaults to B<collectd>.
2821 =item B<SocketPerms> I<Permissions>
2823 Change the file permissions of the UNIX-socket after it has been created. The
2824 permissions must be given as a numeric, octal value as you would pass to
2825 L<chmod(1)>. Defaults to B<0770>.
2827 =item B<MaxConns> I<Number>
2829 Sets the maximum number of connections that can be handled in parallel. Since
2830 this many threads will be started immediately setting this to a very high
2831 value will waste valuable resources. Defaults to B<5> and will be forced to be
2832 at most B<16384> to prevent typos and dumb mistakes.
2836 =head2 Plugin C<ethstat>
2838 The I<ethstat plugin> collects information about network interface cards (NICs)
2839 by talking directly with the underlying kernel driver using L<ioctl(2)>.
2845 Map "rx_csum_offload_errors" "if_rx_errors" "checksum_offload"
2846 Map "multicast" "if_multicast"
2853 =item B<Interface> I<Name>
2855 Collect statistical information about interface I<Name>.
2857 =item B<Map> I<Name> I<Type> [I<TypeInstance>]
2859 By default, the plugin will submit values as type C<derive> and I<type
2860 instance> set to I<Name>, the name of the metric as reported by the driver. If
2861 an appropriate B<Map> option exists, the given I<Type> and, optionally,
2862 I<TypeInstance> will be used.
2864 =item B<MappedOnly> B<true>|B<false>
2866 When set to B<true>, only metrics that can be mapped to a I<type> will be
2867 collected, all other metrics will be ignored. Defaults to B<false>.
2871 =head2 Plugin C<exec>
2873 Please make sure to read L<collectd-exec(5)> before using this plugin. It
2874 contains valuable information on when the executable is executed and the
2875 output that is expected from it.
2879 =item B<Exec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
2881 =item B<NotificationExec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
2883 Execute the executable I<Executable> as user I<User>. If the user name is
2884 followed by a colon and a group name, the effective group is set to that group.
2885 The real group and saved-set group will be set to the default group of that
2886 user. If no group is given the effective group ID will be the same as the real
2889 Please note that in order to change the user and/or group the daemon needs
2890 superuser privileges. If the daemon is run as an unprivileged user you must
2891 specify the same user/group here. If the daemon is run with superuser
2892 privileges, you must supply a non-root user here.
2894 The executable may be followed by optional arguments that are passed to the
2895 program. Please note that due to the configuration parsing numbers and boolean
2896 values may be changed. If you want to be absolutely sure that something is
2897 passed as-is please enclose it in quotes.
2899 The B<Exec> and B<NotificationExec> statements change the semantics of the
2900 programs executed, i.E<nbsp>e. the data passed to them and the response
2901 expected from them. This is documented in great detail in L<collectd-exec(5)>.
2905 =head2 Plugin C<fhcount>
2907 The C<fhcount> plugin provides statistics about used, unused and total number of
2908 file handles on Linux.
2910 The I<fhcount plugin> provides the following configuration options:
2914 =item B<ValuesAbsolute> B<true>|B<false>
2916 Enables or disables reporting of file handles usage in absolute numbers,
2917 e.g. file handles used. Defaults to B<true>.
2919 =item B<ValuesPercentage> B<false>|B<true>
2921 Enables or disables reporting of file handles usage in percentages, e.g.
2922 percent of file handles used. Defaults to B<false>.
2926 =head2 Plugin C<filecount>
2928 The C<filecount> plugin counts the number of files in a certain directory (and
2929 its subdirectories) and their combined size. The configuration is very straight
2932 <Plugin "filecount">
2933 <Directory "/var/qmail/queue/mess">
2934 Instance "qmail-message"
2936 <Directory "/var/qmail/queue/todo">
2937 Instance "qmail-todo"
2939 <Directory "/var/lib/php5">
2940 Instance "php5-sessions"
2945 The example above counts the number of files in QMail's queue directories and
2946 the number of PHP5 sessions. Jfiy: The "todo" queue holds the messages that
2947 QMail has not yet looked at, the "message" queue holds the messages that were
2948 classified into "local" and "remote".
2950 As you can see, the configuration consists of one or more C<Directory> blocks,
2951 each of which specifies a directory in which to count the files. Within those
2952 blocks, the following options are recognized:
2956 =item B<Plugin> I<Plugin>
2958 Use I<Plugin> as the plugin name when submitting values.
2959 Defaults to B<filecount>.
2961 =item B<Instance> I<Instance>
2963 Sets the plugin instance to I<Instance>. If not given, the instance is set to
2964 the directory name with all slashes replaced by underscores and all leading
2965 underscores removed. Empty value is allowed.
2967 =item B<Name> I<Pattern>
2969 Only count files that match I<Pattern>, where I<Pattern> is a shell-like
2970 wildcard as understood by L<fnmatch(3)>. Only the B<filename> is checked
2971 against the pattern, not the entire path. In case this makes it easier for you:
2972 This option has been named after the B<-name> parameter to L<find(1)>.
2974 =item B<MTime> I<Age>
2976 Count only files of a specific age: If I<Age> is greater than zero, only files
2977 that haven't been touched in the last I<Age> seconds are counted. If I<Age> is
2978 a negative number, this is inversed. For example, if B<-60> is specified, only
2979 files that have been modified in the last minute will be counted.
2981 The number can also be followed by a "multiplier" to easily specify a larger
2982 timespan. When given in this notation, the argument must in quoted, i.E<nbsp>e.
2983 must be passed as string. So the B<-60> could also be written as B<"-1m"> (one
2984 minute). Valid multipliers are C<s> (second), C<m> (minute), C<h> (hour), C<d>
2985 (day), C<w> (week), and C<y> (year). There is no "month" multiplier. You can
2986 also specify fractional numbers, e.E<nbsp>g. B<"0.5d"> is identical to
2989 =item B<Size> I<Size>
2991 Count only files of a specific size. When I<Size> is a positive number, only
2992 files that are at least this big are counted. If I<Size> is a negative number,
2993 this is inversed, i.E<nbsp>e. only files smaller than the absolute value of
2994 I<Size> are counted.
2996 As with the B<MTime> option, a "multiplier" may be added. For a detailed
2997 description see above. Valid multipliers here are C<b> (byte), C<k> (kilobyte),
2998 C<m> (megabyte), C<g> (gigabyte), C<t> (terabyte), and C<p> (petabyte). Please
2999 note that there are 1000 bytes in a kilobyte, not 1024.
3001 =item B<Recursive> I<true>|I<false>
3003 Controls whether or not to recurse into subdirectories. Enabled by default.
3005 =item B<IncludeHidden> I<true>|I<false>
3007 Controls whether or not to include "hidden" files and directories in the count.
3008 "Hidden" files and directories are those, whose name begins with a dot.
3009 Defaults to I<false>, i.e. by default hidden files and directories are ignored.
3011 =item B<RegularOnly> I<true>|I<false>
3013 Controls whether or not to include only regular files in the count.
3014 Defaults to I<true>, i.e. by default non regular files are ignored.
3016 =item B<FilesSizeType> I<Type>
3018 Sets the type used to dispatch files combined size. Empty value ("") disables
3019 reporting. Defaults to B<bytes>.
3021 =item B<FilesCountType> I<Type>
3023 Sets the type used to dispatch number of files. Empty value ("") disables
3024 reporting. Defaults to B<files>.
3026 =item B<TypeInstance> I<Instance>
3028 Sets the I<type instance> used to dispatch values. Defaults to an empty string
3029 (no plugin instance).
3033 =head2 Plugin C<GenericJMX>
3035 The I<GenericJMX plugin> is written in I<Java> and therefore documented in
3036 L<collectd-java(5)>.
3038 =head2 Plugin C<gmond>
3040 The I<gmond> plugin received the multicast traffic sent by B<gmond>, the
3041 statistics collection daemon of Ganglia. Mappings for the standard "metrics"
3042 are built-in, custom mappings may be added via B<Metric> blocks, see below.
3047 MCReceiveFrom "239.2.11.71" "8649"
3048 <Metric "swap_total">
3050 TypeInstance "total"
3053 <Metric "swap_free">
3060 The following metrics are built-in:
3066 load_one, load_five, load_fifteen
3070 cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio
3074 mem_free, mem_shared, mem_buffers, mem_cached, mem_total
3086 Available configuration options:
3090 =item B<MCReceiveFrom> I<MCGroup> [I<Port>]
3092 Sets sets the multicast group and UDP port to which to subscribe.
3094 Default: B<239.2.11.71>E<nbsp>/E<nbsp>B<8649>
3096 =item E<lt>B<Metric> I<Name>E<gt>
3098 These blocks add a new metric conversion to the internal table. I<Name>, the
3099 string argument to the B<Metric> block, is the metric name as used by Ganglia.
3103 =item B<Type> I<Type>
3105 Type to map this metric to. Required.
3107 =item B<TypeInstance> I<Instance>
3109 Type-instance to use. Optional.
3111 =item B<DataSource> I<Name>
3113 Data source to map this metric to. If the configured type has exactly one data
3114 source, this is optional. Otherwise the option is required.
3120 =head2 Plugin C<gps>
3122 The C<gps plugin> connects to gpsd on the host machine.
3123 The host, port, timeout and pause are configurable.
3125 This is useful if you run an NTP server using a GPS for source and you want to
3128 Mind your GPS must send $--GSA for having the data reported!
3130 The following elements are collected:
3136 Number of satellites used for fix (type instance "used") and in view (type
3137 instance "visible"). 0 means no GPS satellites are visible.
3139 =item B<dilution_of_precision>
3141 Vertical and horizontal dilution (type instance "horizontal" or "vertical").
3142 It should be between 0 and 3.
3143 Look at the documentation of your GPS to know more.
3151 # Connect to localhost on gpsd regular port:
3156 # PauseConnect of 5 sec. between connection attempts.
3160 Available configuration options:
3164 =item B<Host> I<Host>
3166 The host on which gpsd daemon runs. Defaults to B<localhost>.
3168 =item B<Port> I<Port>
3170 Port to connect to gpsd on the host machine. Defaults to B<2947>.
3172 =item B<Timeout> I<Seconds>
3174 Timeout in seconds (default 0.015 sec).
3176 The GPS data stream is fetch by the plugin form the daemon.
3177 It waits for data to be available, if none arrives it times out
3178 and loop for another reading.
3179 Mind to put a low value gpsd expects value in the micro-seconds area
3180 (recommended is 500 us) since the waiting function is blocking.
3181 Value must be between 500 us and 5 sec., if outside that range the
3182 default value is applied.
3184 This only applies from gpsd release-2.95.
3186 =item B<PauseConnect> I<Seconds>
3188 Pause to apply between attempts of connection to gpsd in seconds (default 5 sec).
3192 =head2 Plugin C<grpc>
3194 The I<grpc> plugin provides an RPC interface to submit values to or query
3195 values from collectd based on the open source gRPC framework. It exposes an
3196 end-point for dispatching values to the daemon.
3198 The B<gRPC> homepage can be found at L<https://grpc.io/>.
3202 =item B<Server> I<Host> I<Port>
3204 The B<Server> statement sets the address of a server to which to send metrics
3205 via the C<DispatchValues> function.
3207 The argument I<Host> may be a hostname, an IPv4 address, or an IPv6 address.
3209 Optionally, B<Server> may be specified as a configuration block which supports
3210 the following options:
3214 =item B<EnableSSL> B<false>|B<true>
3216 Whether to require SSL for outgoing connections. Default: false.
3218 =item B<SSLCACertificateFile> I<Filename>
3220 =item B<SSLCertificateFile> I<Filename>
3222 =item B<SSLCertificateKeyFile> I<Filename>
3224 Filenames specifying SSL certificate and key material to be used with SSL
3229 =item B<Listen> I<Host> I<Port>
3231 The B<Listen> statement sets the network address to bind to. When multiple
3232 statements are specified, the daemon will bind to all of them. If none are
3233 specified, it defaults to B<0.0.0.0:50051>.
3235 The argument I<Host> may be a hostname, an IPv4 address, or an IPv6 address.
3237 Optionally, B<Listen> may be specified as a configuration block which
3238 supports the following options:
3242 =item B<EnableSSL> I<true>|I<false>
3244 Whether to enable SSL for incoming connections. Default: false.
3246 =item B<SSLCACertificateFile> I<Filename>
3248 =item B<SSLCertificateFile> I<Filename>
3250 =item B<SSLCertificateKeyFile> I<Filename>
3252 Filenames specifying SSL certificate and key material to be used with SSL
3255 =item B<VerifyPeer> B<true>|B<false>
3257 When enabled, a valid client certificate is required to connect to the server.
3258 When disabled, a client certifiacte is not requested and any unsolicited client
3259 certificate is accepted.
3266 =head2 Plugin C<hddtemp>
3268 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
3269 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
3270 default values, see below. C<hddtemp> has to be running to work correctly. If
3271 C<hddtemp> is not running timeouts may appear which may interfere with other
3274 The B<hddtemp> homepage can be found at
3275 L<http://www.guzu.net/linux/hddtemp.php>.
3279 =item B<Host> I<Hostname>
3281 Hostname to connect to. Defaults to B<127.0.0.1>.
3283 =item B<Port> I<Port>
3285 TCP-Port to connect to. Defaults to B<7634>.
3289 =head2 Plugin C<hugepages>
3291 To collect B<hugepages> information, collectd reads directories
3292 "/sys/devices/system/node/*/hugepages" and
3293 "/sys/kernel/mm/hugepages".
3294 Reading of these directories can be disabled by the following
3295 options (default is enabled).
3299 =item B<ReportPerNodeHP> B<true>|B<false>
3301 If enabled, information will be collected from the hugepage
3302 counters in "/sys/devices/system/node/*/hugepages".
3303 This is used to check the per-node hugepage statistics on
3306 =item B<ReportRootHP> B<true>|B<false>
3308 If enabled, information will be collected from the hugepage
3309 counters in "/sys/kernel/mm/hugepages".
3310 This can be used on both NUMA and non-NUMA systems to check
3311 the overall hugepage statistics.
3313 =item B<ValuesPages> B<true>|B<false>
3315 Whether to report hugepages metrics in number of pages.
3316 Defaults to B<true>.
3318 =item B<ValuesBytes> B<false>|B<true>
3320 Whether to report hugepages metrics in bytes.
3321 Defaults to B<false>.
3323 =item B<ValuesPercentage> B<false>|B<true>
3325 Whether to report hugepages metrics as percentage.
3326 Defaults to B<false>.
3330 =head2 Plugin C<intel_pmu>
3332 The I<intel_pmu> plugin collects performance counters data on Intel CPUs using
3333 Linux perf interface. All events are reported on a per core basis.
3338 ReportHardwareCacheEvents true
3339 ReportKernelPMUEvents true
3340 ReportSoftwareEvents true
3341 EventList "/var/cache/pmu/GenuineIntel-6-2D-core.json"
3342 HardwareEvents "L2_RQSTS.CODE_RD_HIT,L2_RQSTS.CODE_RD_MISS" "L2_RQSTS.ALL_CODE_RD"
3349 =item B<ReportHardwareCacheEvents> B<false>|B<true>
3351 Enable or disable measuring of hardware CPU cache events:
3353 - L1-dcache-load-misses
3355 - L1-dcache-store-misses
3356 - L1-dcache-prefetches
3357 - L1-dcache-prefetch-misses
3359 - L1-icache-load-misses
3360 - L1-icache-prefetches
3361 - L1-icache-prefetch-misses
3367 - LLC-prefetch-misses
3373 - dTLB-prefetch-misses
3377 - branch-load-misses
3379 =item B<ReportKernelPMUEvents> B<false>|B<true>
3381 Enable or disable measuring of the following events:
3390 =item B<ReportSoftwareEvents> B<false>|B<true>
3392 Enable or disable measuring of software events provided by kernel:
3403 =item B<EventList> I<filename>
3405 JSON performance counter event list file name. To be able to monitor all Intel
3406 CPU specific events JSON event list file should be downloaded. Use the pmu-tools
3407 event_download.py script to download event list for current CPU.
3409 =item B<HardwareEvents> I<events>
3411 This field is a list of event names or groups of comma separated event names.
3412 This option requires B<EventList> option to be configured.
3416 =head2 Plugin C<intel_rdt>
3418 The I<intel_rdt> plugin collects information provided by monitoring features of
3419 Intel Resource Director Technology (Intel(R) RDT) like Cache Monitoring
3420 Technology (CMT), Memory Bandwidth Monitoring (MBM). These features provide
3421 information about utilization of shared resources. CMT monitors last level cache
3422 occupancy (LLC). MBM supports two types of events reporting local and remote
3423 memory bandwidth. Local memory bandwidth (MBL) reports the bandwidth of
3424 accessing memory associated with the local socket. Remote memory bandwidth (MBR)
3425 reports the bandwidth of accessing the remote socket. Also this technology
3426 allows to monitor instructions per clock (IPC).
3427 Monitor events are hardware dependant. Monitoring capabilities are detected on
3428 plugin initialization and only supported events are monitored.
3430 B<Note:> I<intel_rdt> plugin is using model-specific registers (MSRs), which
3431 require an additional capability to be enabled if collectd is run as a service.
3432 Please refer to I<contrib/systemd.collectd.service> file for more details.
3436 <Plugin "intel_rdt">
3437 Cores "0-2" "3,4,6" "8-10,15"
3444 =item B<Interval> I<seconds>
3446 The interval within which to retrieve statistics on monitored events in seconds.
3447 For milliseconds divide the time by 1000 for example if the desired interval
3448 is 50ms, set interval to 0.05. Due to limited capacity of counters it is not
3449 recommended to set interval higher than 1 sec.
3451 =item B<Cores> I<cores groups>
3453 All events are reported on a per core basis. Monitoring of the events can be
3454 configured for group of cores (aggregated statistics). This field defines groups
3455 of cores on which to monitor supported events. The field is represented as list
3456 of strings with core group values. Each string represents a list of cores in a
3457 group. Allowed formats are:
3462 If an empty string is provided as value for this field default cores
3463 configuration is applied - a separate group is created for each core.
3467 B<Note:> By default global interval is used to retrieve statistics on monitored
3468 events. To configure a plugin specific interval use B<Interval> option of the
3469 intel_rdt <LoadPlugin> block. For milliseconds divide the time by 1000 for
3470 example if the desired interval is 50ms, set interval to 0.05.
3471 Due to limited capacity of counters it is not recommended to set interval higher
3474 =head2 Plugin C<interface>
3478 =item B<Interface> I<Interface>
3480 Select this interface. By default these interfaces will then be collected. For
3481 a more detailed description see B<IgnoreSelected> below.
3483 See F</"IGNORELISTS"> for details.
3485 =item B<IgnoreSelected> I<true>|I<false>
3487 If no configuration is given, the B<interface>-plugin will collect data from
3488 all interfaces. This may not be practical, especially for loopback- and
3489 similar interfaces. Thus, you can use the B<Interface>-option to pick the
3490 interfaces you're interested in. Sometimes, however, it's easier/preferred
3491 to collect all interfaces I<except> a few ones. This option enables you to
3492 do that: By setting B<IgnoreSelected> to I<true> the effect of
3493 B<Interface> is inverted: All selected interfaces are ignored and all
3494 other interfaces are collected.
3496 It is possible to use regular expressions to match interface names, if the
3497 name is surrounded by I</.../> and collectd was compiled with support for
3498 regexps. This is useful if there's a need to collect (or ignore) data
3499 for a group of interfaces that are similarly named, without the need to
3500 explicitly list all of them (especially useful if the list is dynamic).
3505 Interface "/^tun[0-9]+/"
3506 IgnoreSelected "true"
3508 This will ignore the loopback interface, all interfaces with names starting
3509 with I<veth> and all interfaces with names starting with I<tun> followed by
3512 =item B<ReportInactive> I<true>|I<false>
3514 When set to I<false>, only interfaces with non-zero traffic will be
3515 reported. Note that the check is done by looking into whether a
3516 package was sent at any time from boot and the corresponding counter
3517 is non-zero. So, if the interface has been sending data in the past
3518 since boot, but not during the reported time-interval, it will still
3521 The default value is I<true> and results in collection of the data
3522 from all interfaces that are selected by B<Interface> and
3523 B<IgnoreSelected> options.
3525 =item B<UniqueName> I<true>|I<false>
3527 Interface name is not unique on Solaris (KSTAT), interface name is unique
3528 only within a module/instance. Following tuple is considered unique:
3529 (ks_module, ks_instance, ks_name)
3530 If this option is set to true, interface name contains above three fields
3531 separated by an underscore. For more info on KSTAT, visit
3532 L<http://docs.oracle.com/cd/E23824_01/html/821-1468/kstat-3kstat.html#REFMAN3Ekstat-3kstat>
3534 This option is only available on Solaris.
3538 =head2 Plugin C<ipmi>
3540 The B<ipmi plugin> allows to monitor server platform status using the Intelligent
3541 Platform Management Interface (IPMI). Local and remote interfaces are supported.
3543 The plugin configuration consists of one or more B<Instance> blocks which
3544 specify one I<ipmi> connection each. Each block requires one unique string
3545 argument as the instance name. If instances are not configured, an instance with
3546 the default option values will be created.
3548 For backwards compatibility, any option other than B<Instance> block will trigger
3549 legacy config handling and it will be treated as an option within B<Instance>
3550 block. This support will go away in the next major version of Collectd.
3552 Within the B<Instance> blocks, the following options are allowed:
3556 =item B<Address> I<Address>
3558 Hostname or IP to connect to. If not specified, plugin will try to connect to
3559 local management controller (BMC).
3561 =item B<Username> I<Username>
3563 =item B<Password> I<Password>
3565 The username and the password to use for the connection to remote BMC.
3567 =item B<AuthType> I<MD5>|I<rmcp+>
3569 Forces the authentication type to use for the connection to remote BMC.
3570 By default most secure type is seleted.
3572 =item B<Host> I<Hostname>
3574 Sets the B<host> field of dispatched values. Defaults to the global hostname
3577 =item B<Sensor> I<Sensor>
3579 Selects sensors to collect or to ignore, depending on B<IgnoreSelected>.
3581 See F</"IGNORELISTS"> for details.
3583 =item B<IgnoreSelected> I<true>|I<false>
3585 If no configuration if given, the B<ipmi> plugin will collect data from all
3586 sensors found of type "temperature", "voltage", "current" and "fanspeed".
3587 This option enables you to do that: By setting B<IgnoreSelected> to I<true>
3588 the effect of B<Sensor> is inverted: All selected sensors are ignored and
3589 all other sensors are collected.
3591 =item B<NotifySensorAdd> I<true>|I<false>
3593 If a sensor appears after initialization time of a minute a notification
3596 =item B<NotifySensorRemove> I<true>|I<false>
3598 If a sensor disappears a notification is sent.
3600 =item B<NotifySensorNotPresent> I<true>|I<false>
3602 If you have for example dual power supply and one of them is (un)plugged then
3603 a notification is sent.
3605 =item B<NotifyIPMIConnectionState> I<true>|I<false>
3607 If a IPMI connection state changes after initialization time of a minute
3608 a notification is sent. Defaults to B<false>.
3610 =item B<SELEnabled> I<true>|I<false>
3612 If system event log (SEL) is enabled, plugin will listen for sensor threshold
3613 and discrete events. When event is received the notification is sent.
3614 Defaults to B<false>.
3616 =item B<SELClearEvent> I<true>|I<false>
3618 If SEL clear event is enabled, plugin will delete event from SEL list after
3619 it is received and successfully handled. In this case other tools that are
3620 subscribed for SEL events will receive an empty event.
3621 Defaults to B<false>.
3625 =head2 Plugin C<iptables>
3629 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
3631 =item B<Chain6> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
3633 Select the iptables/ip6tables filter rules to count packets and bytes from.
3635 If only I<Table> and I<Chain> are given, this plugin will collect the counters
3636 of all rules which have a comment-match. The comment is then used as
3639 If I<Comment> or I<Number> is given, only the rule with the matching comment or
3640 the I<n>th rule will be collected. Again, the comment (or the number) will be
3641 used as the type-instance.
3643 If I<Name> is supplied, it will be used as the type-instance instead of the
3644 comment or the number.
3648 =head2 Plugin C<irq>
3654 Select this irq. By default these irqs will then be collected. For a more
3655 detailed description see B<IgnoreSelected> below.
3657 See F</"IGNORELISTS"> for details.
3659 =item B<IgnoreSelected> I<true>|I<false>
3661 If no configuration if given, the B<irq>-plugin will collect data from all
3662 irqs. This may not be practical, especially if no interrupts happen. Thus, you
3663 can use the B<Irq>-option to pick the interrupt you're interested in.
3664 Sometimes, however, it's easier/preferred to collect all interrupts I<except> a
3665 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
3666 I<true> the effect of B<Irq> is inverted: All selected interrupts are ignored
3667 and all other interrupts are collected.
3671 =head2 Plugin C<java>
3673 The I<Java> plugin makes it possible to write extensions for collectd in Java.
3674 This section only discusses the syntax and semantic of the configuration
3675 options. For more in-depth information on the I<Java> plugin, please read
3676 L<collectd-java(5)>.
3681 JVMArg "-verbose:jni"
3682 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
3683 LoadPlugin "org.collectd.java.Foobar"
3684 <Plugin "org.collectd.java.Foobar">
3685 # To be parsed by the plugin
3689 Available configuration options:
3693 =item B<JVMArg> I<Argument>
3695 Argument that is to be passed to the I<Java Virtual Machine> (JVM). This works
3696 exactly the way the arguments to the I<java> binary on the command line work.
3697 Execute C<javaE<nbsp>--help> for details.
3699 Please note that B<all> these options must appear B<before> (i.E<nbsp>e. above)
3700 any other options! When another option is found, the JVM will be started and
3701 later options will have to be ignored!
3703 =item B<LoadPlugin> I<JavaClass>
3705 Instantiates a new I<JavaClass> object. The constructor of this object very
3706 likely then registers one or more callback methods with the server.
3708 See L<collectd-java(5)> for details.
3710 When the first such option is found, the virtual machine (JVM) is created. This
3711 means that all B<JVMArg> options must appear before (i.E<nbsp>e. above) all
3712 B<LoadPlugin> options!
3714 =item B<Plugin> I<Name>
3716 The entire block is passed to the Java plugin as an
3717 I<org.collectd.api.OConfigItem> object.
3719 For this to work, the plugin has to register a configuration callback first,
3720 see L<collectd-java(5)/"config callback">. This means, that the B<Plugin> block
3721 must appear after the appropriate B<LoadPlugin> block. Also note, that I<Name>
3722 depends on the (Java) plugin registering the callback and is completely
3723 independent from the I<JavaClass> argument passed to B<LoadPlugin>.
3727 =head2 Plugin C<load>
3729 The I<Load plugin> collects the system load. These numbers give a rough overview
3730 over the utilization of a machine. The system load is defined as the number of
3731 runnable tasks in the run-queue and is provided by many operating systems as a
3732 one, five or fifteen minute average.
3734 The following configuration options are available:
3738 =item B<ReportRelative> B<false>|B<true>
3740 When enabled, system load divided by number of available CPU cores is reported
3741 for intervals 1 min, 5 min and 15 min. Defaults to false.
3746 =head2 Plugin C<logfile>
3750 =item B<LogLevel> B<debug|info|notice|warning|err>
3752 Sets the log-level. If, for example, set to B<notice>, then all events with
3753 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
3755 Please note that B<debug> is only available if collectd has been compiled with
3758 =item B<File> I<File>
3760 Sets the file to write log messages to. The special strings B<stdout> and
3761 B<stderr> can be used to write to the standard output and standard error
3762 channels, respectively. This, of course, only makes much sense when I<collectd>
3763 is running in foreground- or non-daemon-mode.
3765 =item B<Timestamp> B<true>|B<false>
3767 Prefix all lines printed by the current time. Defaults to B<true>.
3769 =item B<PrintSeverity> B<true>|B<false>
3771 When enabled, all lines are prefixed by the severity of the log message, for
3772 example "warning". Defaults to B<false>.
3776 B<Note>: There is no need to notify the daemon after moving or removing the
3777 log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
3778 for each line it writes.
3780 =head2 Plugin C<log_logstash>
3782 The I<log logstash plugin> behaves like the logfile plugin but formats
3783 messages as JSON events for logstash to parse and input.
3787 =item B<LogLevel> B<debug|info|notice|warning|err>
3789 Sets the log-level. If, for example, set to B<notice>, then all events with
3790 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
3792 Please note that B<debug> is only available if collectd has been compiled with
3795 =item B<File> I<File>
3797 Sets the file to write log messages to. The special strings B<stdout> and
3798 B<stderr> can be used to write to the standard output and standard error
3799 channels, respectively. This, of course, only makes much sense when I<collectd>
3800 is running in foreground- or non-daemon-mode.
3804 B<Note>: There is no need to notify the daemon after moving or removing the
3805 log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
3806 for each line it writes.
3808 =head2 Plugin C<lpar>
3810 The I<LPAR plugin> reads CPU statistics of I<Logical Partitions>, a
3811 virtualization technique for IBM POWER processors. It takes into account CPU
3812 time stolen from or donated to a partition, in addition to the usual user,
3813 system, I/O statistics.
3815 The following configuration options are available:
3819 =item B<CpuPoolStats> B<false>|B<true>
3821 When enabled, statistics about the processor pool are read, too. The partition
3822 needs to have pool authority in order to be able to acquire this information.
3825 =item B<ReportBySerial> B<false>|B<true>
3827 If enabled, the serial of the physical machine the partition is currently
3828 running on is reported as I<hostname> and the logical hostname of the machine
3829 is reported in the I<plugin instance>. Otherwise, the logical hostname will be
3830 used (just like other plugins) and the I<plugin instance> will be empty.
3835 =head2 Plugin C<lua>
3837 This plugin embeds a Lua interpreter into collectd and provides an interface
3838 to collectd's plugin system. See L<collectd-lua(5)> for its documentation.
3841 =head2 Plugin C<mbmon>
3843 The C<mbmon plugin> uses mbmon to retrieve temperature, voltage, etc.
3845 Be default collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>. The
3846 B<Host> and B<Port> options can be used to change these values, see below.
3847 C<mbmon> has to be running to work correctly. If C<mbmon> is not running
3848 timeouts may appear which may interfere with other statistics..
3850 C<mbmon> must be run with the -r option ("print TAG and Value format");
3851 Debian's F</etc/init.d/mbmon> script already does this, other people
3852 will need to ensure that this is the case.
3856 =item B<Host> I<Hostname>
3858 Hostname to connect to. Defaults to B<127.0.0.1>.
3860 =item B<Port> I<Port>
3862 TCP-Port to connect to. Defaults to B<411>.
3866 =head2 Plugin C<mcelog>
3868 The C<mcelog plugin> uses mcelog to retrieve machine check exceptions.
3870 By default the plugin connects to B<"/var/run/mcelog-client"> to check if the
3871 mcelog server is running. When the server is running, the plugin will tail the
3872 specified logfile to retrieve machine check exception information and send a
3873 notification with the details from the logfile. The plugin will use the mcelog
3874 client protocol to retrieve memory related machine check exceptions. Note that
3875 for memory exceptions, notifications are only sent when there is a change in
3876 the number of corrected/uncorrected memory errors.
3878 =head3 The Memory block
3880 Note: these options cannot be used in conjunction with the logfile options, they are mutually
3885 =item B<McelogClientSocket> I<Path>
3886 Connect to the mcelog client socket using the UNIX domain socket at I<Path>.
3887 Defaults to B<"/var/run/mcelog-client">.
3889 =item B<PersistentNotification> B<true>|B<false>
3890 Override default configuration to only send notifications when sent when there
3891 is a change in the number of corrected/uncorrected memory errors. When set to
3892 true notifications will be sent for every read cycle. Default is false. Does
3893 not affect the stats being dispatched.
3899 =item B<McelogLogfile> I<Path>
3901 The mcelog file to parse. Defaults to B<"/var/log/mcelog">. Note: this option
3902 cannot be used in conjunction with the memory block options, they are mutually
3909 The C<md plugin> collects information from Linux Software-RAID devices (md).
3911 All reported values are of the type C<md_disks>. Reported type instances are
3912 I<active>, I<failed> (present but not operational), I<spare> (hot stand-by) and
3913 I<missing> (physically absent) disks.
3917 =item B<Device> I<Device>
3919 Select md devices based on device name. The I<device name> is the basename of
3920 the device, i.e. the name of the block device without the leading C</dev/>.
3921 See B<IgnoreSelected> for more details.
3923 See F</"IGNORELISTS"> for details.
3925 =item B<IgnoreSelected> B<true>|B<false>
3927 Invert device selection: If set to B<true>, all md devices B<except> those
3928 listed using B<Device> are collected. If B<false> (the default), only those
3929 listed are collected. If no configuration is given, the B<md> plugin will
3930 collect data from all md devices.
3934 =head2 Plugin C<memcachec>
3936 The C<memcachec plugin> connects to a memcached server, queries one or more
3937 given I<pages> and parses the returned data according to user specification.
3938 The I<matches> used are the same as the matches used in the C<curl> and C<tail>
3941 In order to talk to the memcached server, this plugin uses the I<libmemcached>
3942 library. Please note that there is another library with a very similar name,
3943 libmemcache (notice the missing `d'), which is not applicable.
3945 Synopsis of the configuration:
3947 <Plugin "memcachec">
3948 <Page "plugin_instance">
3951 Plugin "plugin_name"
3953 Regex "(\\d+) bytes sent"
3956 Instance "type_instance"
3961 The configuration options are:
3965 =item E<lt>B<Page> I<Name>E<gt>
3967 Each B<Page> block defines one I<page> to be queried from the memcached server.
3968 The block requires one string argument which is used as I<plugin instance>.
3970 =item B<Server> I<Address>
3972 Sets the server address to connect to when querying the page. Must be inside a
3977 When connected to the memcached server, asks for the page I<Key>.
3979 =item B<Plugin> I<Plugin>
3981 Use I<Plugin> as the plugin name when submitting values.
3982 Defaults to C<memcachec>.
3984 =item E<lt>B<Match>E<gt>
3986 Match blocks define which strings to look for and how matches substrings are
3987 interpreted. For a description of match blocks, please see L<"Plugin tail">.
3991 =head2 Plugin C<memcached>
3993 The B<memcached plugin> connects to a memcached server and queries statistics
3994 about cache utilization, memory and bandwidth used.
3995 L<http://memcached.org/>
3997 <Plugin "memcached">
3999 #Host "memcache.example.com"
4005 The plugin configuration consists of one or more B<Instance> blocks which
4006 specify one I<memcached> connection each. Within the B<Instance> blocks, the
4007 following options are allowed:
4011 =item B<Host> I<Hostname>
4013 Sets the B<host> field of dispatched values. Defaults to the global hostname
4015 For backwards compatibility, values are also dispatched with the global
4016 hostname when B<Host> is set to B<127.0.0.1> or B<localhost> and B<Address> is
4019 =item B<Address> I<Address>
4021 Hostname or IP to connect to. For backwards compatibility, defaults to the
4022 value of B<Host> or B<127.0.0.1> if B<Host> is unset.
4024 =item B<Port> I<Port>
4026 TCP port to connect to. Defaults to B<11211>.
4028 =item B<Socket> I<Path>
4030 Connect to I<memcached> using the UNIX domain socket at I<Path>. If this
4031 setting is given, the B<Address> and B<Port> settings are ignored.
4035 =head2 Plugin C<mic>
4037 The B<mic plugin> gathers CPU statistics, memory usage and temperatures from
4038 Intel's Many Integrated Core (MIC) systems.
4047 ShowTemperatures true
4050 IgnoreSelectedTemperature true
4055 IgnoreSelectedPower true
4058 The following options are valid inside the B<PluginE<nbsp>mic> block:
4062 =item B<ShowCPU> B<true>|B<false>
4064 If enabled (the default) a sum of the CPU usage across all cores is reported.
4066 =item B<ShowCPUCores> B<true>|B<false>
4068 If enabled (the default) per-core CPU usage is reported.
4070 =item B<ShowMemory> B<true>|B<false>
4072 If enabled (the default) the physical memory usage of the MIC system is
4075 =item B<ShowTemperatures> B<true>|B<false>
4077 If enabled (the default) various temperatures of the MIC system are reported.
4079 =item B<Temperature> I<Name>
4081 This option controls which temperatures are being reported. Whether matching
4082 temperatures are being ignored or I<only> matching temperatures are reported
4083 depends on the B<IgnoreSelectedTemperature> setting below. By default I<all>
4084 temperatures are reported.
4086 =item B<IgnoreSelectedTemperature> B<false>|B<true>
4088 Controls the behavior of the B<Temperature> setting above. If set to B<false>
4089 (the default) only temperatures matching a B<Temperature> option are reported
4090 or, if no B<Temperature> option is specified, all temperatures are reported. If
4091 set to B<true>, matching temperatures are I<ignored> and all other temperatures
4094 Known temperature names are:
4128 =item B<ShowPower> B<true>|B<false>
4130 If enabled (the default) various temperatures of the MIC system are reported.
4132 =item B<Power> I<Name>
4134 This option controls which power readings are being reported. Whether matching
4135 power readings are being ignored or I<only> matching power readings are reported
4136 depends on the B<IgnoreSelectedPower> setting below. By default I<all>
4137 power readings are reported.
4139 =item B<IgnoreSelectedPower> B<false>|B<true>
4141 Controls the behavior of the B<Power> setting above. If set to B<false>
4142 (the default) only power readings matching a B<Power> option are reported
4143 or, if no B<Power> option is specified, all power readings are reported. If
4144 set to B<true>, matching power readings are I<ignored> and all other power readings
4147 Known power names are:
4153 Total power utilization averaged over Time Window 0 (uWatts).
4157 Total power utilization averaged over Time Window 0 (uWatts).
4161 Instantaneous power (uWatts).
4165 Max instantaneous power (uWatts).
4169 PCI-E connector power (uWatts).
4173 2x3 connector power (uWatts).
4177 2x4 connector power (uWatts).
4185 Uncore rail (uVolts).
4189 Memory subsystem rail (uVolts).
4195 =head2 Plugin C<memory>
4197 The I<memory plugin> provides the following configuration options:
4201 =item B<ValuesAbsolute> B<true>|B<false>
4203 Enables or disables reporting of physical memory usage in absolute numbers,
4204 i.e. bytes. Defaults to B<true>.
4206 =item B<ValuesPercentage> B<false>|B<true>
4208 Enables or disables reporting of physical memory usage in percentages, e.g.
4209 percent of physical memory used. Defaults to B<false>.
4211 This is useful for deploying I<collectd> in a heterogeneous environment in
4212 which the sizes of physical memory vary.
4216 =head2 Plugin C<modbus>
4218 The B<modbus plugin> connects to a Modbus "slave" via Modbus/TCP or Modbus/RTU and
4219 reads register values. It supports reading single registers (unsigned 16E<nbsp>bit
4220 values), large integer values (unsigned 32E<nbsp>bit values) and floating point
4221 values (two registers interpreted as IEEE floats in big endian notation).
4225 <Data "voltage-input-1">
4228 RegisterCmd ReadHolding
4233 <Data "voltage-input-2">
4236 RegisterCmd ReadHolding
4241 <Data "supply-temperature-1">
4244 RegisterCmd ReadHolding
4249 <Host "modbus.example.com">
4250 Address "192.168.0.42"
4255 Instance "power-supply"
4256 Collect "voltage-input-1"
4257 Collect "voltage-input-2"
4262 Device "/dev/ttyUSB0"
4267 Instance "temperature"
4268 Collect "supply-temperature-1"
4274 =item E<lt>B<Data> I<Name>E<gt> blocks
4276 Data blocks define a mapping between register numbers and the "types" used by
4279 Within E<lt>DataE<nbsp>/E<gt> blocks, the following options are allowed:
4283 =item B<RegisterBase> I<Number>
4285 Configures the base register to read from the device. If the option
4286 B<RegisterType> has been set to B<Uint32> or B<Float>, this and the next
4287 register will be read (the register number is increased by one).
4289 =item B<RegisterType> B<Int16>|B<Int32>|B<Uint16>|B<Uint32>|B<Float>
4291 Specifies what kind of data is returned by the device. If the type is B<Int32>,
4292 B<Uint32> or B<Float>, two 16E<nbsp>bit registers will be read and the data is
4293 combined into one value. Defaults to B<Uint16>.
4295 =item B<RegisterCmd> B<ReadHolding>|B<ReadInput>
4297 Specifies register type to be collected from device. Works only with libmodbus
4298 2.9.2 or higher. Defaults to B<ReadHolding>.
4300 =item B<Type> I<Type>
4302 Specifies the "type" (data set) to use when dispatching the value to
4303 I<collectd>. Currently, only data sets with exactly one data source are
4306 =item B<Instance> I<Instance>
4308 Sets the type instance to use when dispatching the value to I<collectd>. If
4309 unset, an empty string (no type instance) is used.
4313 =item E<lt>B<Host> I<Name>E<gt> blocks
4315 Host blocks are used to specify to which hosts to connect and what data to read
4316 from their "slaves". The string argument I<Name> is used as hostname when
4317 dispatching the values to I<collectd>.
4319 Within E<lt>HostE<nbsp>/E<gt> blocks, the following options are allowed:
4323 =item B<Address> I<Hostname>
4325 For Modbus/TCP, specifies the node name (the actual network address) used to
4326 connect to the host. This may be an IP address or a hostname. Please note that
4327 the used I<libmodbus> library only supports IPv4 at the moment.
4329 =item B<Port> I<Service>
4331 for Modbus/TCP, specifies the port used to connect to the host. The port can
4332 either be given as a number or as a service name. Please note that the
4333 I<Service> argument must be a string, even if ports are given in their numerical
4334 form. Defaults to "502".
4336 =item B<Device> I<Devicenode>
4338 For Modbus/RTU, specifies the path to the serial device being used.
4340 =item B<Baudrate> I<Baudrate>
4342 For Modbus/RTU, specifies the baud rate of the serial device.
4343 Note, connections currently support only 8/N/1.
4345 =item B<Interval> I<Interval>
4347 Sets the interval (in seconds) in which the values will be collected from this
4348 host. By default the global B<Interval> setting will be used.
4350 =item E<lt>B<Slave> I<ID>E<gt>
4352 Over each connection, multiple Modbus devices may be reached. The slave ID
4353 is used to specify which device should be addressed. For each device you want
4354 to query, one B<Slave> block must be given.
4356 Within E<lt>SlaveE<nbsp>/E<gt> blocks, the following options are allowed:
4360 =item B<Instance> I<Instance>
4362 Specify the plugin instance to use when dispatching the values to I<collectd>.
4363 By default "slave_I<ID>" is used.
4365 =item B<Collect> I<DataName>
4367 Specifies which data to retrieve from the device. I<DataName> must be the same
4368 string as the I<Name> argument passed to a B<Data> block. You can specify this
4369 option multiple times to collect more than one value from a slave. At least one
4370 B<Collect> option is mandatory.
4378 =head2 Plugin C<mqtt>
4380 The I<MQTT plugin> can send metrics to MQTT (B<Publish> blocks) and receive
4381 values from MQTT (B<Subscribe> blocks).
4387 Host "mqtt.example.com"
4391 Host "mqtt.example.com"
4396 The plugin's configuration is in B<Publish> and/or B<Subscribe> blocks,
4397 configuring the sending and receiving direction respectively. The plugin will
4398 register a write callback named C<mqtt/I<name>> where I<name> is the string
4399 argument given to the B<Publish> block. Both types of blocks share many but not
4400 all of the following options. If an option is valid in only one of the blocks,
4401 it will be mentioned explicitly.
4407 =item B<Host> I<Hostname>
4409 Hostname of the MQTT broker to connect to.
4411 =item B<Port> I<Service>
4413 Port number or service name of the MQTT broker to connect to.
4415 =item B<User> I<UserName>
4417 Username used when authenticating to the MQTT broker.
4419 =item B<Password> I<Password>
4421 Password used when authenticating to the MQTT broker.
4423 =item B<ClientId> I<ClientId>
4425 MQTT client ID to use. Defaults to the hostname used by I<collectd>.
4427 =item B<QoS> [B<0>-B<2>]
4429 Sets the I<Quality of Service>, with the values C<0>, C<1> and C<2> meaning:
4447 In B<Publish> blocks, this option determines the QoS flag set on outgoing
4448 messages and defaults to B<0>. In B<Subscribe> blocks, determines the maximum
4449 QoS setting the client is going to accept and defaults to B<2>. If the QoS flag
4450 on a message is larger than the maximum accepted QoS of a subscriber, the
4451 message's QoS will be downgraded.
4453 =item B<Prefix> I<Prefix> (Publish only)
4455 This plugin will use one topic per I<value list> which will looks like a path.
4456 I<Prefix> is used as the first path element and defaults to B<collectd>.
4458 An example topic name would be:
4460 collectd/cpu-0/cpu-user
4462 =item B<Retain> B<false>|B<true> (Publish only)
4464 Controls whether the MQTT broker will retain (keep a copy of) the last message
4465 sent to each topic and deliver it to new subscribers. Defaults to B<false>.
4467 =item B<StoreRates> B<true>|B<false> (Publish only)
4469 Controls whether C<DERIVE> and C<COUNTER> metrics are converted to a I<rate>
4470 before sending. Defaults to B<true>.
4472 =item B<CleanSession> B<true>|B<false> (Subscribe only)
4474 Controls whether the MQTT "cleans" the session up after the subscriber
4475 disconnects or if it maintains the subscriber's subscriptions and all messages
4476 that arrive while the subscriber is disconnected. Defaults to B<true>.
4478 =item B<Topic> I<TopicName> (Subscribe only)
4480 Configures the topic(s) to subscribe to. You can use the single level C<+> and
4481 multi level C<#> wildcards. Defaults to B<collectd/#>, i.e. all topics beneath
4482 the B<collectd> branch.
4484 =item B<CACert> I<file>
4486 Path to the PEM-encoded CA certificate file. Setting this option enables TLS
4487 communication with the MQTT broker, and as such, B<Port> should be the TLS-enabled
4488 port of the MQTT broker.
4489 This option enables the use of TLS.
4491 =item B<CertificateFile> I<file>
4493 Path to the PEM-encoded certificate file to use as client certificate when
4494 connecting to the MQTT broker.
4495 Only valid if B<CACert> and B<CertificateKeyFile> are also set.
4497 =item B<CertificateKeyFile> I<file>
4499 Path to the unencrypted PEM-encoded key file corresponding to B<CertificateFile>.
4500 Only valid if B<CACert> and B<CertificateFile> are also set.
4502 =item B<TLSProtocol> I<protocol>
4504 If configured, this specifies the string protocol version (e.g. C<tlsv1>,
4505 C<tlsv1.2>) to use for the TLS connection to the broker. If not set a default
4506 version is used which depends on the version of OpenSSL the Mosquitto library
4508 Only valid if B<CACert> is set.
4510 =item B<CipherSuite> I<ciphersuite>
4512 A string describing the ciphers available for use. See L<ciphers(1)> and the
4513 C<openssl ciphers> utility for more information. If unset, the default ciphers
4515 Only valid if B<CACert> is set.
4519 =head2 Plugin C<mysql>
4521 The C<mysql plugin> requires B<mysqlclient> to be installed. It connects to
4522 one or more databases when started and keeps the connection up as long as
4523 possible. When the connection is interrupted for whatever reason it will try
4524 to re-connect. The plugin will complain loudly in case anything goes wrong.
4526 This plugin issues the MySQL C<SHOW STATUS> / C<SHOW GLOBAL STATUS> command
4527 and collects information about MySQL network traffic, executed statements,
4528 requests, the query cache and threads by evaluating the
4529 C<Bytes_{received,sent}>, C<Com_*>, C<Handler_*>, C<Qcache_*> and C<Threads_*>
4530 return values. Please refer to the B<MySQL reference manual>, I<5.1.6. Server
4531 Status Variables> for an explanation of these values.
4533 Optionally, master and slave statistics may be collected in a MySQL
4534 replication setup. In that case, information about the synchronization state
4535 of the nodes are collected by evaluating the C<Position> return value of the
4536 C<SHOW MASTER STATUS> command and the C<Seconds_Behind_Master>,
4537 C<Read_Master_Log_Pos> and C<Exec_Master_Log_Pos> return values of the
4538 C<SHOW SLAVE STATUS> command. See the B<MySQL reference manual>,
4539 I<12.5.5.21 SHOW MASTER STATUS Syntax> and
4540 I<12.5.5.31 SHOW SLAVE STATUS Syntax> for details.
4552 SSLKey "/path/to/key.pem"
4553 SSLCert "/path/to/cert.pem"
4554 SSLCA "/path/to/ca.pem"
4555 SSLCAPath "/path/to/cas/"
4556 SSLCipher "DHE-RSA-AES256-SHA"
4562 Socket "/var/run/mysql/mysqld.sock"
4564 SlaveNotifications true
4570 Socket "/var/run/mysql/mysqld.sock"
4575 A B<Database> block defines one connection to a MySQL database. It accepts a
4576 single argument which specifies the name of the database. None of the other
4577 options are required. MySQL will use default values as documented in the
4578 "mysql_real_connect()" and "mysql_ssl_set()" sections in the
4579 B<MySQL reference manual>.
4583 =item B<Alias> I<Alias>
4585 Alias to use as sender instead of hostname when reporting. This may be useful
4586 when having cryptic hostnames.
4588 =item B<Host> I<Hostname>
4590 Hostname of the database server. Defaults to B<localhost>.
4592 =item B<User> I<Username>
4594 Username to use when connecting to the database. The user does not have to be
4595 granted any privileges (which is synonym to granting the C<USAGE> privilege),
4596 unless you want to collectd replication statistics (see B<MasterStats> and
4597 B<SlaveStats> below). In this case, the user needs the C<REPLICATION CLIENT>
4598 (or C<SUPER>) privileges. Else, any existing MySQL user will do.
4600 =item B<Password> I<Password>
4602 Password needed to log into the database.
4604 =item B<Database> I<Database>
4606 Select this database. Defaults to I<no database> which is a perfectly reasonable
4607 option for what this plugin does.
4609 =item B<Port> I<Port>
4611 TCP-port to connect to. The port must be specified in its numeric form, but it
4612 must be passed as a string nonetheless. For example:
4616 If B<Host> is set to B<localhost> (the default), this setting has no effect.
4617 See the documentation for the C<mysql_real_connect> function for details.
4619 =item B<Socket> I<Socket>
4621 Specifies the path to the UNIX domain socket of the MySQL server. This option
4622 only has any effect, if B<Host> is set to B<localhost> (the default).
4623 Otherwise, use the B<Port> option above. See the documentation for the
4624 C<mysql_real_connect> function for details.
4626 =item B<InnodbStats> I<true|false>
4628 If enabled, metrics about the InnoDB storage engine are collected.
4629 Disabled by default.
4631 =item B<MasterStats> I<true|false>
4633 =item B<SlaveStats> I<true|false>
4635 Enable the collection of master / slave statistics in a replication setup. In
4636 order to be able to get access to these statistics, the user needs special
4637 privileges. See the B<User> documentation above. Defaults to B<false>.
4639 =item B<SlaveNotifications> I<true|false>
4641 If enabled, the plugin sends a notification if the replication slave I/O and /
4642 or SQL threads are not running. Defaults to B<false>.
4644 =item B<WsrepStats> I<true|false>
4646 Enable the collection of wsrep plugin statistics, used in Master-Master
4647 replication setups like in MySQL Galera/Percona XtraDB Cluster.
4648 User needs only privileges to execute 'SHOW GLOBAL STATUS'
4650 =item B<ConnectTimeout> I<Seconds>
4652 Sets the connect timeout for the MySQL client.
4654 =item B<SSLKey> I<Path>
4656 If provided, the X509 key in PEM format.
4658 =item B<SSLCert> I<Path>
4660 If provided, the X509 cert in PEM format.
4662 =item B<SSLCA> I<Path>
4664 If provided, the CA file in PEM format (check OpenSSL docs).
4666 =item B<SSLCAPath> I<Path>
4668 If provided, the CA directory (check OpenSSL docs).
4670 =item B<SSLCipher> I<String>
4672 If provided, the SSL cipher to use.
4676 =head2 Plugin C<netapp>
4678 The netapp plugin can collect various performance and capacity information
4679 from a NetApp filer using the NetApp API.
4681 Please note that NetApp has a wide line of products and a lot of different
4682 software versions for each of these products. This plugin was developed for a
4683 NetApp FAS3040 running OnTap 7.2.3P8 and tested on FAS2050 7.3.1.1L1,
4684 FAS3140 7.2.5.1 and FAS3020 7.2.4P9. It I<should> work for most combinations of
4685 model and software version but it is very hard to test this.
4686 If you have used this plugin with other models and/or software version, feel
4687 free to send us a mail to tell us about the results, even if it's just a short
4690 To collect these data collectd will log in to the NetApp via HTTP(S) and HTTP
4691 basic authentication.
4693 B<Do not use a regular user for this!> Create a special collectd user with just
4694 the minimum of capabilities needed. The user only needs the "login-http-admin"
4695 capability as well as a few more depending on which data will be collected.
4696 Required capabilities are documented below.
4701 <Host "netapp1.example.com">
4725 IgnoreSelectedIO false
4727 IgnoreSelectedOps false
4728 GetLatency "volume0"
4729 IgnoreSelectedLatency false
4736 IgnoreSelectedCapacity false
4739 IgnoreSelectedSnapshot false
4767 The netapp plugin accepts the following configuration options:
4771 =item B<Host> I<Name>
4773 A host block defines one NetApp filer. It will appear in collectd with the name
4774 you specify here which does not have to be its real name nor its hostname (see
4775 the B<Address> option below).
4777 =item B<VFiler> I<Name>
4779 A B<VFiler> block may only be used inside a host block. It accepts all the
4780 same options as the B<Host> block (except for cascaded B<VFiler> blocks) and
4781 will execute all NetApp API commands in the context of the specified
4782 VFiler(R). It will appear in collectd with the name you specify here which
4783 does not have to be its real name. The VFiler name may be specified using the
4784 B<VFilerName> option. If this is not specified, it will default to the name
4787 The VFiler block inherits all connection related settings from the surrounding
4788 B<Host> block (which appear before the B<VFiler> block) but they may be
4789 overwritten inside the B<VFiler> block.
4791 This feature is useful, for example, when using a VFiler as SnapVault target
4792 (supported since OnTap 8.1). In that case, the SnapVault statistics are not
4793 available in the host filer (vfiler0) but only in the respective VFiler
4796 =item B<Protocol> B<httpd>|B<http>
4798 The protocol collectd will use to query this host.
4806 Valid options: http, https
4808 =item B<Address> I<Address>
4810 The hostname or IP address of the host.
4816 Default: The "host" block's name.
4818 =item B<Port> I<Port>
4820 The TCP port to connect to on the host.
4826 Default: 80 for protocol "http", 443 for protocol "https"
4828 =item B<User> I<User>
4830 =item B<Password> I<Password>
4832 The username and password to use to login to the NetApp.
4838 =item B<VFilerName> I<Name>
4840 The name of the VFiler in which context to execute API commands. If not
4841 specified, the name provided to the B<VFiler> block will be used instead.
4847 Default: name of the B<VFiler> block
4849 B<Note:> This option may only be used inside B<VFiler> blocks.
4851 =item B<Interval> I<Interval>
4857 The following options decide what kind of data will be collected. You can
4858 either use them as a block and fine tune various parameters inside this block,
4859 use them as a single statement to just accept all default values, or omit it to
4860 not collect any data.
4862 The following options are valid inside all blocks:
4866 =item B<Interval> I<Seconds>
4868 Collect the respective statistics every I<Seconds> seconds. Defaults to the
4869 host specific setting.
4873 =head3 The System block
4875 This will collect various performance data about the whole system.
4877 B<Note:> To get this data the collectd user needs the
4878 "api-perf-object-get-instances" capability.
4882 =item B<Interval> I<Seconds>
4884 Collect disk statistics every I<Seconds> seconds.
4886 =item B<GetCPULoad> B<true>|B<false>
4888 If you set this option to true the current CPU usage will be read. This will be
4889 the average usage between all CPUs in your NetApp without any information about
4892 B<Note:> These are the same values that the NetApp CLI command "sysstat"
4893 returns in the "CPU" field.
4901 Result: Two value lists of type "cpu", and type instances "idle" and "system".
4903 =item B<GetInterfaces> B<true>|B<false>
4905 If you set this option to true the current traffic of the network interfaces
4906 will be read. This will be the total traffic over all interfaces of your NetApp
4907 without any information about individual interfaces.
4909 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
4910 in the "Net kB/s" field.
4920 Result: One value list of type "if_octects".
4922 =item B<GetDiskIO> B<true>|B<false>
4924 If you set this option to true the current IO throughput will be read. This
4925 will be the total IO of your NetApp without any information about individual
4926 disks, volumes or aggregates.
4928 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
4929 in the "DiskE<nbsp>kB/s" field.
4937 Result: One value list of type "disk_octets".
4939 =item B<GetDiskOps> B<true>|B<false>
4941 If you set this option to true the current number of HTTP, NFS, CIFS, FCP,
4942 iSCSI, etc. operations will be read. This will be the total number of
4943 operations on your NetApp without any information about individual volumes or
4946 B<Note:> These are the same values that the NetApp CLI command "sysstat"
4947 returns in the "NFS", "CIFS", "HTTP", "FCP" and "iSCSI" fields.
4955 Result: A variable number of value lists of type "disk_ops_complex". Each type
4956 of operation will result in one value list with the name of the operation as
4961 =head3 The WAFL block
4963 This will collect various performance data about the WAFL file system. At the
4964 moment this just means cache performance.
4966 B<Note:> To get this data the collectd user needs the
4967 "api-perf-object-get-instances" capability.
4969 B<Note:> The interface to get these values is classified as "Diagnostics" by
4970 NetApp. This means that it is not guaranteed to be stable even between minor
4975 =item B<Interval> I<Seconds>
4977 Collect disk statistics every I<Seconds> seconds.
4979 =item B<GetNameCache> B<true>|B<false>
4987 Result: One value list of type "cache_ratio" and type instance
4990 =item B<GetDirCache> B<true>|B<false>
4998 Result: One value list of type "cache_ratio" and type instance "find_dir_hit".
5000 =item B<GetInodeCache> B<true>|B<false>
5008 Result: One value list of type "cache_ratio" and type instance
5011 =item B<GetBufferCache> B<true>|B<false>
5013 B<Note:> This is the same value that the NetApp CLI command "sysstat" returns
5014 in the "Cache hit" field.
5022 Result: One value list of type "cache_ratio" and type instance "buf_hash_hit".
5026 =head3 The Disks block
5028 This will collect performance data about the individual disks in the NetApp.
5030 B<Note:> To get this data the collectd user needs the
5031 "api-perf-object-get-instances" capability.
5035 =item B<Interval> I<Seconds>
5037 Collect disk statistics every I<Seconds> seconds.
5039 =item B<GetBusy> B<true>|B<false>
5041 If you set this option to true the busy time of all disks will be calculated
5042 and the value of the busiest disk in the system will be written.
5044 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
5045 in the "Disk util" field. Probably.
5053 Result: One value list of type "percent" and type instance "disk_busy".
5057 =head3 The VolumePerf block
5059 This will collect various performance data about the individual volumes.
5061 You can select which data to collect about which volume using the following
5062 options. They follow the standard ignorelist semantic.
5064 B<Note:> To get this data the collectd user needs the
5065 I<api-perf-object-get-instances> capability.
5069 =item B<Interval> I<Seconds>
5071 Collect volume performance data every I<Seconds> seconds.
5073 =item B<GetIO> I<Volume>
5075 =item B<GetOps> I<Volume>
5077 =item B<GetLatency> I<Volume>
5079 Select the given volume for IO, operations or latency statistics collection.
5080 The argument is the name of the volume without the C</vol/> prefix.
5082 Since the standard ignorelist functionality is used here, you can use a string
5083 starting and ending with a slash to specify regular expression matching: To
5084 match the volumes "vol0", "vol2" and "vol7", you can use this regular
5087 GetIO "/^vol[027]$/"
5089 If no regular expression is specified, an exact match is required. Both,
5090 regular and exact matching are case sensitive.
5092 If no volume was specified at all for either of the three options, that data
5093 will be collected for all available volumes.
5095 See F</"IGNORELISTS"> for details.
5097 =item B<IgnoreSelectedIO> B<true>|B<false>
5099 =item B<IgnoreSelectedOps> B<true>|B<false>
5101 =item B<IgnoreSelectedLatency> B<true>|B<false>
5103 When set to B<true>, the volumes selected for IO, operations or latency
5104 statistics collection will be ignored and the data will be collected for all
5107 When set to B<false>, data will only be collected for the specified volumes and
5108 all other volumes will be ignored.
5110 If no volumes have been specified with the above B<Get*> options, all volumes
5111 will be collected regardless of the B<IgnoreSelected*> option.
5113 Defaults to B<false>
5117 =head3 The VolumeUsage block
5119 This will collect capacity data about the individual volumes.
5121 B<Note:> To get this data the collectd user needs the I<api-volume-list-info>
5126 =item B<Interval> I<Seconds>
5128 Collect volume usage statistics every I<Seconds> seconds.
5130 =item B<GetCapacity> I<VolumeName>
5132 The current capacity of the volume will be collected. This will result in two
5133 to four value lists, depending on the configuration of the volume. All data
5134 sources are of type "df_complex" with the name of the volume as
5137 There will be type_instances "used" and "free" for the number of used and
5138 available bytes on the volume. If the volume has some space reserved for
5139 snapshots, a type_instance "snap_reserved" will be available. If the volume
5140 has SIS enabled, a type_instance "sis_saved" will be available. This is the
5141 number of bytes saved by the SIS feature.
5143 B<Note:> The current NetApp API has a bug that results in this value being
5144 reported as a 32E<nbsp>bit number. This plugin tries to guess the correct
5145 number which works most of the time. If you see strange values here, bug
5146 NetApp support to fix this.
5148 Repeat this option to specify multiple volumes.
5150 =item B<IgnoreSelectedCapacity> B<true>|B<false>
5152 Specify whether to collect only the volumes selected by the B<GetCapacity>
5153 option or to ignore those volumes. B<IgnoreSelectedCapacity> defaults to
5154 B<false>. However, if no B<GetCapacity> option is specified at all, all
5155 capacities will be selected anyway.
5157 =item B<GetSnapshot> I<VolumeName>
5159 Select volumes from which to collect snapshot information.
5161 Usually, the space used for snapshots is included in the space reported as
5162 "used". If snapshot information is collected as well, the space used for
5163 snapshots is subtracted from the used space.
5165 To make things even more interesting, it is possible to reserve space to be
5166 used for snapshots. If the space required for snapshots is less than that
5167 reserved space, there is "reserved free" and "reserved used" space in addition
5168 to "free" and "used". If the space required for snapshots exceeds the reserved
5169 space, that part allocated in the normal space is subtracted from the "used"
5172 Repeat this option to specify multiple volumes.
5174 =item B<IgnoreSelectedSnapshot>
5176 Specify whether to collect only the volumes selected by the B<GetSnapshot>
5177 option or to ignore those volumes. B<IgnoreSelectedSnapshot> defaults to
5178 B<false>. However, if no B<GetSnapshot> option is specified at all, all
5179 capacities will be selected anyway.
5183 =head3 The Quota block
5185 This will collect (tree) quota statistics (used disk space and number of used
5186 files). This mechanism is useful to get usage information for single qtrees.
5187 In case the quotas are not used for any other purpose, an entry similar to the
5188 following in C</etc/quotas> would be sufficient:
5190 /vol/volA/some_qtree tree - - - - -
5192 After adding the entry, issue C<quota on -w volA> on the NetApp filer.
5196 =item B<Interval> I<Seconds>
5198 Collect SnapVault(R) statistics every I<Seconds> seconds.
5202 =head3 The SnapVault block
5204 This will collect statistics about the time and traffic of SnapVault(R)
5209 =item B<Interval> I<Seconds>
5211 Collect SnapVault(R) statistics every I<Seconds> seconds.
5215 =head2 Plugin C<netlink>
5217 The C<netlink> plugin uses a netlink socket to query the Linux kernel about
5218 statistics of various interface and routing aspects.
5222 =item B<Interface> I<Interface>
5224 =item B<VerboseInterface> I<Interface>
5226 Instruct the plugin to collect interface statistics. This is basically the same
5227 as the statistics provided by the C<interface> plugin (see above) but
5228 potentially much more detailed.
5230 When configuring with B<Interface> only the basic statistics will be collected,
5231 namely octets, packets, and errors. These statistics are collected by
5232 the C<interface> plugin, too, so using both at the same time is no benefit.
5234 When configured with B<VerboseInterface> all counters B<except> the basic ones,
5235 so that no data needs to be collected twice if you use the C<interface> plugin.
5236 This includes dropped packets, received multicast packets, collisions and a
5237 whole zoo of differentiated RX and TX errors. You can try the following command
5238 to get an idea of what awaits you:
5242 If I<Interface> is B<All>, all interfaces will be selected.
5244 =item B<QDisc> I<Interface> [I<QDisc>]
5246 =item B<Class> I<Interface> [I<Class>]
5248 =item B<Filter> I<Interface> [I<Filter>]
5250 Collect the octets and packets that pass a certain qdisc, class or filter.
5252 QDiscs and classes are identified by their type and handle (or classid).
5253 Filters don't necessarily have a handle, therefore the parent's handle is used.
5254 The notation used in collectd differs from that used in tc(1) in that it
5255 doesn't skip the major or minor number if it's zero and doesn't print special
5256 ids by their name. So, for example, a qdisc may be identified by
5257 C<pfifo_fast-1:0> even though the minor number of B<all> qdiscs is zero and
5258 thus not displayed by tc(1).
5260 If B<QDisc>, B<Class>, or B<Filter> is given without the second argument,
5261 i.E<nbsp>.e. without an identifier, all qdiscs, classes, or filters that are
5262 associated with that interface will be collected.
5264 Since a filter itself doesn't necessarily have a handle, the parent's handle is
5265 used. This may lead to problems when more than one filter is attached to a
5266 qdisc or class. This isn't nice, but we don't know how this could be done any
5267 better. If you have a idea, please don't hesitate to tell us.
5269 As with the B<Interface> option you can specify B<All> as the interface,
5270 meaning all interfaces.
5272 Here are some examples to help you understand the above text more easily:
5275 VerboseInterface "All"
5276 QDisc "eth0" "pfifo_fast-1:0"
5278 Class "ppp0" "htb-1:10"
5279 Filter "ppp0" "u32-1:0"
5282 See F</"IGNORELISTS"> for details.
5284 =item B<IgnoreSelected>
5286 The behavior is the same as with all other similar plugins: If nothing is
5287 selected at all, everything is collected. If some things are selected using the
5288 options described above, only these statistics are collected. If you set
5289 B<IgnoreSelected> to B<true>, this behavior is inverted, i.E<nbsp>e. the
5290 specified statistics will not be collected.
5294 =head2 Plugin C<network>
5296 The Network plugin sends data to a remote instance of collectd, receives data
5297 from a remote instance, or both at the same time. Data which has been received
5298 from the network is usually not transmitted again, but this can be activated, see
5299 the B<Forward> option below.
5301 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
5302 multicast group is C<239.192.74.66>. The default I<UDP> port is B<25826>.
5304 Both, B<Server> and B<Listen> can be used as single option or as block. When
5305 used as block, given options are valid for this socket only. The following
5306 example will export the metrics twice: Once to an "internal" server (without
5307 encryption and signing) and one to an external server (with cryptographic
5311 # Export to an internal server
5312 # (demonstrates usage without additional options)
5313 Server "collectd.internal.tld"
5315 # Export to an external server
5316 # (demonstrates usage with signature options)
5317 <Server "collectd.external.tld">
5318 SecurityLevel "sign"
5319 Username "myhostname"
5326 =item B<E<lt>Server> I<Host> [I<Port>]B<E<gt>>
5328 The B<Server> statement/block sets the server to send datagrams to. The
5329 statement may occur multiple times to send each datagram to multiple
5332 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. The
5333 optional second argument specifies a port number or a service name. If not
5334 given, the default, B<25826>, is used.
5336 The following options are recognized within B<Server> blocks:
5340 =item B<SecurityLevel> B<Encrypt>|B<Sign>|B<None>
5342 Set the security you require for network communication. When the security level
5343 has been set to B<Encrypt>, data sent over the network will be encrypted using
5344 I<AES-256>. The integrity of encrypted packets is ensured using I<SHA-1>. When
5345 set to B<Sign>, transmitted data is signed using the I<HMAC-SHA-256> message
5346 authentication code. When set to B<None>, data is sent without any security.
5348 This feature is only available if the I<network> plugin was linked with
5351 =item B<Username> I<Username>
5353 Sets the username to transmit. This is used by the server to lookup the
5354 password. See B<AuthFile> below. All security levels except B<None> require
5357 This feature is only available if the I<network> plugin was linked with
5360 =item B<Password> I<Password>
5362 Sets a password (shared secret) for this socket. All security levels except
5363 B<None> require this setting.
5365 This feature is only available if the I<network> plugin was linked with
5368 =item B<Interface> I<Interface name>
5370 Set the outgoing interface for IP packets. This applies at least
5371 to IPv6 packets and if possible to IPv4. If this option is not applicable,
5372 undefined or a non-existent interface name is specified, the default
5373 behavior is to let the kernel choose the appropriate interface. Be warned
5374 that the manual selection of an interface for unicast traffic is only
5375 necessary in rare cases.
5377 =item B<ResolveInterval> I<Seconds>
5379 Sets the interval at which to re-resolve the DNS for the I<Host>. This is
5380 useful to force a regular DNS lookup to support a high availability setup. If
5381 not specified, re-resolves are never attempted.
5385 =item B<E<lt>Listen> I<Host> [I<Port>]B<E<gt>>
5387 The B<Listen> statement sets the interfaces to bind to. When multiple
5388 statements are found the daemon will bind to multiple interfaces.
5390 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
5391 the argument is a multicast address the daemon will join that multicast group.
5392 The optional second argument specifies a port number or a service name. If not
5393 given, the default, B<25826>, is used.
5395 The following options are recognized within C<E<lt>ListenE<gt>> blocks:
5399 =item B<SecurityLevel> B<Encrypt>|B<Sign>|B<None>
5401 Set the security you require for network communication. When the security level
5402 has been set to B<Encrypt>, only encrypted data will be accepted. The integrity
5403 of encrypted packets is ensured using I<SHA-1>. When set to B<Sign>, only
5404 signed and encrypted data is accepted. When set to B<None>, all data will be
5405 accepted. If an B<AuthFile> option was given (see below), encrypted data is
5406 decrypted if possible.
5408 This feature is only available if the I<network> plugin was linked with
5411 =item B<AuthFile> I<Filename>
5413 Sets a file in which usernames are mapped to passwords. These passwords are
5414 used to verify signatures and to decrypt encrypted network packets. If
5415 B<SecurityLevel> is set to B<None>, this is optional. If given, signed data is
5416 verified and encrypted packets are decrypted. Otherwise, signed data is
5417 accepted without checking the signature and encrypted data cannot be decrypted.
5418 For the other security levels this option is mandatory.
5420 The file format is very simple: Each line consists of a username followed by a
5421 colon and any number of spaces followed by the password. To demonstrate, an
5422 example file could look like this:
5427 Each time a packet is received, the modification time of the file is checked
5428 using L<stat(2)>. If the file has been changed, the contents is re-read. While
5429 the file is being read, it is locked using L<fcntl(2)>.
5431 =item B<Interface> I<Interface name>
5433 Set the incoming interface for IP packets explicitly. This applies at least
5434 to IPv6 packets and if possible to IPv4. If this option is not applicable,
5435 undefined or a non-existent interface name is specified, the default
5436 behavior is, to let the kernel choose the appropriate interface. Thus incoming
5437 traffic gets only accepted, if it arrives on the given interface.
5441 =item B<TimeToLive> I<1-255>
5443 Set the time-to-live of sent packets. This applies to all, unicast and
5444 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
5445 That means that multicast packets will be sent with a TTL of C<1> (one) on most
5448 =item B<MaxPacketSize> I<1024-65535>
5450 Set the maximum size for datagrams received over the network. Packets larger
5451 than this will be truncated. Defaults to 1452E<nbsp>bytes, which is the maximum
5452 payload size that can be transmitted in one Ethernet frame using IPv6E<nbsp>/
5455 On the server side, this limit should be set to the largest value used on
5456 I<any> client. Likewise, the value on the client must not be larger than the
5457 value on the server, or data will be lost.
5459 B<Compatibility:> Versions prior to I<versionE<nbsp>4.8> used a fixed sized
5460 buffer of 1024E<nbsp>bytes. Versions I<4.8>, I<4.9> and I<4.10> used a default
5461 value of 1024E<nbsp>bytes to avoid problems when sending data to an older
5464 =item B<Forward> I<true|false>
5466 If set to I<true>, write packets that were received via the network plugin to
5467 the sending sockets. This should only be activated when the B<Listen>- and
5468 B<Server>-statements differ. Otherwise packets may be send multiple times to
5469 the same multicast group. While this results in more network traffic than
5470 necessary it's not a huge problem since the plugin has a duplicate detection,
5471 so the values will not loop.
5473 =item B<ReportStats> B<true>|B<false>
5475 The network plugin cannot only receive and send statistics, it can also create
5476 statistics about itself. Collectd data included the number of received and
5477 sent octets and packets, the length of the receive queue and the number of
5478 values handled. When set to B<true>, the I<Network plugin> will make these
5479 statistics available. Defaults to B<false>.
5483 =head2 Plugin C<nfs>
5485 The I<nfs plugin> collects information about the usage of the Network File
5486 System (NFS). It counts the number of procedure calls for each procedure,
5487 grouped by version and whether the system runs as server or client.
5489 It is possibly to omit metrics for a specific NFS version by setting one or
5490 more of the following options to B<false> (all of them default to B<true>).
5494 =item B<ReportV2> B<true>|B<false>
5496 =item B<ReportV3> B<true>|B<false>
5498 =item B<ReportV4> B<true>|B<false>
5502 =head2 Plugin C<nginx>
5504 This plugin collects the number of connections and requests handled by the
5505 C<nginx daemon> (speak: engineE<nbsp>X), a HTTP and mail server/proxy. It
5506 queries the page provided by the C<ngx_http_stub_status_module> module, which
5507 isn't compiled by default. Please refer to
5508 L<http://wiki.codemongers.com/NginxStubStatusModule> for more information on
5509 how to compile and configure nginx and this module.
5511 The following options are accepted by the C<nginx plugin>:
5515 =item B<URL> I<http://host/nginx_status>
5517 Sets the URL of the C<ngx_http_stub_status_module> output.
5519 =item B<User> I<Username>
5521 Optional user name needed for authentication.
5523 =item B<Password> I<Password>
5525 Optional password needed for authentication.
5527 =item B<VerifyPeer> B<true|false>
5529 Enable or disable peer SSL certificate verification. See
5530 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
5532 =item B<VerifyHost> B<true|false>
5534 Enable or disable peer host name verification. If enabled, the plugin checks
5535 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
5536 certificate matches the host name provided by the B<URL> option. If this
5537 identity check fails, the connection is aborted. Obviously, only works when
5538 connecting to a SSL enabled server. Enabled by default.
5540 =item B<CACert> I<File>
5542 File that holds one or more SSL certificates. If you want to use HTTPS you will
5543 possibly need this option. What CA certificates come bundled with C<libcurl>
5544 and are checked by default depends on the distribution you use.
5546 =item B<Timeout> I<Milliseconds>
5548 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
5549 milliseconds. By default, the configured B<Interval> is used to set the
5554 =head2 Plugin C<notify_desktop>
5556 This plugin sends a desktop notification to a notification daemon, as defined
5557 in the Desktop Notification Specification. To actually display the
5558 notifications, B<notification-daemon> is required and B<collectd> has to be
5559 able to access the X server (i.E<nbsp>e., the C<DISPLAY> and C<XAUTHORITY>
5560 environment variables have to be set correctly) and the D-Bus message bus.
5562 The Desktop Notification Specification can be found at
5563 L<http://www.galago-project.org/specs/notification/>.
5567 =item B<OkayTimeout> I<timeout>
5569 =item B<WarningTimeout> I<timeout>
5571 =item B<FailureTimeout> I<timeout>
5573 Set the I<timeout>, in milliseconds, after which to expire the notification
5574 for C<OKAY>, C<WARNING> and C<FAILURE> severities respectively. If zero has
5575 been specified, the displayed notification will not be closed at all - the
5576 user has to do so herself. These options default to 5000. If a negative number
5577 has been specified, the default is used as well.
5581 =head2 Plugin C<notify_email>
5583 The I<notify_email> plugin uses the I<ESMTP> library to send notifications to a
5584 configured email address.
5586 I<libESMTP> is available from L<http://www.stafford.uklinux.net/libesmtp/>.
5588 Available configuration options:
5592 =item B<From> I<Address>
5594 Email address from which the emails should appear to come from.
5596 Default: C<root@localhost>
5598 =item B<Recipient> I<Address>
5600 Configures the email address(es) to which the notifications should be mailed.
5601 May be repeated to send notifications to multiple addresses.
5603 At least one B<Recipient> must be present for the plugin to work correctly.
5605 =item B<SMTPServer> I<Hostname>
5607 Hostname of the SMTP server to connect to.
5609 Default: C<localhost>
5611 =item B<SMTPPort> I<Port>
5613 TCP port to connect to.
5617 =item B<SMTPUser> I<Username>
5619 Username for ASMTP authentication. Optional.
5621 =item B<SMTPPassword> I<Password>
5623 Password for ASMTP authentication. Optional.
5625 =item B<Subject> I<Subject>
5627 Subject-template to use when sending emails. There must be exactly two
5628 string-placeholders in the subject, given in the standard I<printf(3)> syntax,
5629 i.E<nbsp>e. C<%s>. The first will be replaced with the severity, the second
5632 Default: C<Collectd notify: %s@%s>
5636 =head2 Plugin C<notify_nagios>
5638 The I<notify_nagios> plugin writes notifications to Nagios' I<command file> as
5639 a I<passive service check result>.
5641 Available configuration options:
5645 =item B<CommandFile> I<Path>
5647 Sets the I<command file> to write to. Defaults to F</usr/local/nagios/var/rw/nagios.cmd>.
5651 =head2 Plugin C<ntpd>
5653 The C<ntpd> plugin collects per-peer ntp data such as time offset and time
5656 For talking to B<ntpd>, it mimics what the B<ntpdc> control program does on
5657 the wire - using B<mode 7> specific requests. This mode is deprecated with
5658 newer B<ntpd> releases (4.2.7p230 and later). For the C<ntpd> plugin to work
5659 correctly with them, the ntp daemon must be explicitly configured to
5660 enable B<mode 7> (which is disabled by default). Refer to the I<ntp.conf(5)>
5661 manual page for details.
5663 Available configuration options for the C<ntpd> plugin:
5667 =item B<Host> I<Hostname>
5669 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
5671 =item B<Port> I<Port>
5673 UDP-Port to connect to. Defaults to B<123>.
5675 =item B<ReverseLookups> B<true>|B<false>
5677 Sets whether or not to perform reverse lookups on peers. Since the name or
5678 IP-address may be used in a filename it is recommended to disable reverse
5679 lookups. The default is to do reverse lookups to preserve backwards
5680 compatibility, though.
5682 =item B<IncludeUnitID> B<true>|B<false>
5684 When a peer is a refclock, include the unit ID in the I<type instance>.
5685 Defaults to B<false> for backward compatibility.
5687 If two refclock peers use the same driver and this is B<false>, the plugin will
5688 try to write simultaneous measurements from both to the same type instance.
5689 This will result in error messages in the log and only one set of measurements
5694 =head2 Plugin C<nut>
5698 =item B<UPS> I<upsname>B<@>I<hostname>[B<:>I<port>]
5700 Add a UPS to collect data from. The format is identical to the one accepted by
5703 =item B<ForceSSL> B<true>|B<false>
5705 Stops connections from falling back to unsecured if an SSL connection
5706 cannot be established. Defaults to false if undeclared.
5708 =item B<VerifyPeer> I<true>|I<false>
5710 If set to true, requires a CAPath be provided. Will use the CAPath to find
5711 certificates to use as Trusted Certificates to validate a upsd server certificate.
5712 If validation of the upsd server certificate fails, the connection will not be
5713 established. If ForceSSL is undeclared or set to false, setting VerifyPeer to true
5714 will override and set ForceSSL to true.
5716 =item B<CAPath> I/path/to/certs/folder
5718 If VerifyPeer is set to true, this is required. Otherwise this is ignored.
5719 The folder pointed at must contain certificate(s) named according to their hash.
5720 Ex: XXXXXXXX.Y where X is the hash value of a cert and Y is 0. If name collisions
5721 occur because two different certs have the same hash value, Y can be incremented
5722 in order to avoid conflict. To create a symbolic link to a certificate the following
5723 command can be used from within the directory where the cert resides:
5725 C<ln -s some.crt ./$(openssl x509 -hash -noout -in some.crt).0>
5727 Alternatively, the package openssl-perl provides a command C<c_rehash> that will
5728 generate links like the one described above for ALL certs in a given folder.
5730 C<c_rehash /path/to/certs/folder>
5732 =item B<ConnectTimeout> I<Milliseconds>
5734 The B<ConnectTimeout> option sets the connect timeout, in milliseconds.
5735 By default, the configured B<Interval> is used to set the timeout.
5739 =head2 Plugin C<olsrd>
5741 The I<olsrd> plugin connects to the TCP port opened by the I<txtinfo> plugin of
5742 the Optimized Link State Routing daemon and reads information about the current
5743 state of the meshed network.
5745 The following configuration options are understood:
5749 =item B<Host> I<Host>
5751 Connect to I<Host>. Defaults to B<"localhost">.
5753 =item B<Port> I<Port>
5755 Specifies the port to connect to. This must be a string, even if you give the
5756 port as a number rather than a service name. Defaults to B<"2006">.
5758 =item B<CollectLinks> B<No>|B<Summary>|B<Detail>
5760 Specifies what information to collect about links, i.E<nbsp>e. direct
5761 connections of the daemon queried. If set to B<No>, no information is
5762 collected. If set to B<Summary>, the number of links and the average of all
5763 I<link quality> (LQ) and I<neighbor link quality> (NLQ) values is calculated.
5764 If set to B<Detail> LQ and NLQ are collected per link.
5766 Defaults to B<Detail>.
5768 =item B<CollectRoutes> B<No>|B<Summary>|B<Detail>
5770 Specifies what information to collect about routes of the daemon queried. If
5771 set to B<No>, no information is collected. If set to B<Summary>, the number of
5772 routes and the average I<metric> and I<ETX> is calculated. If set to B<Detail>
5773 metric and ETX are collected per route.
5775 Defaults to B<Summary>.
5777 =item B<CollectTopology> B<No>|B<Summary>|B<Detail>
5779 Specifies what information to collect about the global topology. If set to
5780 B<No>, no information is collected. If set to B<Summary>, the number of links
5781 in the entire topology and the average I<link quality> (LQ) is calculated.
5782 If set to B<Detail> LQ and NLQ are collected for each link in the entire topology.
5784 Defaults to B<Summary>.
5788 =head2 Plugin C<onewire>
5790 B<EXPERIMENTAL!> See notes below.
5792 The C<onewire> plugin uses the B<owcapi> library from the B<owfs> project
5793 L<http://owfs.org/> to read sensors connected via the onewire bus.
5795 It can be used in two possible modes - standard or advanced.
5797 In the standard mode only temperature sensors (sensors with the family code
5798 C<10>, C<22> and C<28> - e.g. DS1820, DS18S20, DS1920) can be read. If you have
5799 other sensors you would like to have included, please send a sort request to
5800 the mailing list. You can select sensors to be read or to be ignored depending
5801 on the option B<IgnoreSelected>). When no list is provided the whole bus is
5802 walked and all sensors are read.
5804 Hubs (the DS2409 chips) are working, but read the note, why this plugin is
5805 experimental, below.
5807 In the advanced mode you can configure any sensor to be read (only numerical
5808 value) using full OWFS path (e.g. "/uncached/10.F10FCA000800/temperature").
5809 In this mode you have to list all the sensors. Neither default bus walk nor
5810 B<IgnoreSelected> are used here. Address and type (file) is extracted from
5811 the path automatically and should produce compatible structure with the "standard"
5812 mode (basically the path is expected as for example
5813 "/uncached/10.F10FCA000800/temperature" where it would extract address part
5814 "F10FCA000800" and the rest after the slash is considered the type - here
5816 There are two advantages to this mode - you can access virtually any sensor
5817 (not just temperature), select whether to use cached or directly read values
5818 and it is slighlty faster. The downside is more complex configuration.
5820 The two modes are distinguished automatically by the format of the address.
5821 It is not possible to mix the two modes. Once a full path is detected in any
5822 B<Sensor> then the whole addressing (all sensors) is considered to be this way
5823 (and as standard addresses will fail parsing they will be ignored).
5827 =item B<Device> I<Device>
5829 Sets the device to read the values from. This can either be a "real" hardware
5830 device, such as a serial port or an USB port, or the address of the
5831 L<owserver(1)> socket, usually B<localhost:4304>.
5833 Though the documentation claims to automatically recognize the given address
5834 format, with versionE<nbsp>2.7p4 we had to specify the type explicitly. So
5835 with that version, the following configuration worked for us:
5838 Device "-s localhost:4304"
5841 This directive is B<required> and does not have a default value.
5843 =item B<Sensor> I<Sensor>
5845 In the standard mode selects sensors to collect or to ignore
5846 (depending on B<IgnoreSelected>, see below). Sensors are specified without
5847 the family byte at the beginning, so you have to use for example C<F10FCA000800>,
5848 and B<not> include the leading C<10.> family byte and point.
5849 When no B<Sensor> is configured the whole Onewire bus is walked and all supported
5850 sensors (see above) are read.
5852 In the advanced mode the B<Sensor> specifies full OWFS path - e.g.
5853 C</uncached/10.F10FCA000800/temperature> (or when cached values are OK
5854 C</10.F10FCA000800/temperature>). B<IgnoreSelected> is not used.
5856 As there can be multiple devices on the bus you can list multiple sensor (use
5857 multiple B<Sensor> elements).
5859 See F</"IGNORELISTS"> for details.
5861 =item B<IgnoreSelected> I<true>|I<false>
5863 If no configuration is given, the B<onewire> plugin will collect data from all
5864 sensors found. This may not be practical, especially if sensors are added and
5865 removed regularly. Sometimes, however, it's easier/preferred to collect only
5866 specific sensors or all sensors I<except> a few specified ones. This option
5867 enables you to do that: By setting B<IgnoreSelected> to I<true> the effect of
5868 B<Sensor> is inverted: All selected interfaces are ignored and all other
5869 interfaces are collected.
5871 Used only in the standard mode - see above.
5873 =item B<Interval> I<Seconds>
5875 Sets the interval in which all sensors should be read. If not specified, the
5876 global B<Interval> setting is used.
5880 B<EXPERIMENTAL!> The C<onewire> plugin is experimental, because it doesn't yet
5881 work with big setups. It works with one sensor being attached to one
5882 controller, but as soon as you throw in a couple more senors and maybe a hub
5883 or two, reading all values will take more than ten seconds (the default
5884 interval). We will probably add some separate thread for reading the sensors
5885 and some cache or something like that, but it's not done yet. We will try to
5886 maintain backwards compatibility in the future, but we can't promise. So in
5887 short: If it works for you: Great! But keep in mind that the config I<might>
5888 change, though this is unlikely. Oh, and if you want to help improving this
5889 plugin, just send a short notice to the mailing list. ThanksE<nbsp>:)
5891 =head2 Plugin C<openldap>
5893 To use the C<openldap> plugin you first need to configure the I<OpenLDAP>
5894 server correctly. The backend database C<monitor> needs to be loaded and
5895 working. See slapd-monitor(5) for the details.
5897 The configuration of the C<openldap> plugin consists of one or more B<Instance>
5898 blocks. Each block requires one string argument as the instance name. For
5903 URL "ldap://localhost/"
5906 URL "ldaps://localhost/"
5910 The instance name will be used as the I<plugin instance>. To emulate the old
5911 (versionE<nbsp>4) behavior, you can use an empty string (""). In order for the
5912 plugin to work correctly, each instance name must be unique. This is not
5913 enforced by the plugin and it is your responsibility to ensure it is.
5915 The following options are accepted within each B<Instance> block:
5919 =item B<URL> I<ldap://host/binddn>
5921 Sets the URL to use to connect to the I<OpenLDAP> server. This option is
5924 =item B<BindDN> I<BindDN>
5926 Name in the form of an LDAP distinguished name intended to be used for
5927 authentication. Defaults to empty string to establish an anonymous authorization.
5929 =item B<Password> I<Password>
5931 Password for simple bind authentication. If this option is not set,
5932 unauthenticated bind operation is used.
5934 =item B<StartTLS> B<true|false>
5936 Defines whether TLS must be used when connecting to the I<OpenLDAP> server.
5937 Disabled by default.
5939 =item B<VerifyHost> B<true|false>
5941 Enables or disables peer host name verification. If enabled, the plugin checks
5942 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
5943 certificate matches the host name provided by the B<URL> option. If this
5944 identity check fails, the connection is aborted. Enabled by default.
5946 =item B<CACert> I<File>
5948 File that holds one or more SSL certificates. If you want to use TLS/SSL you
5949 may possibly need this option. What CA certificates are checked by default
5950 depends on the distribution you use and can be changed with the usual ldap
5951 client configuration mechanisms. See ldap.conf(5) for the details.
5953 =item B<Timeout> I<Seconds>
5955 Sets the timeout value for ldap operations, in seconds. By default, the
5956 configured B<Interval> is used to set the timeout. Use B<-1> to disable
5959 =item B<Version> I<Version>
5961 An integer which sets the LDAP protocol version number to use when connecting
5962 to the I<OpenLDAP> server. Defaults to B<3> for using I<LDAPv3>.
5966 =head2 Plugin C<openvpn>
5968 The OpenVPN plugin reads a status file maintained by OpenVPN and gathers
5969 traffic statistics about connected clients.
5971 To set up OpenVPN to write to the status file periodically, use the
5972 B<--status> option of OpenVPN.
5974 So, in a nutshell you need:
5976 openvpn $OTHER_OPTIONS \
5977 --status "/var/run/openvpn-status" 10
5983 =item B<StatusFile> I<File>
5985 Specifies the location of the status file.
5987 =item B<ImprovedNamingSchema> B<true>|B<false>
5989 When enabled, the filename of the status file will be used as plugin instance
5990 and the client's "common name" will be used as type instance. This is required
5991 when reading multiple status files. Enabling this option is recommended, but to
5992 maintain backwards compatibility this option is disabled by default.
5994 =item B<CollectCompression> B<true>|B<false>
5996 Sets whether or not statistics about the compression used by OpenVPN should be
5997 collected. This information is only available in I<single> mode. Enabled by
6000 =item B<CollectIndividualUsers> B<true>|B<false>
6002 Sets whether or not traffic information is collected for each connected client
6003 individually. If set to false, currently no traffic data is collected at all
6004 because aggregating this data in a save manner is tricky. Defaults to B<true>.
6006 =item B<CollectUserCount> B<true>|B<false>
6008 When enabled, the number of currently connected clients or users is collected.
6009 This is especially interesting when B<CollectIndividualUsers> is disabled, but
6010 can be configured independently from that option. Defaults to B<false>.
6014 =head2 Plugin C<oracle>
6016 The "oracle" plugin uses the Oracle® Call Interface I<(OCI)> to connect to an
6017 Oracle® Database and lets you execute SQL statements there. It is very similar
6018 to the "dbi" plugin, because it was written around the same time. See the "dbi"
6019 plugin's documentation above for details.
6022 <Query "out_of_stock">
6023 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
6026 # InstancePrefix "foo"
6027 InstancesFrom "category"
6031 <Database "product_information">
6036 Query "out_of_stock"
6040 =head3 B<Query> blocks
6042 The Query blocks are handled identically to the Query blocks of the "dbi"
6043 plugin. Please see its documentation above for details on how to specify
6046 =head3 B<Database> blocks
6048 Database blocks define a connection to a database and which queries should be
6049 sent to that database. Each database needs a "name" as string argument in the
6050 starting tag of the block. This name will be used as "PluginInstance" in the
6051 values submitted to the daemon. Other than that, that name is not used.
6055 =item B<Plugin> I<Plugin>
6057 Use I<Plugin> as the plugin name when submitting query results from
6058 this B<Database>. Defaults to C<oracle>.
6060 =item B<ConnectID> I<ID>
6062 Defines the "database alias" or "service name" to connect to. Usually, these
6063 names are defined in the file named C<$ORACLE_HOME/network/admin/tnsnames.ora>.
6065 =item B<Host> I<Host>
6067 Hostname to use when dispatching values for this database. Defaults to using
6068 the global hostname of the I<collectd> instance.
6070 =item B<Username> I<Username>
6072 Username used for authentication.
6074 =item B<Password> I<Password>
6076 Password used for authentication.
6078 =item B<Query> I<QueryName>
6080 Associates the query named I<QueryName> with this database connection. The
6081 query needs to be defined I<before> this statement, i.E<nbsp>e. all query
6082 blocks you want to refer to must be placed above the database block you want to
6087 =head2 Plugin C<ovs_events>
6089 The I<ovs_events> plugin monitors the link status of I<Open vSwitch> (OVS)
6090 connected interfaces, dispatches the values to collectd and sends the
6091 notification whenever the link state change occurs. This plugin uses OVS
6092 database to get a link state change notification.
6096 <Plugin "ovs_events">
6099 Socket "/var/run/openvswitch/db.sock"
6100 Interfaces "br0" "veth0"
6101 SendNotification true
6102 DispatchValues false
6105 The plugin provides the following configuration options:
6109 =item B<Address> I<node>
6111 The address of the OVS DB server JSON-RPC interface used by the plugin. To
6112 enable the interface, OVS DB daemon should be running with C<--remote=ptcp:>
6113 option. See L<ovsdb-server(1)> for more details. The option may be either
6114 network hostname, IPv4 numbers-and-dots notation or IPv6 hexadecimal string
6115 format. Defaults to C<localhost>.
6117 =item B<Port> I<service>
6119 TCP-port to connect to. Either a service name or a port number may be given.
6120 Defaults to B<6640>.
6122 =item B<Socket> I<path>
6124 The UNIX domain socket path of OVS DB server JSON-RPC interface used by the
6125 plugin. To enable the interface, the OVS DB daemon should be running with
6126 C<--remote=punix:> option. See L<ovsdb-server(1)> for more details. If this
6127 option is set, B<Address> and B<Port> options are ignored.
6129 =item B<Interfaces> [I<ifname> ...]
6131 List of interface names to be monitored by this plugin. If this option is not
6132 specified or is empty then all OVS connected interfaces on all bridges are
6135 Default: empty (all interfaces on all bridges are monitored)
6137 =item B<SendNotification> I<true|false>
6139 If set to true, OVS link notifications (interface status and OVS DB connection
6140 terminate) are sent to collectd. Default value is true.
6142 =item B<DispatchValues> I<true|false>
6144 Dispatch the OVS DB interface link status value with configured plugin interval.
6145 Defaults to false. Please note, if B<SendNotification> and B<DispatchValues>
6146 options are false, no OVS information will be provided by the plugin.
6150 B<Note:> By default, the global interval setting is used within which to
6151 retrieve the OVS link status. To configure a plugin-specific interval, please
6152 use B<Interval> option of the OVS B<LoadPlugin> block settings. For milliseconds
6153 simple divide the time by 1000 for example if the desired interval is 50ms, set
6156 =head2 Plugin C<ovs_stats>
6158 The I<ovs_stats> plugin collects statistics of OVS connected interfaces.
6159 This plugin uses OVSDB management protocol (RFC7047) monitor mechanism to get
6160 statistics from OVSDB
6164 <Plugin "ovs_stats">
6167 Socket "/var/run/openvswitch/db.sock"
6168 Bridges "br0" "br_ext"
6171 The plugin provides the following configuration options:
6175 =item B<Address> I<node>
6177 The address of the OVS DB server JSON-RPC interface used by the plugin. To
6178 enable the interface, OVS DB daemon should be running with C<--remote=ptcp:>
6179 option. See L<ovsdb-server(1)> for more details. The option may be either
6180 network hostname, IPv4 numbers-and-dots notation or IPv6 hexadecimal string
6181 format. Defaults to C<localhost>.
6183 =item B<Port> I<service>
6185 TCP-port to connect to. Either a service name or a port number may be given.
6186 Defaults to B<6640>.
6188 =item B<Socket> I<path>
6190 The UNIX domain socket path of OVS DB server JSON-RPC interface used by the
6191 plugin. To enable the interface, the OVS DB daemon should be running with
6192 C<--remote=punix:> option. See L<ovsdb-server(1)> for more details. If this
6193 option is set, B<Address> and B<Port> options are ignored.
6195 =item B<Bridges> [I<brname> ...]
6197 List of OVS bridge names to be monitored by this plugin. If this option is
6198 omitted or is empty then all OVS bridges will be monitored.
6200 Default: empty (monitor all bridges)
6204 =head2 Plugin C<perl>
6206 This plugin embeds a Perl-interpreter into collectd and provides an interface
6207 to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
6209 =head2 Plugin C<pinba>
6211 The I<Pinba plugin> receives profiling information from I<Pinba>, an extension
6212 for the I<PHP> interpreter. At the end of executing a script, i.e. after a
6213 PHP-based webpage has been delivered, the extension will send a UDP packet
6214 containing timing information, peak memory usage and so on. The plugin will
6215 wait for such packets, parse them and account the provided information, which
6216 is then dispatched to the daemon once per interval.
6223 # Overall statistics for the website.
6225 Server "www.example.com"
6227 # Statistics for www-a only
6229 Host "www-a.example.com"
6230 Server "www.example.com"
6232 # Statistics for www-b only
6234 Host "www-b.example.com"
6235 Server "www.example.com"
6239 The plugin provides the following configuration options:
6243 =item B<Address> I<Node>
6245 Configures the address used to open a listening socket. By default, plugin will
6246 bind to the I<any> address C<::0>.
6248 =item B<Port> I<Service>
6250 Configures the port (service) to bind to. By default the default Pinba port
6251 "30002" will be used. The option accepts service names in addition to port
6252 numbers and thus requires a I<string> argument.
6254 =item E<lt>B<View> I<Name>E<gt> block
6256 The packets sent by the Pinba extension include the hostname of the server, the
6257 server name (the name of the virtual host) and the script that was executed.
6258 Using B<View> blocks it is possible to separate the data into multiple groups
6259 to get more meaningful statistics. Each packet is added to all matching groups,
6260 so that a packet may be accounted for more than once.
6264 =item B<Host> I<Host>
6266 Matches the hostname of the system the webserver / script is running on. This
6267 will contain the result of the L<gethostname(2)> system call. If not
6268 configured, all hostnames will be accepted.
6270 =item B<Server> I<Server>
6272 Matches the name of the I<virtual host>, i.e. the contents of the
6273 C<$_SERVER["SERVER_NAME"]> variable when within PHP. If not configured, all
6274 server names will be accepted.
6276 =item B<Script> I<Script>
6278 Matches the name of the I<script name>, i.e. the contents of the
6279 C<$_SERVER["SCRIPT_NAME"]> variable when within PHP. If not configured, all
6280 script names will be accepted.
6286 =head2 Plugin C<ping>
6288 The I<Ping> plugin starts a new thread which sends ICMP "ping" packets to the
6289 configured hosts periodically and measures the network latency. Whenever the
6290 C<read> function of the plugin is called, it submits the average latency, the
6291 standard deviation and the drop rate for each host.
6293 Available configuration options:
6297 =item B<Host> I<IP-address>
6299 Host to ping periodically. This option may be repeated several times to ping
6302 =item B<Interval> I<Seconds>
6304 Sets the interval in which to send ICMP echo packets to the configured hosts.
6305 This is B<not> the interval in which metrics are read from the plugin but the
6306 interval in which the hosts are "pinged". Therefore, the setting here should be
6307 smaller than or equal to the global B<Interval> setting. Fractional times, such
6308 as "1.24" are allowed.
6312 =item B<Timeout> I<Seconds>
6314 Time to wait for a response from the host to which an ICMP packet had been
6315 sent. If a reply was not received after I<Seconds> seconds, the host is assumed
6316 to be down or the packet to be dropped. This setting must be smaller than the
6317 B<Interval> setting above for the plugin to work correctly. Fractional
6318 arguments are accepted.
6322 =item B<TTL> I<0-255>
6324 Sets the Time-To-Live of generated ICMP packets.
6326 =item B<Size> I<size>
6328 Sets the size of the data payload in ICMP packet to specified I<size> (it
6329 will be filled with regular ASCII pattern). If not set, default 56 byte
6330 long string is used so that the packet size of an ICMPv4 packet is exactly
6331 64 bytes, similar to the behaviour of normal ping(1) command.
6333 =item B<SourceAddress> I<host>
6335 Sets the source address to use. I<host> may either be a numerical network
6336 address or a network hostname.
6338 =item B<Device> I<name>
6340 Sets the outgoing network device to be used. I<name> has to specify an
6341 interface name (e.E<nbsp>g. C<eth0>). This might not be supported by all
6344 =item B<MaxMissed> I<Packets>
6346 Trigger a DNS resolve after the host has not replied to I<Packets> packets. This
6347 enables the use of dynamic DNS services (like dyndns.org) with the ping plugin.
6349 Default: B<-1> (disabled)
6353 =head2 Plugin C<postgresql>
6355 The C<postgresql> plugin queries statistics from PostgreSQL databases. It
6356 keeps a persistent connection to all configured databases and tries to
6357 reconnect if the connection has been interrupted. A database is configured by
6358 specifying a B<Database> block as described below. The default statistics are
6359 collected from PostgreSQL's B<statistics collector> which thus has to be
6360 enabled for this plugin to work correctly. This should usually be the case by
6361 default. See the section "The Statistics Collector" of the B<PostgreSQL
6362 Documentation> for details.
6364 By specifying custom database queries using a B<Query> block as described
6365 below, you may collect any data that is available from some PostgreSQL
6366 database. This way, you are able to access statistics of external daemons
6367 which are available in a PostgreSQL database or use future or special
6368 statistics provided by PostgreSQL without the need to upgrade your collectd
6371 Starting with version 5.2, the C<postgresql> plugin supports writing data to
6372 PostgreSQL databases as well. This has been implemented in a generic way. You
6373 need to specify an SQL statement which will then be executed by collectd in
6374 order to write the data (see below for details). The benefit of that approach
6375 is that there is no fixed database layout. Rather, the layout may be optimized
6376 for the current setup.
6378 The B<PostgreSQL Documentation> manual can be found at
6379 L<http://www.postgresql.org/docs/manuals/>.
6383 Statement "SELECT magic FROM wizard WHERE host = $1;"
6387 InstancePrefix "magic"
6392 <Query rt36_tickets>
6393 Statement "SELECT COUNT(type) AS count, type \
6395 WHEN resolved = 'epoch' THEN 'open' \
6396 ELSE 'resolved' END AS type \
6397 FROM tickets) type \
6401 InstancePrefix "rt36_tickets"
6402 InstancesFrom "type"
6408 Statement "SELECT collectd_insert($1, $2, $3, $4, $5, $6, $7, $8, $9);"
6419 KRBSrvName "kerberos_service_name"
6425 Service "service_name"
6426 Query backends # predefined
6437 The B<Query> block defines one database query which may later be used by a
6438 database definition. It accepts a single mandatory argument which specifies
6439 the name of the query. The names of all queries have to be unique (see the
6440 B<MinVersion> and B<MaxVersion> options below for an exception to this
6443 In each B<Query> block, there is one or more B<Result> blocks. Multiple
6444 B<Result> blocks may be used to extract multiple values from a single query.
6446 The following configuration options are available to define the query:
6450 =item B<Statement> I<sql query statement>
6452 Specify the I<sql query statement> which the plugin should execute. The string
6453 may contain the tokens B<$1>, B<$2>, etc. which are used to reference the
6454 first, second, etc. parameter. The value of the parameters is specified by the
6455 B<Param> configuration option - see below for details. To include a literal
6456 B<$> character followed by a number, surround it with single quotes (B<'>).
6458 Any SQL command which may return data (such as C<SELECT> or C<SHOW>) is
6459 allowed. Note, however, that only a single command may be used. Semicolons are
6460 allowed as long as a single non-empty command has been specified only.
6462 The returned lines will be handled separately one after another.
6464 =item B<Param> I<hostname>|I<database>|I<instance>|I<username>|I<interval>
6466 Specify the parameters which should be passed to the SQL query. The parameters
6467 are referred to in the SQL query as B<$1>, B<$2>, etc. in the same order as
6468 they appear in the configuration file. The value of the parameter is
6469 determined depending on the value of the B<Param> option as follows:
6475 The configured hostname of the database connection. If a UNIX domain socket is
6476 used, the parameter expands to "localhost".
6480 The name of the database of the current connection.
6484 The name of the database plugin instance. See the B<Instance> option of the
6485 database specification below for details.
6489 The username used to connect to the database.
6493 The interval with which this database is queried (as specified by the database
6494 specific or global B<Interval> options).
6498 Please note that parameters are only supported by PostgreSQL's protocol
6499 version 3 and above which was introduced in version 7.4 of PostgreSQL.
6501 =item B<PluginInstanceFrom> I<column>
6503 Specify how to create the "PluginInstance" for reporting this query results.
6504 Only one column is supported. You may concatenate fields and string values in
6505 the query statement to get the required results.
6507 =item B<MinVersion> I<version>
6509 =item B<MaxVersion> I<version>
6511 Specify the minimum or maximum version of PostgreSQL that this query should be
6512 used with. Some statistics might only be available with certain versions of
6513 PostgreSQL. This allows you to specify multiple queries with the same name but
6514 which apply to different versions, thus allowing you to use the same
6515 configuration in a heterogeneous environment.
6517 The I<version> has to be specified as the concatenation of the major, minor
6518 and patch-level versions, each represented as two-decimal-digit numbers. For
6519 example, version 8.2.3 will become 80203.
6523 The B<Result> block defines how to handle the values returned from the query.
6524 It defines which column holds which value and how to dispatch that value to
6529 =item B<Type> I<type>
6531 The I<type> name to be used when dispatching the values. The type describes
6532 how to handle the data and where to store it. See L<types.db(5)> for more
6533 details on types and their configuration. The number and type of values (as
6534 selected by the B<ValuesFrom> option) has to match the type of the given name.
6536 This option is mandatory.
6538 =item B<InstancePrefix> I<prefix>
6540 =item B<InstancesFrom> I<column0> [I<column1> ...]
6542 Specify how to create the "TypeInstance" for each data set (i.E<nbsp>e. line).
6543 B<InstancePrefix> defines a static prefix that will be prepended to all type
6544 instances. B<InstancesFrom> defines the column names whose values will be used
6545 to create the type instance. Multiple values will be joined together using the
6546 hyphen (C<->) as separation character.
6548 The plugin itself does not check whether or not all built instances are
6549 different. It is your responsibility to assure that each is unique.
6551 Both options are optional. If none is specified, the type instance will be
6554 =item B<ValuesFrom> I<column0> [I<column1> ...]
6556 Names the columns whose content is used as the actual data for the data sets
6557 that are dispatched to the daemon. How many such columns you need is
6558 determined by the B<Type> setting as explained above. If you specify too many
6559 or not enough columns, the plugin will complain about that and no data will be
6560 submitted to the daemon.
6562 The actual data type, as seen by PostgreSQL, is not that important as long as
6563 it represents numbers. The plugin will automatically cast the values to the
6564 right type if it know how to do that. For that, it uses the L<strtoll(3)> and
6565 L<strtod(3)> functions, so anything supported by those functions is supported
6566 by the plugin as well.
6568 This option is required inside a B<Result> block and may be specified multiple
6569 times. If multiple B<ValuesFrom> options are specified, the columns are read
6574 The following predefined queries are available (the definitions can be found
6575 in the F<postgresql_default.conf> file which, by default, is available at
6576 C<I<prefix>/share/collectd/>):
6582 This query collects the number of backends, i.E<nbsp>e. the number of
6585 =item B<transactions>
6587 This query collects the numbers of committed and rolled-back transactions of
6592 This query collects the numbers of various table modifications (i.E<nbsp>e.
6593 insertions, updates, deletions) of the user tables.
6595 =item B<query_plans>
6597 This query collects the numbers of various table scans and returned tuples of
6600 =item B<table_states>
6602 This query collects the numbers of live and dead rows in the user tables.
6606 This query collects disk block access counts for user tables.
6610 This query collects the on-disk size of the database in bytes.
6614 In addition, the following detailed queries are available by default. Please
6615 note that each of those queries collects information B<by table>, thus,
6616 potentially producing B<a lot> of data. For details see the description of the
6617 non-by_table queries above.
6621 =item B<queries_by_table>
6623 =item B<query_plans_by_table>
6625 =item B<table_states_by_table>
6627 =item B<disk_io_by_table>
6631 The B<Writer> block defines a PostgreSQL writer backend. It accepts a single
6632 mandatory argument specifying the name of the writer. This will then be used
6633 in the B<Database> specification in order to activate the writer instance. The
6634 names of all writers have to be unique. The following options may be
6639 =item B<Statement> I<sql statement>
6641 This mandatory option specifies the SQL statement that will be executed for
6642 each submitted value. A single SQL statement is allowed only. Anything after
6643 the first semicolon will be ignored.
6645 Nine parameters will be passed to the statement and should be specified as
6646 tokens B<$1>, B<$2>, through B<$9> in the statement string. The following
6647 values are made available through those parameters:
6653 The timestamp of the queried value as an RFC 3339-formatted local time.
6657 The hostname of the queried value.
6661 The plugin name of the queried value.
6665 The plugin instance of the queried value. This value may be B<NULL> if there
6666 is no plugin instance.
6670 The type of the queried value (cf. L<types.db(5)>).
6674 The type instance of the queried value. This value may be B<NULL> if there is
6679 An array of names for the submitted values (i.E<nbsp>e., the name of the data
6680 sources of the submitted value-list).
6684 An array of types for the submitted values (i.E<nbsp>e., the type of the data
6685 sources of the submitted value-list; C<counter>, C<gauge>, ...). Note, that if
6686 B<StoreRates> is enabled (which is the default, see below), all types will be
6691 An array of the submitted values. The dimensions of the value name and value
6696 In general, it is advisable to create and call a custom function in the
6697 PostgreSQL database for this purpose. Any procedural language supported by
6698 PostgreSQL will do (see chapter "Server Programming" in the PostgreSQL manual
6701 =item B<StoreRates> B<false>|B<true>
6703 If set to B<true> (the default), convert counter values to rates. If set to
6704 B<false> counter values are stored as is, i.E<nbsp>e. as an increasing integer
6709 The B<Database> block defines one PostgreSQL database for which to collect
6710 statistics. It accepts a single mandatory argument which specifies the
6711 database name. None of the other options are required. PostgreSQL will use
6712 default values as documented in the section "CONNECTING TO A DATABASE" in the
6713 L<psql(1)> manpage. However, be aware that those defaults may be influenced by
6714 the user collectd is run as and special environment variables. See the manpage
6719 =item B<Interval> I<seconds>
6721 Specify the interval with which the database should be queried. The default is
6722 to use the global B<Interval> setting.
6724 =item B<CommitInterval> I<seconds>
6726 This option may be used for database connections which have "writers" assigned
6727 (see above). If specified, it causes a writer to put several updates into a
6728 single transaction. This transaction will last for the specified amount of
6729 time. By default, each update will be executed in a separate transaction. Each
6730 transaction generates a fair amount of overhead which can, thus, be reduced by
6731 activating this option. The draw-back is, that data covering the specified
6732 amount of time will be lost, for example, if a single statement within the
6733 transaction fails or if the database server crashes.
6735 =item B<Plugin> I<Plugin>
6737 Use I<Plugin> as the plugin name when submitting query results from
6738 this B<Database>. Defaults to C<postgresql>.
6740 =item B<Instance> I<name>
6742 Specify the plugin instance name that should be used instead of the database
6743 name (which is the default, if this option has not been specified). This
6744 allows one to query multiple databases of the same name on the same host (e.g.
6745 when running multiple database server versions in parallel).
6746 The plugin instance name can also be set from the query result using
6747 the B<PluginInstanceFrom> option in B<Query> block.
6749 =item B<Host> I<hostname>
6751 Specify the hostname or IP of the PostgreSQL server to connect to. If the
6752 value begins with a slash, it is interpreted as the directory name in which to
6753 look for the UNIX domain socket.
6755 This option is also used to determine the hostname that is associated with a
6756 collected data set. If it has been omitted or either begins with with a slash
6757 or equals B<localhost> it will be replaced with the global hostname definition
6758 of collectd. Any other value will be passed literally to collectd when
6759 dispatching values. Also see the global B<Hostname> and B<FQDNLookup> options.
6761 =item B<Port> I<port>
6763 Specify the TCP port or the local UNIX domain socket file extension of the
6766 =item B<User> I<username>
6768 Specify the username to be used when connecting to the server.
6770 =item B<Password> I<password>
6772 Specify the password to be used when connecting to the server.
6774 =item B<ExpireDelay> I<delay>
6776 Skip expired values in query output.
6778 =item B<SSLMode> I<disable>|I<allow>|I<prefer>|I<require>
6780 Specify whether to use an SSL connection when contacting the server. The
6781 following modes are supported:
6787 Do not use SSL at all.
6791 First, try to connect without using SSL. If that fails, try using SSL.
6793 =item I<prefer> (default)
6795 First, try to connect using SSL. If that fails, try without using SSL.
6803 =item B<Instance> I<name>
6805 Specify the plugin instance name that should be used instead of the database
6806 name (which is the default, if this option has not been specified). This
6807 allows one to query multiple databases of the same name on the same host (e.g.
6808 when running multiple database server versions in parallel).
6810 =item B<KRBSrvName> I<kerberos_service_name>
6812 Specify the Kerberos service name to use when authenticating with Kerberos 5
6813 or GSSAPI. See the sections "Kerberos authentication" and "GSSAPI" of the
6814 B<PostgreSQL Documentation> for details.
6816 =item B<Service> I<service_name>
6818 Specify the PostgreSQL service name to use for additional parameters. That
6819 service has to be defined in F<pg_service.conf> and holds additional
6820 connection parameters. See the section "The Connection Service File" in the
6821 B<PostgreSQL Documentation> for details.
6823 =item B<Query> I<query>
6825 Specifies a I<query> which should be executed in the context of the database
6826 connection. This may be any of the predefined or user-defined queries. If no
6827 such option is given, it defaults to "backends", "transactions", "queries",
6828 "query_plans", "table_states", "disk_io" and "disk_usage" (unless a B<Writer>
6829 has been specified). Else, the specified queries are used only.
6831 =item B<Writer> I<writer>
6833 Assigns the specified I<writer> backend to the database connection. This
6834 causes all collected data to be send to the database using the settings
6835 defined in the writer configuration (see the section "FILTER CONFIGURATION"
6836 below for details on how to selectively send data to certain plugins).
6838 Each writer will register a flush callback which may be used when having long
6839 transactions enabled (see the B<CommitInterval> option above). When issuing
6840 the B<FLUSH> command (see L<collectd-unixsock(5)> for details) the current
6841 transaction will be committed right away. Two different kinds of flush
6842 callbacks are available with the C<postgresql> plugin:
6848 Flush all writer backends.
6850 =item B<postgresql->I<database>
6852 Flush all writers of the specified I<database> only.
6858 =head2 Plugin C<powerdns>
6860 The C<powerdns> plugin queries statistics from an authoritative PowerDNS
6861 nameserver and/or a PowerDNS recursor. Since both offer a wide variety of
6862 values, many of which are probably meaningless to most users, but may be useful
6863 for some. So you may chose which values to collect, but if you don't, some
6864 reasonable defaults will be collected.
6867 <Server "server_name">
6869 Collect "udp-answers" "udp-queries"
6870 Socket "/var/run/pdns.controlsocket"
6872 <Recursor "recursor_name">
6874 Collect "cache-hits" "cache-misses"
6875 Socket "/var/run/pdns_recursor.controlsocket"
6877 LocalSocket "/opt/collectd/var/run/collectd-powerdns"
6882 =item B<Server> and B<Recursor> block
6884 The B<Server> block defines one authoritative server to query, the B<Recursor>
6885 does the same for an recursing server. The possible options in both blocks are
6886 the same, though. The argument defines a name for the serverE<nbsp>/ recursor
6891 =item B<Collect> I<Field>
6893 Using the B<Collect> statement you can select which values to collect. Here,
6894 you specify the name of the values as used by the PowerDNS servers, e.E<nbsp>g.
6895 C<dlg-only-drops>, C<answers10-100>.
6897 The method of getting the values differs for B<Server> and B<Recursor> blocks:
6898 When querying the server a C<SHOW *> command is issued in any case, because
6899 that's the only way of getting multiple values out of the server at once.
6900 collectd then picks out the values you have selected. When querying the
6901 recursor, a command is generated to query exactly these values. So if you
6902 specify invalid fields when querying the recursor, a syntax error may be
6903 returned by the daemon and collectd may not collect any values at all.
6905 If no B<Collect> statement is given, the following B<Server> values will be
6912 =item packetcache-hit
6914 =item packetcache-miss
6916 =item packetcache-size
6918 =item query-cache-hit
6920 =item query-cache-miss
6922 =item recursing-answers
6924 =item recursing-questions
6936 The following B<Recursor> values will be collected by default:
6940 =item noerror-answers
6942 =item nxdomain-answers
6944 =item servfail-answers
6962 Please note that up to that point collectd doesn't know what values are
6963 available on the server and values that are added do not need a change of the
6964 mechanism so far. However, the values must be mapped to collectd's naming
6965 scheme, which is done using a lookup table that lists all known values. If
6966 values are added in the future and collectd does not know about them, you will
6967 get an error much like this:
6969 powerdns plugin: submit: Not found in lookup table: foobar = 42
6971 In this case please file a bug report with the collectd team.
6973 =item B<Socket> I<Path>
6975 Configures the path to the UNIX domain socket to be used when connecting to the
6976 daemon. By default C<${localstatedir}/run/pdns.controlsocket> will be used for
6977 an authoritative server and C<${localstatedir}/run/pdns_recursor.controlsocket>
6978 will be used for the recursor.
6982 =item B<LocalSocket> I<Path>
6984 Querying the recursor is done using UDP. When using UDP over UNIX domain
6985 sockets, the client socket needs a name in the file system, too. You can set
6986 this local name to I<Path> using the B<LocalSocket> option. The default is
6987 C<I<prefix>/var/run/collectd-powerdns>.
6991 =head2 Plugin C<processes>
6993 Collects information about processes of local system.
6995 By default, with no process matches configured, only general statistics is
6996 collected: the number of processes in each state and fork rate.
6998 Process matches can be configured by B<Process> and B<ProcessMatch> options.
6999 These may also be a block in which further options may be specified.
7001 The statistics collected for matched processes are:
7002 - size of the resident segment size (RSS)
7003 - user- and system-time used
7004 - number of processes
7006 - number of open files (under Linux)
7007 - number of memory mapped files (under Linux)
7008 - io data (where available)
7009 - context switches (under Linux)
7010 - minor and major pagefaults
7011 - Delay Accounting information (Linux only, requires libmnl)
7016 CollectFileDescriptor true
7017 CollectContextSwitch true
7018 CollectDelayAccounting false
7020 ProcessMatch "name" "regex"
7021 <Process "collectd">
7022 CollectFileDescriptor false
7023 CollectContextSwitch false
7024 CollectDelayAccounting true
7026 <ProcessMatch "name" "regex">
7027 CollectFileDescriptor false
7028 CollectContextSwitch true
7034 =item B<Process> I<Name>
7036 Select more detailed statistics of processes matching this name.
7038 Some platforms have a limit on the length of process names.
7039 I<Name> must stay below this limit.
7041 =item B<ProcessMatch> I<name> I<regex>
7043 Select more detailed statistics of processes matching the specified I<regex>
7044 (see L<regex(7)> for details). The statistics of all matching processes are
7045 summed up and dispatched to the daemon using the specified I<name> as an
7046 identifier. This allows one to "group" several processes together.
7047 I<name> must not contain slashes.
7049 =item B<CollectContextSwitch> I<Boolean>
7051 Collect the number of context switches for matched processes.
7052 Disabled by default.
7054 =item B<CollectDelayAccounting> I<Boolean>
7056 If enabled, collect Linux Delay Accounding information for matching processes.
7057 Delay Accounting provides the time processes wait for the CPU to become
7058 available, for I/O operations to finish, for pages to be swapped in and for
7059 freed pages to be reclaimed. The metrics are reported as "seconds per second"
7060 using the C<delay_rate> type, e.g. C<delay_rate-delay-cpu>.
7061 Disabled by default.
7063 This option is only available on Linux, requires the C<libmnl> library and
7064 requires the C<CAP_NET_ADMIN> capability at runtime.
7066 =item B<CollectFileDescriptor> I<Boolean>
7068 Collect number of file descriptors of matched processes.
7069 Disabled by default.
7071 =item B<CollectMemoryMaps> I<Boolean>
7073 Collect the number of memory mapped files of the process.
7074 The limit for this number is configured via F</proc/sys/vm/max_map_count> in
7079 The B<CollectContextSwitch>, B<CollectDelayAccounting>,
7080 B<CollectFileDescriptor> and B<CollectMemoryMaps> options may be used inside
7081 B<Process> and B<ProcessMatch> blocks. When used there, these options affect
7082 reporting the corresponding processes only. Outside of B<Process> and
7083 B<ProcessMatch> blocks these options set the default value for subsequent
7086 =head2 Plugin C<protocols>
7088 Collects a lot of information about various network protocols, such as I<IP>,
7089 I<TCP>, I<UDP>, etc.
7091 Available configuration options:
7095 =item B<Value> I<Selector>
7097 Selects whether or not to select a specific value. The string being matched is
7098 of the form "I<Protocol>:I<ValueName>", where I<Protocol> will be used as the
7099 plugin instance and I<ValueName> will be used as type instance. An example of
7100 the string being used would be C<Tcp:RetransSegs>.
7102 You can use regular expressions to match a large number of values with just one
7103 configuration option. To select all "extended" I<TCP> values, you could use the
7104 following statement:
7108 Whether only matched values are selected or all matched values are ignored
7109 depends on the B<IgnoreSelected>. By default, only matched values are selected.
7110 If no value is configured at all, all values will be selected.
7112 See F</"IGNORELISTS"> for details.
7114 =item B<IgnoreSelected> B<true>|B<false>
7116 If set to B<true>, inverts the selection made by B<Value>, i.E<nbsp>e. all
7117 matching values will be ignored.
7121 =head2 Plugin C<python>
7123 This plugin embeds a Python-interpreter into collectd and provides an interface
7124 to collectd's plugin system. See L<collectd-python(5)> for its documentation.
7126 =head2 Plugin C<routeros>
7128 The C<routeros> plugin connects to a device running I<RouterOS>, the
7129 Linux-based operating system for routers by I<MikroTik>. The plugin uses
7130 I<librouteros> to connect and reads information about the interfaces and
7131 wireless connections of the device. The configuration supports querying
7136 Host "router0.example.com"
7139 CollectInterface true
7144 Host "router1.example.com"
7147 CollectInterface true
7148 CollectRegistrationTable true
7154 As you can see above, the configuration of the I<routeros> plugin consists of
7155 one or more B<E<lt>RouterE<gt>> blocks. Within each block, the following
7156 options are understood:
7160 =item B<Host> I<Host>
7162 Hostname or IP-address of the router to connect to.
7164 =item B<Port> I<Port>
7166 Port name or port number used when connecting. If left unspecified, the default
7167 will be chosen by I<librouteros>, currently "8728". This option expects a
7168 string argument, even when a numeric port number is given.
7170 =item B<User> I<User>
7172 Use the user name I<User> to authenticate. Defaults to "admin".
7174 =item B<Password> I<Password>
7176 Set the password used to authenticate.
7178 =item B<CollectInterface> B<true>|B<false>
7180 When set to B<true>, interface statistics will be collected for all interfaces
7181 present on the device. Defaults to B<false>.
7183 =item B<CollectRegistrationTable> B<true>|B<false>
7185 When set to B<true>, information about wireless LAN connections will be
7186 collected. Defaults to B<false>.
7188 =item B<CollectCPULoad> B<true>|B<false>
7190 When set to B<true>, information about the CPU usage will be collected. The
7191 number is a dimensionless value where zero indicates no CPU usage at all.
7192 Defaults to B<false>.
7194 =item B<CollectMemory> B<true>|B<false>
7196 When enabled, the amount of used and free memory will be collected. How used
7197 memory is calculated is unknown, for example whether or not caches are counted
7199 Defaults to B<false>.
7201 =item B<CollectDF> B<true>|B<false>
7203 When enabled, the amount of used and free disk space will be collected.
7204 Defaults to B<false>.
7206 =item B<CollectDisk> B<true>|B<false>
7208 When enabled, the number of sectors written and bad blocks will be collected.
7209 Defaults to B<false>.
7213 =head2 Plugin C<redis>
7215 The I<Redis plugin> connects to one or more Redis servers and gathers
7216 information about each server's state. For each server there is a I<Node> block
7217 which configures the connection parameters for this node.
7224 <Query "LLEN myqueue">
7231 The information shown in the synopsis above is the I<default configuration>
7232 which is used by the plugin if no configuration is present.
7236 =item B<Node> I<Nodename>
7238 The B<Node> block identifies a new Redis node, that is a new Redis instance
7239 running in an specified host and port. The name for node is a canonical
7240 identifier which is used as I<plugin instance>. It is limited to
7241 64E<nbsp>characters in length.
7243 =item B<Host> I<Hostname>
7245 The B<Host> option is the hostname or IP-address where the Redis instance is
7248 =item B<Port> I<Port>
7250 The B<Port> option is the TCP port on which the Redis instance accepts
7251 connections. Either a service name of a port number may be given. Please note
7252 that numerical port numbers must be given as a string, too.
7254 =item B<Password> I<Password>
7256 Use I<Password> to authenticate when connecting to I<Redis>.
7258 =item B<Timeout> I<Milliseconds>
7260 The B<Timeout> option set the socket timeout for node response. Since the Redis
7261 read function is blocking, you should keep this value as low as possible. Keep
7262 in mind that the sum of all B<Timeout> values for all B<Nodes> should be lower
7263 than B<Interval> defined globally.
7265 =item B<Query> I<Querystring>
7267 The B<Query> block identifies a query to execute against the redis server.
7268 There may be an arbitrary number of queries to execute.
7270 =item B<Type> I<Collectd type>
7272 Within a query definition, a valid collectd type to use as when submitting
7273 the result of the query. When not supplied, will default to B<gauge>.
7275 =item B<Instance> I<Type instance>
7277 Within a query definition, an optional type instance to use when submitting
7278 the result of the query. When not supplied will default to the escaped
7279 command, up to 64 chars.
7283 =head2 Plugin C<rrdcached>
7285 The C<rrdcached> plugin uses the RRDtool accelerator daemon, L<rrdcached(1)>,
7286 to store values to RRD files in an efficient manner. The combination of the
7287 C<rrdcached> B<plugin> and the C<rrdcached> B<daemon> is very similar to the
7288 way the C<rrdtool> plugin works (see below). The added abstraction layer
7289 provides a number of benefits, though: Because the cache is not within
7290 C<collectd> anymore, it does not need to be flushed when C<collectd> is to be
7291 restarted. This results in much shorter (if any) gaps in graphs, especially
7292 under heavy load. Also, the C<rrdtool> command line utility is aware of the
7293 daemon so that it can flush values to disk automatically when needed. This
7294 allows one to integrate automated flushing of values into graphing solutions
7297 There are disadvantages, though: The daemon may reside on a different host, so
7298 it may not be possible for C<collectd> to create the appropriate RRD files
7299 anymore. And even if C<rrdcached> runs on the same host, it may run in a
7300 different base directory, so relative paths may do weird stuff if you're not
7303 So the B<recommended configuration> is to let C<collectd> and C<rrdcached> run
7304 on the same host, communicating via a UNIX domain socket. The B<DataDir>
7305 setting should be set to an absolute path, so that a changed base directory
7306 does not result in RRD files being createdE<nbsp>/ expected in the wrong place.
7310 =item B<DaemonAddress> I<Address>
7312 Address of the daemon as understood by the C<rrdc_connect> function of the RRD
7313 library. See L<rrdcached(1)> for details. Example:
7315 <Plugin "rrdcached">
7316 DaemonAddress "unix:/var/run/rrdcached.sock"
7319 =item B<DataDir> I<Directory>
7321 Set the base directory in which the RRD files reside. If this is a relative
7322 path, it is relative to the working base directory of the C<rrdcached> daemon!
7323 Use of an absolute path is recommended.
7325 =item B<CreateFiles> B<true>|B<false>
7327 Enables or disables the creation of RRD files. If the daemon is not running
7328 locally, or B<DataDir> is set to a relative path, this will not work as
7329 expected. Default is B<true>.
7331 =item B<CreateFilesAsync> B<false>|B<true>
7333 When enabled, new RRD files are enabled asynchronously, using a separate thread
7334 that runs in the background. This prevents writes to block, which is a problem
7335 especially when many hundreds of files need to be created at once. However,
7336 since the purpose of creating the files asynchronously is I<not> to block until
7337 the file is available, values before the file is available will be discarded.
7338 When disabled (the default) files are created synchronously, blocking for a
7339 short while, while the file is being written.
7341 =item B<StepSize> I<Seconds>
7343 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
7344 this setting is unset and the stepsize is set to the interval in which the data
7345 is collected. Do not use this option unless you absolutely have to for some
7346 reason. Setting this option may cause problems with the C<snmp plugin>, the
7347 C<exec plugin> or when the daemon is set up to receive data from other hosts.
7349 =item B<HeartBeat> I<Seconds>
7351 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
7352 in which case the heartbeat is set to twice the B<StepSize> which should equal
7353 the interval in which data is collected. Do not set this option unless you have
7354 a very good reason to do so.
7356 =item B<RRARows> I<NumRows>
7358 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
7359 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
7360 three times five RRAs, i. e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
7361 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
7362 week, one month, and one year.
7364 So for each timespan, it calculates how many PDPs need to be consolidated into
7365 one CDP by calculating:
7366 number of PDPs = timespan / (stepsize * rrarows)
7368 Bottom line is, set this no smaller than the width of you graphs in pixels. The
7371 =item B<RRATimespan> I<Seconds>
7373 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
7374 more then one RRA. If this option is never used, the built-in default of (3600,
7375 86400, 604800, 2678400, 31622400) is used.
7377 For more information on how RRA-sizes are calculated see B<RRARows> above.
7379 =item B<XFF> I<Factor>
7381 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
7382 I<Factor> must be in the range C<[0.0-1.0)>, i.e. between zero (inclusive) and
7385 =item B<CollectStatistics> B<false>|B<true>
7387 When set to B<true>, various statistics about the I<rrdcached> daemon will be
7388 collected, with "rrdcached" as the I<plugin name>. Defaults to B<false>.
7390 Statistics are read via I<rrdcached>s socket using the STATS command.
7391 See L<rrdcached(1)> for details.
7395 =head2 Plugin C<rrdtool>
7397 You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
7398 fine-tune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
7399 using these settings. If you don't want to dive into the depths of RRDtool, you
7400 can safely ignore these settings.
7404 =item B<DataDir> I<Directory>
7406 Set the directory to store RRD files under. By default RRD files are generated
7407 beneath the daemon's working directory, i.e. the B<BaseDir>.
7409 =item B<CreateFilesAsync> B<false>|B<true>
7411 When enabled, new RRD files are enabled asynchronously, using a separate thread
7412 that runs in the background. This prevents writes to block, which is a problem
7413 especially when many hundreds of files need to be created at once. However,
7414 since the purpose of creating the files asynchronously is I<not> to block until
7415 the file is available, values before the file is available will be discarded.
7416 When disabled (the default) files are created synchronously, blocking for a
7417 short while, while the file is being written.
7419 =item B<StepSize> I<Seconds>
7421 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
7422 this setting is unset and the stepsize is set to the interval in which the data
7423 is collected. Do not use this option unless you absolutely have to for some
7424 reason. Setting this option may cause problems with the C<snmp plugin>, the
7425 C<exec plugin> or when the daemon is set up to receive data from other hosts.
7427 =item B<HeartBeat> I<Seconds>
7429 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
7430 in which case the heartbeat is set to twice the B<StepSize> which should equal
7431 the interval in which data is collected. Do not set this option unless you have
7432 a very good reason to do so.
7434 =item B<RRARows> I<NumRows>
7436 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
7437 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
7438 three times five RRAs, i.e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
7439 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
7440 week, one month, and one year.
7442 So for each timespan, it calculates how many PDPs need to be consolidated into
7443 one CDP by calculating:
7444 number of PDPs = timespan / (stepsize * rrarows)
7446 Bottom line is, set this no smaller than the width of you graphs in pixels. The
7449 =item B<RRATimespan> I<Seconds>
7451 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
7452 more then one RRA. If this option is never used, the built-in default of (3600,
7453 86400, 604800, 2678400, 31622400) is used.
7455 For more information on how RRA-sizes are calculated see B<RRARows> above.
7457 =item B<XFF> I<Factor>
7459 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
7460 I<Factor> must be in the range C<[0.0-1.0)>, i.e. between zero (inclusive) and
7463 =item B<CacheFlush> I<Seconds>
7465 When the C<rrdtool> plugin uses a cache (by setting B<CacheTimeout>, see below)
7466 it writes all values for a certain RRD-file if the oldest value is older than
7467 (or equal to) the number of seconds specified by B<CacheTimeout>.
7468 That check happens on new values arriwal. If some RRD-file is not updated
7469 anymore for some reason (the computer was shut down, the network is broken,
7470 etc.) some values may still be in the cache. If B<CacheFlush> is set, then
7471 every I<Seconds> seconds the entire cache is searched for entries older than
7472 B<CacheTimeout> + B<RandomTimeout> seconds. The entries found are written to
7473 disk. Since scanning the entire cache is kind of expensive and does nothing
7474 under normal circumstances, this value should not be too small. 900 seconds
7475 might be a good value, though setting this to 7200 seconds doesn't normally
7476 do much harm either.
7478 Defaults to 10x B<CacheTimeout>.
7479 B<CacheFlush> must be larger than or equal to B<CacheTimeout>, otherwise the
7480 above default is used.
7482 =item B<CacheTimeout> I<Seconds>
7484 If this option is set to a value greater than zero, the C<rrdtool plugin> will
7485 save values in a cache, as described above. Writing multiple values at once
7486 reduces IO-operations and thus lessens the load produced by updating the files.
7487 The trade off is that the graphs kind of "drag behind" and that more memory is
7490 =item B<WritesPerSecond> I<Updates>
7492 When collecting many statistics with collectd and the C<rrdtool> plugin, you
7493 will run serious performance problems. The B<CacheFlush> setting and the
7494 internal update queue assert that collectd continues to work just fine even
7495 under heavy load, but the system may become very unresponsive and slow. This is
7496 a problem especially if you create graphs from the RRD files on the same
7497 machine, for example using the C<graph.cgi> script included in the
7498 C<contrib/collection3/> directory.
7500 This setting is designed for very large setups. Setting this option to a value
7501 between 25 and 80 updates per second, depending on your hardware, will leave
7502 the server responsive enough to draw graphs even while all the cached values
7503 are written to disk. Flushed values, i.E<nbsp>e. values that are forced to disk
7504 by the B<FLUSH> command, are B<not> effected by this limit. They are still
7505 written as fast as possible, so that web frontends have up to date data when
7508 For example: If you have 100,000 RRD files and set B<WritesPerSecond> to 30
7509 updates per second, writing all values to disk will take approximately
7510 56E<nbsp>minutes. Together with the flushing ability that's integrated into
7511 "collection3" you'll end up with a responsive and fast system, up to date
7512 graphs and basically a "backup" of your values every hour.
7514 =item B<RandomTimeout> I<Seconds>
7516 When set, the actual timeout for each value is chosen randomly between
7517 I<CacheTimeout>-I<RandomTimeout> and I<CacheTimeout>+I<RandomTimeout>. The
7518 intention is to avoid high load situations that appear when many values timeout
7519 at the same time. This is especially a problem shortly after the daemon starts,
7520 because all values were added to the internal cache at roughly the same time.
7524 =head2 Plugin C<sensors>
7526 The I<Sensors plugin> uses B<lm_sensors> to retrieve sensor-values. This means
7527 that all the needed modules have to be loaded and lm_sensors has to be
7528 configured (most likely by editing F</etc/sensors.conf>. Read
7529 L<sensors.conf(5)> for details.
7531 The B<lm_sensors> homepage can be found at
7532 L<http://secure.netroedge.com/~lm78/>.
7536 =item B<SensorConfigFile> I<File>
7538 Read the I<lm_sensors> configuration from I<File>. When unset (recommended),
7539 the library's default will be used.
7541 =item B<Sensor> I<chip-bus-address/type-feature>
7543 Selects the name of the sensor which you want to collect or ignore, depending
7544 on the B<IgnoreSelected> below. For example, the option "B<Sensor>
7545 I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
7546 voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
7548 See F</"IGNORELISTS"> for details.
7550 =item B<IgnoreSelected> I<true>|I<false>
7552 If no configuration if given, the B<sensors>-plugin will collect data from all
7553 sensors. This may not be practical, especially for uninteresting sensors.
7554 Thus, you can use the B<Sensor>-option to pick the sensors you're interested
7555 in. Sometimes, however, it's easier/preferred to collect all sensors I<except> a
7556 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
7557 I<true> the effect of B<Sensor> is inverted: All selected sensors are ignored
7558 and all other sensors are collected.
7560 =item B<UseLabels> I<true>|I<false>
7562 Configures how sensor readings are reported. When set to I<true>, sensor
7563 readings are reported using their descriptive label (e.g. "VCore"). When set to
7564 I<false> (the default) the sensor name is used ("in0").
7568 =head2 Plugin C<sigrok>
7570 The I<sigrok plugin> uses I<libsigrok> to retrieve measurements from any device
7571 supported by the L<sigrok|http://sigrok.org/> project.
7577 <Device "AC Voltage">
7582 <Device "Sound Level">
7583 Driver "cem-dt-885x"
7590 =item B<LogLevel> B<0-5>
7592 The I<sigrok> logging level to pass on to the I<collectd> log, as a number
7593 between B<0> and B<5> (inclusive). These levels correspond to C<None>,
7594 C<Errors>, C<Warnings>, C<Informational>, C<Debug >and C<Spew>, respectively.
7595 The default is B<2> (C<Warnings>). The I<sigrok> log messages, regardless of
7596 their level, are always submitted to I<collectd> at its INFO log level.
7598 =item E<lt>B<Device> I<Name>E<gt>
7600 A sigrok-supported device, uniquely identified by this section's options. The
7601 I<Name> is passed to I<collectd> as the I<plugin instance>.
7603 =item B<Driver> I<DriverName>
7605 The sigrok driver to use for this device.
7607 =item B<Conn> I<ConnectionSpec>
7609 If the device cannot be auto-discovered, or more than one might be discovered
7610 by the driver, I<ConnectionSpec> specifies the connection string to the device.
7611 It can be of the form of a device path (e.g.E<nbsp>C</dev/ttyUSB2>), or, in
7612 case of a non-serial USB-connected device, the USB I<VendorID>B<.>I<ProductID>
7613 separated by a period (e.g.E<nbsp>C<0403.6001>). A USB device can also be
7614 specified as I<Bus>B<.>I<Address> (e.g.E<nbsp>C<1.41>).
7616 =item B<SerialComm> I<SerialSpec>
7618 For serial devices with non-standard port settings, this option can be used
7619 to specify them in a form understood by I<sigrok>, e.g.E<nbsp>C<9600/8n1>.
7620 This should not be necessary; drivers know how to communicate with devices they
7623 =item B<MinimumInterval> I<Seconds>
7625 Specifies the minimum time between measurement dispatches to I<collectd>, in
7626 seconds. Since some I<sigrok> supported devices can acquire measurements many
7627 times per second, it may be necessary to throttle these. For example, the
7628 I<RRD plugin> cannot process writes more than once per second.
7630 The default B<MinimumInterval> is B<0>, meaning measurements received from the
7631 device are always dispatched to I<collectd>. When throttled, unused
7632 measurements are discarded.
7636 =head2 Plugin C<smart>
7638 The C<smart> plugin collects SMART information from physical
7639 disks. Values collectd include temperature, power cycle count, poweron
7640 time and bad sectors. Also, all SMART attributes are collected along
7641 with the normalized current value, the worst value, the threshold and
7642 a human readable value.
7644 Using the following two options you can ignore some disks or configure the
7645 collection only of specific disks.
7649 =item B<Disk> I<Name>
7651 Select the disk I<Name>. Whether it is collected or ignored depends on the
7652 B<IgnoreSelected> setting, see below. As with other plugins that use the
7653 daemon's ignorelist functionality, a string that starts and ends with a slash
7654 is interpreted as a regular expression. Examples:
7659 See F</"IGNORELISTS"> for details.
7661 =item B<IgnoreSelected> B<true>|B<false>
7663 Sets whether selected disks, i.E<nbsp>e. the ones matches by any of the B<Disk>
7664 statements, are ignored or if all other disks are ignored. The behavior
7665 (hopefully) is intuitive: If no B<Disk> option is configured, all disks are
7666 collected. If at least one B<Disk> option is given and no B<IgnoreSelected> or
7667 set to B<false>, B<only> matching disks will be collected. If B<IgnoreSelected>
7668 is set to B<true>, all disks are collected B<except> the ones matched.
7670 =item B<IgnoreSleepMode> B<true>|B<false>
7672 Normally, the C<smart> plugin will ignore disks that are reported to be asleep.
7673 This option disables the sleep mode check and allows the plugin to collect data
7674 from these disks anyway. This is useful in cases where libatasmart mistakenly
7675 reports disks as asleep because it has not been updated to incorporate support
7676 for newer idle states in the ATA spec.
7678 =item B<UseSerial> B<true>|B<false>
7680 A disk's kernel name (e.g., sda) can change from one boot to the next. If this
7681 option is enabled, the C<smart> plugin will use the disk's serial number (e.g.,
7682 HGST_HUH728080ALE600_2EJ8VH8X) instead of the kernel name as the key for
7683 storing data. This ensures that the data for a given disk will be kept together
7684 even if the kernel name changes.
7688 =head2 Plugin C<snmp>
7690 Since the configuration of the C<snmp plugin> is a little more complicated than
7691 other plugins, its documentation has been moved to an own manpage,
7692 L<collectd-snmp(5)>. Please see there for details.
7694 =head2 Plugin C<snmp_agent>
7696 The I<snmp_agent> plugin is an AgentX subagent that receives and handles queries
7697 from SNMP master agent and returns the data collected by read plugins.
7698 The I<snmp_agent> plugin handles requests only for OIDs specified in
7699 configuration file. To handle SNMP queries the plugin gets data from collectd
7700 and translates requested values from collectd's internal format to SNMP format.
7701 This plugin is a generic plugin and cannot work without configuration.
7702 For more details on AgentX subagent see
7703 <http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/>
7708 <Data "memAvailReal">
7710 #PluginInstance "some"
7713 OIDs "1.3.6.1.4.1.2021.4.6.0"
7716 IndexOID "IF-MIB::ifIndex"
7717 SizeOID "IF-MIB::ifNumber"
7721 OIDs "IF-MIB::ifDescr"
7727 OIDs "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
7732 There are two types of blocks that can be contained in the
7733 C<E<lt>PluginE<nbsp> snmp_agentE<gt>> block: B<Data> and B<Table>:
7735 =head3 The B<Data> block
7737 The B<Data> block defines a list OIDs that are to be handled. This block can
7738 define scalar or table OIDs. If B<Data> block is defined inside of B<Table>
7739 block it reperesents table OIDs.
7740 The following options can be set:
7744 =item B<Instance> I<true|false>
7746 When B<Instance> is set to B<true>, the value for requested OID is copied from
7747 plugin instance field of corresponding collectd value. If B<Data> block defines
7748 scalar data type B<Instance> has no effect and can be omitted.
7750 =item B<Plugin> I<String>
7752 Read plugin name whose collected data will be mapped to specified OIDs.
7754 =item B<PluginInstance> I<String>
7756 Read plugin instance whose collected data will be mapped to specified OIDs.
7757 The field is optional and by default there is no plugin instance check.
7758 Allowed only if B<Data> block defines scalar data type.
7760 =item B<Type> I<String>
7762 Collectd's type that is to be used for specified OID, e.E<nbsp>g. "if_octets"
7763 for example. The types are read from the B<TypesDB> (see L<collectd.conf(5)>).
7765 =item B<TypeInstance> I<String>
7767 Collectd's type-instance that is to be used for specified OID.
7769 =item B<OIDs> I<OID> [I<OID> ...]
7771 Configures the OIDs to be handled by I<snmp_agent> plugin. Values for these OIDs
7772 are taken from collectd data type specified by B<Plugin>, B<PluginInstance>,
7773 B<Type>, B<TypeInstance> fields of this B<Data> block. Number of the OIDs
7774 configured should correspond to number of values in specified B<Type>.
7775 For example two OIDs "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets" can be mapped to
7776 "rx" and "tx" values of "if_octets" type.
7778 =item B<Scale> I<Value>
7780 The values taken from collectd are multiplied by I<Value>. The field is optional
7781 and the default is B<1.0>.
7783 =item B<Shift> I<Value>
7785 I<Value> is added to values from collectd after they have been multiplied by
7786 B<Scale> value. The field is optional and the default value is B<0.0>.
7790 =head3 The B<Table> block
7792 The B<Table> block defines a collection of B<Data> blocks that belong to one
7793 snmp table. In addition to multiple B<Data> blocks the following options can be
7798 =item B<IndexOID> I<OID>
7800 OID that is handled by the plugin and is mapped to numerical index value that is
7801 generated by the plugin for each table record.
7803 =item B<SizeOID> I<OID>
7805 OID that is handled by the plugin. Returned value is the number of records in
7806 the table. The field is optional.
7810 =head2 Plugin C<statsd>
7812 The I<statsd plugin> listens to a UDP socket, reads "events" in the statsd
7813 protocol and dispatches rates or other aggregates of these numbers
7816 The plugin implements the I<Counter>, I<Timer>, I<Gauge> and I<Set> types which
7817 are dispatched as the I<collectd> types C<derive>, C<latency>, C<gauge> and
7818 C<objects> respectively.
7820 The following configuration options are valid:
7824 =item B<Host> I<Host>
7826 Bind to the hostname / address I<Host>. By default, the plugin will bind to the
7827 "any" address, i.e. accept packets sent to any of the hosts addresses.
7829 =item B<Port> I<Port>
7831 UDP port to listen to. This can be either a service name or a port number.
7832 Defaults to C<8125>.
7834 =item B<DeleteCounters> B<false>|B<true>
7836 =item B<DeleteTimers> B<false>|B<true>
7838 =item B<DeleteGauges> B<false>|B<true>
7840 =item B<DeleteSets> B<false>|B<true>
7842 These options control what happens if metrics are not updated in an interval.
7843 If set to B<False>, the default, metrics are dispatched unchanged, i.e. the
7844 rate of counters and size of sets will be zero, timers report C<NaN> and gauges
7845 are unchanged. If set to B<True>, the such metrics are not dispatched and
7846 removed from the internal cache.
7848 =item B<CounterSum> B<false>|B<true>
7850 When enabled, creates a C<count> metric which reports the change since the last
7851 read. This option primarily exists for compatibility with the I<statsd>
7852 implementation by Etsy.
7854 =item B<TimerPercentile> I<Percent>
7856 Calculate and dispatch the configured percentile, i.e. compute the latency, so
7857 that I<Percent> of all reported timers are smaller than or equal to the
7858 computed latency. This is useful for cutting off the long tail latency, as it's
7859 often done in I<Service Level Agreements> (SLAs).
7861 Different percentiles can be calculated by setting this option several times.
7862 If none are specified, no percentiles are calculated / dispatched.
7864 =item B<TimerLower> B<false>|B<true>
7866 =item B<TimerUpper> B<false>|B<true>
7868 =item B<TimerSum> B<false>|B<true>
7870 =item B<TimerCount> B<false>|B<true>
7872 Calculate and dispatch various values out of I<Timer> metrics received during
7873 an interval. If set to B<False>, the default, these values aren't calculated /
7876 Please note what reported timer values less than 0.001 are ignored in all B<Timer*> reports.
7880 =head2 Plugin C<swap>
7882 The I<Swap plugin> collects information about used and available swap space. On
7883 I<Linux> and I<Solaris>, the following options are available:
7887 =item B<ReportByDevice> B<false>|B<true>
7889 Configures how to report physical swap devices. If set to B<false> (the
7890 default), the summary over all swap devices is reported only, i.e. the globally
7891 used and available space over all devices. If B<true> is configured, the used
7892 and available space of each device will be reported separately.
7894 This option is only available if the I<Swap plugin> can read C</proc/swaps>
7895 (under Linux) or use the L<swapctl(2)> mechanism (under I<Solaris>).
7897 =item B<ReportBytes> B<false>|B<true>
7899 When enabled, the I<swap I/O> is reported in bytes. When disabled, the default,
7900 I<swap I/O> is reported in pages. This option is available under Linux only.
7902 =item B<ValuesAbsolute> B<true>|B<false>
7904 Enables or disables reporting of absolute swap metrics, i.e. number of I<bytes>
7905 available and used. Defaults to B<true>.
7907 =item B<ValuesPercentage> B<false>|B<true>
7909 Enables or disables reporting of relative swap metrics, i.e. I<percent>
7910 available and free. Defaults to B<false>.
7912 This is useful for deploying I<collectd> in a heterogeneous environment, where
7913 swap sizes differ and you want to specify generic thresholds or similar.
7915 =item B<ReportIO> B<true>|B<false>
7917 Enables or disables reporting swap IO. Defaults to B<true>.
7919 This is useful for the cases when swap IO is not neccessary, is not available,
7924 =head2 Plugin C<syslog>
7928 =item B<LogLevel> B<debug|info|notice|warning|err>
7930 Sets the log-level. If, for example, set to B<notice>, then all events with
7931 severity B<notice>, B<warning>, or B<err> will be submitted to the
7934 Please note that B<debug> is only available if collectd has been compiled with
7937 =item B<NotifyLevel> B<OKAY>|B<WARNING>|B<FAILURE>
7939 Controls which notifications should be sent to syslog. The default behaviour is
7940 not to send any. Less severe notifications always imply logging more severe
7941 notifications: Setting this to B<OKAY> means all notifications will be sent to
7942 syslog, setting this to B<WARNING> will send B<WARNING> and B<FAILURE>
7943 notifications but will dismiss B<OKAY> notifications. Setting this option to
7944 B<FAILURE> will only send failures to syslog.
7948 =head2 Plugin C<table>
7950 The C<table plugin> provides generic means to parse tabular data and dispatch
7951 user specified values. Values are selected based on column numbers. For
7952 example, this plugin may be used to get values from the Linux L<proc(5)>
7953 filesystem or CSV (comma separated values) files.
7956 <Table "/proc/slabinfo">
7962 InstancePrefix "active_objs"
7968 InstancePrefix "objperslab"
7975 The configuration consists of one or more B<Table> blocks, each of which
7976 configures one file to parse. Within each B<Table> block, there are one or
7977 more B<Result> blocks, which configure which data to select and how to
7980 The following options are available inside a B<Table> block:
7984 =item B<Plugin> I<Plugin>
7986 If specified, I<Plugin> is used as the plugin name when submitting values.
7987 Defaults to B<table>.
7989 =item B<Instance> I<instance>
7991 If specified, I<instance> is used as the plugin instance. If omitted, the
7992 filename of the table is used instead, with all special characters replaced
7993 with an underscore (C<_>).
7995 =item B<Separator> I<string>
7997 Any character of I<string> is interpreted as a delimiter between the different
7998 columns of the table. A sequence of two or more contiguous delimiters in the
7999 table is considered to be a single delimiter, i.E<nbsp>e. there cannot be any
8000 empty columns. The plugin uses the L<strtok_r(3)> function to parse the lines
8001 of a table - see its documentation for more details. This option is mandatory.
8003 A horizontal tab, newline and carriage return may be specified by C<\\t>,
8004 C<\\n> and C<\\r> respectively. Please note that the double backslashes are
8005 required because of collectd's config parsing.
8009 The following options are available inside a B<Result> block:
8013 =item B<Type> I<type>
8015 Sets the type used to dispatch the values to the daemon. Detailed information
8016 about types and their configuration can be found in L<types.db(5)>. This
8017 option is mandatory.
8019 =item B<InstancePrefix> I<prefix>
8021 If specified, prepend I<prefix> to the type instance. If omitted, only the
8022 B<InstancesFrom> option is considered for the type instance.
8024 =item B<InstancesFrom> I<column0> [I<column1> ...]
8026 If specified, the content of the given columns (identified by the column
8027 number starting at zero) will be used to create the type instance for each
8028 row. Multiple values (and the instance prefix) will be joined together with
8029 dashes (I<->) as separation character. If omitted, only the B<InstancePrefix>
8030 option is considered for the type instance.
8032 The plugin itself does not check whether or not all built instances are
8033 different. It’s your responsibility to assure that each is unique. This is
8034 especially true, if you do not specify B<InstancesFrom>: B<You> have to make
8035 sure that the table only contains one row.
8037 If neither B<InstancePrefix> nor B<InstancesFrom> is given, the type instance
8040 =item B<ValuesFrom> I<column0> [I<column1> ...]
8042 Specifies the columns (identified by the column numbers starting at zero)
8043 whose content is used as the actual data for the data sets that are dispatched
8044 to the daemon. How many such columns you need is determined by the B<Type>
8045 setting above. If you specify too many or not enough columns, the plugin will
8046 complain about that and no data will be submitted to the daemon. The plugin
8047 uses L<strtoll(3)> and L<strtod(3)> to parse counter and gauge values
8048 respectively, so anything supported by those functions is supported by the
8049 plugin as well. This option is mandatory.
8053 =head2 Plugin C<tail>
8055 The C<tail plugin> follows logfiles, just like L<tail(1)> does, parses
8056 each line and dispatches found values. What is matched can be configured by the
8057 user using (extended) regular expressions, as described in L<regex(7)>.
8060 <File "/var/log/exim4/mainlog">
8065 Regex "S=([1-9][0-9]*)"
8071 Regex "\\<R=local_user\\>"
8072 ExcludeRegex "\\<R=local_user\\>.*mail_spool defer"
8075 Instance "local_user"
8078 Regex "l=([0-9]*\\.[0-9]*)"
8079 <DSType "Distribution">
8082 #BucketType "bucket"
8090 The config consists of one or more B<File> blocks, each of which configures one
8091 logfile to parse. Within each B<File> block, there are one or more B<Match>
8092 blocks, which configure a regular expression to search for.
8094 The B<Plugin> and B<Instance> options in the B<File> block may be used to set
8095 the plugin name and instance respectively. So in the above example the plugin name
8096 C<mail-exim> would be used.
8098 These options are applied for all B<Match> blocks that B<follow> it, until the
8099 next B<Plugin> or B<Instance> option. This way you can extract several plugin
8100 instances from one logfile, handy when parsing syslog and the like.
8102 The B<Interval> option allows you to define the length of time between reads. If
8103 this is not set, the default Interval will be used.
8105 Each B<Match> block has the following options to describe how the match should
8110 =item B<Regex> I<regex>
8112 Sets the regular expression to use for matching against a line. The first
8113 subexpression has to match something that can be turned into a number by
8114 L<strtoll(3)> or L<strtod(3)>, depending on the value of C<CounterAdd>, see
8115 below. Because B<extended> regular expressions are used, you do not need to use
8116 backslashes for subexpressions! If in doubt, please consult L<regex(7)>. Due to
8117 collectd's config parsing you need to escape backslashes, though. So if you
8118 want to match literal parentheses you need to do the following:
8120 Regex "SPAM \\(Score: (-?[0-9]+\\.[0-9]+)\\)"
8122 =item B<ExcludeRegex> I<regex>
8124 Sets an optional regular expression to use for excluding lines from the match.
8125 An example which excludes all connections from localhost from the match:
8127 ExcludeRegex "127\\.0\\.0\\.1"
8129 =item B<DSType> I<Type>
8131 Sets how the values are cumulated. I<Type> is one of:
8135 =item B<GaugeAverage>
8137 Calculate the average.
8141 Use the smallest number only.
8145 Use the greatest number only.
8149 Use the last number found.
8151 =item B<GaugePersist>
8153 Use the last number found. The number is not reset at the end of an interval.
8154 It is continously reported until another number is matched. This is intended
8155 for cases in which only state changes are reported, for example a thermometer
8156 that only reports the temperature when it changes.
8162 =item B<AbsoluteSet>
8164 The matched number is a counter. Simply I<sets> the internal counter to this
8165 value. Variants exist for C<COUNTER>, C<DERIVE>, and C<ABSOLUTE> data sources.
8173 Add the matched value to the internal counter. In case of B<DeriveAdd>, the
8174 matched number may be negative, which will effectively subtract from the
8183 Increase the internal counter by one. These B<DSType> are the only ones that do
8184 not use the matched subexpression, but simply count the number of matched
8185 lines. Thus, you may use a regular expression without submatch in this case.
8187 =item B<Distribution>
8189 Type to do calculations based on the distribution of values, primarily
8190 calculating percentiles. This is primarily geared towards latency, but can be
8191 used for other metrics as well. The range of values tracked with this setting
8192 must be in the range (0–2^34) and can be fractional. Please note that neither
8193 zero nor 2^34 are inclusive bounds, i.e. zero I<cannot> be handled by a
8196 This option must be used together with the B<Percentile> and/or B<Bucket>
8201 <DSType "Distribution">
8209 =item B<Percentile> I<Percent>
8211 Calculate and dispatch the configured percentile, i.e. compute the value, so
8212 that I<Percent> of all matched values are smaller than or equal to the computed
8215 Metrics are reported with the I<type> B<Type> (the value of the above option)
8216 and the I<type instance> C<[E<lt>InstanceE<gt>-]E<lt>PercentE<gt>>.
8218 This option may be repeated to calculate more than one percentile.
8220 =item B<Bucket> I<lower_bound> I<upper_bound>
8222 Export the number of values (a C<DERIVE>) falling within the given range. Both,
8223 I<lower_bound> and I<upper_bound> may be a fractional number, such as B<0.5>.
8224 Each B<Bucket> option specifies an interval C<(I<lower_bound>,
8225 I<upper_bound>]>, i.e. the range I<excludes> the lower bound and I<includes>
8226 the upper bound. I<lower_bound> and I<upper_bound> may be zero, meaning no
8229 To export the entire (0–inf) range without overlap, use the upper bound of the
8230 previous range as the lower bound of the following range. In other words, use
8231 the following schema:
8241 Metrics are reported with the I<type> set by B<BucketType> option (C<bucket>
8242 by default) and the I<type instance>
8243 C<E<lt>TypeE<gt>[-E<lt>InstanceE<gt>]-E<lt>lower_boundE<gt>_E<lt>upper_boundE<gt>>.
8245 This option may be repeated to calculate more than one rate.
8247 =item B<BucketType> I<Type>
8249 Sets the type used to dispatch B<Bucket> metrics.
8250 Optional, by default C<bucket> will be used.
8256 The B<Gauge*> and B<Distribution> types interpret the submatch as a floating
8257 point number, using L<strtod(3)>. The B<Counter*> and B<AbsoluteSet> types
8258 interpret the submatch as an unsigned integer using L<strtoull(3)>. The
8259 B<Derive*> types interpret the submatch as a signed integer using
8260 L<strtoll(3)>. B<CounterInc> and B<DeriveInc> do not use the submatch at all
8261 and it may be omitted in this case.
8263 =item B<Type> I<Type>
8265 Sets the type used to dispatch this value. Detailed information about types and
8266 their configuration can be found in L<types.db(5)>.
8268 =item B<Instance> I<TypeInstance>
8270 This optional setting sets the type instance to use.
8274 =head2 Plugin C<tail_csv>
8276 The I<tail_csv plugin> reads files in the CSV format, e.g. the statistics file
8277 written by I<Snort>.
8282 <Metric "snort-dropped">
8287 <File "/var/log/snort/snort.stats">
8291 Collect "snort-dropped"
8295 The configuration consists of one or more B<Metric> blocks that define an index
8296 into the line of the CSV file and how this value is mapped to I<collectd's>
8297 internal representation. These are followed by one or more B<Instance> blocks
8298 which configure which file to read, in which interval and which metrics to
8303 =item E<lt>B<Metric> I<Name>E<gt>
8305 The B<Metric> block configures a new metric to be extracted from the statistics
8306 file and how it is mapped on I<collectd's> data model. The string I<Name> is
8307 only used inside the B<Instance> blocks to refer to this block, so you can use
8308 one B<Metric> block for multiple CSV files.
8312 =item B<Type> I<Type>
8314 Configures which I<Type> to use when dispatching this metric. Types are defined
8315 in the L<types.db(5)> file, see the appropriate manual page for more
8316 information on specifying types. Only types with a single I<data source> are
8317 supported by the I<tail_csv plugin>. The information whether the value is an
8318 absolute value (i.e. a C<GAUGE>) or a rate (i.e. a C<DERIVE>) is taken from the
8319 I<Type's> definition.
8321 =item B<Instance> I<TypeInstance>
8323 If set, I<TypeInstance> is used to populate the type instance field of the
8324 created value lists. Otherwise, no type instance is used.
8326 =item B<ValueFrom> I<Index>
8328 Configure to read the value from the field with the zero-based index I<Index>.
8329 If the value is parsed as signed integer, unsigned integer or double depends on
8330 the B<Type> setting, see above.
8334 =item E<lt>B<File> I<Path>E<gt>
8336 Each B<File> block represents one CSV file to read. There must be at least one
8337 I<File> block but there can be multiple if you have multiple CSV files.
8341 =item B<Plugin> I<Plugin>
8343 Use I<Plugin> as the plugin name when submitting values.
8344 Defaults to C<tail_csv>.
8346 =item B<Instance> I<PluginInstance>
8348 Sets the I<plugin instance> used when dispatching the values.
8350 =item B<Collect> I<Metric>
8352 Specifies which I<Metric> to collect. This option must be specified at least
8353 once, and you can use this option multiple times to specify more than one
8354 metric to be extracted from this statistic file.
8356 =item B<Interval> I<Seconds>
8358 Configures the interval in which to read values from this instance / file.
8359 Defaults to the plugin's default interval.
8361 =item B<TimeFrom> I<Index>
8363 Rather than using the local time when dispatching a value, read the timestamp
8364 from the field with the zero-based index I<Index>. The value is interpreted as
8365 seconds since epoch. The value is parsed as a double and may be factional.
8371 =head2 Plugin C<teamspeak2>
8373 The C<teamspeak2 plugin> connects to the query port of a teamspeak2 server and
8374 polls interesting global and virtual server data. The plugin can query only one
8375 physical server but unlimited virtual servers. You can use the following
8376 options to configure it:
8380 =item B<Host> I<hostname/ip>
8382 The hostname or ip which identifies the physical server.
8385 =item B<Port> I<port>
8387 The query port of the physical server. This needs to be a string.
8390 =item B<Server> I<port>
8392 This option has to be added once for every virtual server the plugin should
8393 query. If you want to query the virtual server on port 8767 this is what the
8394 option would look like:
8398 This option, although numeric, needs to be a string, i.E<nbsp>e. you B<must>
8399 use quotes around it! If no such statement is given only global information
8404 =head2 Plugin C<ted>
8406 The I<TED> plugin connects to a device of "The Energy Detective", a device to
8407 measure power consumption. These devices are usually connected to a serial
8408 (RS232) or USB port. The plugin opens a configured device and tries to read the
8409 current energy readings. For more information on TED, visit
8410 L<http://www.theenergydetective.com/>.
8412 Available configuration options:
8416 =item B<Device> I<Path>
8418 Path to the device on which TED is connected. collectd will need read and write
8419 permissions on that file.
8421 Default: B</dev/ttyUSB0>
8423 =item B<Retries> I<Num>
8425 Apparently reading from TED is not that reliable. You can therefore configure a
8426 number of retries here. You only configure the I<retries> here, to if you
8427 specify zero, one reading will be performed (but no retries if that fails); if
8428 you specify three, a maximum of four readings are performed. Negative values
8435 =head2 Plugin C<tcpconns>
8437 The C<tcpconns plugin> counts the number of currently established TCP
8438 connections based on the local port and/or the remote port. Since there may be
8439 a lot of connections the default if to count all connections with a local port,
8440 for which a listening socket is opened. You can use the following options to
8441 fine-tune the ports you are interested in:
8445 =item B<ListeningPorts> I<true>|I<false>
8447 If this option is set to I<true>, statistics for all local ports for which a
8448 listening socket exists are collected. The default depends on B<LocalPort> and
8449 B<RemotePort> (see below): If no port at all is specifically selected, the
8450 default is to collect listening ports. If specific ports (no matter if local or
8451 remote ports) are selected, this option defaults to I<false>, i.E<nbsp>e. only
8452 the selected ports will be collected unless this option is set to I<true>
8455 =item B<LocalPort> I<Port>
8457 Count the connections to a specific local port. This can be used to see how
8458 many connections are handled by a specific daemon, e.E<nbsp>g. the mailserver.
8459 You have to specify the port in numeric form, so for the mailserver example
8460 you'd need to set B<25>.
8462 =item B<RemotePort> I<Port>
8464 Count the connections to a specific remote port. This is useful to see how
8465 much a remote service is used. This is most useful if you want to know how many
8466 connections a local service has opened to remote services, e.E<nbsp>g. how many
8467 connections a mail server or news server has to other mail or news servers, or
8468 how many connections a web proxy holds to web servers. You have to give the
8469 port in numeric form.
8471 =item B<AllPortsSummary> I<true>|I<false>
8473 If this option is set to I<true> a summary of statistics from all connections
8474 are collected. This option defaults to I<false>.
8478 =head2 Plugin C<thermal>
8482 =item B<ForceUseProcfs> I<true>|I<false>
8484 By default, the I<Thermal plugin> tries to read the statistics from the Linux
8485 C<sysfs> interface. If that is not available, the plugin falls back to the
8486 C<procfs> interface. By setting this option to I<true>, you can force the
8487 plugin to use the latter. This option defaults to I<false>.
8489 =item B<Device> I<Device>
8491 Selects the name of the thermal device that you want to collect or ignore,
8492 depending on the value of the B<IgnoreSelected> option. This option may be
8493 used multiple times to specify a list of devices.
8495 See F</"IGNORELISTS"> for details.
8497 =item B<IgnoreSelected> I<true>|I<false>
8499 Invert the selection: If set to true, all devices B<except> the ones that
8500 match the device names specified by the B<Device> option are collected. By
8501 default only selected devices are collected if a selection is made. If no
8502 selection is configured at all, B<all> devices are selected.
8506 =head2 Plugin C<threshold>
8508 The I<Threshold plugin> checks values collected or received by I<collectd>
8509 against a configurable I<threshold> and issues I<notifications> if values are
8512 Documentation for this plugin is available in the L<collectd-threshold(5)>
8515 =head2 Plugin C<tokyotyrant>
8517 The I<TokyoTyrant plugin> connects to a TokyoTyrant server and collects a
8518 couple metrics: number of records, and database size on disk.
8522 =item B<Host> I<Hostname/IP>
8524 The hostname or IP which identifies the server.
8525 Default: B<127.0.0.1>
8527 =item B<Port> I<Service/Port>
8529 The query port of the server. This needs to be a string, even if the port is
8530 given in its numeric form.
8535 =head2 Plugin C<turbostat>
8537 The I<Turbostat plugin> reads CPU frequency and C-state residency on modern
8538 Intel processors by using I<Model Specific Registers>.
8542 =item B<CoreCstates> I<Bitmask(Integer)>
8544 Bit mask of the list of core C-states supported by the processor.
8545 This option should only be used if the automated detection fails.
8546 Default value extracted from the CPU model and family.
8548 Currently supported C-states (by this plugin): 3, 6, 7
8552 All states (3, 6 and 7):
8553 (1<<3) + (1<<6) + (1<<7) = 392
8555 =item B<PackageCstates> I<Bitmask(Integer)>
8557 Bit mask of the list of packages C-states supported by the processor. This
8558 option should only be used if the automated detection fails. Default value
8559 extracted from the CPU model and family.
8561 Currently supported C-states (by this plugin): 2, 3, 6, 7, 8, 9, 10
8565 States 2, 3, 6 and 7:
8566 (1<<2) + (1<<3) + (1<<6) + (1<<7) = 396
8568 =item B<SystemManagementInterrupt> I<true>|I<false>
8570 Boolean enabling the collection of the I/O System-Management Interrupt counter.
8571 This option should only be used if the automated detection fails or if you want
8572 to disable this feature.
8574 =item B<DigitalTemperatureSensor> I<true>|I<false>
8576 Boolean enabling the collection of the temperature of each core. This option
8577 should only be used if the automated detection fails or if you want to disable
8580 =item B<TCCActivationTemp> I<Temperature>
8582 I<Thermal Control Circuit Activation Temperature> of the installed CPU. This
8583 temperature is used when collecting the temperature of cores or packages. This
8584 option should only be used if the automated detection fails. Default value
8585 extracted from B<MSR_IA32_TEMPERATURE_TARGET>.
8587 =item B<RunningAveragePowerLimit> I<Bitmask(Integer)>
8589 Bit mask of the list of elements to be thermally monitored. This option should
8590 only be used if the automated detection fails or if you want to disable some
8591 collections. The different bits of this bit mask accepted by this plugin are:
8595 =item 0 ('1'): Package
8599 =item 2 ('4'): Cores
8601 =item 3 ('8'): Embedded graphic device
8605 =item B<LogicalCoreNames> I<true>|I<false>
8607 Boolean enabling the use of logical core numbering for per core statistics.
8608 When enabled, C<cpuE<lt>nE<gt>> is used as plugin instance, where I<n> is a
8609 dynamic number assigned by the kernel. Otherwise, C<coreE<lt>nE<gt>> is used
8610 if there is only one package and C<pkgE<lt>nE<gt>-coreE<lt>mE<gt>> if there is
8611 more than one, where I<n> is the n-th core of package I<m>.
8615 =head2 Plugin C<unixsock>
8619 =item B<SocketFile> I<Path>
8621 Sets the socket-file which is to be created.
8623 =item B<SocketGroup> I<Group>
8625 If running as root change the group of the UNIX-socket after it has been
8626 created. Defaults to B<collectd>.
8628 =item B<SocketPerms> I<Permissions>
8630 Change the file permissions of the UNIX-socket after it has been created. The
8631 permissions must be given as a numeric, octal value as you would pass to
8632 L<chmod(1)>. Defaults to B<0770>.
8634 =item B<DeleteSocket> B<false>|B<true>
8636 If set to B<true>, delete the socket file before calling L<bind(2)>, if a file
8637 with the given name already exists. If I<collectd> crashes a socket file may be
8638 left over, preventing the daemon from opening a new socket when restarted.
8639 Since this is potentially dangerous, this defaults to B<false>.
8643 =head2 Plugin C<uuid>
8645 This plugin, if loaded, causes the Hostname to be taken from the machine's
8646 UUID. The UUID is a universally unique designation for the machine, usually
8647 taken from the machine's BIOS. This is most useful if the machine is running in
8648 a virtual environment such as Xen, in which case the UUID is preserved across
8649 shutdowns and migration.
8651 The following methods are used to find the machine's UUID, in order:
8657 Check I</etc/uuid> (or I<UUIDFile>).
8661 Check for UUID from HAL (L<http://www.freedesktop.org/wiki/Software/hal>) if
8666 Check for UUID from C<dmidecode> / SMBIOS.
8670 Check for UUID from Xen hypervisor.
8674 If no UUID can be found then the hostname is not modified.
8678 =item B<UUIDFile> I<Path>
8680 Take the UUID from the given file (default I</etc/uuid>).
8684 =head2 Plugin C<varnish>
8686 The I<varnish plugin> collects information about Varnish, an HTTP accelerator.
8687 It collects a subset of the values displayed by L<varnishstat(1)>, and
8688 organizes them in categories which can be enabled or disabled. Currently only
8689 metrics shown in L<varnishstat(1)>'s I<MAIN> section are collected. The exact
8690 meaning of each metric can be found in L<varnish-counters(7)>.
8695 <Instance "example">
8699 CollectConnections true
8700 CollectDirectorDNS false
8704 CollectObjects false
8706 CollectSession false
8716 CollectWorkers false
8718 CollectMempool false
8719 CollectManagement false
8726 The configuration consists of one or more E<lt>B<Instance>E<nbsp>I<Name>E<gt>
8727 blocks. I<Name> is the parameter passed to "varnishd -n". If left empty, it
8728 will collectd statistics from the default "varnishd" instance (this should work
8729 fine in most cases).
8731 Inside each E<lt>B<Instance>E<gt> blocks, the following options are recognized:
8735 =item B<CollectBackend> B<true>|B<false>
8737 Back-end connection statistics, such as successful, reused,
8738 and closed connections. True by default.
8740 =item B<CollectBan> B<true>|B<false>
8742 Statistics about ban operations, such as number of bans added, retired, and
8743 number of objects tested against ban operations. Only available with Varnish
8744 3.x and above. False by default.
8746 =item B<CollectCache> B<true>|B<false>
8748 Cache hits and misses. True by default.
8750 =item B<CollectConnections> B<true>|B<false>
8752 Number of client connections received, accepted and dropped. True by default.
8754 =item B<CollectDirectorDNS> B<true>|B<false>
8756 DNS director lookup cache statistics. Only available with Varnish 3.x. False by
8759 =item B<CollectESI> B<true>|B<false>
8761 Edge Side Includes (ESI) parse statistics. False by default.
8763 =item B<CollectFetch> B<true>|B<false>
8765 Statistics about fetches (HTTP requests sent to the backend). False by default.
8767 =item B<CollectHCB> B<true>|B<false>
8769 Inserts and look-ups in the crit bit tree based hash. Look-ups are
8770 divided into locked and unlocked look-ups. False by default.
8772 =item B<CollectObjects> B<true>|B<false>
8774 Statistics on cached objects: number of objects expired, nuked (prematurely
8775 expired), saved, moved, etc. False by default.
8777 =item B<CollectPurge> B<true>|B<false>
8779 Statistics about purge operations, such as number of purges added, retired, and
8780 number of objects tested against purge operations. Only available with Varnish
8781 2.x. False by default.
8783 =item B<CollectSession> B<true>|B<false>
8785 Client session statistics. Number of past and current sessions, session herd and
8786 linger counters, etc. False by default. Note that if using Varnish 4.x, some
8787 metrics found in the Connections and Threads sections with previous versions of
8788 Varnish have been moved here.
8790 =item B<CollectSHM> B<true>|B<false>
8792 Statistics about the shared memory log, a memory region to store
8793 log messages which is flushed to disk when full. True by default.
8795 =item B<CollectSMA> B<true>|B<false>
8797 malloc or umem (umem_alloc(3MALLOC) based) storage statistics. The umem storage
8798 component is Solaris specific. Note: SMA, SMF and MSE share counters, enable
8799 only the one used by the Varnish instance. Only available with Varnish 2.x.
8802 =item B<CollectSMS> B<true>|B<false>
8804 synth (synthetic content) storage statistics. This storage
8805 component is used internally only. False by default.
8807 =item B<CollectSM> B<true>|B<false>
8809 file (memory mapped file) storage statistics. Only available with Varnish 2.x.,
8810 in varnish 4.x. use CollectSMF.
8813 =item B<CollectStruct> B<true>|B<false>
8815 Current varnish internal state statistics. Number of current sessions, objects
8816 in cache store, open connections to backends (with Varnish 2.x), etc. False by
8819 =item B<CollectTotals> B<true>|B<false>
8821 Collects overview counters, such as the number of sessions created,
8822 the number of requests and bytes transferred. False by default.
8824 =item B<CollectUptime> B<true>|B<false>
8826 Varnish uptime. Only available with Varnish 3.x and above. False by default.
8828 =item B<CollectVCL> B<true>|B<false>
8830 Number of total (available + discarded) VCL (config files). False by default.
8832 =item B<CollectVSM> B<true>|B<false>
8834 Collect statistics about Varnish's shared memory usage (used by the logging and
8835 statistics subsystems). Only available with Varnish 4.x. False by default.
8837 =item B<CollectWorkers> B<true>|B<false>
8839 Collect statistics about worker threads. False by default.
8841 =item B<CollectVBE> B<true>|B<false>
8843 Backend counters. Only available with Varnish 4.x. False by default.
8845 =item B<CollectSMF> B<true>|B<false>
8847 file (memory mapped file) storage statistics. Only available with Varnish 4.x.
8848 Note: SMA, SMF and MSE share counters, enable only the one used by the Varnish
8849 instance. Used to be called SM in Varnish 2.x. False by default.
8851 =item B<CollectManagement> B<true>|B<false>
8853 Management process counters. Only available with Varnish 4.x. False by default.
8855 =item B<CollectLock> B<true>|B<false>
8857 Lock counters. Only available with Varnish 4.x. False by default.
8859 =item B<CollectMempool> B<true>|B<false>
8861 Memory pool counters. Only available with Varnish 4.x. False by default.
8863 =item B<CollectMSE> B<true>|B<false>
8865 Varnish Massive Storage Engine 2.0 (MSE2) is an improved storage backend for
8866 Varnish, replacing the traditional malloc and file storages. Only available
8867 with Varnish-Plus 4.x. Note: SMA, SMF and MSE share counters, enable only the
8868 one used by the Varnish instance. False by default.
8872 =head2 Plugin C<virt>
8874 This plugin allows CPU, disk, network load and other metrics to be collected for
8875 virtualized guests on the machine. The statistics are collected through libvirt
8876 API (L<http://libvirt.org/>). Majority of metrics can be gathered without
8877 installing any additional software on guests, especially I<collectd>, which runs
8878 only on the host system.
8880 Only I<Connection> is required.
8884 =item B<Connection> I<uri>
8886 Connect to the hypervisor given by I<uri>. For example if using Xen use:
8888 Connection "xen:///"
8890 Details which URIs allowed are given at L<http://libvirt.org/uri.html>.
8892 =item B<RefreshInterval> I<seconds>
8894 Refresh the list of domains and devices every I<seconds>. The default is 60
8895 seconds. Setting this to be the same or smaller than the I<Interval> will cause
8896 the list of domains and devices to be refreshed on every iteration.
8898 Refreshing the devices in particular is quite a costly operation, so if your
8899 virtualization setup is static you might consider increasing this. If this
8900 option is set to 0, refreshing is disabled completely.
8902 =item B<Domain> I<name>
8904 =item B<BlockDevice> I<name:dev>
8906 =item B<InterfaceDevice> I<name:dev>
8908 =item B<IgnoreSelected> B<true>|B<false>
8910 Select which domains and devices are collected.
8912 If I<IgnoreSelected> is not given or B<false> then only the listed domains and
8913 disk/network devices are collected.
8915 If I<IgnoreSelected> is B<true> then the test is reversed and the listed
8916 domains and disk/network devices are ignored, while the rest are collected.
8918 The domain name and device names may use a regular expression, if the name is
8919 surrounded by I</.../> and collectd was compiled with support for regexps.
8921 The default is to collect statistics for all domains and all their devices.
8925 BlockDevice "/:hdb/"
8926 IgnoreSelected "true"
8928 Ignore all I<hdb> devices on any domain, but other block devices (eg. I<hda>)
8931 =item B<BlockDeviceFormat> B<target>|B<source>
8933 If I<BlockDeviceFormat> is set to B<target>, the default, then the device name
8934 seen by the guest will be used for reporting metrics.
8935 This corresponds to the C<E<lt>targetE<gt>> node in the XML definition of the
8938 If I<BlockDeviceFormat> is set to B<source>, then metrics will be reported
8939 using the path of the source, e.g. an image file.
8940 This corresponds to the C<E<lt>sourceE<gt>> node in the XML definition of the
8945 If the domain XML have the following device defined:
8947 <disk type='block' device='disk'>
8948 <driver name='qemu' type='raw' cache='none' io='native' discard='unmap'/>
8949 <source dev='/var/lib/libvirt/images/image1.qcow2'/>
8950 <target dev='sda' bus='scsi'/>
8952 <address type='drive' controller='0' bus='0' target='0' unit='0'/>
8955 Setting C<BlockDeviceFormat target> will cause the I<type instance> to be set
8957 Setting C<BlockDeviceFormat source> will cause the I<type instance> to be set
8958 to C<var_lib_libvirt_images_image1.qcow2>.
8960 =item B<BlockDeviceFormatBasename> B<false>|B<true>
8962 The B<BlockDeviceFormatBasename> controls whether the full path or the
8963 L<basename(1)> of the source is being used as the I<type instance> when
8964 B<BlockDeviceFormat> is set to B<source>. Defaults to B<false>.
8968 Assume the device path (source tag) is C</var/lib/libvirt/images/image1.qcow2>.
8969 Setting C<BlockDeviceFormatBasename false> will cause the I<type instance> to
8970 be set to C<var_lib_libvirt_images_image1.qcow2>.
8971 Setting C<BlockDeviceFormatBasename true> will cause the I<type instance> to be
8972 set to C<image1.qcow2>.
8974 =item B<HostnameFormat> B<name|uuid|hostname|...>
8976 When the virt plugin logs data, it sets the hostname of the collected data
8977 according to this setting. The default is to use the guest name as provided by
8978 the hypervisor, which is equal to setting B<name>.
8980 B<uuid> means use the guest's UUID. This is useful if you want to track the
8981 same guest across migrations.
8983 B<hostname> means to use the global B<Hostname> setting, which is probably not
8984 useful on its own because all guests will appear to have the same name.
8986 You can also specify combinations of these fields. For example B<name uuid>
8987 means to concatenate the guest name and UUID (with a literal colon character
8988 between, thus I<"foo:1234-1234-1234-1234">).
8990 At the moment of writing (collectd-5.5), hostname string is limited to 62
8991 characters. In case when combination of fields exceeds 62 characters,
8992 hostname will be truncated without a warning.
8994 =item B<InterfaceFormat> B<name>|B<address>
8996 When the virt plugin logs interface data, it sets the name of the collected
8997 data according to this setting. The default is to use the path as provided by
8998 the hypervisor (the "dev" property of the target node), which is equal to
9001 B<address> means use the interface's mac address. This is useful since the
9002 interface path might change between reboots of a guest or across migrations.
9004 =item B<PluginInstanceFormat> B<name|uuid|none>
9006 When the virt plugin logs data, it sets the plugin_instance of the collected
9007 data according to this setting. The default is to not set the plugin_instance.
9009 B<name> means use the guest's name as provided by the hypervisor.
9010 B<uuid> means use the guest's UUID.
9012 You can also specify combinations of the B<name> and B<uuid> fields.
9013 For example B<name uuid> means to concatenate the guest name and UUID
9014 (with a literal colon character between, thus I<"foo:1234-1234-1234-1234">).
9016 =item B<Instances> B<integer>
9018 How many read instances you want to use for this plugin. The default is one,
9019 and the sensible setting is a multiple of the B<ReadThreads> value.
9020 If you are not sure, just use the default setting.
9022 =item B<ExtraStats> B<string>
9024 Report additional extra statistics. The default is no extra statistics, preserving
9025 the previous behaviour of the plugin. If unsure, leave the default. If enabled,
9026 allows the plugin to reported more detailed statistics about the behaviour of
9027 Virtual Machines. The argument is a space-separated list of selectors.
9029 Currently supported selectors are:
9033 =item B<cpu_util>: report CPU utilization per domain in percentage.
9035 =item B<disk>: report extra statistics like number of flush operations and total
9036 service time for read, write and flush operations. Requires libvirt API version
9039 =item B<disk_err>: report disk errors if any occured. Requires libvirt API version
9042 =item B<domain_state>: report domain state and reason in human-readable format as
9043 a notification. If libvirt API version I<0.9.2> or later is available, domain
9044 reason will be included in notification.
9046 =item B<fs_info>: report file system information as a notification. Requires
9047 libvirt API version I<1.2.11> or later. Can be collected only if I<Guest Agent>
9048 is installed and configured inside VM. Make sure that installed I<Guest Agent>
9049 version supports retrieving file system information.
9051 =item B<job_stats_background>: report statistics about progress of a background
9052 job on a domain. Only one type of job statistics can be collected at the same time.
9053 Requires libvirt API version I<1.2.9> or later.
9055 =item B<job_stats_completed>: report statistics about a recently completed job on
9056 a domain. Only one type of job statistics can be collected at the same time.
9057 Requires libvirt API version I<1.2.9> or later.
9059 =item B<pcpu>: report the physical user/system cpu time consumed by the hypervisor, per-vm.
9060 Requires libvirt API version I<0.9.11> or later.
9062 =item B<perf>: report performance monitoring events. To collect performance
9063 metrics they must be enabled for domain and supported by the platform. Requires
9064 libvirt API version I<1.3.3> or later.
9065 B<Note>: I<perf> metrics can't be collected if I<intel_rdt> plugin is enabled.
9067 =item B<vcpupin>: report pinning of domain VCPUs to host physical CPUs.
9073 =head2 Plugin C<vmem>
9075 The C<vmem> plugin collects information about the usage of virtual memory.
9076 Since the statistics provided by the Linux kernel are very detailed, they are
9077 collected very detailed. However, to get all the details, you have to switch
9078 them on manually. Most people just want an overview over, such as the number of
9079 pages read from swap space.
9083 =item B<Verbose> B<true>|B<false>
9085 Enables verbose collection of information. This will start collecting page
9086 "actions", e.E<nbsp>g. page allocations, (de)activations, steals and so on.
9087 Part of these statistics are collected on a "per zone" basis.
9091 =head2 Plugin C<vserver>
9093 This plugin doesn't have any options. B<VServer> support is only available for
9094 Linux. It cannot yet be found in a vanilla kernel, though. To make use of this
9095 plugin you need a kernel that has B<VServer> support built in, i.E<nbsp>e. you
9096 need to apply the patches and compile your own kernel, which will then provide
9097 the F</proc/virtual> filesystem that is required by this plugin.
9099 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
9101 B<Note>: The traffic collected by this plugin accounts for the amount of
9102 traffic passing a socket which might be a lot less than the actual on-wire
9103 traffic (e.E<nbsp>g. due to headers and retransmission). If you want to
9104 collect on-wire traffic you could, for example, use the logging facilities of
9105 iptables to feed data for the guest IPs into the iptables plugin.
9107 =head2 Plugin C<write_graphite>
9109 The C<write_graphite> plugin writes data to I<Graphite>, an open-source metrics
9110 storage and graphing project. The plugin connects to I<Carbon>, the data layer
9111 of I<Graphite>, via I<TCP> or I<UDP> and sends data via the "line based"
9112 protocol (per default using portE<nbsp>2003). The data will be sent in blocks
9113 of at most 1428 bytes to minimize the number of network packets.
9117 <Plugin write_graphite>
9127 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
9128 blocks. Inside the B<Node> blocks, the following options are recognized:
9132 =item B<Host> I<Address>
9134 Hostname or address to connect to. Defaults to C<localhost>.
9136 =item B<Port> I<Service>
9138 Service name or port number to connect to. Defaults to C<2003>.
9140 =item B<Protocol> I<String>
9142 Protocol to use when connecting to I<Graphite>. Defaults to C<tcp>.
9144 =item B<ReconnectInterval> I<Seconds>
9146 When set to non-zero, forces the connection to the Graphite backend to be
9147 closed and re-opend periodically. This behavior is desirable in environments
9148 where the connection to the Graphite backend is done through load balancers,
9149 for example. When set to zero, the default, the connetion is kept open for as
9152 =item B<LogSendErrors> B<false>|B<true>
9154 If set to B<true> (the default), logs errors when sending data to I<Graphite>.
9155 If set to B<false>, it will not log the errors. This is especially useful when
9156 using Protocol UDP since many times we want to use the "fire-and-forget"
9157 approach and logging errors fills syslog with unneeded messages.
9159 =item B<Prefix> I<String>
9161 When set, I<String> is added in front of the host name. Dots and whitespace are
9162 I<not> escaped in this string (see B<EscapeCharacter> below).
9164 =item B<Postfix> I<String>
9166 When set, I<String> is appended to the host name. Dots and whitespace are
9167 I<not> escaped in this string (see B<EscapeCharacter> below).
9169 =item B<EscapeCharacter> I<Char>
9171 I<Carbon> uses the dot (C<.>) as escape character and doesn't allow whitespace
9172 in the identifier. The B<EscapeCharacter> option determines which character
9173 dots, whitespace and control characters are replaced with. Defaults to
9176 =item B<StoreRates> B<false>|B<true>
9178 If set to B<true> (the default), convert counter values to rates. If set to
9179 B<false> counter values are stored as is, i.E<nbsp>e. as an increasing integer
9182 =item B<SeparateInstances> B<false>|B<true>
9184 If set to B<true>, the plugin instance and type instance will be in their own
9185 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
9186 default), the plugin and plugin instance (and likewise the type and type
9187 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
9189 =item B<AlwaysAppendDS> B<false>|B<true>
9191 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
9192 identifier. If set to B<false> (the default), this is only done when there is
9195 =item B<PreserveSeparator> B<false>|B<true>
9197 If set to B<false> (the default) the C<.> (dot) character is replaced with
9198 I<EscapeCharacter>. Otherwise, if set to B<true>, the C<.> (dot) character
9199 is preserved, i.e. passed through.
9201 =item B<DropDuplicateFields> B<false>|B<true>
9203 If set to B<true>, detect and remove duplicate components in Graphite metric
9204 names. For example, the metric name C<host.load.load.shortterm> will
9205 be shortened to C<host.load.shortterm>.
9209 =head2 Plugin C<write_log>
9211 The C<write_log> plugin writes metrics as INFO log messages.
9213 This plugin supports two output formats: I<Graphite> and I<JSON>.
9223 =item B<Format> I<Format>
9225 The output format to use. Can be one of C<Graphite> or C<JSON>.
9229 =head2 Plugin C<write_tsdb>
9231 The C<write_tsdb> plugin writes data to I<OpenTSDB>, a scalable open-source
9232 time series database. The plugin connects to a I<TSD>, a masterless, no shared
9233 state daemon that ingests metrics and stores them in HBase. The plugin uses
9234 I<TCP> over the "line based" protocol with a default port 4242. The data will
9235 be sent in blocks of at most 1428 bytes to minimize the number of network
9244 Host "tsd-1.my.domain"
9246 HostTags "status=production"
9250 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
9251 blocks and global directives.
9253 Global directives are:
9257 =item B<ResolveInterval> I<seconds>
9259 =item B<ResolveJitter> I<seconds>
9261 When I<collectd> connects to a TSDB node, it will request the hostname from
9262 DNS. This can become a problem if the TSDB node is unavailable or badly
9263 configured because collectd will request DNS in order to reconnect for every
9264 metric, which can flood your DNS. So you can cache the last value for
9265 I<ResolveInterval> seconds.
9266 Defaults to the I<Interval> of the I<write_tsdb plugin>, e.g. 10E<nbsp>seconds.
9268 You can also define a jitter, a random interval to wait in addition to
9269 I<ResolveInterval>. This prevents all your collectd servers to resolve the
9270 hostname at the same time when the connection fails.
9271 Defaults to the I<Interval> of the I<write_tsdb plugin>, e.g. 10E<nbsp>seconds.
9273 B<Note:> If the DNS resolution has already been successful when the socket
9274 closes, the plugin will try to reconnect immediately with the cached
9275 information. DNS is queried only when the socket is closed for a longer than
9276 I<ResolveInterval> + I<ResolveJitter> seconds.
9280 Inside the B<Node> blocks, the following options are recognized:
9284 =item B<Host> I<Address>
9286 Hostname or address to connect to. Defaults to C<localhost>.
9288 =item B<Port> I<Service>
9290 Service name or port number to connect to. Defaults to C<4242>.
9293 =item B<HostTags> I<String>
9295 When set, I<HostTags> is added to the end of the metric. It is intended to be
9296 used for name=value pairs that the TSD will tag the metric with. Dots and
9297 whitespace are I<not> escaped in this string.
9299 =item B<StoreRates> B<false>|B<true>
9301 If set to B<true>, convert counter values to rates. If set to B<false>
9302 (the default) counter values are stored as is, as an increasing
9305 =item B<AlwaysAppendDS> B<false>|B<true>
9307 If set the B<true>, append the name of the I<Data Source> (DS) to the "metric"
9308 identifier. If set to B<false> (the default), this is only done when there is
9313 =head2 Plugin C<write_mongodb>
9315 The I<write_mongodb plugin> will send values to I<MongoDB>, a schema-less
9320 <Plugin "write_mongodb">
9329 The plugin can send values to multiple instances of I<MongoDB> by specifying
9330 one B<Node> block for each instance. Within the B<Node> blocks, the following
9331 options are available:
9335 =item B<Host> I<Address>
9337 Hostname or address to connect to. Defaults to C<localhost>.
9339 =item B<Port> I<Service>
9341 Service name or port number to connect to. Defaults to C<27017>.
9343 =item B<Timeout> I<Milliseconds>
9345 Set the timeout for each operation on I<MongoDB> to I<Timeout> milliseconds.
9346 Setting this option to zero means no timeout, which is the default.
9348 =item B<StoreRates> B<false>|B<true>
9350 If set to B<true> (the default), convert counter values to rates. If set to
9351 B<false> counter values are stored as is, i.e. as an increasing integer
9354 =item B<Database> I<Database>
9356 =item B<User> I<User>
9358 =item B<Password> I<Password>
9360 Sets the information used when authenticating to a I<MongoDB> database. The
9361 fields are optional (in which case no authentication is attempted), but if you
9362 want to use authentication all three fields must be set.
9366 =head2 Plugin C<write_prometheus>
9368 The I<write_prometheus plugin> implements a tiny webserver that can be scraped
9369 using I<Prometheus>.
9375 =item B<Port> I<Port>
9377 Port the embedded webserver should listen on. Defaults to B<9103>.
9379 =item B<StalenessDelta> I<Seconds>
9381 Time in seconds after which I<Prometheus> considers a metric "stale" if it
9382 hasn't seen any update for it. This value must match the setting in Prometheus.
9383 It defaults to B<300> seconds (5 minutes), same as Prometheus.
9387 I<Prometheus> has a global setting, C<StalenessDelta>, which controls after
9388 which time a metric without updates is considered "stale". This setting
9389 effectively puts an upper limit on the interval in which metrics are reported.
9391 When the I<write_prometheus plugin> encounters a metric with an interval
9392 exceeding this limit, it will inform you, the user, and provide the metric to
9393 I<Prometheus> B<without> a timestamp. That causes I<Prometheus> to consider the
9394 metric "fresh" each time it is scraped, with the time of the scrape being
9395 considered the time of the update. The result is that there appear more
9396 datapoints in I<Prometheus> than were actually created, but at least the metric
9397 doesn't disappear periodically.
9401 =head2 Plugin C<write_http>
9403 This output plugin submits values to an HTTP server using POST requests and
9404 encoding metrics with JSON or using the C<PUTVAL> command described in
9405 L<collectd-unixsock(5)>.
9409 <Plugin "write_http">
9411 URL "http://example.com/post-collectd"
9418 The plugin can send values to multiple HTTP servers by specifying one
9419 E<lt>B<Node>E<nbsp>I<Name>E<gt> block for each server. Within each B<Node>
9420 block, the following options are available:
9426 URL to which the values are submitted to. Mandatory.
9428 =item B<User> I<Username>
9430 Optional user name needed for authentication.
9432 =item B<Password> I<Password>
9434 Optional password needed for authentication.
9436 =item B<VerifyPeer> B<true>|B<false>
9438 Enable or disable peer SSL certificate verification. See
9439 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
9441 =item B<VerifyHost> B<true|false>
9443 Enable or disable peer host name verification. If enabled, the plugin checks if
9444 the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
9445 matches the host name provided by the B<URL> option. If this identity check
9446 fails, the connection is aborted. Obviously, only works when connecting to a
9447 SSL enabled server. Enabled by default.
9449 =item B<CACert> I<File>
9451 File that holds one or more SSL certificates. If you want to use HTTPS you will
9452 possibly need this option. What CA certificates come bundled with C<libcurl>
9453 and are checked by default depends on the distribution you use.
9455 =item B<CAPath> I<Directory>
9457 Directory holding one or more CA certificate files. You can use this if for
9458 some reason all the needed CA certificates aren't in the same file and can't be
9459 pointed to using the B<CACert> option. Requires C<libcurl> to be built against
9462 =item B<ClientKey> I<File>
9464 File that holds the private key in PEM format to be used for certificate-based
9467 =item B<ClientCert> I<File>
9469 File that holds the SSL certificate to be used for certificate-based
9472 =item B<ClientKeyPass> I<Password>
9474 Password required to load the private key in B<ClientKey>.
9476 =item B<Header> I<Header>
9478 A HTTP header to add to the request. Multiple headers are added if this option is specified more than once. Example:
9480 Header "X-Custom-Header: custom_value"
9482 =item B<SSLVersion> B<SSLv2>|B<SSLv3>|B<TLSv1>|B<TLSv1_0>|B<TLSv1_1>|B<TLSv1_2>
9484 Define which SSL protocol version must be used. By default C<libcurl> will
9485 attempt to figure out the remote SSL protocol version. See
9486 L<curl_easy_setopt(3)> for more details.
9488 =item B<Format> B<Command>|B<JSON>|B<KAIROSDB>
9490 Format of the output to generate. If set to B<Command>, will create output that
9491 is understood by the I<Exec> and I<UnixSock> plugins. When set to B<JSON>, will
9492 create output in the I<JavaScript Object Notation> (JSON). When set to KAIROSDB
9493 , will create output in the KairosDB format.
9495 Defaults to B<Command>.
9497 =item B<Attribute> I<String> I<String>
9499 Only available for the KAIROSDB output format.
9501 Consider the two given strings to be the key and value of an additional tag for
9502 each metric being sent out.
9504 You can add multiple B<Attribute>.
9508 Only available for the KAIROSDB output format.
9510 Sets the Cassandra ttl for the data points.
9512 Please refer to L<http://kairosdb.github.io/docs/build/html/restapi/AddDataPoints.html?highlight=ttl>
9514 =item B<Prefix> I<String>
9516 Only available for the KAIROSDB output format.
9518 Sets the metrics prefix I<string>. Defaults to I<collectd>.
9520 =item B<Metrics> B<true>|B<false>
9522 Controls whether I<metrics> are POSTed to this location. Defaults to B<true>.
9524 =item B<Notifications> B<false>|B<true>
9526 Controls whether I<notifications> are POSTed to this location. Defaults to B<false>.
9528 =item B<StoreRates> B<true|false>
9530 If set to B<true>, convert counter values to rates. If set to B<false> (the
9531 default) counter values are stored as is, i.e. as an increasing integer number.
9533 =item B<BufferSize> I<Bytes>
9535 Sets the send buffer size to I<Bytes>. By increasing this buffer, less HTTP
9536 requests will be generated, but more metrics will be batched / metrics are
9537 cached for longer before being sent, introducing additional delay until they
9538 are available on the server side. I<Bytes> must be at least 1024 and cannot
9539 exceed the size of an C<int>, i.e. 2E<nbsp>GByte.
9540 Defaults to C<4096>.
9542 =item B<LowSpeedLimit> I<Bytes per Second>
9544 Sets the minimal transfer rate in I<Bytes per Second> below which the
9545 connection with the HTTP server will be considered too slow and aborted. All
9546 the data submitted over this connection will probably be lost. Defaults to 0,
9547 which means no minimum transfer rate is enforced.
9549 =item B<Timeout> I<Timeout>
9551 Sets the maximum time in milliseconds given for HTTP POST operations to
9552 complete. When this limit is reached, the POST operation will be aborted, and
9553 all the data in the current send buffer will probably be lost. Defaults to 0,
9554 which means the connection never times out.
9556 =item B<LogHttpError> B<false>|B<true>
9558 Enables printing of HTTP error code to log. Turned off by default.
9560 The C<write_http> plugin regularly submits the collected values to the HTTP
9561 server. How frequently this happens depends on how much data you are collecting
9562 and the size of B<BufferSize>. The optimal value to set B<Timeout> to is
9563 slightly below this interval, which you can estimate by monitoring the network
9564 traffic between collectd and the HTTP server.
9568 =head2 Plugin C<write_kafka>
9570 The I<write_kafka plugin> will send values to a I<Kafka> topic, a distributed
9574 <Plugin "write_kafka">
9575 Property "metadata.broker.list" "broker1:9092,broker2:9092"
9581 The following options are understood by the I<write_kafka plugin>:
9585 =item E<lt>B<Topic> I<Name>E<gt>
9587 The plugin's configuration consists of one or more B<Topic> blocks. Each block
9588 is given a unique I<Name> and specifies one kafka producer.
9589 Inside the B<Topic> block, the following per-topic options are
9594 =item B<Property> I<String> I<String>
9596 Configure the named property for the current topic. Properties are
9597 forwarded to the kafka producer library B<librdkafka>.
9599 =item B<Key> I<String>
9601 Use the specified string as a partitioning key for the topic. Kafka breaks
9602 topic into partitions and guarantees that for a given topology, the same
9603 consumer will be used for a specific key. The special (case insensitive)
9604 string B<Random> can be used to specify that an arbitrary partition should
9607 =item B<Format> B<Command>|B<JSON>|B<Graphite>
9609 Selects the format in which messages are sent to the broker. If set to
9610 B<Command> (the default), values are sent as C<PUTVAL> commands which are
9611 identical to the syntax used by the I<Exec> and I<UnixSock plugins>.
9613 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
9614 an easy and straight forward exchange format.
9616 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
9617 C<E<lt>metricE<gt> E<lt>valueE<gt> E<lt>timestampE<gt>\n>.
9619 =item B<StoreRates> B<true>|B<false>
9621 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
9622 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
9623 default), no conversion is performed. Otherwise the conversion is performed
9624 using the internal value cache.
9626 Please note that currently this option is only used if the B<Format> option has
9627 been set to B<JSON>.
9629 =item B<GraphitePrefix> (B<Format>=I<Graphite> only)
9631 A prefix can be added in the metric name when outputting in the I<Graphite>
9632 format. It's added before the I<Host> name.
9634 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>>
9636 =item B<GraphitePostfix> (B<Format>=I<Graphite> only)
9638 A postfix can be added in the metric name when outputting in the I<Graphite>
9639 format. It's added after the I<Host> name.
9641 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>>
9643 =item B<GraphiteEscapeChar> (B<Format>=I<Graphite> only)
9645 Specify a character to replace dots (.) in the host part of the metric name.
9646 In I<Graphite> metric name, dots are used as separators between different
9647 metric parts (host, plugin, type).
9648 Default is C<_> (I<Underscore>).
9650 =item B<GraphiteSeparateInstances> B<false>|B<true>
9652 If set to B<true>, the plugin instance and type instance will be in their own
9653 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
9654 default), the plugin and plugin instance (and likewise the type and type
9655 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
9657 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
9659 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
9660 identifier. If set to B<false> (the default), this is only done when there is
9663 =item B<GraphitePreserveSeparator> B<false>|B<true>
9665 If set to B<false> (the default) the C<.> (dot) character is replaced with
9666 I<GraphiteEscapeChar>. Otherwise, if set to B<true>, the C<.> (dot) character
9667 is preserved, i.e. passed through.
9669 =item B<StoreRates> B<true>|B<false>
9671 If set to B<true> (the default), convert counter values to rates. If set to
9672 B<false> counter values are stored as is, i.e. as an increasing integer number.
9674 This will be reflected in the C<ds_type> tag: If B<StoreRates> is enabled,
9675 converted values will have "rate" appended to the data source type, e.g.
9676 C<ds_type:derive:rate>.
9680 =item B<Property> I<String> I<String>
9682 Configure the kafka producer through properties, you almost always will
9683 want to set B<metadata.broker.list> to your Kafka broker list.
9687 =head2 Plugin C<write_redis>
9689 The I<write_redis plugin> submits values to I<Redis>, a data structure server.
9693 <Plugin "write_redis">
9706 Values are submitted to I<Sorted Sets>, using the metric name as the key, and
9707 the timestamp as the score. Retrieving a date range can then be done using the
9708 C<ZRANGEBYSCORE> I<Redis> command. Additionally, all the identifiers of these
9709 I<Sorted Sets> are kept in a I<Set> called C<collectd/values> (or
9710 C<${prefix}/values> if the B<Prefix> option was specified) and can be retrieved
9711 using the C<SMEMBERS> I<Redis> command. You can specify the database to use
9712 with the B<Database> parameter (default is C<0>). See
9713 L<http://redis.io/commands#sorted_set> and L<http://redis.io/commands#set> for
9716 The information shown in the synopsis above is the I<default configuration>
9717 which is used by the plugin if no configuration is present.
9719 The plugin can send values to multiple instances of I<Redis> by specifying
9720 one B<Node> block for each instance. Within the B<Node> blocks, the following
9721 options are available:
9725 =item B<Node> I<Nodename>
9727 The B<Node> block identifies a new I<Redis> node, that is a new I<Redis>
9728 instance running on a specified host and port. The node name is a
9729 canonical identifier which is used as I<plugin instance>. It is limited to
9730 51E<nbsp>characters in length.
9732 =item B<Host> I<Hostname>
9734 The B<Host> option is the hostname or IP-address where the I<Redis> instance is
9737 =item B<Port> I<Port>
9739 The B<Port> option is the TCP port on which the Redis instance accepts
9740 connections. Either a service name of a port number may be given. Please note
9741 that numerical port numbers must be given as a string, too.
9743 =item B<Timeout> I<Milliseconds>
9745 The B<Timeout> option sets the socket connection timeout, in milliseconds.
9747 =item B<Prefix> I<Prefix>
9749 Prefix used when constructing the name of the I<Sorted Sets> and the I<Set>
9750 containing all metrics. Defaults to C<collectd/>, so metrics will have names
9751 like C<collectd/cpu-0/cpu-user>. When setting this to something different, it
9752 is recommended but not required to include a trailing slash in I<Prefix>.
9754 =item B<Database> I<Index>
9756 This index selects the redis database to use for writing operations. Defaults
9759 =item B<MaxSetSize> I<Items>
9761 The B<MaxSetSize> option limits the number of items that the I<Sorted Sets> can
9762 hold. Negative values for I<Items> sets no limit, which is the default behavior.
9764 =item B<MaxSetDuration> I<Seconds>
9766 The B<MaxSetDuration> option limits the duration of items that the
9767 I<Sorted Sets> can hold. Negative values for I<Items> sets no duration, which
9768 is the default behavior.
9770 =item B<StoreRates> B<true>|B<false>
9772 If set to B<true> (the default), convert counter values to rates. If set to
9773 B<false> counter values are stored as is, i.e. as an increasing integer number.
9777 =head2 Plugin C<write_riemann>
9779 The I<write_riemann plugin> will send values to I<Riemann>, a powerful stream
9780 aggregation and monitoring system. The plugin sends I<Protobuf> encoded data to
9781 I<Riemann> using UDP packets.
9785 <Plugin "write_riemann">
9791 AlwaysAppendDS false
9795 Attribute "foo" "bar"
9798 The following options are understood by the I<write_riemann plugin>:
9802 =item E<lt>B<Node> I<Name>E<gt>
9804 The plugin's configuration consists of one or more B<Node> blocks. Each block
9805 is given a unique I<Name> and specifies one connection to an instance of
9806 I<Riemann>. Indise the B<Node> block, the following per-connection options are
9811 =item B<Host> I<Address>
9813 Hostname or address to connect to. Defaults to C<localhost>.
9815 =item B<Port> I<Service>
9817 Service name or port number to connect to. Defaults to C<5555>.
9819 =item B<Protocol> B<UDP>|B<TCP>|B<TLS>
9821 Specify the protocol to use when communicating with I<Riemann>. Defaults to
9824 =item B<TLSCertFile> I<Path>
9826 When using the B<TLS> protocol, path to a PEM certificate to present
9829 =item B<TLSCAFile> I<Path>
9831 When using the B<TLS> protocol, path to a PEM CA certificate to
9832 use to validate the remote hosts's identity.
9834 =item B<TLSKeyFile> I<Path>
9836 When using the B<TLS> protocol, path to a PEM private key associated
9837 with the certificate defined by B<TLSCertFile>.
9839 =item B<Batch> B<true>|B<false>
9841 If set to B<true> and B<Protocol> is set to B<TCP>,
9842 events will be batched in memory and flushed at
9843 regular intervals or when B<BatchMaxSize> is exceeded.
9845 Notifications are not batched and sent as soon as possible.
9847 When enabled, it can occur that events get processed by the Riemann server
9848 close to or after their expiration time. Tune the B<TTLFactor> and
9849 B<BatchMaxSize> settings according to the amount of values collected, if this
9854 =item B<BatchMaxSize> I<size>
9856 Maximum payload size for a riemann packet. Defaults to 8192
9858 =item B<BatchFlushTimeout> I<seconds>
9860 Maximum amount of seconds to wait in between to batch flushes.
9861 No timeout by default.
9863 =item B<StoreRates> B<true>|B<false>
9865 If set to B<true> (the default), convert counter values to rates. If set to
9866 B<false> counter values are stored as is, i.e. as an increasing integer number.
9868 This will be reflected in the C<ds_type> tag: If B<StoreRates> is enabled,
9869 converted values will have "rate" appended to the data source type, e.g.
9870 C<ds_type:derive:rate>.
9872 =item B<AlwaysAppendDS> B<false>|B<true>
9874 If set to B<true>, append the name of the I<Data Source> (DS) to the
9875 "service", i.e. the field that, together with the "host" field, uniquely
9876 identifies a metric in I<Riemann>. If set to B<false> (the default), this is
9877 only done when there is more than one DS.
9879 =item B<TTLFactor> I<Factor>
9881 I<Riemann> events have a I<Time to Live> (TTL) which specifies how long each
9882 event is considered active. I<collectd> populates this field based on the
9883 metrics interval setting. This setting controls the factor with which the
9884 interval is multiplied to set the TTL. The default value is B<2.0>. Unless you
9885 know exactly what you're doing, you should only increase this setting from its
9888 =item B<Notifications> B<false>|B<true>
9890 If set to B<true>, create riemann events for notifications. This is B<true>
9891 by default. When processing thresholds from write_riemann, it might prove
9892 useful to avoid getting notification events.
9894 =item B<CheckThresholds> B<false>|B<true>
9896 If set to B<true>, attach state to events based on thresholds defined
9897 in the B<Threshold> plugin. Defaults to B<false>.
9899 =item B<EventServicePrefix> I<String>
9901 Add the given string as a prefix to the event service name.
9902 If B<EventServicePrefix> not set or set to an empty string (""),
9903 no prefix will be used.
9907 =item B<Tag> I<String>
9909 Add the given string as an additional tag to the metric being sent to
9912 =item B<Attribute> I<String> I<String>
9914 Consider the two given strings to be the key and value of an additional
9915 attribute for each metric being sent out to I<Riemann>.
9919 =head2 Plugin C<write_sensu>
9921 The I<write_sensu plugin> will send values to I<Sensu>, a powerful stream
9922 aggregation and monitoring system. The plugin sends I<JSON> encoded data to
9923 a local I<Sensu> client using a TCP socket.
9925 At the moment, the I<write_sensu plugin> does not send over a collectd_host
9926 parameter so it is not possible to use one collectd instance as a gateway for
9927 others. Each collectd host must pair with one I<Sensu> client.
9931 <Plugin "write_sensu">
9936 AlwaysAppendDS false
9937 MetricHandler "influx"
9938 MetricHandler "default"
9939 NotificationHandler "flapjack"
9940 NotificationHandler "howling_monkey"
9944 Attribute "foo" "bar"
9947 The following options are understood by the I<write_sensu plugin>:
9951 =item E<lt>B<Node> I<Name>E<gt>
9953 The plugin's configuration consists of one or more B<Node> blocks. Each block
9954 is given a unique I<Name> and specifies one connection to an instance of
9955 I<Sensu>. Inside the B<Node> block, the following per-connection options are
9960 =item B<Host> I<Address>
9962 Hostname or address to connect to. Defaults to C<localhost>.
9964 =item B<Port> I<Service>
9966 Service name or port number to connect to. Defaults to C<3030>.
9968 =item B<StoreRates> B<true>|B<false>
9970 If set to B<true> (the default), convert counter values to rates. If set to
9971 B<false> counter values are stored as is, i.e. as an increasing integer number.
9973 This will be reflected in the C<collectd_data_source_type> tag: If
9974 B<StoreRates> is enabled, converted values will have "rate" appended to the
9975 data source type, e.g. C<collectd_data_source_type:derive:rate>.
9977 =item B<AlwaysAppendDS> B<false>|B<true>
9979 If set the B<true>, append the name of the I<Data Source> (DS) to the
9980 "service", i.e. the field that, together with the "host" field, uniquely
9981 identifies a metric in I<Sensu>. If set to B<false> (the default), this is
9982 only done when there is more than one DS.
9984 =item B<Notifications> B<false>|B<true>
9986 If set to B<true>, create I<Sensu> events for notifications. This is B<false>
9987 by default. At least one of B<Notifications> or B<Metrics> should be enabled.
9989 =item B<Metrics> B<false>|B<true>
9991 If set to B<true>, create I<Sensu> events for metrics. This is B<false>
9992 by default. At least one of B<Notifications> or B<Metrics> should be enabled.
9995 =item B<Separator> I<String>
9997 Sets the separator for I<Sensu> metrics name or checks. Defaults to "/".
9999 =item B<MetricHandler> I<String>
10001 Add a handler that will be set when metrics are sent to I<Sensu>. You can add
10002 several of them, one per line. Defaults to no handler.
10004 =item B<NotificationHandler> I<String>
10006 Add a handler that will be set when notifications are sent to I<Sensu>. You can
10007 add several of them, one per line. Defaults to no handler.
10009 =item B<EventServicePrefix> I<String>
10011 Add the given string as a prefix to the event service name.
10012 If B<EventServicePrefix> not set or set to an empty string (""),
10013 no prefix will be used.
10017 =item B<Tag> I<String>
10019 Add the given string as an additional tag to the metric being sent to
10022 =item B<Attribute> I<String> I<String>
10024 Consider the two given strings to be the key and value of an additional
10025 attribute for each metric being sent out to I<Sensu>.
10029 =head2 Plugin C<xencpu>
10031 This plugin collects metrics of hardware CPU load for machine running Xen
10032 hypervisor. Load is calculated from 'idle time' value, provided by Xen.
10033 Result is reported using the C<percent> type, for each CPU (core).
10035 This plugin doesn't have any options (yet).
10037 =head2 Plugin C<zookeeper>
10039 The I<zookeeper plugin> will collect statistics from a I<Zookeeper> server
10040 using the mntr command. It requires Zookeeper 3.4.0+ and access to the
10045 <Plugin "zookeeper">
10052 =item B<Host> I<Address>
10054 Hostname or address to connect to. Defaults to C<localhost>.
10056 =item B<Port> I<Service>
10058 Service name or port number to connect to. Defaults to C<2181>.
10062 =head1 THRESHOLD CONFIGURATION
10064 Starting with version C<4.3.0> collectd has support for B<monitoring>. By that
10065 we mean that the values are not only stored or sent somewhere, but that they
10066 are judged and, if a problem is recognized, acted upon. The only action
10067 collectd takes itself is to generate and dispatch a "notification". Plugins can
10068 register to receive notifications and perform appropriate further actions.
10070 Since systems and what you expect them to do differ a lot, you can configure
10071 B<thresholds> for your values freely. This gives you a lot of flexibility but
10072 also a lot of responsibility.
10074 Every time a value is out of range a notification is dispatched. This means
10075 that the idle percentage of your CPU needs to be less then the configured
10076 threshold only once for a notification to be generated. There's no such thing
10077 as a moving average or similar - at least not now.
10079 Also, all values that match a threshold are considered to be relevant or
10080 "interesting". As a consequence collectd will issue a notification if they are
10081 not received for B<Timeout> iterations. The B<Timeout> configuration option is
10082 explained in section L<"GLOBAL OPTIONS">. If, for example, B<Timeout> is set to
10083 "2" (the default) and some hosts sends it's CPU statistics to the server every
10084 60 seconds, a notification will be dispatched after about 120 seconds. It may
10085 take a little longer because the timeout is checked only once each B<Interval>
10088 When a value comes within range again or is received after it was missing, an
10089 "OKAY-notification" is dispatched.
10091 Here is a configuration example to get you started. Read below for more
10104 <Plugin "interface">
10107 FailureMax 10000000
10121 WarningMin 100000000
10127 There are basically two types of configuration statements: The C<Host>,
10128 C<Plugin>, and C<Type> blocks select the value for which a threshold should be
10129 configured. The C<Plugin> and C<Type> blocks may be specified further using the
10130 C<Instance> option. You can combine the block by nesting the blocks, though
10131 they must be nested in the above order, i.E<nbsp>e. C<Host> may contain either
10132 C<Plugin> and C<Type> blocks, C<Plugin> may only contain C<Type> blocks and
10133 C<Type> may not contain other blocks. If multiple blocks apply to the same
10134 value the most specific block is used.
10136 The other statements specify the threshold to configure. They B<must> be
10137 included in a C<Type> block. Currently the following statements are recognized:
10141 =item B<FailureMax> I<Value>
10143 =item B<WarningMax> I<Value>
10145 Sets the upper bound of acceptable values. If unset defaults to positive
10146 infinity. If a value is greater than B<FailureMax> a B<FAILURE> notification
10147 will be created. If the value is greater than B<WarningMax> but less than (or
10148 equal to) B<FailureMax> a B<WARNING> notification will be created.
10150 =item B<FailureMin> I<Value>
10152 =item B<WarningMin> I<Value>
10154 Sets the lower bound of acceptable values. If unset defaults to negative
10155 infinity. If a value is less than B<FailureMin> a B<FAILURE> notification will
10156 be created. If the value is less than B<WarningMin> but greater than (or equal
10157 to) B<FailureMin> a B<WARNING> notification will be created.
10159 =item B<DataSource> I<DSName>
10161 Some data sets have more than one "data source". Interesting examples are the
10162 C<if_octets> data set, which has received (C<rx>) and sent (C<tx>) bytes and
10163 the C<disk_ops> data set, which holds C<read> and C<write> operations. The
10164 system load data set, C<load>, even has three data sources: C<shortterm>,
10165 C<midterm>, and C<longterm>.
10167 Normally, all data sources are checked against a configured threshold. If this
10168 is undesirable, or if you want to specify different limits for each data
10169 source, you can use the B<DataSource> option to have a threshold apply only to
10172 =item B<Invert> B<true>|B<false>
10174 If set to B<true> the range of acceptable values is inverted, i.E<nbsp>e.
10175 values between B<FailureMin> and B<FailureMax> (B<WarningMin> and
10176 B<WarningMax>) are not okay. Defaults to B<false>.
10178 =item B<Persist> B<true>|B<false>
10180 Sets how often notifications are generated. If set to B<true> one notification
10181 will be generated for each value that is out of the acceptable range. If set to
10182 B<false> (the default) then a notification is only generated if a value is out
10183 of range but the previous value was okay.
10185 This applies to missing values, too: If set to B<true> a notification about a
10186 missing value is generated once every B<Interval> seconds. If set to B<false>
10187 only one such notification is generated until the value appears again.
10189 =item B<Percentage> B<true>|B<false>
10191 If set to B<true>, the minimum and maximum values given are interpreted as
10192 percentage value, relative to the other data sources. This is helpful for
10193 example for the "df" type, where you may want to issue a warning when less than
10194 5E<nbsp>% of the total space is available. Defaults to B<false>.
10196 =item B<Hits> I<Number>
10198 Delay creating the notification until the threshold has been passed I<Number>
10199 times. When a notification has been generated, or when a subsequent value is
10200 inside the threshold, the counter is reset. If, for example, a value is
10201 collected once every 10E<nbsp>seconds and B<Hits> is set to 3, a notification
10202 will be dispatched at most once every 30E<nbsp>seconds.
10204 This is useful when short bursts are not a problem. If, for example, 100% CPU
10205 usage for up to a minute is normal (and data is collected every
10206 10E<nbsp>seconds), you could set B<Hits> to B<6> to account for this.
10208 =item B<Hysteresis> I<Number>
10210 When set to non-zero, a hysteresis value is applied when checking minimum and
10211 maximum bounds. This is useful for values that increase slowly and fluctuate a
10212 bit while doing so. When these values come close to the threshold, they may
10213 "flap", i.e. switch between failure / warning case and okay case repeatedly.
10215 If, for example, the threshold is configures as
10220 then a I<Warning> notification is created when the value exceeds I<101> and the
10221 corresponding I<Okay> notification is only created once the value falls below
10222 I<99>, thus avoiding the "flapping".
10226 =head1 FILTER CONFIGURATION
10228 Starting with collectd 4.6 there is a powerful filtering infrastructure
10229 implemented in the daemon. The concept has mostly been copied from
10230 I<ip_tables>, the packet filter infrastructure for Linux. We'll use a similar
10231 terminology, so that users that are familiar with iptables feel right at home.
10235 The following are the terms used in the remainder of the filter configuration
10236 documentation. For an ASCII-art schema of the mechanism, see
10237 L<"General structure"> below.
10243 A I<match> is a criteria to select specific values. Examples are, of course, the
10244 name of the value or it's current value.
10246 Matches are implemented in plugins which you have to load prior to using the
10247 match. The name of such plugins starts with the "match_" prefix.
10251 A I<target> is some action that is to be performed with data. Such actions
10252 could, for example, be to change part of the value's identifier or to ignore
10253 the value completely.
10255 Some of these targets are built into the daemon, see L<"Built-in targets">
10256 below. Other targets are implemented in plugins which you have to load prior to
10257 using the target. The name of such plugins starts with the "target_" prefix.
10261 The combination of any number of matches and at least one target is called a
10262 I<rule>. The target actions will be performed for all values for which B<all>
10263 matches apply. If the rule does not have any matches associated with it, the
10264 target action will be performed for all values.
10268 A I<chain> is a list of rules and possibly default targets. The rules are tried
10269 in order and if one matches, the associated target will be called. If a value
10270 is handled by a rule, it depends on the target whether or not any subsequent
10271 rules are considered or if traversal of the chain is aborted, see
10272 L<"Flow control"> below. After all rules have been checked, the default targets
10277 =head2 General structure
10279 The following shows the resulting structure:
10286 +---------+ +---------+ +---------+ +---------+
10287 ! Rule !->! Match !->! Match !->! Target !
10288 +---------+ +---------+ +---------+ +---------+
10291 +---------+ +---------+ +---------+
10292 ! Rule !->! Target !->! Target !
10293 +---------+ +---------+ +---------+
10300 +---------+ +---------+ +---------+
10301 ! Rule !->! Match !->! Target !
10302 +---------+ +---------+ +---------+
10310 =head2 Flow control
10312 There are four ways to control which way a value takes through the filter
10319 The built-in B<jump> target can be used to "call" another chain, i.E<nbsp>e.
10320 process the value with another chain. When the called chain finishes, usually
10321 the next target or rule after the jump is executed.
10325 The stop condition, signaled for example by the built-in target B<stop>, causes
10326 all processing of the value to be stopped immediately.
10330 Causes processing in the current chain to be aborted, but processing of the
10331 value generally will continue. This means that if the chain was called via
10332 B<Jump>, the next target or rule after the jump will be executed. If the chain
10333 was not called by another chain, control will be returned to the daemon and it
10334 may pass the value to another chain.
10338 Most targets will signal the B<continue> condition, meaning that processing
10339 should continue normally. There is no special built-in target for this
10346 The configuration reflects this structure directly:
10348 PostCacheChain "PostCache"
10349 <Chain "PostCache">
10350 <Rule "ignore_mysql_show">
10353 Type "^mysql_command$"
10354 TypeInstance "^show_"
10364 The above configuration example will ignore all values where the plugin field
10365 is "mysql", the type is "mysql_command" and the type instance begins with
10366 "show_". All other values will be sent to the C<rrdtool> write plugin via the
10367 default target of the chain. Since this chain is run after the value has been
10368 added to the cache, the MySQL C<show_*> command statistics will be available
10369 via the C<unixsock> plugin.
10371 =head2 List of configuration options
10375 =item B<PreCacheChain> I<ChainName>
10377 =item B<PostCacheChain> I<ChainName>
10379 Configure the name of the "pre-cache chain" and the "post-cache chain". The
10380 argument is the name of a I<chain> that should be executed before and/or after
10381 the values have been added to the cache.
10383 To understand the implications, it's important you know what is going on inside
10384 I<collectd>. The following diagram shows how values are passed from the
10385 read-plugins to the write-plugins:
10391 + - - - - V - - - - +
10392 : +---------------+ :
10395 : +-------+-------+ :
10398 : +-------+-------+ : +---------------+
10399 : ! Cache !--->! Value Cache !
10400 : ! insert ! : +---+---+-------+
10401 : +-------+-------+ : ! !
10402 : ! ,------------' !
10404 : +-------+---+---+ : +-------+-------+
10405 : ! Post-Cache +--->! Write-Plugins !
10406 : ! Chain ! : +---------------+
10407 : +---------------+ :
10409 : dispatch values :
10410 + - - - - - - - - - +
10412 After the values are passed from the "read" plugins to the dispatch functions,
10413 the pre-cache chain is run first. The values are added to the internal cache
10414 afterwards. The post-cache chain is run after the values have been added to the
10415 cache. So why is it such a huge deal if chains are run before or after the
10416 values have been added to this cache?
10418 Targets that change the identifier of a value list should be executed before
10419 the values are added to the cache, so that the name in the cache matches the
10420 name that is used in the "write" plugins. The C<unixsock> plugin, too, uses
10421 this cache to receive a list of all available values. If you change the
10422 identifier after the value list has been added to the cache, this may easily
10423 lead to confusion, but it's not forbidden of course.
10425 The cache is also used to convert counter values to rates. These rates are, for
10426 example, used by the C<value> match (see below). If you use the rate stored in
10427 the cache B<before> the new value is added, you will use the old, B<previous>
10428 rate. Write plugins may use this rate, too, see the C<csv> plugin, for example.
10429 The C<unixsock> plugin uses these rates too, to implement the C<GETVAL>
10432 Last but not last, the B<stop> target makes a difference: If the pre-cache
10433 chain returns the stop condition, the value will not be added to the cache and
10434 the post-cache chain will not be run.
10436 =item B<Chain> I<Name>
10438 Adds a new chain with a certain name. This name can be used to refer to a
10439 specific chain, for example to jump to it.
10441 Within the B<Chain> block, there can be B<Rule> blocks and B<Target> blocks.
10443 =item B<Rule> [I<Name>]
10445 Adds a new rule to the current chain. The name of the rule is optional and
10446 currently has no meaning for the daemon.
10448 Within the B<Rule> block, there may be any number of B<Match> blocks and there
10449 must be at least one B<Target> block.
10451 =item B<Match> I<Name>
10453 Adds a match to a B<Rule> block. The name specifies what kind of match should
10454 be performed. Available matches depend on the plugins that have been loaded.
10456 The arguments inside the B<Match> block are passed to the plugin implementing
10457 the match, so which arguments are valid here depends on the plugin being used.
10458 If you do not need any to pass any arguments to a match, you can use the
10463 Which is equivalent to:
10468 =item B<Target> I<Name>
10470 Add a target to a rule or a default target to a chain. The name specifies what
10471 kind of target is to be added. Which targets are available depends on the
10472 plugins being loaded.
10474 The arguments inside the B<Target> block are passed to the plugin implementing
10475 the target, so which arguments are valid here depends on the plugin being used.
10476 If you do not need any to pass any arguments to a target, you can use the
10481 This is the same as writing:
10488 =head2 Built-in targets
10490 The following targets are built into the core daemon and therefore need no
10491 plugins to be loaded:
10497 Signals the "return" condition, see the L<"Flow control"> section above. This
10498 causes the current chain to stop processing the value and returns control to
10499 the calling chain. The calling chain will continue processing targets and rules
10500 just after the B<jump> target (see below). This is very similar to the
10501 B<RETURN> target of iptables, see L<iptables(8)>.
10503 This target does not have any options.
10511 Signals the "stop" condition, see the L<"Flow control"> section above. This
10512 causes processing of the value to be aborted immediately. This is similar to
10513 the B<DROP> target of iptables, see L<iptables(8)>.
10515 This target does not have any options.
10523 Sends the value to "write" plugins.
10529 =item B<Plugin> I<Name>
10531 Name of the write plugin to which the data should be sent. This option may be
10532 given multiple times to send the data to more than one write plugin. If the
10533 plugin supports multiple instances, the plugin's instance(s) must also be
10538 If no plugin is explicitly specified, the values will be sent to all available
10541 Single-instance plugin example:
10547 Multi-instance plugin example:
10549 <Plugin "write_graphite">
10559 Plugin "write_graphite/foo"
10564 Starts processing the rules of another chain, see L<"Flow control"> above. If
10565 the end of that chain is reached, or a stop condition is encountered,
10566 processing will continue right after the B<jump> target, i.E<nbsp>e. with the
10567 next target or the next rule. This is similar to the B<-j> command line option
10568 of iptables, see L<iptables(8)>.
10574 =item B<Chain> I<Name>
10576 Jumps to the chain I<Name>. This argument is required and may appear only once.
10588 =head2 Available matches
10594 Matches a value using regular expressions.
10600 =item B<Host> I<Regex>
10602 =item B<Plugin> I<Regex>
10604 =item B<PluginInstance> I<Regex>
10606 =item B<Type> I<Regex>
10608 =item B<TypeInstance> I<Regex>
10610 =item B<MetaData> I<String> I<Regex>
10612 Match values where the given regular expressions match the various fields of
10613 the identifier of a value. If multiple regular expressions are given, B<all>
10614 regexen must match for a value to match.
10616 =item B<Invert> B<false>|B<true>
10618 When set to B<true>, the result of the match is inverted, i.e. all value lists
10619 where all regular expressions apply are not matched, all other value lists are
10620 matched. Defaults to B<false>.
10627 Host "customer[0-9]+"
10633 Matches values that have a time which differs from the time on the server.
10635 This match is mainly intended for servers that receive values over the
10636 C<network> plugin and write them to disk using the C<rrdtool> plugin. RRDtool
10637 is very sensitive to the timestamp used when updating the RRD files. In
10638 particular, the time must be ever increasing. If a misbehaving client sends one
10639 packet with a timestamp far in the future, all further packets with a correct
10640 time will be ignored because of that one packet. What's worse, such corrupted
10641 RRD files are hard to fix.
10643 This match lets one match all values B<outside> a specified time range
10644 (relative to the server's time), so you can use the B<stop> target (see below)
10645 to ignore the value, for example.
10651 =item B<Future> I<Seconds>
10653 Matches all values that are I<ahead> of the server's time by I<Seconds> or more
10654 seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
10657 =item B<Past> I<Seconds>
10659 Matches all values that are I<behind> of the server's time by I<Seconds> or
10660 more seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
10672 This example matches all values that are five minutes or more ahead of the
10673 server or one hour (or more) lagging behind.
10677 Matches the actual value of data sources against given minimumE<nbsp>/ maximum
10678 values. If a data-set consists of more than one data-source, all data-sources
10679 must match the specified ranges for a positive match.
10685 =item B<Min> I<Value>
10687 Sets the smallest value which still results in a match. If unset, behaves like
10690 =item B<Max> I<Value>
10692 Sets the largest value which still results in a match. If unset, behaves like
10695 =item B<Invert> B<true>|B<false>
10697 Inverts the selection. If the B<Min> and B<Max> settings result in a match,
10698 no-match is returned and vice versa. Please note that the B<Invert> setting
10699 only effects how B<Min> and B<Max> are applied to a specific value. Especially
10700 the B<DataSource> and B<Satisfy> settings (see below) are not inverted.
10702 =item B<DataSource> I<DSName> [I<DSName> ...]
10704 Select one or more of the data sources. If no data source is configured, all
10705 data sources will be checked. If the type handled by the match does not have a
10706 data source of the specified name(s), this will always result in no match
10707 (independent of the B<Invert> setting).
10709 =item B<Satisfy> B<Any>|B<All>
10711 Specifies how checking with several data sources is performed. If set to
10712 B<Any>, the match succeeds if one of the data sources is in the configured
10713 range. If set to B<All> the match only succeeds if all data sources are within
10714 the configured range. Default is B<All>.
10716 Usually B<All> is used for positive matches, B<Any> is used for negative
10717 matches. This means that with B<All> you usually check that all values are in a
10718 "good" range, while with B<Any> you check if any value is within a "bad" range
10719 (or outside the "good" range).
10723 Either B<Min> or B<Max>, but not both, may be unset.
10727 # Match all values smaller than or equal to 100. Matches only if all data
10728 # sources are below 100.
10734 # Match if the value of any data source is outside the range of 0 - 100.
10742 =item B<empty_counter>
10744 Matches all values with one or more data sources of type B<COUNTER> and where
10745 all counter values are zero. These counters usually I<never> increased since
10746 they started existing (and are therefore uninteresting), or got reset recently
10747 or overflowed and you had really, I<really> bad luck.
10749 Please keep in mind that ignoring such counters can result in confusing
10750 behavior: Counters which hardly ever increase will be zero for long periods of
10751 time. If the counter is reset for some reason (machine or service restarted,
10752 usually), the graph will be empty (NAN) for a long time. People may not
10757 Calculates a hash value of the host name and matches values according to that
10758 hash value. This makes it possible to divide all hosts into groups and match
10759 only values that are in a specific group. The intended use is in load
10760 balancing, where you want to handle only part of all data and leave the rest
10763 The hashing function used tries to distribute the hosts evenly. First, it
10764 calculates a 32E<nbsp>bit hash value using the characters of the hostname:
10767 for (i = 0; host[i] != 0; i++)
10768 hash_value = (hash_value * 251) + host[i];
10770 The constant 251 is a prime number which is supposed to make this hash value
10771 more random. The code then checks the group for this host according to the
10772 I<Total> and I<Match> arguments:
10774 if ((hash_value % Total) == Match)
10779 Please note that when you set I<Total> to two (i.E<nbsp>e. you have only two
10780 groups), then the least significant bit of the hash value will be the XOR of
10781 all least significant bits in the host name. One consequence is that when you
10782 have two hosts, "server0.example.com" and "server1.example.com", where the host
10783 name differs in one digit only and the digits differ by one, those hosts will
10784 never end up in the same group.
10790 =item B<Match> I<Match> I<Total>
10792 Divide the data into I<Total> groups and match all hosts in group I<Match> as
10793 described above. The groups are numbered from zero, i.E<nbsp>e. I<Match> must
10794 be smaller than I<Total>. I<Total> must be at least one, although only values
10795 greater than one really do make any sense.
10797 You can repeat this option to match multiple groups, for example:
10802 The above config will divide the data into seven groups and match groups three
10803 and five. One use would be to keep every value on two hosts so that if one
10804 fails the missing data can later be reconstructed from the second host.
10810 # Operate on the pre-cache chain, so that ignored values are not even in the
10815 # Divide all received hosts in seven groups and accept all hosts in
10819 # If matched: Return and continue.
10822 # If not matched: Return and stop.
10828 =head2 Available targets
10832 =item B<notification>
10834 Creates and dispatches a notification.
10840 =item B<Message> I<String>
10842 This required option sets the message of the notification. The following
10843 placeholders will be replaced by an appropriate value:
10851 =item B<%{plugin_instance}>
10855 =item B<%{type_instance}>
10857 These placeholders are replaced by the identifier field of the same name.
10859 =item B<%{ds:>I<name>B<}>
10861 These placeholders are replaced by a (hopefully) human readable representation
10862 of the current rate of this data source. If you changed the instance name
10863 (using the B<set> or B<replace> targets, see below), it may not be possible to
10864 convert counter values to rates.
10868 Please note that these placeholders are B<case sensitive>!
10870 =item B<Severity> B<"FAILURE">|B<"WARNING">|B<"OKAY">
10872 Sets the severity of the message. If omitted, the severity B<"WARNING"> is
10879 <Target "notification">
10880 Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
10886 Replaces parts of the identifier using regular expressions.
10892 =item B<Host> I<Regex> I<Replacement>
10894 =item B<Plugin> I<Regex> I<Replacement>
10896 =item B<PluginInstance> I<Regex> I<Replacement>
10898 =item B<TypeInstance> I<Regex> I<Replacement>
10900 =item B<MetaData> I<String> I<Regex> I<Replacement>
10902 =item B<DeleteMetaData> I<String> I<Regex>
10904 Match the appropriate field with the given regular expression I<Regex>. If the
10905 regular expression matches, that part that matches is replaced with
10906 I<Replacement>. If multiple places of the input buffer match a given regular
10907 expression, only the first occurrence will be replaced.
10909 You can specify each option multiple times to use multiple regular expressions
10917 # Replace "example.net" with "example.com"
10918 Host "\\<example.net\\>" "example.com"
10920 # Strip "www." from hostnames
10921 Host "\\<www\\." ""
10926 Sets part of the identifier of a value to a given string.
10932 =item B<Host> I<String>
10934 =item B<Plugin> I<String>
10936 =item B<PluginInstance> I<String>
10938 =item B<TypeInstance> I<String>
10940 =item B<MetaData> I<String> I<String>
10942 Set the appropriate field to the given string. The strings for plugin instance,
10943 type instance, and meta data may be empty, the strings for host and plugin may
10944 not be empty. It's currently not possible to set the type of a value this way.
10946 The following placeholders will be replaced by an appropriate value:
10954 =item B<%{plugin_instance}>
10958 =item B<%{type_instance}>
10960 These placeholders are replaced by the identifier field of the same name.
10962 =item B<%{meta:>I<name>B<}>
10964 These placeholders are replaced by the meta data value with the given name.
10968 Please note that these placeholders are B<case sensitive>!
10970 =item B<DeleteMetaData> I<String>
10972 Delete the named meta data field.
10979 PluginInstance "coretemp"
10980 TypeInstance "core3"
10985 =head2 Backwards compatibility
10987 If you use collectd with an old configuration, i.E<nbsp>e. one without a
10988 B<Chain> block, it will behave as it used to. This is equivalent to the
10989 following configuration:
10991 <Chain "PostCache">
10995 If you specify a B<PostCacheChain>, the B<write> target will not be added
10996 anywhere and you will have to make sure that it is called where appropriate. We
10997 suggest to add the above snippet as default target to your "PostCache" chain.
11001 Ignore all values, where the hostname does not contain a dot, i.E<nbsp>e. can't
11016 B<Ignorelists> are a generic framework to either ignore some metrics or report
11017 specific metircs only. Plugins usually provide one or more options to specify
11018 the items (mounts points, devices, ...) and the boolean option
11023 =item B<Select> I<String>
11025 Selects the item I<String>. This option often has a plugin specific name, e.g.
11026 B<Sensor> in the C<sensors> plugin. It is also plugin specific what this string
11027 is compared to. For example, the C<df> plugin's B<MountPoint> compares it to a
11028 mount point and the C<sensors> plugin's B<Sensor> compares it to a sensor name.
11030 By default, this option is doing a case-sensitive full-string match. The
11031 following config will match C<foo>, but not C<Foo>:
11035 If I<String> starts and ends with C</> (a slash), the string is compiled as a
11036 I<regular expression>. For example, so match all item starting with C<foo>, use
11037 could use the following syntax:
11041 The regular expression is I<not> anchored, i.e. the following config will match
11042 C<foobar>, C<barfoo> and C<AfooZ>:
11046 The B<Select> option may be repeated to select multiple items.
11048 =item B<IgnoreSelected> B<true>|B<false>
11050 If set to B<true>, matching metrics are I<ignored> and all other metrics are
11051 collected. If set to B<false>, matching metrics are I<collected> and all other
11052 metrics are ignored.
11059 L<collectd-exec(5)>,
11060 L<collectd-perl(5)>,
11061 L<collectd-unixsock(5)>,
11074 Florian Forster E<lt>octo@collectd.orgE<gt>