Debian Codegraph @

src/collectd.conf.pod

raw
1 =encoding UTF-8
2
3 =head1 NAME
4
5 collectd.conf - Configuration for the system statistics collection daemon B<collectd>
6
7 =head1 SYNOPSIS
8
9 BaseDir "/var/lib/collectd"
10 PIDFile "/run/collectd.pid"
11 Interval 10.0
12
13 LoadPlugin cpu
14 LoadPlugin load
15
16 <LoadPlugin df>
17 Interval 3600
18 </LoadPlugin>
19 <Plugin df>
20 ValuesPercentage true
21 </Plugin>
22
23 LoadPlugin ping
24 <Plugin ping>
25 Host "example.org"
26 Host "provider.net"
27 </Plugin>
28
29 =head1 DESCRIPTION
30
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.
37
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>.
53
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.
59
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.
66
67 =head1 GLOBAL OPTIONS
68
69 =over 4
70
71 =item B<BaseDir> I<Directory>
72
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.
76
77 =item B<LoadPlugin> I<Plugin>
78
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.
82
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.
90
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:
94
95 LoadPlugin "cpu"
96
97 Options inside a B<LoadPlugin> block can override default settings and
98 influence the way plugins are loaded, e.g.:
99
100 <LoadPlugin perl>
101 Interval 60
102 </LoadPlugin>
103
104 The following options are valid inside B<LoadPlugin> blocks:
105
106 =over 4
107
108 =item B<Globals> B<true|false>
109
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.
114
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.
122
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.
126
127 =item B<Interval> I<Seconds>
128
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.
132
133 =item B<FlushInterval> I<Seconds>
134
135 Specifies the interval, in seconds, to call the flush callback if it's
136 defined in this plugin. By default, this is disabled.
137
138 =item B<FlushTimeout> I<Seconds>
139
140 Specifies the value of the timeout argument of the flush callback.
141
142 =back
143
144 =item B<AutoLoadPlugin> B<false>|B<true>
145
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.
151
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>.
156
157 =item B<CollectInternalStats> B<false>|B<true>
158
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>.
161
162 The following metrics are reported:
163
164 =over 4
165
166 =item C<collectd-write_queue/queue_length>
167
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.
170
171 =item C<collectd-write_queue/derive-dropped>
172
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.
176
177 =item C<collectd-cache/cache_size>
178
179 The number of elements in the metric cache (the cache you can interact with
180 using L<collectd-unixsock(5)>).
181
182 =back
183
184 =item B<Include> I<Path> [I<pattern>]
185
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:
191
192 Include "/etc/collectd.d/*.conf"
193
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
196 currently allowed:
197
198 <Include "/etc/collectd.d">
199 Filter "*.conf"
200 </Include>
201
202 =over 4
203
204 =item B<Filter> I<pattern>
205
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>.
212
213 =back
214
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.
219
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.
225
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.
228
229 =item B<PIDFile> I<File>
230
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.
234
235 =item B<PluginDir> I<Directory>
236
237 Path to the plugins (shared objects) of collectd.
238
239 =item B<TypesDB> I<File> [I<File> ...]
240
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.
243
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.
249
250 =item B<Interval> I<Seconds>
251
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.
255
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.)
259
260 =item B<MaxReadInterval> I<Seconds>
261
262 A read plugin doubles the interval between queries after each failed attempt
263 to get data.
264
265 This options limits the maximum value of the interval. The default value is
266 B<86400>.
267
268 =item B<Timeout> I<Iterations>
269
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.
277
278 =item B<ReadThreads> I<Num>
279
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.
284
285 =item B<WriteThreads> I<Num>
286
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.
290
291 =item B<WriteQueueLimitHigh> I<HighNum>
292
293 =item B<WriteQueueLimitLow> I<LowNum>
294
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
299 queue.
300
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.
304
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%.)
313
314 If B<WriteQueueLimitHigh> is set to non-zero and B<WriteQueueLimitLow> is
315 unset, the latter will default to half of B<WriteQueueLimitHigh>.
316
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>
319 to the same value.
320
321 Enabling the B<CollectInternalStats> option is of great help to figure out the
322 values to set B<WriteQueueLimitHigh> and B<WriteQueueLimitLow> to.
323
324 =item B<Hostname> I<Name>
325
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.
328
329 =item B<FQDNLookup> B<true|false>
330
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.
335
336 =item B<PreCacheChain> I<ChainName>
337
338 =item B<PostCacheChain> I<ChainName>
339
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.
343
344 =back
345
346 =head1 PLUGIN OPTIONS
347
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.
354
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
357 well.
358
359 =head2 Plugin C<aggregation>
360
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.
365
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.
370
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
375 statement.
376
377 Plugin "cpu"
378 Type "cpu"
379
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.
385
386 GroupBy "Host"
387 GroupBy "TypeInstance"
388
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
392 take place.
393
394 The full example configuration looks like this:
395
396 <Plugin "aggregation">
397 <Aggregation>
398 Plugin "cpu"
399 Type "cpu"
400
401 GroupBy "Host"
402 GroupBy "TypeInstance"
403
404 CalculateSum true
405 CalculateAverage true
406 </Aggregation>
407 </Plugin>
408
409 There are a couple of limitations you should be aware of:
410
411 =over 4
412
413 =item *
414
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
417 to group by type.
418
419 =item *
420
421 There must be at least one unspecified, ungrouped field. Otherwise nothing
422 will be aggregated.
423
424 =back
425
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:
430
431 =over 4
432
433 =item B<Host> I<Host>
434
435 =item B<Plugin> I<Plugin>
436
437 =item B<PluginInstance> I<PluginInstance>
438
439 =item B<Type> I<Type>
440
441 =item B<TypeInstance> I<TypeInstance>
442
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.
445
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:
449
450 Host "/^db[0-9]\\.example\\.com$/"
451
452 =item B<GroupBy> B<Host>|B<Plugin>|B<PluginInstance>|B<TypeInstance>
453
454 Group valued by the specified field. The B<GroupBy> option may be repeated to
455 group by multiple fields.
456
457 =item B<SetHost> I<Host>
458
459 =item B<SetPlugin> I<Plugin>
460
461 =item B<SetPluginInstance> I<PluginInstance>
462
463 =item B<SetTypeInstance> I<TypeInstance>
464
465 Sets the appropriate part of the identifier to the provided string.
466
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.
471
472 The following example calculates the average usage of all "even" CPUs:
473
474 <Plugin "aggregation">
475 <Aggregation>
476 Plugin "cpu"
477 PluginInstance "/[0,2,4,6,8]$/"
478 Type "cpu"
479
480 SetPlugin "cpu"
481 SetPluginInstance "even-%{aggregation}"
482
483 GroupBy "Host"
484 GroupBy "TypeInstance"
485
486 CalculateAverage true
487 </Aggregation>
488 </Plugin>
489
490 This will create the files:
491
492 =over 4
493
494 =item *
495
496 foo.example.com/cpu-even-average/cpu-idle
497
498 =item *
499
500 foo.example.com/cpu-even-average/cpu-system
501
502 =item *
503
504 foo.example.com/cpu-even-average/cpu-user
505
506 =item *
507
508 ...
509
510 =back
511
512 =item B<CalculateNum> B<true>|B<false>
513
514 =item B<CalculateSum> B<true>|B<false>
515
516 =item B<CalculateAverage> B<true>|B<false>
517
518 =item B<CalculateMinimum> B<true>|B<false>
519
520 =item B<CalculateMaximum> B<true>|B<false>
521
522 =item B<CalculateStddev> B<true>|B<false>
523
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.
527
528 =back
529
530 =head2 Plugin C<amqp>
531
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.
536
537 B<Synopsis:>
538
539 <Plugin "amqp">
540 # Send values to an AMQP broker
541 <Publish "some_name">
542 Host "localhost"
543 Host "fallback-amqp.example.com"
544 Port "5672"
545 VHost "/"
546 User "guest"
547 Password "guest"
548 Exchange "amq.fanout"
549 # ExchangeType "fanout"
550 # RoutingKey "collectd"
551 # Persistent false
552 # ConnectionRetryDelay 0
553 # Format "command"
554 # StoreRates false
555 # TLSEnabled false
556 # TLSVerifyPeer true
557 # TLSVerifyHostName true
558 # TLSCACert "/path/to/ca.pem"
559 # TLSClientCert "/path/to/client-cert.pem"
560 # TLSClientKey "/path/to/client-key.pem"
561 # GraphitePrefix "collectd."
562 # GraphiteEscapeChar "_"
563 # GraphiteSeparateInstances false
564 # GraphiteAlwaysAppendDS false
565 # GraphitePreserveSeparator false
566 </Publish>
567
568 # Receive values from an AMQP broker
569 <Subscribe "some_name">
570 Host "localhost"
571 Port "5672"
572 VHost "/"
573 User "guest"
574 Password "guest"
575 Exchange "amq.fanout"
576 # ExchangeType "fanout"
577 # Queue "queue_name"
578 # QueueDurable false
579 # QueueAutoDelete true
580 # RoutingKey "collectd.#"
581 # ConnectionRetryDelay 0
582 # TLSEnabled false
583 # TLSVerifyPeer true
584 # TLSVerifyHostName true
585 # TLSCACert "/path/to/ca.pem"
586 # TLSClientCert "/path/to/client-cert.pem"
587 # TLSClientKey "/path/to/client-key.pem"
588 </Subscribe>
589 </Plugin>
590
591 The plugin's configuration consists of a number of I<Publish> and I<Subscribe>
592 blocks, which configure sending and receiving of values respectively. The two
593 blocks are very similar, so unless otherwise noted, an option can be used in
594 either block. The name given in the blocks starting tag is only used for
595 reporting messages, but may be used to support I<flushing> of certain
596 I<Publish> blocks in the future.
597
598 =over 4
599
600 =item B<Host> I<Host> [I<Host> ...]
601
602 Hostname or IP-address of the AMQP broker. Defaults to the default behavior of
603 the underlying communications library, I<rabbitmq-c>, which is "localhost".
604
605 If multiple hosts are specified, then a random one is chosen at each
606 (re)connection attempt. This is useful for failover with a clustered broker.
607
608 =item B<Port> I<Port>
609
610 Service name or port number on which the AMQP broker accepts connections. This
611 argument must be a string, even if the numeric form is used. Defaults to
612 "5672".
613
614 =item B<VHost> I<VHost>
615
616 Name of the I<virtual host> on the AMQP broker to use. Defaults to "/".
617
618 =item B<User> I<User>
619
620 =item B<Password> I<Password>
621
622 Credentials used to authenticate to the AMQP broker. By default "guest"/"guest"
623 is used.
624
625 =item B<Exchange> I<Exchange>
626
627 In I<Publish> blocks, this option specifies the I<exchange> to send values to.
628 By default, "amq.fanout" will be used.
629
630 In I<Subscribe> blocks this option is optional. If given, a I<binding> between
631 the given exchange and the I<queue> is created, using the I<routing key> if
632 configured. See the B<Queue> and B<RoutingKey> options below.
633
634 =item B<ExchangeType> I<Type>
635
636 If given, the plugin will try to create the configured I<exchange> with this
637 I<type> after connecting. When in a I<Subscribe> block, the I<queue> will then
638 be bound to this exchange.
639
640 =item B<Queue> I<Queue> (Subscribe only)
641
642 Configures the I<queue> name to subscribe to. If no queue name was configured
643 explicitly, a unique queue name will be created by the broker.
644
645 =item B<QueueDurable> B<true>|B<false> (Subscribe only)
646
647 Defines if the I<queue> subscribed to is durable (saved to persistent storage)
648 or transient (will disappear if the AMQP broker is restarted). Defaults to
649 "false".
650
651 This option should be used in conjunction with the I<Persistent> option on the
652 publish side.
653
654 =item B<QueueAutoDelete> B<true>|B<false> (Subscribe only)
655
656 Defines if the I<queue> subscribed to will be deleted once the last consumer
657 unsubscribes. Defaults to "true".
658
659 =item B<RoutingKey> I<Key>
660
661 In I<Publish> blocks, this configures the routing key to set on all outgoing
662 messages. If not given, the routing key will be computed from the I<identifier>
663 of the value. The host, plugin, type and the two instances are concatenated
664 together using dots as the separator and all containing dots replaced with
665 slashes. For example "collectd.host/example/com.cpu.0.cpu.user". This makes it
666 possible to receive only specific values using a "topic" exchange.
667
668 In I<Subscribe> blocks, configures the I<routing key> used when creating a
669 I<binding> between an I<exchange> and the I<queue>. The usual wildcards can be
670 used to filter messages when using a "topic" exchange. If you're only
671 interested in CPU statistics, you could use the routing key "collectd.*.cpu.#"
672 for example.
673
674 =item B<Persistent> B<true>|B<false> (Publish only)
675
676 Selects the I<delivery method> to use. If set to B<true>, the I<persistent>
677 mode will be used, i.e. delivery is guaranteed. If set to B<false> (the
678 default), the I<transient> delivery mode will be used, i.e. messages may be
679 lost due to high load, overflowing queues or similar issues.
680
681 =item B<ConnectionRetryDelay> I<Delay>
682
683 When the connection to the AMQP broker is lost, defines the time in seconds to
684 wait before attempting to reconnect. Defaults to 0, which implies collectd will
685 attempt to reconnect at each read interval (in Subscribe mode) or each time
686 values are ready for submission (in Publish mode).
687
688 =item B<Format> B<Command>|B<JSON>|B<Graphite> (Publish only)
689
690 Selects the format in which messages are sent to the broker. If set to
691 B<Command> (the default), values are sent as C<PUTVAL> commands which are
692 identical to the syntax used by the I<Exec> and I<UnixSock plugins>. In this
693 case, the C<Content-Type> header field will be set to C<text/collectd>.
694
695 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
696 an easy and straight forward exchange format. The C<Content-Type> header field
697 will be set to C<application/json>.
698
699 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
700 "<metric> <value> <timestamp>\n". The C<Content-Type> header field will be set to
701 C<text/graphite>.
702
703 A subscribing client I<should> use the C<Content-Type> header field to
704 determine how to decode the values. Currently, the I<AMQP plugin> itself can
705 only decode the B<Command> format.
706
707 =item B<StoreRates> B<true>|B<false> (Publish only)
708
709 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
710 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
711 default), no conversion is performed. Otherwise the conversion is performed
712 using the internal value cache.
713
714 Please note that currently this option is only used if the B<Format> option has
715 been set to B<JSON>.
716
717 =item B<GraphitePrefix> (Publish and B<Format>=I<Graphite> only)
718
719 A prefix can be added in the metric name when outputting in the I<Graphite> format.
720 It's added before the I<Host> name.
721 Metric name will be "<prefix><host><postfix><plugin><type><name>"
722
723 =item B<GraphitePostfix> (Publish and B<Format>=I<Graphite> only)
724
725 A postfix can be added in the metric name when outputting in the I<Graphite> format.
726 It's added after the I<Host> name.
727 Metric name will be "<prefix><host><postfix><plugin><type><name>"
728
729 =item B<GraphiteEscapeChar> (Publish and B<Format>=I<Graphite> only)
730
731 Specify a character to replace dots (.) in the host part of the metric name.
732 In I<Graphite> metric name, dots are used as separators between different
733 metric parts (host, plugin, type).
734 Default is "_" (I<Underscore>).
735
736 =item B<GraphiteSeparateInstances> B<true>|B<false>
737
738 If set to B<true>, the plugin instance and type instance will be in their own
739 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
740 default), the plugin and plugin instance (and likewise the type and type
741 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
742
743 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
744
745 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
746 identifier. If set to B<false> (the default), this is only done when there is
747 more than one DS.
748
749 =item B<GraphitePreserveSeparator> B<false>|B<true>
750
751 If set to B<false> (the default) the C<.> (dot) character is replaced with
752 I<GraphiteEscapeChar>. Otherwise, if set to B<true>, the C<.> (dot) character
753 is preserved, i.e. passed through.
754
755 =item B<TLSEnabled> B<true>|B<false>
756
757 If set to B<true> then connect to the broker using a TLS connection.
758 If set to B<false> (the default), then a plain text connection is used.
759
760 Requires rabbitmq-c >= 0.4.
761
762 =item B<TLSVerifyPeer> B<true>|B<false>
763
764 If set to B<true> (the default) then the server certificate chain is verified.
765 Setting this to B<false> will skip verification (insecure).
766
767 Requires rabbitmq-c >= 0.8.
768
769 =item B<TLSVerifyHostName> B<true>|B<false>
770
771 If set to B<true> (the default) then the server host name is verified.
772 Setting this to B<false> will skip verification (insecure).
773
774 Requires rabbitmq-c >= 0.8.
775
776 =item B<TLSCACert> I<Path>
777
778 Path to the CA cert file in PEM format.
779
780 =item B<TLSClientCert> I<Path>
781
782 Path to the client certificate in PEM format.
783 If this is set, then B<TLSClientKey> must be set as well.
784
785 =item B<TLSClientKey> I<Path>
786
787 Path to the client key in PEM format.
788 If this is set, then B<TLSClientCert> must be set as well.
789
790 =back
791
792 =head2 Plugin C<amqp1>
793
794 The I<AMQP1 plugin> can be used to communicate with other instances of
795 I<collectd> or third party applications using an AMQP 1.0 message
796 intermediary. Metric values or notifications are sent to the
797 messaging intermediary which may handle direct messaging or
798 queue based transfer.
799
800 B<Synopsis:>
801
802 <Plugin "amqp1">
803 # Send values to an AMQP 1.0 intermediary
804 <Transport "name">
805 Host "localhost"
806 Port "5672"
807 User "guest"
808 Password "guest"
809 Address "collectd"
810 # RetryDelay 1
811 <Instance "some_name">
812 Format "command"
813 PreSettle false
814 Notify false
815 # StoreRates false
816 # GraphitePrefix "collectd."
817 # GraphiteEscapeChar "_"
818 # GraphiteSeparateInstances false
819 # GraphiteAlwaysAppendDS false
820 # GraphitePreserveSeparator false
821 </Instance>
822 </Transport>
823 </Plugin>
824
825 The plugin's configuration consists of a I<Transport> that configures
826 communications to the AMQP 1.0 messaging bus and one or more I<Instance>
827 corresponding to metric or event publishers to the messaging system.
828
829 The address in the I<Transport> block concatenated with the name given in the
830 I<Instance> block starting tag will be used as the send-to address for
831 communications over the messaging link.
832
833 The following options are accepted within each I<Transport> block:
834
835 =over 4
836
837 =item B<Host> I<Host>
838
839 Hostname or IP-address of the AMQP 1.0 intermediary. Defaults to the
840 default behavior of the underlying communications library,
841 I<libqpid-proton>, which is "localhost".
842
843 =item B<Port> I<Port>
844
845 Service name or port number on which the AMQP 1.0 intermediary accepts
846 connections. This argument must be a string, even if the numeric form
847 is used. Defaults to "5672".
848
849 =item B<User> I<User>
850
851 =item B<Password> I<Password>
852
853 Credentials used to authenticate to the AMQP 1.0 intermediary. By
854 default "guest"/"guest" is used.
855
856 =item B<Address> I<Address>
857
858 This option specifies the prefix for the send-to value in the message.
859 By default, "collectd" will be used.
860
861 =item B<RetryDelay> I<RetryDelay>
862
863 When the AMQP1 connection is lost, defines the time in seconds to wait
864 before attempting to reconnect. Defaults to 1, which implies attempt
865 to reconnect at 1 second intervals.
866
867 =item B<SendQueueLimit> I<SendQueueLimit>
868 If there is no AMQP1 connection, the plugin will continue to queue
869 messages to send, which could result in unbounded memory consumption. This
870 parameter is used to limit the number of messages in the outbound queue to
871 the specified value. The default value is 0, which disables this feature.
872
873 =back
874
875 The following options are accepted within each I<Instance> block:
876
877 =over 4
878
879 =item B<Format> B<Command>|B<JSON>|B<Graphite>
880
881 Selects the format in which messages are sent to the intermediary. If set to
882 B<Command> (the default), values are sent as C<PUTVAL> commands which are
883 identical to the syntax used by the I<Exec> and I<UnixSock plugins>. In this
884 case, the C<Content-Type> header field will be set to C<text/collectd>.
885
886 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
887 an easy and straight forward exchange format. The C<Content-Type> header field
888 will be set to C<application/json>.
889
890 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
891 "<metric> <value> <timestamp>\n". The C<Content-Type> header field will be set to
892 C<text/graphite>.
893
894 A subscribing client I<should> use the C<Content-Type> header field to
895 determine how to decode the values.
896
897 =item B<PreSettle> B<true>|B<false>
898
899 If set to B<false> (the default), the plugin will wait for a message
900 acknowledgement from the messaging bus before sending the next
901 message. This indicates transfer of ownership to the messaging
902 system. If set to B<true>, the plugin will not wait for a message
903 acknowledgement and the message may be dropped prior to transfer of
904 ownership.
905
906 =item B<Notify> B<true>|B<false>
907
908 If set to B<false> (the default), the plugin will service the
909 instance write call back as a value list. If set to B<true> the
910 plugin will service the instance as a write notification callback
911 for alert formatting.
912
913 =item B<StoreRates> B<true>|B<false>
914
915 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
916 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
917 default), no conversion is performed. Otherwise the conversion is performed
918 using the internal value cache.
919
920 Please note that currently this option is only used if the B<Format> option has
921 been set to B<JSON>.
922
923 =item B<GraphitePrefix>
924
925 A prefix can be added in the metric name when outputting in the I<Graphite> format.
926 It's added before the I<Host> name.
927 Metric name will be "<prefix><host><postfix><plugin><type><name>"
928
929 =item B<GraphitePostfix>
930
931 A postfix can be added in the metric name when outputting in the I<Graphite> format.
932 It's added after the I<Host> name.
933 Metric name will be "<prefix><host><postfix><plugin><type><name>"
934
935 =item B<GraphiteEscapeChar>
936
937 Specify a character to replace dots (.) in the host part of the metric name.
938 In I<Graphite> metric name, dots are used as separators between different
939 metric parts (host, plugin, type).
940 Default is "_" (I<Underscore>).
941
942 =item B<GraphiteSeparateInstances> B<true>|B<false>
943
944 If set to B<true>, the plugin instance and type instance will be in their own
945 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
946 default), the plugin and plugin instance (and likewise the type and type
947 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
948
949 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
950
951 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
952 identifier. If set to B<false> (the default), this is only done when there is
953 more than one DS.
954
955 =item B<GraphitePreserveSeparator> B<false>|B<true>
956
957 If set to B<false> (the default) the C<.> (dot) character is replaced with
958 I<GraphiteEscapeChar>. Otherwise, if set to B<true>, the C<.> (dot) character
959 is preserved, i.e. passed through.
960
961 =back
962
963 =head2 Plugin C<apache>
964
965 To configure the C<apache>-plugin you first need to configure the Apache
966 webserver correctly. The Apache-plugin C<mod_status> needs to be loaded and
967 working and the C<ExtendedStatus> directive needs to be B<enabled>. You can use
968 the following snipped to base your Apache config upon:
969
970 ExtendedStatus on
971 <IfModule mod_status.c>
972 <Location /mod_status>
973 SetHandler server-status
974 </Location>
975 </IfModule>
976
977 Since its C<mod_status> module is very similar to Apache's, B<lighttpd> is
978 also supported. It introduces a new field, called C<BusyServers>, to count the
979 number of currently connected clients. This field is also supported.
980
981 The configuration of the I<Apache> plugin consists of one or more
982 C<E<lt>InstanceE<nbsp>/E<gt>> blocks. Each block requires one string argument
983 as the instance name. For example:
984
985 <Plugin "apache">
986 <Instance "www1">
987 URL "http://www1.example.com/mod_status?auto"
988 </Instance>
989 <Instance "www2">
990 URL "http://www2.example.com/mod_status?auto"
991 </Instance>
992 </Plugin>
993
994 The instance name will be used as the I<plugin instance>. To emulate the old
995 (versionE<nbsp>4) behavior, you can use an empty string (""). In order for the
996 plugin to work correctly, each instance name must be unique. This is not
997 enforced by the plugin and it is your responsibility to ensure it.
998
999 The following options are accepted within each I<Instance> block:
1000
1001 =over 4
1002
1003 =item B<URL> I<http://host/mod_status?auto>
1004
1005 Sets the URL of the C<mod_status> output. This needs to be the output generated
1006 by C<ExtendedStatus on> and it needs to be the machine readable output
1007 generated by appending the C<?auto> argument. This option is I<mandatory>.
1008
1009 =item B<User> I<Username>
1010
1011 Optional user name needed for authentication.
1012
1013 =item B<Password> I<Password>
1014
1015 Optional password needed for authentication.
1016
1017 =item B<VerifyPeer> B<true|false>
1018
1019 Enable or disable peer SSL certificate verification. See
1020 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
1021
1022 =item B<VerifyHost> B<true|false>
1023
1024 Enable or disable peer host name verification. If enabled, the plugin checks
1025 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
1026 certificate matches the host name provided by the B<URL> option. If this
1027 identity check fails, the connection is aborted. Obviously, only works when
1028 connecting to a SSL enabled server. Enabled by default.
1029
1030 =item B<CACert> I<File>
1031
1032 File that holds one or more SSL certificates. If you want to use HTTPS you will
1033 possibly need this option. What CA certificates come bundled with C<libcurl>
1034 and are checked by default depends on the distribution you use.
1035
1036 =item B<SSLCiphers> I<list of ciphers>
1037
1038 Specifies which ciphers to use in the connection. The list of ciphers
1039 must specify valid ciphers. See
1040 L<http://www.openssl.org/docs/apps/ciphers.html> for details.
1041
1042 =item B<Timeout> I<Milliseconds>
1043
1044 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
1045 milliseconds. By default, the configured B<Interval> is used to set the
1046 timeout.
1047
1048 =back
1049
1050 =head2 Plugin C<apcups>
1051
1052 =over 4
1053
1054 =item B<Host> I<Hostname>
1055
1056 Hostname of the host running B<apcupsd>. Defaults to B<localhost>. Please note
1057 that IPv6 support has been disabled unless someone can confirm or decline that
1058 B<apcupsd> can handle it.
1059
1060 =item B<Port> I<Port>
1061
1062 TCP-Port to connect to. Defaults to B<3551>.
1063
1064 =item B<ReportSeconds> B<true>|B<false>
1065
1066 If set to B<true>, the time reported in the C<timeleft> metric will be
1067 converted to seconds. This is the recommended setting. If set to B<false>, the
1068 default for backwards compatibility, the time will be reported in minutes.
1069
1070 =item B<PersistentConnection> B<true>|B<false>
1071
1072 The plugin is designed to keep the connection to I<apcupsd> open between reads.
1073 If plugin poll interval is greater than 15 seconds (hardcoded socket close
1074 timeout in I<apcupsd> NIS), then this option is B<false> by default.
1075
1076 You can instruct the plugin to close the connection after each read by setting
1077 this option to B<false> or force keeping the connection by setting it to B<true>.
1078
1079 If I<apcupsd> appears to close the connection due to inactivity quite quickly,
1080 the plugin will try to detect this problem and switch to an open-read-close mode.
1081
1082 =back
1083
1084 =head2 Plugin C<aquaero>
1085
1086 This plugin collects the value of the available sensors in an
1087 I<AquaeroE<nbsp>5> board. AquaeroE<nbsp>5 is a water-cooling controller board,
1088 manufactured by Aqua Computer GmbH L<http://www.aquacomputer.de/>, with a USB2
1089 connection for monitoring and configuration. The board can handle multiple
1090 temperature sensors, fans, water pumps and water level sensors and adjust the
1091 output settings such as fan voltage or power used by the water pump based on
1092 the available inputs using a configurable controller included in the board.
1093 This plugin collects all the available inputs as well as some of the output
1094 values chosen by this controller. The plugin is based on the I<libaquaero5>
1095 library provided by I<aquatools-ng>.
1096
1097 =over 4
1098
1099 =item B<Device> I<DevicePath>
1100
1101 Device path of the AquaeroE<nbsp>5's USB HID (human interface device), usually
1102 in the form C</dev/usb/hiddevX>. If this option is no set the plugin will try
1103 to auto-detect the Aquaero 5 USB device based on vendor-ID and product-ID.
1104
1105 =back
1106
1107 =head2 Plugin C<ascent>
1108
1109 This plugin collects information about an Ascent server, a free server for the
1110 "World of Warcraft" game. This plugin gathers the information by fetching the
1111 XML status page using C<libcurl> and parses it using C<libxml2>.
1112
1113 The configuration options are the same as for the C<apache> plugin above:
1114
1115 =over 4
1116
1117 =item B<URL> I<http://localhost/ascent/status/>
1118
1119 Sets the URL of the XML status output.
1120
1121 =item B<User> I<Username>
1122
1123 Optional user name needed for authentication.
1124
1125 =item B<Password> I<Password>
1126
1127 Optional password needed for authentication.
1128
1129 =item B<VerifyPeer> B<true|false>
1130
1131 Enable or disable peer SSL certificate verification. See
1132 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
1133
1134 =item B<VerifyHost> B<true|false>
1135
1136 Enable or disable peer host name verification. If enabled, the plugin checks
1137 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
1138 certificate matches the host name provided by the B<URL> option. If this
1139 identity check fails, the connection is aborted. Obviously, only works when
1140 connecting to a SSL enabled server. Enabled by default.
1141
1142 =item B<CACert> I<File>
1143
1144 File that holds one or more SSL certificates. If you want to use HTTPS you will
1145 possibly need this option. What CA certificates come bundled with C<libcurl>
1146 and are checked by default depends on the distribution you use.
1147
1148 =item B<Timeout> I<Milliseconds>
1149
1150 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
1151 milliseconds. By default, the configured B<Interval> is used to set the
1152 timeout.
1153
1154 =back
1155
1156 =head2 Plugin C<barometer>
1157
1158 This plugin reads absolute air pressure using digital barometer sensor on a I2C
1159 bus. Supported sensors are:
1160
1161 =over 5
1162
1163 =item I<MPL115A2> from Freescale,
1164 see L<http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL115A>.
1165
1166
1167 =item I<MPL3115> from Freescale
1168 see L<http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL3115A2>.
1169
1170
1171 =item I<BMP085> from Bosch Sensortec
1172
1173 =back
1174
1175 The sensor type - one of the above - is detected automatically by the plugin
1176 and indicated in the plugin_instance (you will see subdirectory
1177 "barometer-mpl115" or "barometer-mpl3115", or "barometer-bmp085"). The order of
1178 detection is BMP085 -> MPL3115 -> MPL115A2, the first one found will be used
1179 (only one sensor can be used by the plugin).
1180
1181 The plugin provides absolute barometric pressure, air pressure reduced to sea
1182 level (several possible approximations) and as an auxiliary value also internal
1183 sensor temperature. It uses (expects/provides) typical metric units - pressure
1184 in [hPa], temperature in [C], altitude in [m].
1185
1186 It was developed and tested under Linux only. The only platform dependency is
1187 the standard Linux i2c-dev interface (the particular bus driver has to
1188 support the SM Bus command subset).
1189
1190 The reduction or normalization to mean sea level pressure requires (depending
1191 on selected method/approximation) also altitude and reference to temperature
1192 sensor(s). When multiple temperature sensors are configured the minimum of
1193 their values is always used (expecting that the warmer ones are affected by
1194 e.g. direct sun light at that moment).
1195
1196 Synopsis:
1197
1198 <Plugin "barometer">
1199 Device "/dev/i2c-0";
1200 Oversampling 512
1201 PressureOffset 0.0
1202 TemperatureOffset 0.0
1203 Normalization 2
1204 Altitude 238.0
1205 TemperatureSensor "myserver/onewire-F10FCA000800/temperature"
1206 </Plugin>
1207
1208 =over 4
1209
1210 =item B<Device> I<device>
1211
1212 The only mandatory configuration parameter.
1213
1214 Device name of the I2C bus to which the sensor is connected. Note that
1215 typically you need to have loaded the i2c-dev module.
1216 Using i2c-tools you can check/list i2c buses available on your system by:
1217
1218 i2cdetect -l
1219
1220 Then you can scan for devices on given bus. E.g. to scan the whole bus 0 use:
1221
1222 i2cdetect -y -a 0
1223
1224 This way you should be able to verify that the pressure sensor (either type) is
1225 connected and detected on address 0x60.
1226
1227 =item B<Oversampling> I<value>
1228
1229 Optional parameter controlling the oversampling/accuracy. Default value
1230 is 1 providing fastest and least accurate reading.
1231
1232 For I<MPL115> this is the size of the averaging window. To filter out sensor
1233 noise a simple averaging using floating window of this configurable size is
1234 used. The plugin will use average of the last C<value> measurements (value of 1
1235 means no averaging). Minimal size is 1, maximal 1024.
1236
1237 For I<MPL3115> this is the oversampling value. The actual oversampling is
1238 performed by the sensor and the higher value the higher accuracy and longer
1239 conversion time (although nothing to worry about in the collectd context).
1240 Supported values are: 1, 2, 4, 8, 16, 32, 64 and 128. Any other value is
1241 adjusted by the plugin to the closest supported one.
1242
1243 For I<BMP085> this is the oversampling value. The actual oversampling is
1244 performed by the sensor and the higher value the higher accuracy and longer
1245 conversion time (although nothing to worry about in the collectd context).
1246 Supported values are: 1, 2, 4, 8. Any other value is adjusted by the plugin to
1247 the closest supported one.
1248
1249 =item B<PressureOffset> I<offset>
1250
1251 Optional parameter for MPL3115 only.
1252
1253 You can further calibrate the sensor by supplying pressure and/or temperature
1254 offsets. This is added to the measured/caclulated value (i.e. if the measured
1255 value is too high then use negative offset).
1256 In hPa, default is 0.0.
1257
1258 =item B<TemperatureOffset> I<offset>
1259
1260 Optional parameter for MPL3115 only.
1261
1262 You can further calibrate the sensor by supplying pressure and/or temperature
1263 offsets. This is added to the measured/caclulated value (i.e. if the measured
1264 value is too high then use negative offset).
1265 In C, default is 0.0.
1266
1267 =item B<Normalization> I<method>
1268
1269 Optional parameter, default value is 0.
1270
1271 Normalization method - what approximation/model is used to compute the mean sea
1272 level pressure from the air absolute pressure.
1273
1274 Supported values of the C<method> (integer between from 0 to 2) are:
1275
1276 =over 5
1277
1278 =item B<0> - no conversion, absolute pressure is simply copied over. For this method you
1279 do not need to configure C<Altitude> or C<TemperatureSensor>.
1280
1281 =item B<1> - international formula for conversion ,
1282 See
1283 L<http://en.wikipedia.org/wiki/Atmospheric_pressure#Altitude_atmospheric_pressure_variation>.
1284 For this method you have to configure C<Altitude> but do not need
1285 C<TemperatureSensor> (uses fixed global temperature average instead).
1286
1287 =item B<2> - formula as recommended by the Deutsche Wetterdienst (German
1288 Meteorological Service).
1289 See L<http://de.wikipedia.org/wiki/Barometrische_H%C3%B6henformel#Theorie>
1290 For this method you have to configure both C<Altitude> and
1291 C<TemperatureSensor>.
1292
1293 =back
1294
1295
1296 =item B<Altitude> I<altitude>
1297
1298 The altitude (in meters) of the location where you meassure the pressure.
1299
1300 =item B<TemperatureSensor> I<reference>
1301
1302 Temperature sensor(s) which should be used as a reference when normalizing the
1303 pressure using C<Normalization> method 2.
1304 When specified more sensors a minimum is found and used each time. The
1305 temperature reading directly from this pressure sensor/plugin is typically not
1306 suitable as the pressure sensor will be probably inside while we want outside
1307 temperature. The collectd reference name is something like
1308 <hostname>/<plugin_name>-<plugin_instance>/<type>-<type_instance>
1309 (<type_instance> is usually omitted when there is just single value type). Or
1310 you can figure it out from the path of the output data files.
1311
1312 =back
1313
1314 =head2 Plugin C<battery>
1315
1316 The I<battery plugin> reports the remaining capacity, power and voltage of
1317 laptop batteries.
1318
1319 =over 4
1320
1321 =item B<ValuesPercentage> B<false>|B<true>
1322
1323 When enabled, remaining capacity is reported as a percentage, e.g. "42%
1324 capacity remaining". Otherwise the capacity is stored as reported by the
1325 battery, most likely in "Wh". This option does not work with all input methods,
1326 in particular when only C</proc/pmu> is available on an old Linux system.
1327 Defaults to B<false>.
1328
1329 =item B<ReportDegraded> B<false>|B<true>
1330
1331 Typical laptop batteries degrade over time, meaning the capacity decreases with
1332 recharge cycles. The maximum charge of the previous charge cycle is tracked as
1333 "last full capacity" and used to determine that a battery is "fully charged".
1334
1335 When this option is set to B<false>, the default, the I<battery plugin> will
1336 only report the remaining capacity. If the B<ValuesPercentage> option is
1337 enabled, the relative remaining capacity is calculated as the ratio of the
1338 "remaining capacity" and the "last full capacity". This is what most tools,
1339 such as the status bar of desktop environments, also do.
1340
1341 When set to B<true>, the battery plugin will report three values: B<charged>
1342 (remaining capacity), B<discharged> (difference between "last full capacity"
1343 and "remaining capacity") and B<degraded> (difference between "design capacity"
1344 and "last full capacity").
1345
1346 =item B<QueryStateFS> B<false>|B<true>
1347
1348 When set to B<true>, the battery plugin will only read statistics
1349 related to battery performance as exposed by StateFS at
1350 /run/state. StateFS is used in Mer-based Sailfish OS, for
1351 example.
1352
1353 =back
1354
1355 =head2 Plugin C<bind>
1356
1357 Starting with BIND 9.5.0, the most widely used DNS server software provides
1358 extensive statistics about queries, responses and lots of other information.
1359 The bind plugin retrieves this information that's encoded in XML and provided
1360 via HTTP and submits the values to collectd.
1361
1362 To use this plugin, you first need to tell BIND to make this information
1363 available. This is done with the C<statistics-channels> configuration option:
1364
1365 statistics-channels {
1366 inet localhost port 8053;
1367 };
1368
1369 The configuration follows the grouping that can be seen when looking at the
1370 data with an XSLT compatible viewer, such as a modern web browser. It's
1371 probably a good idea to make yourself familiar with the provided values, so you
1372 can understand what the collected statistics actually mean.
1373
1374 Synopsis:
1375
1376 <Plugin "bind">
1377 URL "http://localhost:8053/"
1378 ParseTime false
1379 OpCodes true
1380 QTypes true
1381
1382 ServerStats true
1383 ZoneMaintStats true
1384 ResolverStats false
1385 MemoryStats true
1386
1387 <View "_default">
1388 QTypes true
1389 ResolverStats true
1390 CacheRRSets true
1391
1392 Zone "127.in-addr.arpa/IN"
1393 </View>
1394 </Plugin>
1395
1396 The bind plugin accepts the following configuration options:
1397
1398 =over 4
1399
1400 =item B<URL> I<URL>
1401
1402 URL from which to retrieve the XML data. If not specified,
1403 C<http://localhost:8053/> will be used.
1404
1405 =item B<ParseTime> B<true>|B<false>
1406
1407 When set to B<true>, the time provided by BIND will be parsed and used to
1408 dispatch the values. When set to B<false>, the local time source is queried.
1409
1410 This setting is set to B<true> by default for backwards compatibility; setting
1411 this to B<false> is I<recommended> to avoid problems with timezones and
1412 localization.
1413
1414 =item B<OpCodes> B<true>|B<false>
1415
1416 When enabled, statistics about the I<"OpCodes">, for example the number of
1417 C<QUERY> packets, are collected.
1418
1419 Default: Enabled.
1420
1421 =item B<QTypes> B<true>|B<false>
1422
1423 When enabled, the number of I<incoming> queries by query types (for example
1424 C<A>, C<MX>, C<AAAA>) is collected.
1425
1426 Default: Enabled.
1427
1428 =item B<ServerStats> B<true>|B<false>
1429
1430 Collect global server statistics, such as requests received over IPv4 and IPv6,
1431 successful queries, and failed updates.
1432
1433 Default: Enabled.
1434
1435 =item B<ZoneMaintStats> B<true>|B<false>
1436
1437 Collect zone maintenance statistics, mostly information about notifications
1438 (zone updates) and zone transfers.
1439
1440 Default: Enabled.
1441
1442 =item B<ResolverStats> B<true>|B<false>
1443
1444 Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
1445 (e.E<nbsp>g. queries over IPv4, lame servers). Since the global resolver
1446 counters apparently were removed in BIND 9.5.1 and 9.6.0, this is disabled by
1447 default. Use the B<ResolverStats> option within a B<View "_default"> block
1448 instead for the same functionality.
1449
1450 Default: Disabled.
1451
1452 =item B<MemoryStats>
1453
1454 Collect global memory statistics.
1455
1456 Default: Enabled.
1457
1458 =item B<Timeout> I<Milliseconds>
1459
1460 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
1461 milliseconds. By default, the configured B<Interval> is used to set the
1462 timeout.
1463
1464 =item B<View> I<Name>
1465
1466 Collect statistics about a specific I<"view">. BIND can behave different,
1467 mostly depending on the source IP-address of the request. These different
1468 configurations are called "views". If you don't use this feature, you most
1469 likely are only interested in the C<_default> view.
1470
1471 Within a E<lt>B<View>E<nbsp>I<name>E<gt> block, you can specify which
1472 information you want to collect about a view. If no B<View> block is
1473 configured, no detailed view statistics will be collected.
1474
1475 =over 4
1476
1477 =item B<QTypes> B<true>|B<false>
1478
1479 If enabled, the number of I<outgoing> queries by query type (e.E<nbsp>g. C<A>,
1480 C<MX>) is collected.
1481
1482 Default: Enabled.
1483
1484 =item B<ResolverStats> B<true>|B<false>
1485
1486 Collect resolver statistics, i.E<nbsp>e. statistics about outgoing requests
1487 (e.E<nbsp>g. queries over IPv4, lame servers).
1488
1489 Default: Enabled.
1490
1491 =item B<CacheRRSets> B<true>|B<false>
1492
1493 If enabled, the number of entries (I<"RR sets">) in the view's cache by query
1494 type is collected. Negative entries (queries which resulted in an error, for
1495 example names that do not exist) are reported with a leading exclamation mark,
1496 e.E<nbsp>g. "!A".
1497
1498 Default: Enabled.
1499
1500 =item B<Zone> I<Name>
1501
1502 When given, collect detailed information about the given zone in the view. The
1503 information collected if very similar to the global B<ServerStats> information
1504 (see above).
1505
1506 You can repeat this option to collect detailed information about multiple
1507 zones.
1508
1509 By default no detailed zone information is collected.
1510
1511 =back
1512
1513 =back
1514
1515 =head2 Plugin C<buddyinfo>
1516
1517 The B<buddyinfo> plugin collects information by reading "/proc/buddyinfo".
1518 This file contains information about the number of available contagious
1519 physical pages at the moment.
1520
1521 =over 4
1522
1523 =item B<Zone> I<ZoneName>
1524
1525 Zone to collect info about. Will collect all zones by default.
1526
1527 =back
1528
1529 =head2 Plugin C<capabilities>
1530
1531 The C<capabilities> plugin collects selected static platform data using
1532 I<dmidecode> and expose it through micro embedded webserver. The data
1533 returned by plugin is in json format.
1534
1535 B<Synopsis:>
1536
1537 <Plugin capabilities>
1538 Host "localhost"
1539 Port "9104"
1540 </Plugin>
1541
1542 Available configuration options for the C<capabilities> plugin:
1543
1544 =over 4
1545
1546 =item B<Host> I<Hostname>
1547
1548 Bind to the hostname / address I<Host>. By default, the plugin will bind to the
1549 "any" address, i.e. accept packets sent to any of the hosts addresses.
1550
1551 This option is supported only for libmicrohttpd newer than 0.9.0.
1552
1553 =item B<Port> I<Port>
1554
1555 Port the embedded webserver should listen on. Defaults to B<9104>.
1556
1557 =back
1558
1559 =head2 Plugin C<ceph>
1560
1561 The ceph plugin collects values from JSON data to be parsed by B<libyajl>
1562 (L<https://lloyd.github.io/yajl/>) retrieved from ceph daemon admin sockets.
1563
1564 A separate B<Daemon> block must be configured for each ceph daemon to be
1565 monitored. The following example will read daemon statistics from four
1566 separate ceph daemons running on the same device (two OSDs, one MON, one MDS) :
1567
1568 <Plugin ceph>
1569 LongRunAvgLatency false
1570 ConvertSpecialMetricTypes true
1571 <Daemon "osd.0">
1572 SocketPath "/var/run/ceph/ceph-osd.0.asok"
1573 </Daemon>
1574 <Daemon "osd.1">
1575 SocketPath "/var/run/ceph/ceph-osd.1.asok"
1576 </Daemon>
1577 <Daemon "mon.a">
1578 SocketPath "/var/run/ceph/ceph-mon.ceph1.asok"
1579 </Daemon>
1580 <Daemon "mds.a">
1581 SocketPath "/var/run/ceph/ceph-mds.ceph1.asok"
1582 </Daemon>
1583 </Plugin>
1584
1585 The ceph plugin accepts the following configuration options:
1586
1587 =over 4
1588
1589 =item B<LongRunAvgLatency> B<true>|B<false>
1590
1591 If enabled, latency values(sum,count pairs) are calculated as the long run
1592 average - average since the ceph daemon was started = (sum / count).
1593 When disabled, latency values are calculated as the average since the last
1594 collection = (sum_now - sum_last) / (count_now - count_last).
1595
1596 Default: Disabled
1597
1598 =item B<ConvertSpecialMetricTypes> B<true>|B<false>
1599
1600 If enabled, special metrics (metrics that differ in type from similar counters)
1601 are converted to the type of those similar counters. This currently only
1602 applies to filestore.journal_wr_bytes which is a counter for OSD daemons. The
1603 ceph schema reports this metric type as a sum,count pair while similar counters
1604 are treated as derive types. When converted, the sum is used as the counter
1605 value and is treated as a derive type.
1606 When disabled, all metrics are treated as the types received from the ceph schema.
1607
1608 Default: Enabled
1609
1610 =back
1611
1612 Each B<Daemon> block must have a string argument for the plugin instance name.
1613 A B<SocketPath> is also required for each B<Daemon> block:
1614
1615 =over 4
1616
1617 =item B<Daemon> I<DaemonName>
1618
1619 Name to be used as the instance name for this daemon.
1620
1621 =item B<SocketPath> I<SocketPath>
1622
1623 Specifies the path to the UNIX admin socket of the ceph daemon.
1624
1625 =back
1626
1627 =head2 Plugin C<cgroups>
1628
1629 This plugin collects the CPU user/system time for each I<cgroup> by reading the
1630 F<cpuacct.stat> files in the first cpuacct-mountpoint (typically
1631 F</sys/fs/cgroup/cpu.cpuacct> on machines using systemd).
1632
1633 =over 4
1634
1635 =item B<CGroup> I<Directory>
1636
1637 Select I<cgroup> based on the name. Whether only matching I<cgroups> are
1638 collected or if they are ignored is controlled by the B<IgnoreSelected> option;
1639 see below.
1640
1641 See F</"IGNORELISTS"> for details.
1642
1643 =item B<IgnoreSelected> B<true>|B<false>
1644
1645 Invert the selection: If set to true, all cgroups I<except> the ones that
1646 match any one of the criteria are collected. By default only selected
1647 cgroups are collected if a selection is made. If no selection is configured
1648 at all, B<all> cgroups are selected.
1649
1650 =back
1651
1652 =head2 Plugin C<check_uptime>
1653
1654 The I<check_uptime plugin> designed to check and notify about host or service
1655 status based on I<uptime> metric.
1656
1657 When new metric of I<uptime> type appears in cache, OK notification is sent.
1658 When new value for metric is less than previous value, WARNING notification is
1659 sent about host/service restart.
1660 When no new updates comes for metric and cache entry expires, then FAILURE
1661 notification is sent about unreachable host or service.
1662
1663 By default (when no explicit configuration), plugin checks for I<uptime> metric.
1664
1665 B<Synopsis:>
1666
1667 <Plugin "check_uptime">
1668 Type "uptime"
1669 Type "my_uptime_type"
1670 </Plugin>
1671
1672 =over 4
1673
1674 =item B<Type> I<Type>
1675
1676 Metric type to check for status/values. The type should consist single GAUGE
1677 data source.
1678
1679 =back
1680
1681 =head2 Plugin C<chrony>
1682
1683 The C<chrony> plugin collects ntp data from a B<chronyd> server, such as clock
1684 skew and per-peer stratum.
1685
1686 For talking to B<chronyd>, it mimics what the B<chronyc> control program does
1687 on the wire.
1688
1689 Available configuration options for the C<chrony> plugin:
1690
1691 =over 4
1692
1693 =item B<Host> I<Hostname>
1694
1695 Hostname of the host running B<chronyd>. Defaults to B<localhost>.
1696
1697 =item B<Port> I<Port>
1698
1699 UDP-Port to connect to. Defaults to B<323>.
1700
1701 =item B<Timeout> I<Timeout>
1702
1703 Connection timeout in seconds. Defaults to B<2>.
1704
1705 =back
1706
1707 =head2 Plugin Connectivity
1708
1709 connectivity - Documentation of collectd's C<connectivity plugin>
1710
1711
1712 LoadPlugin connectivity
1713 # ...
1714 <Plugin connectivity>
1715 Interface eth0
1716 </Plugin>
1717
1718 The C<connectivity plugin> queries interface status using netlink (man 7 netlink) which provides information about network interfaces via the NETLINK_ROUTE family (man 7 rtnetlink). The plugin translates the value it receives to collectd's internal format and, depending on the write plugins you have loaded, it may be written to disk or submitted to another instance.
1719 The plugin listens to interfaces enumerated within the plugin configuration (see below). If no interfaces are listed, then the default is for all interfaces to be monitored.
1720
1721 This example shows C<connectivity plugin> monitoring all interfaces.
1722 LoadPlugin connectivity
1723 <Plugin connectivity>
1724 </Plugin>
1725
1726 This example shows C<connectivity plugin> monitoring 2 interfaces, "eth0" and "eth1".
1727 LoadPlugin connectivity
1728 <Plugin connectivity>
1729 Interface eth0
1730 Interface eth1
1731 </Plugin>
1732
1733 This example shows C<connectivity plugin> monitoring all interfaces except "eth1".
1734 LoadPlugin connectivity
1735 <Plugin connectivity>
1736 Interface eth1
1737 IgnoreSelected true
1738 </Plugin>
1739
1740 =over 4
1741
1742 =item B<Interface> I<interface_name>
1743
1744 interface(s) to monitor connect to.
1745
1746 =back
1747
1748 =head2 Plugin C<conntrack>
1749
1750 This plugin collects IP conntrack statistics.
1751
1752 =over 4
1753
1754 =item B<OldFiles>
1755
1756 Assume the B<conntrack_count> and B<conntrack_max> files to be found in
1757 F</proc/sys/net/ipv4/netfilter> instead of F</proc/sys/net/netfilter/>.
1758
1759 =back
1760
1761 =head2 Plugin C<cpu>
1762
1763 The I<CPU plugin> collects CPU usage metrics. By default, CPU usage is reported
1764 as Jiffies, using the C<cpu> type. Two aggregations are available:
1765
1766 =over 4
1767
1768 =item *
1769
1770 Sum, per-state, over all CPUs installed in the system; and
1771
1772 =item *
1773
1774 Sum, per-CPU, over all non-idle states of a CPU, creating an "active" state.
1775
1776 =back
1777
1778 The two aggregations can be combined, leading to I<collectd> only emitting a
1779 single "active" metric for the entire system. As soon as one of these
1780 aggregations (or both) is enabled, the I<cpu plugin> will report a percentage,
1781 rather than Jiffies. In addition, you can request individual, per-state,
1782 per-CPU metrics to be reported as percentage.
1783
1784 The following configuration options are available:
1785
1786 =over 4
1787
1788 =item B<ReportByState> B<true>|B<false>
1789
1790 When set to B<true>, the default, reports per-state metrics, e.g. "system",
1791 "user" and "idle".
1792 When set to B<false>, aggregates (sums) all I<non-idle> states into one
1793 "active" metric.
1794
1795 =item B<ReportByCpu> B<true>|B<false>
1796
1797 When set to B<true>, the default, reports per-CPU (per-core) metrics.
1798 When set to B<false>, instead of reporting metrics for individual CPUs, only a
1799 global sum of CPU states is emitted.
1800
1801 =item B<ValuesPercentage> B<false>|B<true>
1802
1803 This option is only considered when both, B<ReportByCpu> and B<ReportByState>
1804 are set to B<true>. In this case, by default, metrics will be reported as
1805 Jiffies. By setting this option to B<true>, you can request percentage values
1806 in the un-aggregated (per-CPU, per-state) mode as well.
1807
1808 =item B<ReportNumCpu> B<false>|B<true>
1809
1810 When set to B<true>, reports the number of available CPUs.
1811 Defaults to B<false>.
1812
1813 =item B<ReportGuestState> B<false>|B<true>
1814
1815 When set to B<true>, reports the "guest" and "guest_nice" CPU states.
1816 Defaults to B<false>.
1817
1818 =item B<SubtractGuestState> B<false>|B<true>
1819
1820 This option is only considered when B<ReportGuestState> is set to B<true>.
1821 "guest" and "guest_nice" are included in respectively "user" and "nice".
1822 If set to B<true>, "guest" will be subtracted from "user" and "guest_nice"
1823 will be subtracted from "nice".
1824 Defaults to B<true>.
1825
1826 =back
1827
1828 =head2 Plugin C<cpufreq>
1829
1830 This plugin is available on Linux and FreeBSD only. It doesn't have any
1831 options. On Linux it reads
1832 F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for the first CPU
1833 installed) to get the current CPU frequency. If this file does not exist make
1834 sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a similar tool is
1835 installed and an "cpu governor" (that's a kernel module) is loaded.
1836
1837 On Linux, if the system has the I<cpufreq-stats> kernel module loaded, this
1838 plugin reports the rate of p-state (cpu frequency) transitions and the
1839 percentage of time spent in each p-state.
1840
1841 On FreeBSD it does a sysctl dev.cpu.0.freq and submits this as instance 0.
1842 At this time FreeBSD only has one frequency setting for all cores.
1843 See the BUGS section in the FreeBSD man page for cpufreq(4) for more details.
1844
1845 On FreeBSD the plugin checks the success of sysctl dev.cpu.0.freq and
1846 unregisters the plugin when this fails. A message will be logged to indicate
1847 this.
1848
1849 =head2 Plugin C<cpusleep>
1850
1851 This plugin doesn't have any options. It reads CLOCK_BOOTTIME and
1852 CLOCK_MONOTONIC and reports the difference between these clocks. Since
1853 BOOTTIME clock increments while device is suspended and MONOTONIC
1854 clock does not, the derivative of the difference between these clocks
1855 gives the relative amount of time the device has spent in suspend
1856 state. The recorded value is in milliseconds of sleep per seconds of
1857 wall clock.
1858
1859 =head2 Plugin C<csv>
1860
1861 =over 4
1862
1863 =item B<DataDir> I<Directory>
1864
1865 Set the directory to store CSV-files under. Per default CSV-files are generated
1866 beneath the daemon's working directory, i.E<nbsp>e. the B<BaseDir>.
1867 The special strings B<stdout> and B<stderr> can be used to write to the standard
1868 output and standard error channels, respectively. This, of course, only makes
1869 much sense when collectd is running in foreground- or non-daemon-mode.
1870
1871 =item B<StoreRates> B<true|false>
1872
1873 If set to B<true>, convert counter values to rates. If set to B<false> (the
1874 default) counter values are stored as is, i.E<nbsp>e. as an increasing integer
1875 number.
1876
1877 =back
1878
1879 =head2 cURL Statistics
1880
1881 All cURL-based plugins support collection of generic, request-based
1882 statistics. These are disabled by default and can be enabled selectively for
1883 each page or URL queried from the curl, curl_json, or curl_xml plugins. See
1884 the documentation of those plugins for specific information. This section
1885 describes the available metrics that can be configured for each plugin. All
1886 options are disabled by default.
1887
1888 See L<http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html> for more details.
1889
1890 =over 4
1891
1892 =item B<TotalTime> B<true|false>
1893
1894 Total time of the transfer, including name resolving, TCP connect, etc.
1895
1896 =item B<NamelookupTime> B<true|false>
1897
1898 Time it took from the start until name resolving was completed.
1899
1900 =item B<ConnectTime> B<true|false>
1901
1902 Time it took from the start until the connect to the remote host (or proxy)
1903 was completed.
1904
1905 =item B<AppconnectTime> B<true|false>
1906
1907 Time it took from the start until the SSL/SSH connect/handshake to the remote
1908 host was completed.
1909
1910 =item B<PretransferTime> B<true|false>
1911
1912 Time it took from the start until just before the transfer begins.
1913
1914 =item B<StarttransferTime> B<true|false>
1915
1916 Time it took from the start until the first byte was received.
1917
1918 =item B<RedirectTime> B<true|false>
1919
1920 Time it took for all redirection steps include name lookup, connect,
1921 pre-transfer and transfer before final transaction was started.
1922
1923 =item B<RedirectCount> B<true|false>
1924
1925 The total number of redirections that were actually followed.
1926
1927 =item B<SizeUpload> B<true|false>
1928
1929 The total amount of bytes that were uploaded.
1930
1931 =item B<SizeDownload> B<true|false>
1932
1933 The total amount of bytes that were downloaded.
1934
1935 =item B<SpeedDownload> B<true|false>
1936
1937 The average download speed that curl measured for the complete download.
1938
1939 =item B<SpeedUpload> B<true|false>
1940
1941 The average upload speed that curl measured for the complete upload.
1942
1943 =item B<HeaderSize> B<true|false>
1944
1945 The total size of all the headers received.
1946
1947 =item B<RequestSize> B<true|false>
1948
1949 The total size of the issued requests.
1950
1951 =item B<ContentLengthDownload> B<true|false>
1952
1953 The content-length of the download.
1954
1955 =item B<ContentLengthUpload> B<true|false>
1956
1957 The specified size of the upload.
1958
1959 =item B<NumConnects> B<true|false>
1960
1961 The number of new connections that were created to achieve the transfer.
1962
1963 =back
1964
1965 =head2 Plugin C<curl>
1966
1967 The curl plugin uses the B<libcurl> (L<http://curl.haxx.se/>) to read web pages
1968 and the match infrastructure (the same code used by the tail plugin) to use
1969 regular expressions with the received data.
1970
1971 The following example will read the current value of AMD stock from Google's
1972 finance page and dispatch the value to collectd.
1973
1974 <Plugin curl>
1975 <Page "stock_quotes">
1976 Plugin "quotes"
1977 URL "http://finance.google.com/finance?q=NYSE%3AAMD"
1978 AddressFamily "any"
1979 User "foo"
1980 Password "bar"
1981 Digest false
1982 VerifyPeer true
1983 VerifyHost true
1984 CACert "/path/to/ca.crt"
1985 Header "X-Custom-Header: foobar"
1986 Post "foo=bar"
1987
1988 MeasureResponseTime false
1989 MeasureResponseCode false
1990
1991 <Match>
1992 Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
1993 DSType "GaugeAverage"
1994 # Note: `stock_value' is not a standard type.
1995 Type "stock_value"
1996 Instance "AMD"
1997 </Match>
1998 </Page>
1999 </Plugin>
2000
2001 In the B<Plugin> block, there may be one or more B<Page> blocks, each defining
2002 a web page and one or more "matches" to be performed on the returned data. The
2003 string argument to the B<Page> block is used as plugin instance.
2004
2005 The following options are valid within B<Page> blocks:
2006
2007 =over 4
2008
2009 =item B<Plugin> I<Plugin>
2010
2011 Use I<Plugin> as the plugin name when submitting values.
2012 Defaults to C<curl>.
2013
2014 =item B<URL> I<URL>
2015
2016 URL of the web site to retrieve. Since a regular expression will be used to
2017 extract information from this data, non-binary data is a big plus here ;)
2018
2019 =item B<AddressFamily> I<Type>
2020
2021 IP version to resolve URL to. Useful in cases when hostname in URL resolves
2022 to both IPv4 and IPv6 addresses, and you are interested in using one of them
2023 specifically.
2024 Use C<ipv4> to enforce IPv4, C<ipv6> to enforce IPv6, or C<any> to keep the
2025 default behavior of resolving addresses to all IP versions your system allows.
2026 If C<libcurl> is compiled without IPv6 support, using C<ipv6> will result in
2027 a warning and fallback to C<any>.
2028 If C<Type> cannot be parsed, a warning will be printed and the whole B<Page>
2029 block will be ignored.
2030
2031 =item B<User> I<Name>
2032
2033 Username to use if authorization is required to read the page.
2034
2035 =item B<Password> I<Password>
2036
2037 Password to use if authorization is required to read the page.
2038
2039 =item B<Digest> B<true>|B<false>
2040
2041 Enable HTTP digest authentication.
2042
2043 =item B<VerifyPeer> B<true>|B<false>
2044
2045 Enable or disable peer SSL certificate verification. See
2046 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
2047
2048 =item B<VerifyHost> B<true>|B<false>
2049
2050 Enable or disable peer host name verification. If enabled, the plugin checks if
2051 the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
2052 matches the host name provided by the B<URL> option. If this identity check
2053 fails, the connection is aborted. Obviously, only works when connecting to a
2054 SSL enabled server. Enabled by default.
2055
2056 =item B<CACert> I<file>
2057
2058 File that holds one or more SSL certificates. If you want to use HTTPS you will
2059 possibly need this option. What CA certificates come bundled with C<libcurl>
2060 and are checked by default depends on the distribution you use.
2061
2062 =item B<Header> I<Header>
2063
2064 A HTTP header to add to the request. Multiple headers are added if this option
2065 is specified more than once.
2066
2067 =item B<Post> I<Body>
2068
2069 Specifies that the HTTP operation should be a POST instead of a GET. The
2070 complete data to be posted is given as the argument. This option will usually
2071 need to be accompanied by a B<Header> option to set an appropriate
2072 C<Content-Type> for the post body (e.g. to
2073 C<application/x-www-form-urlencoded>).
2074
2075 =item B<MeasureResponseTime> B<true>|B<false>
2076
2077 Measure response time for the request. If this setting is enabled, B<Match>
2078 blocks (see below) are optional. Disabled by default.
2079
2080 Beware that requests will get aborted if they take too long to complete. Adjust
2081 B<Timeout> accordingly if you expect B<MeasureResponseTime> to report such slow
2082 requests.
2083
2084 This option is similar to enabling the B<TotalTime> statistic but it's
2085 measured by collectd instead of cURL.
2086
2087 =item B<MeasureResponseCode> B<true>|B<false>
2088
2089 Measure response code for the request. If this setting is enabled, B<Match>
2090 blocks (see below) are optional. Disabled by default.
2091
2092 =item B<E<lt>StatisticsE<gt>>
2093
2094 One B<Statistics> block can be used to specify cURL statistics to be collected
2095 for each request to the remote web site. See the section "cURL Statistics"
2096 above for details. If this setting is enabled, B<Match> blocks (see below) are
2097 optional.
2098
2099 =item B<E<lt>MatchE<gt>>
2100
2101 One or more B<Match> blocks that define how to match information in the data
2102 returned by C<libcurl>. The C<curl> plugin uses the same infrastructure that's
2103 used by the C<tail> plugin, so please see the documentation of the C<tail>
2104 plugin below on how matches are defined. If the B<MeasureResponseTime> or
2105 B<MeasureResponseCode> options are set to B<true>, B<Match> blocks are
2106 optional.
2107
2108 =item B<Interval> I<Interval>
2109
2110 Sets the interval (in seconds) in which the values will be collected from this
2111 URL. By default the global B<Interval> setting will be used.
2112
2113 =item B<Timeout> I<Milliseconds>
2114
2115 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
2116 milliseconds. By default, the configured B<Interval> is used to set the
2117 timeout. Prior to version 5.5.0, there was no timeout and requests could hang
2118 indefinitely. This legacy behaviour can be achieved by setting the value of
2119 B<Timeout> to 0.
2120
2121 If B<Timeout> is 0 or bigger than the B<Interval>, keep in mind that each slow
2122 network connection will stall one read thread. Adjust the B<ReadThreads> global
2123 setting accordingly to prevent this from blocking other plugins.
2124
2125 =back
2126
2127 =head2 Plugin C<curl_json>
2128
2129 The B<curl_json plugin> collects values from JSON data to be parsed by
2130 B<libyajl> (L<https://lloyd.github.io/yajl/>) retrieved via
2131 either B<libcurl> (L<http://curl.haxx.se/>) or read directly from a
2132 unix socket. The former can be used, for example, to collect values
2133 from CouchDB documents (which are stored JSON notation), and the
2134 latter to collect values from a uWSGI stats socket.
2135
2136 The following example will collect several values from the built-in
2137 C<_stats> runtime statistics module of I<CouchDB>
2138 (L<http://wiki.apache.org/couchdb/Runtime_Statistics>).
2139
2140 <Plugin curl_json>
2141 <URL "http://localhost:5984/_stats">
2142 AddressFamily "any"
2143 Instance "httpd"
2144 <Key "httpd/requests/count">
2145 Type "http_requests"
2146 </Key>
2147
2148 <Key "httpd_request_methods/*/count">
2149 Type "http_request_methods"
2150 </Key>
2151
2152 <Key "httpd_status_codes/*/count">
2153 Type "http_response_codes"
2154 </Key>
2155 </URL>
2156 </Plugin>
2157
2158 This example will collect data directly from a I<uWSGI> "Stats Server" socket.
2159
2160 <Plugin curl_json>
2161 <Sock "/var/run/uwsgi.stats.sock">
2162 Instance "uwsgi"
2163 <Key "workers/*/requests">
2164 Type "http_requests"
2165 </Key>
2166
2167 <Key "workers/*/apps/*/requests">
2168 Type "http_requests"
2169 </Key>
2170 </Sock>
2171 </Plugin>
2172
2173 In the B<Plugin> block, there may be one or more B<URL> blocks, each
2174 defining a URL to be fetched via HTTP (using libcurl) or B<Sock>
2175 blocks defining a unix socket to read JSON from directly. Each of
2176 these blocks may have one or more B<Key> blocks.
2177
2178 The B<Key> string argument must be in a path format. Each component is
2179 used to match the key from a JSON map or the index of an JSON
2180 array. If a path component of a B<Key> is a I<*>E<nbsp>wildcard, the
2181 values for all map keys or array indices will be collectd.
2182
2183 The following options are valid within B<URL> blocks:
2184
2185 =over 4
2186
2187 =item B<AddressFamily> I<Type>
2188
2189 IP version to resolve URL to. Useful in cases when hostname in URL resolves
2190 to both IPv4 and IPv6 addresses, and you are interested in using one of them
2191 specifically.
2192 Use C<ipv4> to enforce IPv4, C<ipv6> to enforce IPv6, or C<any> to keep the
2193 default behavior of resolving addresses to all IP versions your system allows.
2194 If C<libcurl> is compiled without IPv6 support, using C<ipv6> will result in
2195 a warning and fallback to C<any>.
2196 If C<Type> cannot be parsed, a warning will be printed and the whole B<URL>
2197 block will be ignored.
2198
2199 =item B<Host> I<Name>
2200
2201 Use I<Name> as the host name when submitting values. Defaults to the global
2202 host name setting.
2203
2204 =item B<Plugin> I<Plugin>
2205
2206 Use I<Plugin> as the plugin name when submitting values.
2207 Defaults to C<curl_json>.
2208
2209 =item B<Instance> I<Instance>
2210
2211 Sets the plugin instance to I<Instance>.
2212
2213 =item B<Interval> I<Interval>
2214
2215 Sets the interval (in seconds) in which the values will be collected from this
2216 URL. By default the global B<Interval> setting will be used.
2217
2218 =item B<User> I<Name>
2219
2220 =item B<Password> I<Password>
2221
2222 =item B<Digest> B<true>|B<false>
2223
2224 =item B<VerifyPeer> B<true>|B<false>
2225
2226 =item B<VerifyHost> B<true>|B<false>
2227
2228 =item B<CACert> I<file>
2229
2230 =item B<Header> I<Header>
2231
2232 =item B<Post> I<Body>
2233
2234 =item B<Timeout> I<Milliseconds>
2235
2236 These options behave exactly equivalent to the appropriate options of the
2237 I<cURL> plugin. Please see there for a detailed description.
2238
2239 =item B<E<lt>StatisticsE<gt>>
2240
2241 One B<Statistics> block can be used to specify cURL statistics to be collected
2242 for each request to the remote URL. See the section "cURL Statistics" above
2243 for details.
2244
2245 =back
2246
2247 The following options are valid within B<Key> blocks:
2248
2249 =over 4
2250
2251 =item B<Type> I<Type>
2252
2253 Sets the type used to dispatch the values to the daemon. Detailed information
2254 about types and their configuration can be found in L<types.db(5)>. This
2255 option is mandatory.
2256
2257 =item B<Instance> I<Instance>
2258
2259 Type-instance to use. Defaults to the current map key or current string array element value.
2260
2261 =back
2262
2263 =head2 Plugin C<curl_jolokia>
2264
2265 The B<curl_jolokia plugin> collects values from MBeanServevr - servlet engines equipped
2266 with the jolokia (L<https://jolokia.org>) MBean. It sends a pre-configured
2267 JSON-Postbody to the servlet via HTTP commanding the jolokia Bean to reply with
2268 a singe JSON equipped with all JMX counters requested.
2269 By reducing TCP roundtrips in comparison to conventional JMX clients that
2270 query one value via tcp at a time, it can return hundrets of values in one roundtrip.
2271 Moreof - no java binding is required in collectd to do so.
2272
2273 It uses B<libyajl> (L<https://lloyd.github.io/yajl/>) to parse the
2274 Jolokia JSON reply retrieved via B<libcurl> (L<http://curl.haxx.se/>)
2275
2276 <Plugin curl_jolokia>
2277 <URL "http://10.10.10.10:7101/jolokia-war-1.2.0/?ignoreErrors=true&canonicalNaming=false";>
2278 Host "_APPPERF_JMX"
2279 User "webloginname"
2280 Password "passvoid"
2281 Post <JOLOKIA json post data>
2282
2283 <BeanName "PS_Scavenge">
2284 MBean "java.lang:name=PS Scavenge,type=GarbageCollector"
2285 BeanNameSpace "java_lang"
2286 <AttributeName "collectiontime" >
2287 Attribute "CollectionTime"
2288 type "gauge"
2289 </AttributeName>
2290 <AttributeName "collectioncount" >
2291 Attribute "CollectionCount"
2292 type "gauge"
2293 </AttributeName>
2294 </BeanName>
2295 </Plugin>
2296
2297 The plugin is intended to be written in a simple manner. Thus it doesn't
2298 try to solve the task of generating the jolokia post data, or automatically
2299 map the values, but rather leans on a verbose config containing the prepared
2300 flat JSON post data and a config section per gauge transformed (as one sample shown
2301 above). However, Jolokia can output all available gauges, and we have a python
2302 script to filter them, and generate a configuration for you:
2303
2304 jolokia_2_collectcfg.py
2305
2306 it can gather all interesting gauges, write a simple one value per line config
2307 for itself and subsequent calls.
2308 You can remove lines from this file manually, or create filter lists.
2309 You then use the script to generate a collectd config.
2310 The script can then inspect data files from some testruns, and remove
2311 all gauges, that don't contain any movement.
2312
2313 The base config looks like this:
2314
2315 The following options are valid within B<URL> blocks:
2316
2317 =over 4
2318
2319 =item B<Host> I<Name>
2320
2321 Use I<Name> as the host name when submitting values. Defaults to the global
2322 host name setting.
2323
2324 =item B<Plugin> I<Plugin>
2325
2326 Use I<Plugin> as the plugin name when submitting values.
2327 Defaults to C<curl_jolokia>.
2328
2329 =item B<Instance> I<Instance>
2330
2331 Sets the plugin instance to I<Instance>.
2332
2333 =item B<Interval> I<Interval>
2334
2335 Sets the interval (in seconds) in which the values will be collected from this
2336 URL. By default the global B<Interval> setting will be used.
2337
2338 =item B<User> I<Name>
2339
2340 =item B<Password> I<Password>
2341
2342 =item B<Digest> B<true>|B<false>
2343
2344 =item B<VerifyPeer> B<true>|B<false>
2345
2346 =item B<VerifyHost> B<true>|B<false>
2347
2348 =item B<CACert> I<file>
2349
2350 =item B<Header> I<Header>
2351
2352 =item B<Post> I<Body>
2353
2354 =item B<Timeout> I<Milliseconds>
2355
2356 These options behave exactly equivalent to the appropriate options of the
2357 I<cURL> plugin. Please see there for a detailed description.
2358
2359 =item B<E<lt>BeanNameE<gt>>
2360
2361 One B<BeanName> block configures the translation of the gauges of one bean
2362 to their respective collectd names, where BeanName sets the main name.
2363
2364 =item B<MBean> I<MBean>
2365
2366 The name of the Bean on the server
2367
2368 =item B<BeanNameSpace> I<BeanNameSpace>
2369
2370 The name space the Bean resides under
2371
2372 =over 4
2373
2374 =item B<AttributeName> I<AttributeName>
2375
2376 A bean can contain several Attributes with gauges. Each one can be matched by a
2377 AttributeName section or be ignored.
2378
2379 =item B<Attribute> I<Attribute>
2380
2381 How should this attribute be called under the BeanName in the collectd hierarchy?
2382
2383 =item B<Type> I<Type>
2384
2385 Sets the type used to dispatch the values to the daemon. Detailed information
2386 about types and their configuration can be found in L<types.db(5)>. This
2387 option is mandatory.
2388
2389 =back
2390
2391 =back
2392
2393 =head2 Plugin C<curl_xml>
2394
2395 The B<curl_xml plugin> uses B<libcurl> (L<http://curl.haxx.se/>) and B<libxml2>
2396 (L<http://xmlsoft.org/>) to retrieve XML data via cURL.
2397
2398 <Plugin "curl_xml">
2399 <URL "http://localhost/stats.xml">
2400 AddressFamily "any"
2401 Host "my_host"
2402 #Plugin "curl_xml"
2403 Instance "some_instance"
2404 User "collectd"
2405 Password "thaiNg0I"
2406 VerifyPeer true
2407 VerifyHost true
2408 CACert "/path/to/ca.crt"
2409 Header "X-Custom-Header: foobar"
2410 Post "foo=bar"
2411
2412 <XPath "table[@id=\"magic_level\"]/tr">
2413 Type "magic_level"
2414 #InstancePrefix "prefix-"
2415 InstanceFrom "td[1]"
2416 #PluginInstanceFrom "td[1]"
2417 ValuesFrom "td[2]/span[@class=\"level\"]"
2418 </XPath>
2419 </URL>
2420 </Plugin>
2421
2422 In the B<Plugin> block, there may be one or more B<URL> blocks, each defining a
2423 URL to be fetched using libcurl. Within each B<URL> block there are
2424 options which specify the connection parameters, for example authentication
2425 information, and one or more B<XPath> blocks.
2426
2427 Each B<XPath> block specifies how to get one type of information. The
2428 string argument must be a valid XPath expression which returns a list
2429 of "base elements". One value is dispatched for each "base element". The
2430 I<type instance> and values are looked up using further I<XPath> expressions
2431 that should be relative to the base element.
2432
2433 Within the B<URL> block the following options are accepted:
2434
2435 =over 4
2436
2437 =item B<AddressFamily> I<Type>
2438
2439 IP version to resolve URL to. Useful in cases when hostname in URL resolves
2440 to both IPv4 and IPv6 addresses, and you are interested in using one of them
2441 specifically.
2442 Use C<ipv4> to enforce IPv4, C<ipv6> to enforce IPv6, or C<any> to keep the
2443 default behavior of resolving addresses to all IP versions your system allows.
2444 If C<libcurl> is compiled without IPv6 support, using C<ipv6> will result in
2445 a warning and fallback to C<any>.
2446 If C<Type> cannot be parsed, a warning will be printed and the whole B<URL>
2447 block will be ignored.
2448
2449 =item B<Host> I<Name>
2450
2451 Use I<Name> as the host name when submitting values. Defaults to the global
2452 host name setting.
2453
2454 =item B<Plugin> I<Plugin>
2455
2456 Use I<Plugin> as the plugin name when submitting values.
2457 Defaults to 'curl_xml'.
2458
2459 =item B<Instance> I<Instance>
2460
2461 Use I<Instance> as the plugin instance when submitting values.
2462 May be overridden by B<PluginInstanceFrom> option inside B<XPath> blocks.
2463 Defaults to an empty string (no plugin instance).
2464
2465 =item B<Interval> I<Interval>
2466
2467 Sets the interval (in seconds) in which the values will be collected from this
2468 URL. By default the global B<Interval> setting will be used.
2469
2470 =item B<Namespace> I<Prefix> I<URL>
2471
2472 If an XPath expression references namespaces, they must be specified
2473 with this option. I<Prefix> is the "namespace prefix" used in the XML document.
2474 I<URL> is the "namespace name", an URI reference uniquely identifying the
2475 namespace. The option can be repeated to register multiple namespaces.
2476
2477 Examples:
2478
2479 Namespace "s" "http://schemas.xmlsoap.org/soap/envelope/"
2480 Namespace "m" "http://www.w3.org/1998/Math/MathML"
2481
2482 =item B<User> I<User>
2483
2484 =item B<Password> I<Password>
2485
2486 =item B<Digest> B<true>|B<false>
2487
2488 =item B<VerifyPeer> B<true>|B<false>
2489
2490 =item B<VerifyHost> B<true>|B<false>
2491
2492 =item B<CACert> I<CA Cert File>
2493
2494 =item B<Header> I<Header>
2495
2496 =item B<Post> I<Body>
2497
2498 =item B<Timeout> I<Milliseconds>
2499
2500 These options behave exactly equivalent to the appropriate options of the
2501 I<cURL plugin>. Please see there for a detailed description.
2502
2503 =item B<E<lt>StatisticsE<gt>>
2504
2505 One B<Statistics> block can be used to specify cURL statistics to be collected
2506 for each request to the remote URL. See the section "cURL Statistics" above
2507 for details.
2508
2509 =item E<lt>B<XPath> I<XPath-expression>E<gt>
2510
2511 Within each B<URL> block, there must be one or more B<XPath> blocks. Each
2512 B<XPath> block specifies how to get one type of information. The string
2513 argument must be a valid XPath expression which returns a list of "base
2514 elements". One value is dispatched for each "base element".
2515
2516 Within the B<XPath> block the following options are accepted:
2517
2518 =over 4
2519
2520 =item B<Type> I<Type>
2521
2522 Specifies the I<Type> used for submitting patches. This determines the number
2523 of values that are required / expected and whether the strings are parsed as
2524 signed or unsigned integer or as double values. See L<types.db(5)> for details.
2525 This option is required.
2526
2527 =item B<InstancePrefix> I<InstancePrefix>
2528
2529 Prefix the I<type instance> with I<InstancePrefix>. The values are simply
2530 concatenated together without any separator.
2531 This option is optional.
2532
2533 =item B<InstanceFrom> I<InstanceFrom>
2534
2535 Specifies a XPath expression to use for determining the I<type instance>. The
2536 XPath expression must return exactly one element. The element's value is then
2537 used as I<type instance>, possibly prefixed with I<InstancePrefix> (see above).
2538
2539 =item B<PluginInstanceFrom> I<PluginInstanceFrom>
2540
2541 Specifies a XPath expression to use for determining the I<plugin instance>. The
2542 XPath expression must return exactly one element. The element's value is then
2543 used as I<plugin instance>.
2544
2545 =back
2546
2547 If the "base XPath expression" (the argument to the B<XPath> block) returns
2548 exactly one argument, then I<InstanceFrom> and I<PluginInstanceFrom> may be omitted.
2549 Otherwise, at least one of I<InstanceFrom> or I<PluginInstanceFrom> is required.
2550
2551 =over 4
2552
2553 =item B<ValuesFrom> I<ValuesFrom> [I<ValuesFrom> ...]
2554
2555 Specifies one or more XPath expression to use for reading the values. The
2556 number of XPath expressions must match the number of data sources in the
2557 I<type> specified with B<Type> (see above). Each XPath expression must return
2558 exactly one element. The element's value is then parsed as a number and used as
2559 value for the appropriate value in the value list dispatched to the daemon.
2560 This option is required.
2561
2562 =back
2563
2564 =back
2565
2566 =head2 Plugin C<dbi>
2567
2568 This plugin uses the B<dbi> library (L<http://libdbi.sourceforge.net/>) to
2569 connect to various databases, execute I<SQL> statements and read back the
2570 results. I<dbi> is an acronym for "database interface" in case you were
2571 wondering about the name. You can configure how each column is to be
2572 interpreted and the plugin will generate one or more data sets from each row
2573 returned according to these rules.
2574
2575 Because the plugin is very generic, the configuration is a little more complex
2576 than those of other plugins. It usually looks something like this:
2577
2578 <Plugin dbi>
2579 <Query "out_of_stock">
2580 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
2581 # Use with MySQL 5.0.0 or later
2582 MinVersion 50000
2583 <Result>
2584 Type "gauge"
2585 InstancePrefix "out_of_stock"
2586 InstancesFrom "category"
2587 ValuesFrom "value"
2588 </Result>
2589 </Query>
2590 <Database "product_information">
2591 #Plugin "warehouse"
2592 Driver "mysql"
2593 Interval 120
2594 DriverOption "host" "localhost"
2595 DriverOption "username" "collectd"
2596 DriverOption "password" "aZo6daiw"
2597 DriverOption "dbname" "prod_info"
2598 SelectDB "prod_info"
2599 Query "out_of_stock"
2600 </Database>
2601 </Plugin>
2602
2603 The configuration above defines one query with one result and one database. The
2604 query is then linked to the database with the B<Query> option I<within> the
2605 B<E<lt>DatabaseE<gt>> block. You can have any number of queries and databases
2606 and you can also use the B<Include> statement to split up the configuration
2607 file in multiple, smaller files. However, the B<E<lt>QueryE<gt>> block I<must>
2608 precede the B<E<lt>DatabaseE<gt>> blocks, because the file is interpreted from
2609 top to bottom!
2610
2611 The following is a complete list of options:
2612
2613 =head3 B<Query> blocks
2614
2615 Query blocks define I<SQL> statements and how the returned data should be
2616 interpreted. They are identified by the name that is given in the opening line
2617 of the block. Thus the name needs to be unique. Other than that, the name is
2618 not used in collectd.
2619
2620 In each B<Query> block, there is one or more B<Result> blocks. B<Result> blocks
2621 define which column holds which value or instance information. You can use
2622 multiple B<Result> blocks to create multiple values from one returned row. This
2623 is especially useful, when queries take a long time and sending almost the same
2624 query again and again is not desirable.
2625
2626 Example:
2627
2628 <Query "environment">
2629 Statement "select station, temperature, humidity from environment"
2630 <Result>
2631 Type "temperature"
2632 # InstancePrefix "foo"
2633 InstancesFrom "station"
2634 ValuesFrom "temperature"
2635 </Result>
2636 <Result>
2637 Type "humidity"
2638 InstancesFrom "station"
2639 ValuesFrom "humidity"
2640 </Result>
2641 </Query>
2642
2643 The following options are accepted:
2644
2645 =over 4
2646
2647 =item B<Statement> I<SQL>
2648
2649 Sets the statement that should be executed on the server. This is B<not>
2650 interpreted by collectd, but simply passed to the database server. Therefore,
2651 the SQL dialect that's used depends on the server collectd is connected to.
2652
2653 The query has to return at least two columns, one for the instance and one
2654 value. You cannot omit the instance, even if the statement is guaranteed to
2655 always return exactly one line. In that case, you can usually specify something
2656 like this:
2657
2658 Statement "SELECT \"instance\", COUNT(*) AS value FROM table"
2659
2660 (That works with MySQL but may not be valid SQL according to the spec. If you
2661 use a more strict database server, you may have to select from a dummy table or
2662 something.)
2663
2664 Please note that some databases, for example B<Oracle>, will fail if you
2665 include a semicolon at the end of the statement.
2666
2667 =item B<MinVersion> I<Version>
2668
2669 =item B<MaxVersion> I<Value>
2670
2671 Only use this query for the specified database version. You can use these
2672 options to provide multiple queries with the same name but with a slightly
2673 different syntax. The plugin will use only those queries, where the specified
2674 minimum and maximum versions fit the version of the database in use.
2675
2676 The database version is determined by C<dbi_conn_get_engine_version>, see the
2677 L<libdbi documentation|http://libdbi.sourceforge.net/docs/programmers-guide/reference-conn.html#DBI-CONN-GET-ENGINE-VERSION>
2678 for details. Basically, each part of the version is assumed to be in the range
2679 from B<00> to B<99> and all dots are removed. So version "4.1.2" becomes
2680 "40102", version "5.0.42" becomes "50042".
2681
2682 B<Warning:> The plugin will use B<all> matching queries, so if you specify
2683 multiple queries with the same name and B<overlapping> ranges, weird stuff will
2684 happen. Don't to it! A valid example would be something along these lines:
2685
2686 MinVersion 40000
2687 MaxVersion 49999
2688 ...
2689 MinVersion 50000
2690 MaxVersion 50099
2691 ...
2692 MinVersion 50100
2693 # No maximum
2694
2695 In the above example, there are three ranges that don't overlap. The last one
2696 goes from version "5.1.0" to infinity, meaning "all later versions". Versions
2697 before "4.0.0" are not specified.
2698
2699 =item B<Type> I<Type>
2700
2701 The B<type> that's used for each line returned. See L<types.db(5)> for more
2702 details on how types are defined. In short: A type is a predefined layout of
2703 data and the number of values and type of values has to match the type
2704 definition.
2705
2706 If you specify "temperature" here, you need exactly one gauge column. If you
2707 specify "if_octets", you will need two counter columns. See the B<ValuesFrom>
2708 setting below.
2709
2710 There must be exactly one B<Type> option inside each B<Result> block.
2711
2712 =item B<InstancePrefix> I<prefix>
2713
2714 Prepends I<prefix> to the type instance. If B<InstancesFrom> (see below) is not
2715 given, the string is simply copied. If B<InstancesFrom> is given, I<prefix> and
2716 all strings returned in the appropriate columns are concatenated together,
2717 separated by dashes I<("-")>.
2718
2719 =item B<InstancesFrom> I<column0> [I<column1> ...]
2720
2721 Specifies the columns whose values will be used to create the "type-instance"
2722 for each row. If you specify more than one column, the value of all columns
2723 will be joined together with dashes I<("-")> as separation characters.
2724
2725 The plugin itself does not check whether or not all built instances are
2726 different. It's your responsibility to assure that each is unique. This is
2727 especially true, if you do not specify B<InstancesFrom>: B<You> have to make
2728 sure that only one row is returned in this case.
2729
2730 If neither B<InstancePrefix> nor B<InstancesFrom> is given, the type-instance
2731 will be empty.
2732
2733 =item B<ValuesFrom> I<column0> [I<column1> ...]
2734
2735 Names the columns whose content is used as the actual data for the data sets
2736 that are dispatched to the daemon. How many such columns you need is determined
2737 by the B<Type> setting above. If you specify too many or not enough columns,
2738 the plugin will complain about that and no data will be submitted to the
2739 daemon.
2740
2741 The actual data type in the columns is not that important. The plugin will
2742 automatically cast the values to the right type if it know how to do that. So
2743 it should be able to handle integer an floating point types, as well as strings
2744 (if they include a number at the beginning).
2745
2746 There must be at least one B<ValuesFrom> option inside each B<Result> block.
2747
2748 =item B<MetadataFrom> [I<column0> I<column1> ...]
2749
2750 Names the columns whose content is used as metadata for the data sets
2751 that are dispatched to the daemon.
2752
2753 The actual data type in the columns is not that important. The plugin will
2754 automatically cast the values to the right type if it know how to do that. So
2755 it should be able to handle integer an floating point types, as well as strings
2756 (if they include a number at the beginning).
2757
2758 =back
2759
2760 =head3 B<Database> blocks
2761
2762 Database blocks define a connection to a database and which queries should be
2763 sent to that database. Since the used "dbi" library can handle a wide variety
2764 of databases, the configuration is very generic. If in doubt, refer to libdbi's
2765 documentationE<nbsp>- we stick as close to the terminology used there.
2766
2767 Each database needs a "name" as string argument in the starting tag of the
2768 block. This name will be used as "PluginInstance" in the values submitted to
2769 the daemon. Other than that, that name is not used.
2770
2771 =over 4
2772
2773 =item B<Plugin> I<Plugin>
2774
2775 Use I<Plugin> as the plugin name when submitting query results from
2776 this B<Database>. Defaults to C<dbi>.
2777
2778 =item B<Interval> I<Interval>
2779
2780 Sets the interval (in seconds) in which the values will be collected from this
2781 database. By default the global B<Interval> setting will be used.
2782
2783 =item B<Driver> I<Driver>
2784
2785 Specifies the driver to use to connect to the database. In many cases those
2786 drivers are named after the database they can connect to, but this is not a
2787 technical necessity. These drivers are sometimes referred to as "DBD",
2788 B<D>ataB<B>ase B<D>river, and some distributions ship them in separate
2789 packages. Drivers for the "dbi" library are developed by the B<libdbi-drivers>
2790 project at L<http://libdbi-drivers.sourceforge.net/>.
2791
2792 You need to give the driver name as expected by the "dbi" library here. You
2793 should be able to find that in the documentation for each driver. If you
2794 mistype the driver name, the plugin will dump a list of all known driver names
2795 to the log.
2796
2797 =item B<DriverOption> I<Key> I<Value>
2798
2799 Sets driver-specific options. What option a driver supports can be found in the
2800 documentation for each driver, somewhere at
2801 L<http://libdbi-drivers.sourceforge.net/>. However, the options "host",
2802 "username", "password", and "dbname" seem to be deE<nbsp>facto standards.
2803
2804 DBDs can register two types of options: String options and numeric options. The
2805 plugin will use the C<dbi_conn_set_option> function when the configuration
2806 provides a string and the C<dbi_conn_require_option_numeric> function when the
2807 configuration provides a number. So these two lines will actually result in
2808 different calls being used:
2809
2810 DriverOption "Port" 1234 # numeric
2811 DriverOption "Port" "1234" # string
2812
2813 Unfortunately, drivers are not too keen to report errors when an unknown option
2814 is passed to them, so invalid settings here may go unnoticed. This is not the
2815 plugin's fault, it will report errors if it gets them from the libraryE<nbsp>/
2816 the driver. If a driver complains about an option, the plugin will dump a
2817 complete list of all options understood by that driver to the log. There is no
2818 way to programmatically find out if an option expects a string or a numeric
2819 argument, so you will have to refer to the appropriate DBD's documentation to
2820 find this out. Sorry.
2821
2822 =item B<SelectDB> I<Database>
2823
2824 In some cases, the database name you connect with is not the database name you
2825 want to use for querying data. If this option is set, the plugin will "select"
2826 (switch to) that database after the connection is established.
2827
2828 =item B<Query> I<QueryName>
2829
2830 Associates the query named I<QueryName> with this database connection. The
2831 query needs to be defined I<before> this statement, i.E<nbsp>e. all query
2832 blocks you want to refer to must be placed above the database block you want to
2833 refer to them from.
2834
2835 =item B<Host> I<Hostname>
2836
2837 Sets the B<host> field of I<value lists> to I<Hostname> when dispatching
2838 values. Defaults to the global hostname setting.
2839
2840 =back
2841
2842 =head2 Plugin C<dcpmm>
2843
2844 The I<dcpmm plugin> will collect Intel(R) Optane(TM) DC Persistent Memory related performance statistics.
2845 The plugin requires root privileges to perform the statistics collection.
2846
2847 B<Synopsis:>
2848
2849 <Plugin "dcpmm">
2850 Interval 10.0
2851 CollectHealth false
2852 CollectPerfMetrics true
2853 EnableDispatchAll false
2854 </Plugin>
2855
2856 =over 4
2857
2858 =item B<Interval> I<time in seconds>
2859
2860 Sets the I<Interval (in seconds)> in which the values will be collected. Defaults to C<global Interval> value.
2861 This will override the I<global Interval> for I<dcpmm> plugin. None of the other plugins will be affected.
2862
2863 =item B<CollectHealth> I<true>|I<false>
2864
2865 Collects health information. I<CollectHealth and CollectPerfMetrics cannot be true at the same time>. Defaults to C<false>.
2866
2867 The health information metrics are the following:
2868 health_status Overall health summary (0: normal | 1: non-critical | 2: critical | 3: fatal).
2869 lifespan_remaining The module’s remaining life as a percentage value of factory expected life span.
2870 lifespan_used The module’s used life as a percentage value of factory expected life span.
2871 power_on_time The lifetime the DIMM has been powered on in seconds.
2872 uptime The current uptime of the DIMM for the current power cycle in seconds.
2873 last_shutdown_time The time the system was last shutdown. The time is represented in epoch (seconds).
2874 media_temperature The media’s current temperature in degree Celsius.
2875 controller_temperature The controller’s current temperature in degree Celsius.
2876 max_media_temperature The media’s the highest temperature reported in degree Celsius.
2877 max_controller_temperature The controller’s highest temperature reported in degree Celsius.
2878 tsc_cycles The number of tsc cycles during each interval.
2879 epoch The timestamp in seconds at which the metrics are collected from DCPMM DIMMs.
2880
2881 =item B<CollectPerfMetrics> I<true>|I<false>
2882
2883 Collects memory performance metrics. I<CollectHealth and CollectPerfMetrics cannot be true at the same time>. Defaults to C<true>.
2884
2885 The memory performance metrics are the following:
2886 total_bytes_read Number of bytes transacted by the read operations.
2887 total_bytes_written Number of bytes transacted by the write operations.
2888 read_64B_ops_rcvd Number of read operations performed to the physical media in 64 bytes granularity.
2889 write_64B_ops_rcvd Number of write operations performed to the physical media in 64 bytes granularity.
2890 media_read_ops Number of read operations performed to the physical media.
2891 media_write_ops Number of write operations performed to the physical media.
2892 host_reads Number of read operations received from the CPU (memory controller).
2893 host_writes Number of write operations received from the CPU (memory controller).
2894 read_hit_ratio Measures the efficiency of the buffer in the read path. Range of 0.0 - 1.0.
2895 write_hit_ratio Measures the efficiency of the buffer in the write path. Range of 0.0 - 1.0.
2896 tsc_cycles The number of tsc cycles during each interval.
2897 epoch The timestamp in seconds at which the metrics are collected from DCPMM DIMMs.
2898
2899 =item B<EnableDispatchAll> I<false>
2900
2901 This parameter helps to seamlessly enable simultaneous health and memory perf metrics collection in future.
2902 This is unused at the moment and I<must> always be I<false>.
2903
2904 =back
2905
2906 =head2 Plugin C<df>
2907
2908 =over 4
2909
2910 =item B<Device> I<Device>
2911
2912 Select partitions based on the devicename.
2913
2914 See F</"IGNORELISTS"> for details.
2915
2916 =item B<MountPoint> I<Directory>
2917
2918 Select partitions based on the mountpoint.
2919
2920 See F</"IGNORELISTS"> for details.
2921
2922 =item B<FSType> I<FSType>
2923
2924 Select partitions based on the filesystem type.
2925
2926 See F</"IGNORELISTS"> for details.
2927
2928 =item B<IgnoreSelected> B<true>|B<false>
2929
2930 Invert the selection: If set to true, all partitions B<except> the ones that
2931 match any one of the criteria are collected. By default only selected
2932 partitions are collected if a selection is made. If no selection is configured
2933 at all, B<all> partitions are selected.
2934
2935 =item B<LogOnce> B<false>|B<false>
2936
2937 Only log stat() errors once.
2938
2939 =item B<ReportByDevice> B<true>|B<false>
2940
2941 Report using the device name rather than the mountpoint. i.e. with this I<false>,
2942 (the default), it will report a disk as "root", but with it I<true>, it will be
2943 "sda1" (or whichever).
2944
2945 =item B<ReportInodes> B<true>|B<false>
2946
2947 Enables or disables reporting of free, reserved and used inodes. Defaults to
2948 inode collection being disabled.
2949
2950 Enable this option if inodes are a scarce resource for you, usually because
2951 many small files are stored on the disk. This is a usual scenario for mail
2952 transfer agents and web caches.
2953
2954 =item B<ValuesAbsolute> B<true>|B<false>
2955
2956 Enables or disables reporting of free and used disk space in 1K-blocks.
2957 Defaults to B<true>.
2958
2959 =item B<ValuesPercentage> B<false>|B<true>
2960
2961 Enables or disables reporting of free and used disk space in percentage.
2962 Defaults to B<false>.
2963
2964 This is useful for deploying I<collectd> on the cloud, where machines with
2965 different disk size may exist. Then it is more practical to configure
2966 thresholds based on relative disk size.
2967
2968 =back
2969
2970 =head2 Plugin C<disk>
2971
2972 The C<disk> plugin collects information about the usage of physical disks and
2973 logical disks (partitions). Values collected are the number of octets written
2974 to and read from a disk or partition, the number of read/write operations
2975 issued to the disk and a rather complex "time" it took for these commands to be
2976 issued.
2977
2978 Using the following two options you can ignore some disks or configure the
2979 collection only of specific disks.
2980
2981 =over 4
2982
2983 =item B<Disk> I<Name>
2984
2985 Select the disk I<Name>. Whether it is collected or ignored depends on the
2986 B<IgnoreSelected> setting, see below. As with other plugins that use the
2987 daemon's ignorelist functionality, a string that starts and ends with a slash
2988 is interpreted as a regular expression. Examples:
2989
2990 Disk "sdd"
2991 Disk "/hda[34]/"
2992
2993 See F</"IGNORELISTS"> for details.
2994
2995 =item B<IgnoreSelected> B<true>|B<false>
2996
2997 Sets whether selected disks, i.E<nbsp>e. the ones matches by any of the B<Disk>
2998 statements, are ignored or if all other disks are ignored. The behavior
2999 (hopefully) is intuitive: If no B<Disk> option is configured, all disks are
3000 collected. If at least one B<Disk> option is given and no B<IgnoreSelected> or
3001 set to B<false>, B<only> matching disks will be collected. If B<IgnoreSelected>
3002 is set to B<true>, all disks are collected B<except> the ones matched.
3003
3004 =item B<UseBSDName> B<true>|B<false>
3005
3006 Whether to use the device's "BSD Name", on MacE<nbsp>OSE<nbsp>X, instead of the
3007 default major/minor numbers. Requires collectd to be built with Apple's
3008 IOKitLib support.
3009
3010 =item B<UdevNameAttr> I<Attribute>
3011
3012 Attempt to override disk instance name with the value of a specified udev
3013 attribute when built with B<libudev>. If the attribute is not defined for the
3014 given device, the default name is used. Example:
3015
3016 UdevNameAttr "DM_NAME"
3017
3018 Please note that using an attribute that does not differentiate between the
3019 whole disk and its particular partitions (like B<ID_SERIAL>) will result in
3020 data about the whole disk and each partition being mixed together incorrectly.
3021 In this case, you can use B<ID_COLLECTD> attribute that is provided by
3022 I<contrib/99-storage-collectd.rules> udev rule file instead.
3023
3024 =back
3025
3026 =head2 Plugin C<dns>
3027
3028 =over 4
3029
3030 =item B<Interface> I<Interface>
3031
3032 The dns plugin uses B<libpcap> to capture dns traffic and analyzes it. This
3033 option sets the interface that should be used. If this option is not set, or
3034 set to "any", the plugin will try to get packets from B<all> interfaces. This
3035 may not work on certain platforms, such as MacE<nbsp>OSE<nbsp>X.
3036
3037 =item B<IgnoreSource> I<IP-address>
3038
3039 Ignore packets that originate from this address.
3040
3041 =item B<SelectNumericQueryTypes> B<true>|B<false>
3042
3043 Enabled by default, collects unknown (and thus presented as numeric only) query types.
3044
3045 =back
3046
3047 =head2 Plugin C<dpdkevents>
3048
3049 The I<dpdkevents plugin> collects events from DPDK such as link status of
3050 network ports and Keep Alive status of DPDK logical cores.
3051 In order to get Keep Alive events following requirements must be met:
3052 - DPDK >= 16.07
3053 - support for Keep Alive implemented in DPDK application. More details can
3054 be found here: http://dpdk.org/doc/guides/sample_app_ug/keep_alive.html
3055
3056 B<Synopsis:>
3057
3058 <Plugin "dpdkevents">
3059 <EAL>
3060 Coremask "0x1"
3061 MemoryChannels "4"
3062 FilePrefix "rte"
3063 </EAL>
3064 <Event "link_status">
3065 SendEventsOnUpdate true
3066 EnabledPortMask 0xffff
3067 PortName "interface1"
3068 PortName "interface2"
3069 SendNotification false
3070 </Event>
3071 <Event "keep_alive">
3072 SendEventsOnUpdate true
3073 LCoreMask "0xf"
3074 KeepAliveShmName "/dpdk_keepalive_shm_name"
3075 SendNotification false
3076 </Event>
3077 </Plugin>
3078
3079 B<Options:>
3080
3081
3082 =head3 The EAL block
3083
3084 =over 4
3085
3086 =item B<Coremask> I<Mask>
3087
3088 =item B<Memorychannels> I<Channels>
3089
3090 Number of memory channels per processor socket.
3091
3092 =item B<FilePrefix> I<File>
3093
3094 The prefix text used for hugepage filenames. The filename will be set to
3095 /var/run/.<prefix>_config where prefix is what is passed in by the user.
3096
3097 =back
3098
3099 =head3 The Event block
3100
3101 The B<Event> block defines configuration for specific event. It accepts a
3102 single argument which specifies the name of the event.
3103
3104 =head4 Link Status event
3105
3106 =over 4
3107
3108 =item B<SendEventOnUpdate> I<true|false>
3109
3110 If set to true link status value will be dispatched only when it is
3111 different from previously read value. This is an optional argument - default
3112 value is true.
3113
3114 =item B<EnabledPortMask> I<Mask>
3115
3116 A hexidecimal bit mask of the DPDK ports which should be enabled. A mask
3117 of 0x0 means that all ports will be disabled. A bitmask of all F's means
3118 that all ports will be enabled. This is an optional argument - by default
3119 all ports are enabled.
3120
3121 =item B<PortName> I<Name>
3122
3123 A string containing an optional name for the enabled DPDK ports. Each PortName
3124 option should contain only one port name; specify as many PortName options as
3125 desired. Default naming convention will be used if PortName is blank. If there
3126 are less PortName options than there are enabled ports, the default naming
3127 convention will be used for the additional ports.
3128
3129 =item B<SendNotification> I<true|false>
3130
3131 If set to true, link status notifications are sent, instead of link status
3132 being collected as a statistic. This is an optional argument - default
3133 value is false.
3134
3135 =back
3136
3137 =head4 Keep Alive event
3138
3139 =over 4
3140
3141 =item B<SendEventOnUpdate> I<true|false>
3142
3143 If set to true keep alive value will be dispatched only when it is
3144 different from previously read value. This is an optional argument - default
3145 value is true.
3146
3147 =item B<LCoreMask> I<Mask>
3148
3149 An hexadecimal bit mask of the logical cores to monitor keep alive state.
3150
3151 =item B<KeepAliveShmName> I<Name>
3152
3153 Shared memory name identifier that is used by secondary process to monitor
3154 the keep alive cores state.
3155
3156 =item B<SendNotification> I<true|false>
3157
3158 If set to true, keep alive notifications are sent, instead of keep alive
3159 information being collected as a statistic. This is an optional
3160 argument - default value is false.
3161
3162 =back
3163
3164 =head2 Plugin C<dpdkstat>
3165
3166 The I<dpdkstat plugin> collects information about DPDK interfaces using the
3167 extended NIC stats API in DPDK.
3168
3169 B<Synopsis:>
3170
3171 <Plugin "dpdkstat">
3172 <EAL>
3173 Coremask "0x4"
3174 MemoryChannels "4"
3175 FilePrefix "rte"
3176 SocketMemory "1024"
3177 LogLevel "7"
3178 RteDriverLibPath "/usr/lib/dpdk-pmd"
3179 </EAL>
3180 SharedMemObj "dpdk_collectd_stats_0"
3181 EnabledPortMask 0xffff
3182 PortName "interface1"
3183 PortName "interface2"
3184 </Plugin>
3185
3186 B<Options:>
3187
3188 =head3 The EAL block
3189
3190 =over 4
3191
3192 =item B<Coremask> I<Mask>
3193
3194 A string containing an hexadecimal bit mask of the cores to run on. Note that
3195 core numbering can change between platforms and should be determined beforehand.
3196
3197 =item B<Memorychannels> I<Channels>
3198
3199 A string containing a number of memory channels per processor socket.
3200
3201 =item B<FilePrefix> I<File>
3202
3203 The prefix text used for hugepage filenames. The filename will be set to
3204 /var/run/.<prefix>_config where prefix is what is passed in by the user.
3205
3206 =item B<SocketMemory> I<MB>
3207
3208 A string containing amount of Memory to allocate from hugepages on specific
3209 sockets in MB. This is an optional value.
3210
3211 =item B<LogLevel> I<LogLevel_number>
3212
3213 A string containing log level number. This parameter is optional.
3214 If parameter is not present then default value "7" - (INFO) is used.
3215 Value "8" - (DEBUG) can be set to enable debug traces.
3216
3217 =item B<RteDriverLibPath> I<Path>
3218
3219 A string containing path to shared pmd driver lib or path to directory,
3220 where shared pmd driver libs are available. This parameter is optional.
3221 This parameter enable loading of shared pmd driver libs from defined path.
3222 E.g.: "/usr/lib/dpdk-pmd/librte_pmd_i40e.so"
3223 or "/usr/lib/dpdk-pmd"
3224
3225 =back
3226
3227 =over 3
3228
3229 =item B<SharedMemObj> I<Mask>
3230
3231 A string containing the name of the shared memory object that should be used to
3232 share stats from the DPDK secondary process to the collectd dpdkstat plugin.
3233 Defaults to dpdk_collectd_stats if no other value is configured.
3234
3235 =item B<EnabledPortMask> I<Mask>
3236
3237 A hexidecimal bit mask of the DPDK ports which should be enabled. A mask
3238 of 0x0 means that all ports will be disabled. A bitmask of all Fs means
3239 that all ports will be enabled. This is an optional argument - default
3240 is all ports enabled.
3241
3242 =item B<PortName> I<Name>
3243
3244 A string containing an optional name for the enabled DPDK ports. Each PortName
3245 option should contain only one port name; specify as many PortName options as
3246 desired. Default naming convention will be used if PortName is blank. If there
3247 are less PortName options than there are enabled ports, the default naming
3248 convention will be used for the additional ports.
3249
3250 =back
3251
3252 =head2 Plugin C<dpdk_telemetry>
3253
3254
3255 The I< dpdk_telemetry > plugin collects DPDK ethernet device metrics via
3256 dpdk_telemetry library.
3257
3258 The plugin retrieves metrics from a DPDK packet forwarding application
3259 by sending the JSON formatted message via a UNIX domain socket.
3260 The DPDK telemetry component will respond with a JSON formatted reply,
3261 delivering the requested metrics. The plugin parses the JSON data,
3262 and publishes the metric values to collectd for further use.
3263
3264 B<Synopsis:>
3265
3266 <Plugin dpdk_telemetry>
3267 ClientSocketPath "/var/run/.client"
3268 DpdkSocketPath "/var/run/dpdk/rte/telemetry"
3269 </Plugin>
3270
3271 B<Options:>
3272
3273 =over 2
3274
3275 =item B<ClientSocketPath> I<Client_Path>
3276
3277 The UNIX domain client socket at I<Client_Path> to receive messages from DPDK
3278 telemetry library. Defaults to B<"/var/run/.client">.
3279
3280 =item B<DpdkSocketPath> I<Dpdk_Path>
3281
3282 The UNIX domain DPDK telemetry socket to be connected at I<Dpdk_Path> to send
3283 messages. Defaults to B<"/var/run/dpdk/rte/telemetry">.
3284
3285 =back
3286
3287 =head2 Plugin C<email>
3288
3289 =over 4
3290
3291 =item B<SocketFile> I<Path>
3292
3293 Sets the socket-file which is to be created.
3294
3295 =item B<SocketGroup> I<Group>
3296
3297 If running as root change the group of the UNIX-socket after it has been
3298 created. Defaults to B<collectd>.
3299
3300 =item B<SocketPerms> I<Permissions>
3301
3302 Change the file permissions of the UNIX-socket after it has been created. The
3303 permissions must be given as a numeric, octal value as you would pass to
3304 L<chmod(1)>. Defaults to B<0770>.
3305
3306 =item B<MaxConns> I<Number>
3307
3308 Sets the maximum number of connections that can be handled in parallel. Since
3309 this many threads will be started immediately setting this to a very high
3310 value will waste valuable resources. Defaults to B<5> and will be forced to be
3311 at most B<16384> to prevent typos and dumb mistakes.
3312
3313 =back
3314
3315 =head2 Plugin C<ethstat>
3316
3317 The I<ethstat plugin> collects information about network interface cards (NICs)
3318 by talking directly with the underlying kernel driver using L<ioctl(2)>.
3319
3320 B<Synopsis:>
3321
3322 <Plugin "ethstat">
3323 Interface "eth0"
3324 Map "rx_csum_offload_errors" "if_rx_errors" "checksum_offload"
3325 Map "multicast" "if_multicast"
3326 </Plugin>
3327
3328 B<Options:>
3329
3330 =over 4
3331
3332 =item B<Interface> I<Name>
3333
3334 Collect statistical information about interface I<Name>.
3335
3336 =item B<Map> I<Name> I<Type> [I<TypeInstance>]
3337
3338 By default, the plugin will submit values as type C<derive> and I<type
3339 instance> set to I<Name>, the name of the metric as reported by the driver. If
3340 an appropriate B<Map> option exists, the given I<Type> and, optionally,
3341 I<TypeInstance> will be used.
3342
3343 =item B<MappedOnly> B<true>|B<false>
3344
3345 When set to B<true>, only metrics that can be mapped to a I<type> will be
3346 collected, all other metrics will be ignored. Defaults to B<false>.
3347
3348 =back
3349
3350 =head2 Plugin C<exec>
3351
3352 Please make sure to read L<collectd-exec(5)> before using this plugin. It
3353 contains valuable information on when the executable is executed and the
3354 output that is expected from it.
3355
3356 =over 4
3357
3358 =item B<Exec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
3359
3360 =item B<NotificationExec> I<User>[:[I<Group>]] I<Executable> [I<E<lt>argE<gt>> [I<E<lt>argE<gt>> ...]]
3361
3362 Execute the executable I<Executable> as user I<User>. If the user name is
3363 followed by a colon and a group name, the effective group is set to that group.
3364 The real group and saved-set group will be set to the default group of that
3365 user. If no group is given the effective group ID will be the same as the real
3366 group ID.
3367
3368 Please note that in order to change the user and/or group the daemon needs
3369 superuser privileges. If the daemon is run as an unprivileged user you must
3370 specify the same user/group here. If the daemon is run with superuser
3371 privileges, you must supply a non-root user here.
3372
3373 The executable may be followed by optional arguments that are passed to the
3374 program. Please note that due to the configuration parsing numbers and boolean
3375 values may be changed. If you want to be absolutely sure that something is
3376 passed as-is please enclose it in quotes.
3377
3378 The B<Exec> and B<NotificationExec> statements change the semantics of the
3379 programs executed, i.E<nbsp>e. the data passed to them and the response
3380 expected from them. This is documented in great detail in L<collectd-exec(5)>.
3381
3382 =back
3383
3384 =head2 Plugin C<fhcount>
3385
3386 The C<fhcount> plugin provides statistics about used, unused and total number of
3387 file handles on Linux.
3388
3389 The I<fhcount plugin> provides the following configuration options:
3390
3391 =over 4
3392
3393 =item B<ValuesAbsolute> B<true>|B<false>
3394
3395 Enables or disables reporting of file handles usage in absolute numbers,
3396 e.g. file handles used. Defaults to B<true>.
3397
3398 =item B<ValuesPercentage> B<false>|B<true>
3399
3400 Enables or disables reporting of file handles usage in percentages, e.g.
3401 percent of file handles used. Defaults to B<false>.
3402
3403 =back
3404
3405 =head2 Plugin C<filecount>
3406
3407 The C<filecount> plugin counts the number of files in a certain directory (and
3408 its subdirectories) and their combined size. The configuration is very straight
3409 forward:
3410
3411 <Plugin "filecount">
3412 <Directory "/var/qmail/queue/mess">
3413 Instance "qmail-message"
3414 </Directory>
3415 <Directory "/var/qmail/queue/todo">
3416 Instance "qmail-todo"
3417 </Directory>
3418 <Directory "/var/lib/php5">
3419 Instance "php5-sessions"
3420 Name "sess_*"
3421 </Directory>
3422 </Plugin>
3423
3424 The example above counts the number of files in QMail's queue directories and
3425 the number of PHP5 sessions. Jfiy: The "todo" queue holds the messages that
3426 QMail has not yet looked at, the "message" queue holds the messages that were
3427 classified into "local" and "remote".
3428
3429 As you can see, the configuration consists of one or more C<Directory> blocks,
3430 each of which specifies a directory in which to count the files. Within those
3431 blocks, the following options are recognized:
3432
3433 =over 4
3434
3435 =item B<Plugin> I<Plugin>
3436
3437 Use I<Plugin> as the plugin name when submitting values.
3438 Defaults to B<filecount>.
3439
3440 =item B<Instance> I<Instance>
3441
3442 Sets the plugin instance to I<Instance>. If not given, the instance is set to
3443 the directory name with all slashes replaced by underscores and all leading
3444 underscores removed. Empty value is allowed.
3445
3446 =item B<Name> I<Pattern>
3447
3448 Only count files that match I<Pattern>, where I<Pattern> is a shell-like
3449 wildcard as understood by L<fnmatch(3)>. Only the B<filename> is checked
3450 against the pattern, not the entire path. In case this makes it easier for you:
3451 This option has been named after the B<-name> parameter to L<find(1)>.
3452
3453 =item B<MTime> I<Age>
3454
3455 Count only files of a specific age: If I<Age> is greater than zero, only files
3456 that haven't been touched in the last I<Age> seconds are counted. If I<Age> is
3457 a negative number, this is inversed. For example, if B<-60> is specified, only
3458 files that have been modified in the last minute will be counted.
3459
3460 The number can also be followed by a "multiplier" to easily specify a larger
3461 timespan. When given in this notation, the argument must in quoted, i.E<nbsp>e.
3462 must be passed as string. So the B<-60> could also be written as B<"-1m"> (one
3463 minute). Valid multipliers are C<s> (second), C<m> (minute), C<h> (hour), C<d>
3464 (day), C<w> (week), and C<y> (year). There is no "month" multiplier. You can
3465 also specify fractional numbers, e.E<nbsp>g. B<"0.5d"> is identical to
3466 B<"12h">.
3467
3468 =item B<Size> I<Size>
3469
3470 Count only files of a specific size. When I<Size> is a positive number, only
3471 files that are at least this big are counted. If I<Size> is a negative number,
3472 this is inversed, i.E<nbsp>e. only files smaller than the absolute value of
3473 I<Size> are counted.
3474
3475 As with the B<MTime> option, a "multiplier" may be added. For a detailed
3476 description see above. Valid multipliers here are C<b> (byte), C<k> (kilobyte),
3477 C<m> (megabyte), C<g> (gigabyte), C<t> (terabyte), and C<p> (petabyte). Please
3478 note that there are 1000 bytes in a kilobyte, not 1024.
3479
3480 =item B<Recursive> I<true>|I<false>
3481
3482 Controls whether or not to recurse into subdirectories. Enabled by default.
3483
3484 =item B<IncludeHidden> I<true>|I<false>
3485
3486 Controls whether or not to include "hidden" files and directories in the count.
3487 "Hidden" files and directories are those, whose name begins with a dot.
3488 Defaults to I<false>, i.e. by default hidden files and directories are ignored.
3489
3490 =item B<RegularOnly> I<true>|I<false>
3491
3492 Controls whether or not to include only regular files in the count.
3493 Defaults to I<true>, i.e. by default non regular files are ignored.
3494
3495 =item B<FilesSizeType> I<Type>
3496
3497 Sets the type used to dispatch files combined size. Empty value ("") disables
3498 reporting. Defaults to B<bytes>.
3499
3500 =item B<FilesCountType> I<Type>
3501
3502 Sets the type used to dispatch number of files. Empty value ("") disables
3503 reporting. Defaults to B<files>.
3504
3505 =item B<TypeInstance> I<Instance>
3506
3507 Sets the I<type instance> used to dispatch values. Defaults to an empty string
3508 (no plugin instance).
3509
3510 =back
3511
3512 =head2 Plugin C<GenericJMX>
3513
3514 The I<GenericJMX plugin> is written in I<Java> and therefore documented in
3515 L<collectd-java(5)>.
3516
3517 =head2 Plugin C<gmond>
3518
3519 The I<gmond> plugin received the multicast traffic sent by B<gmond>, the
3520 statistics collection daemon of Ganglia. Mappings for the standard "metrics"
3521 are built-in, custom mappings may be added via B<Metric> blocks, see below.
3522
3523 Synopsis:
3524
3525 <Plugin "gmond">
3526 MCReceiveFrom "239.2.11.71" "8649"
3527 <Metric "swap_total">
3528 Type "swap"
3529 TypeInstance "total"
3530 DataSource "value"
3531 </Metric>
3532 <Metric "swap_free">
3533 Type "swap"
3534 TypeInstance "free"
3535 DataSource "value"
3536 </Metric>
3537 </Plugin>
3538
3539 The following metrics are built-in:
3540
3541 =over 4
3542
3543 =item *
3544
3545 load_one, load_five, load_fifteen
3546
3547 =item *
3548
3549 cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio
3550
3551 =item *
3552
3553 mem_free, mem_shared, mem_buffers, mem_cached, mem_total
3554
3555 =item *
3556
3557 bytes_in, bytes_out
3558
3559 =item *
3560
3561 pkts_in, pkts_out
3562
3563 =back
3564
3565 Available configuration options:
3566
3567 =over 4
3568
3569 =item B<MCReceiveFrom> I<MCGroup> [I<Port>]
3570
3571 Sets sets the multicast group and UDP port to which to subscribe.
3572
3573 Default: B<239.2.11.71>E<nbsp>/E<nbsp>B<8649>
3574
3575 =item E<lt>B<Metric> I<Name>E<gt>
3576
3577 These blocks add a new metric conversion to the internal table. I<Name>, the
3578 string argument to the B<Metric> block, is the metric name as used by Ganglia.
3579
3580 =over 4
3581
3582 =item B<Type> I<Type>
3583
3584 Type to map this metric to. Required.
3585
3586 =item B<TypeInstance> I<Instance>
3587
3588 Type-instance to use. Optional.
3589
3590 =item B<DataSource> I<Name>
3591
3592 Data source to map this metric to. If the configured type has exactly one data
3593 source, this is optional. Otherwise the option is required.
3594
3595 =back
3596
3597 =back
3598
3599 =head2 Plugin C<gps>
3600
3601 The C<gps plugin> connects to gpsd on the host machine.
3602 The host, port, timeout and pause are configurable.
3603
3604 This is useful if you run an NTP server using a GPS for source and you want to
3605 monitor it.
3606
3607 Mind your GPS must send $--GSA for having the data reported!
3608
3609 The following elements are collected:
3610
3611 =over 4
3612
3613 =item B<satellites>
3614
3615 Number of satellites used for fix (type instance "used") and in view (type
3616 instance "visible"). 0 means no GPS satellites are visible.
3617
3618 =item B<dilution_of_precision>
3619
3620 Vertical and horizontal dilution (type instance "horizontal" or "vertical").
3621 It should be between 0 and 3.
3622 Look at the documentation of your GPS to know more.
3623
3624 =back
3625
3626 Synopsis:
3627
3628 LoadPlugin gps
3629 <Plugin "gps">
3630 # Connect to localhost on gpsd regular port:
3631 Host "127.0.0.1"
3632 Port "2947"
3633 # 15 ms timeout
3634 Timeout 0.015
3635 # PauseConnect of 5 sec. between connection attempts.
3636 PauseConnect 5
3637 </Plugin>
3638
3639 Available configuration options:
3640
3641 =over 4
3642
3643 =item B<Host> I<Host>
3644
3645 The host on which gpsd daemon runs. Defaults to B<localhost>.
3646
3647 =item B<Port> I<Port>
3648
3649 Port to connect to gpsd on the host machine. Defaults to B<2947>.
3650
3651 =item B<Timeout> I<Seconds>
3652
3653 Timeout in seconds (default 0.015 sec).
3654
3655 The GPS data stream is fetch by the plugin form the daemon.
3656 It waits for data to be available, if none arrives it times out
3657 and loop for another reading.
3658 Mind to put a low value gpsd expects value in the micro-seconds area
3659 (recommended is 500 us) since the waiting function is blocking.
3660 Value must be between 500 us and 5 sec., if outside that range the
3661 default value is applied.
3662
3663 This only applies from gpsd release-2.95.
3664
3665 =item B<PauseConnect> I<Seconds>
3666
3667 Pause to apply between attempts of connection to gpsd in seconds (default 5 sec).
3668
3669 =back
3670
3671 =head2 Plugin C<gpu_nvidia>
3672
3673 Efficiently collects various statistics from the system's NVIDIA GPUs using the
3674 NVML library. Currently collected are fan speed, core temperature, percent
3675 load, percent memory used, compute and memory frequencies, and power
3676 consumption.
3677
3678 =over 4
3679
3680 =item B<GPUIndex>
3681
3682 If one or more of these options is specified, only GPUs at that index (as
3683 determined by nvidia-utils through I<nvidia-smi>) have statistics collected.
3684 If no instance of this option is specified, all GPUs are monitored.
3685
3686 =item B<IgnoreSelected>
3687
3688 If set to true, all detected GPUs B<except> the ones at indices specified by
3689 B<GPUIndex> entries are collected. For greater clarity, setting IgnoreSelected
3690 without any GPUIndex directives will result in B<no> statistics being
3691 collected.
3692
3693 =item B<InstanceByGPUIndex>
3694
3695 If set to false, the GPU ID will not be part of the plugin instance. The default
3696 is 'GPU ID'-'GPU name'
3697
3698 =item B<InstanceByGPUName>
3699
3700 If set to false, the GPU name will not be part of the plugin instance. The
3701 default is 'GPU ID'-'GPU name'
3702
3703 =back
3704
3705 =head2 Plugin C<grpc>
3706
3707 The I<grpc> plugin provides an RPC interface to submit values to or query
3708 values from collectd based on the open source gRPC framework. It exposes an
3709 end-point for dispatching values to the daemon.
3710
3711 The B<gRPC> homepage can be found at L<https://grpc.io/>.
3712
3713 =over 4
3714
3715 =item B<Server> I<Host> I<Port>
3716
3717 The B<Server> statement sets the address of a server to which to send metrics
3718 via the C<DispatchValues> function.
3719
3720 The argument I<Host> may be a hostname, an IPv4 address, or an IPv6 address.
3721
3722 Optionally, B<Server> may be specified as a configuration block which supports
3723 the following options:
3724
3725 =over 4
3726
3727 =item B<EnableSSL> B<false>|B<true>
3728
3729 Whether to require SSL for outgoing connections. Default: false.
3730
3731 =item B<SSLCACertificateFile> I<Filename>
3732
3733 =item B<SSLCertificateFile> I<Filename>
3734
3735 =item B<SSLCertificateKeyFile> I<Filename>
3736
3737 Filenames specifying SSL certificate and key material to be used with SSL
3738 connections.
3739
3740 =back
3741
3742 =item B<Listen> I<Host> I<Port>
3743
3744 The B<Listen> statement sets the network address to bind to. When multiple
3745 statements are specified, the daemon will bind to all of them. If none are
3746 specified, it defaults to B<0.0.0.0:50051>.
3747
3748 The argument I<Host> may be a hostname, an IPv4 address, or an IPv6 address.
3749
3750 Optionally, B<Listen> may be specified as a configuration block which
3751 supports the following options:
3752
3753 =over 4
3754
3755 =item B<EnableSSL> I<true>|I<false>
3756
3757 Whether to enable SSL for incoming connections. Default: false.
3758
3759 =item B<SSLCACertificateFile> I<Filename>
3760
3761 =item B<SSLCertificateFile> I<Filename>
3762
3763 =item B<SSLCertificateKeyFile> I<Filename>
3764
3765 Filenames specifying SSL certificate and key material to be used with SSL
3766 connections.
3767
3768 =item B<VerifyPeer> B<true>|B<false>
3769
3770 When enabled, a valid client certificate is required to connect to the server.
3771 When disabled, a client certifiacte is not requested and any unsolicited client
3772 certificate is accepted.
3773 Enabled by default.
3774
3775 =back
3776
3777 =back
3778
3779 =head2 Plugin C<hddtemp>
3780
3781 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
3782 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
3783 default values, see below. C<hddtemp> has to be running to work correctly. If
3784 C<hddtemp> is not running timeouts may appear which may interfere with other
3785 statistics..
3786
3787 The B<hddtemp> homepage can be found at
3788 L<http://www.guzu.net/linux/hddtemp.php>.
3789
3790 =over 4
3791
3792 =item B<Host> I<Hostname>
3793
3794 Hostname to connect to. Defaults to B<127.0.0.1>.
3795
3796 =item B<Port> I<Port>
3797
3798 TCP-Port to connect to. Defaults to B<7634>.
3799
3800 =back
3801
3802 =head2 Plugin C<hugepages>
3803
3804 To collect B<hugepages> information, collectd reads directories
3805 "/sys/devices/system/node/*/hugepages" and
3806 "/sys/kernel/mm/hugepages".
3807 Reading of these directories can be disabled by the following
3808 options (default is enabled).
3809
3810 =over 4
3811
3812 =item B<ReportPerNodeHP> B<true>|B<false>
3813
3814 If enabled, information will be collected from the hugepage
3815 counters in "/sys/devices/system/node/*/hugepages".
3816 This is used to check the per-node hugepage statistics on
3817 a NUMA system.
3818
3819 =item B<ReportRootHP> B<true>|B<false>
3820
3821 If enabled, information will be collected from the hugepage
3822 counters in "/sys/kernel/mm/hugepages".
3823 This can be used on both NUMA and non-NUMA systems to check
3824 the overall hugepage statistics.
3825
3826 =item B<ValuesPages> B<true>|B<false>
3827
3828 Whether to report hugepages metrics in number of pages.
3829 Defaults to B<true>.
3830
3831 =item B<ValuesBytes> B<false>|B<true>
3832
3833 Whether to report hugepages metrics in bytes.
3834 Defaults to B<false>.
3835
3836 =item B<ValuesPercentage> B<false>|B<true>
3837
3838 Whether to report hugepages metrics as percentage.
3839 Defaults to B<false>.
3840
3841 =back
3842
3843 =head2 Plugin C<infiniband>
3844
3845 The C<infiniband> plugin collects information about IB ports. Metrics are
3846 gathered from C</sys/class/infiniband/DEVICE/port/PORTNUM/*>, and I<Port> names
3847 are formatted like C<DEVICE:PORTNUM> (see examples below).
3848
3849 B<Options:>
3850
3851 =over 4
3852
3853 =item B<Port> I<Port>
3854
3855 Select the port I<Port>. Whether it is collected or ignored depends on the
3856 B<IgnoreSelected> setting, see below. As with other plugins that use the
3857 daemon's ignorelist functionality, a string that starts and ends with a slash
3858 is interpreted as a regular expression. Examples:
3859
3860 Port "mlx5_0:1"
3861 Port "/mthca0:[0-9]/"
3862
3863 See F</"IGNORELISTS"> for details.
3864
3865 =item B<IgnoreSelected> I<true>|I<false>
3866
3867 Sets whether selected ports are ignored or if all other ports are ignored. The
3868 behavior (hopefully) is intuitive: If no B<Port> option is configured, all
3869 ports are collected. If at least one B<Port> option is given and
3870 B<IgnoreSelected> is not given or set to I<false>, B<only> matching ports will
3871 be collected. If B<IgnoreSelected> is set to B<true>, all ports are collected
3872 B<except> the ones matched.
3873
3874 =back
3875
3876 =head2 Plugin C<intel_pmu>
3877
3878 The I<intel_pmu> plugin collects performance counters data on Intel CPUs using
3879 Linux perf interface. All events are reported on a per core basis.
3880
3881 B<Synopsis:>
3882
3883 <Plugin intel_pmu>
3884 ReportHardwareCacheEvents true
3885 ReportKernelPMUEvents true
3886 ReportSoftwareEvents true
3887 EventList "/var/cache/pmu/GenuineIntel-6-2D-core.json"
3888 HardwareEvents "L2_RQSTS.CODE_RD_HIT,L2_RQSTS.CODE_RD_MISS" "L2_RQSTS.ALL_CODE_RD"
3889 Cores "0-3" "4,6" "[12-15]"
3890 DispatchMultiPmu false
3891 </Plugin>
3892
3893 B<Options:>
3894
3895 =over 4
3896
3897 =item B<ReportHardwareCacheEvents> B<false>|B<true>
3898
3899 Enable or disable measuring of hardware CPU cache events:
3900 - L1-dcache-loads
3901 - L1-dcache-load-misses
3902 - L1-dcache-stores
3903 - L1-dcache-store-misses
3904 - L1-dcache-prefetches
3905 - L1-dcache-prefetch-misses
3906 - L1-icache-loads
3907 - L1-icache-load-misses
3908 - L1-icache-prefetches
3909 - L1-icache-prefetch-misses
3910 - LLC-loads
3911 - LLC-load-misses
3912 - LLC-stores
3913 - LLC-store-misses
3914 - LLC-prefetches
3915 - LLC-prefetch-misses
3916 - dTLB-loads
3917 - dTLB-load-misses
3918 - dTLB-stores
3919 - dTLB-store-misses
3920 - dTLB-prefetches
3921 - dTLB-prefetch-misses
3922 - iTLB-loads
3923 - iTLB-load-misses
3924 - branch-loads
3925 - branch-load-misses
3926
3927 =item B<ReportKernelPMUEvents> B<false>|B<true>
3928
3929 Enable or disable measuring of the following events:
3930 - cpu-cycles
3931 - instructions
3932 - cache-references
3933 - cache-misses
3934 - branches
3935 - branch-misses
3936 - bus-cycles
3937
3938 =item B<ReportSoftwareEvents> B<false>|B<true>
3939
3940 Enable or disable measuring of software events provided by kernel:
3941 - cpu-clock
3942 - task-clock
3943 - context-switches
3944 - cpu-migrations
3945 - page-faults
3946 - minor-faults
3947 - major-faults
3948 - alignment-faults
3949 - emulation-faults
3950
3951 =item B<EventList> I<filename>
3952
3953 JSON performance counter event list file name. To be able to monitor all Intel
3954 CPU specific events JSON event list file should be downloaded. Use the pmu-tools
3955 event_download.py script to download event list for current CPU.
3956
3957 =item B<HardwareEvents> I<events>
3958
3959 This field is a list of event names or groups of comma separated event names.
3960 This option requires B<EventList> option to be configured.
3961
3962 =item B<Cores> I<cores groups>
3963
3964 All events are reported on a per core basis. Monitoring of the events can be
3965 configured for a group of cores (aggregated statistics). This field defines
3966 groups of cores on which to monitor supported events. The field is represented
3967 as list of strings with core group values. Each string represents a list of
3968 cores in a group. If a group is enclosed in square brackets each core is added
3969 individually to a separate group (that is statistics are not aggregated).
3970 Allowed formats are:
3971 0,1,2,3
3972 0-10,20-18
3973 1,3,5-8,10,0x10-12
3974 [4-15,32-63]
3975
3976 If an empty string is provided as value for this field default cores
3977 configuration is applied - that is separate group is created for each core.
3978
3979 =item B<DispatchMultiPmu> B<false>|B<true>
3980
3981 Enable or disable dispatching of cloned multi PMU for uncore events. If
3982 disabled only total sum is dispatched as single event. If enabled separate
3983 metric is dispatched for every counter.
3984
3985 =back
3986
3987 =head2 Plugin C<intel_rdt>
3988
3989 The I<intel_rdt> plugin collects information provided by monitoring features of
3990 Intel Resource Director Technology (Intel(R) RDT) like Cache Monitoring
3991 Technology (CMT), Memory Bandwidth Monitoring (MBM). These features provide
3992 information about utilization of shared resources. CMT monitors last level cache
3993 occupancy (LLC). MBM supports two types of events reporting local and remote
3994 memory bandwidth. Local memory bandwidth (MBL) reports the bandwidth of
3995 accessing memory associated with the local socket. Remote memory bandwidth (MBR)
3996 reports the bandwidth of accessing the remote socket. Also this technology
3997 allows to monitor instructions per clock (IPC).
3998 Monitor events are hardware dependant. Monitoring capabilities are detected on
3999 plugin initialization and only supported events are monitored.
4000
4001 B<Note:> I<intel_rdt> plugin is using model-specific registers (MSRs), which
4002 require an additional capability to be enabled if collectd is run as a service.
4003 Please refer to I<contrib/systemd.collectd.service> file for more details.
4004
4005 B<Synopsis:>
4006
4007 <Plugin "intel_rdt">
4008 Cores "0-2" "3,4,6" "8-10,15"
4009 Processes "sshd,qemu-system-x86" "bash"
4010 </Plugin>
4011
4012 B<Options:>
4013
4014 =over 4
4015
4016 =item B<Interval> I<seconds>
4017
4018 The interval within which to retrieve statistics on monitored events in seconds.
4019 For milliseconds divide the time by 1000 for example if the desired interval
4020 is 50ms, set interval to 0.05. Due to limited capacity of counters it is not
4021 recommended to set interval higher than 1 sec.
4022
4023 =item B<Cores> I<cores groups>
4024
4025 Monitoring of the events can be configured for group of cores
4026 (aggregated statistics). This field defines groups of cores on which to monitor
4027 supported events. The field is represented as list of strings with core group
4028 values. Each string represents a list of cores in a group. Allowed formats are:
4029 0,1,2,3
4030 0-10,20-18
4031 1,3,5-8,10,0x10-12
4032
4033 If an empty string is provided as value for this field default cores
4034 configuration is applied - a separate group is created for each core.
4035
4036 =item B<Processes> I<process names groups>
4037
4038 Monitoring of the events can be configured for group of processes
4039 (aggregated statistics). This field defines groups of processes on which to
4040 monitor supported events. The field is represented as list of strings with
4041 process names group values. Each string represents a list of processes in a
4042 group. Allowed format is:
4043 sshd,bash,qemu
4044
4045 =back
4046
4047 B<Note:> By default global interval is used to retrieve statistics on monitored
4048 events. To configure a plugin specific interval use B<Interval> option of the
4049 intel_rdt <LoadPlugin> block. For milliseconds divide the time by 1000 for
4050 example if the desired interval is 50ms, set interval to 0.05.
4051 Due to limited capacity of counters it is not recommended to set interval higher
4052 than 1 sec.
4053
4054 =head2 Plugin C<interface>
4055
4056 =over 4
4057
4058 =item B<Interface> I<Interface>
4059
4060 Select this interface. By default these interfaces will then be collected. For
4061 a more detailed description see B<IgnoreSelected> below.
4062
4063 See F</"IGNORELISTS"> for details.
4064
4065 =item B<IgnoreSelected> I<true>|I<false>
4066
4067 If no configuration is given, the B<interface>-plugin will collect data from
4068 all interfaces. This may not be practical, especially for loopback- and
4069 similar interfaces. Thus, you can use the B<Interface>-option to pick the
4070 interfaces you're interested in. Sometimes, however, it's easier/preferred
4071 to collect all interfaces I<except> a few ones. This option enables you to
4072 do that: By setting B<IgnoreSelected> to I<true> the effect of
4073 B<Interface> is inverted: All selected interfaces are ignored and all
4074 other interfaces are collected.
4075
4076 It is possible to use regular expressions to match interface names, if the
4077 name is surrounded by I</.../> and collectd was compiled with support for
4078 regexps. This is useful if there's a need to collect (or ignore) data
4079 for a group of interfaces that are similarly named, without the need to
4080 explicitly list all of them (especially useful if the list is dynamic).
4081 Example:
4082
4083 Interface "lo"
4084 Interface "/^veth/"
4085 Interface "/^tun[0-9]+/"
4086 IgnoreSelected "true"
4087
4088 This will ignore the loopback interface, all interfaces with names starting
4089 with I<veth> and all interfaces with names starting with I<tun> followed by
4090 at least one digit.
4091
4092 =item B<ReportInactive> I<true>|I<false>
4093
4094 When set to I<false>, only interfaces with non-zero traffic will be
4095 reported. Note that the check is done by looking into whether a
4096 package was sent at any time from boot and the corresponding counter
4097 is non-zero. So, if the interface has been sending data in the past
4098 since boot, but not during the reported time-interval, it will still
4099 be reported.
4100
4101 The default value is I<true> and results in collection of the data
4102 from all interfaces that are selected by B<Interface> and
4103 B<IgnoreSelected> options.
4104
4105 =item B<UniqueName> I<true>|I<false>
4106
4107 Interface name is not unique on Solaris (KSTAT), interface name is unique
4108 only within a module/instance. Following tuple is considered unique:
4109 (ks_module, ks_instance, ks_name)
4110 If this option is set to true, interface name contains above three fields
4111 separated by an underscore. For more info on KSTAT, visit
4112 L<http://docs.oracle.com/cd/E23824_01/html/821-1468/kstat-3kstat.html#REFMAN3Ekstat-3kstat>
4113
4114 This option is only available on Solaris.
4115
4116 =back
4117
4118 =head2 Plugin C<ipmi>
4119
4120 The B<ipmi plugin> allows to monitor server platform status using the Intelligent
4121 Platform Management Interface (IPMI). Local and remote interfaces are supported.
4122
4123 The plugin configuration consists of one or more B<Instance> blocks which
4124 specify one I<ipmi> connection each. Each block requires one unique string
4125 argument as the instance name. If instances are not configured, an instance with
4126 the default option values will be created.
4127
4128 For backwards compatibility, any option other than B<Instance> block will trigger
4129 legacy config handling and it will be treated as an option within B<Instance>
4130 block. This support will go away in the next major version of Collectd.
4131
4132 Within the B<Instance> blocks, the following options are allowed:
4133
4134 =over 4
4135
4136 =item B<Address> I<Address>
4137
4138 Hostname or IP to connect to. If not specified, plugin will try to connect to
4139 local management controller (BMC).
4140
4141 =item B<Username> I<Username>
4142
4143 =item B<Password> I<Password>
4144
4145 The username and the password to use for the connection to remote BMC.
4146
4147 =item B<AuthType> I<MD5>|I<rmcp+>
4148
4149 Forces the authentication type to use for the connection to remote BMC.
4150 By default most secure type is seleted.
4151
4152 =item B<Host> I<Hostname>
4153
4154 Sets the B<host> field of dispatched values. Defaults to the global hostname
4155 setting.
4156
4157 =item B<Sensor> I<Sensor>
4158
4159 Selects sensors to collect or to ignore, depending on B<IgnoreSelected>.
4160
4161 See F</"IGNORELISTS"> for details.
4162
4163 =item B<IgnoreSelected> I<true>|I<false>
4164
4165 If no configuration if given, the B<ipmi> plugin will collect data from all
4166 sensors found of type "temperature", "voltage", "current" and "fanspeed".
4167 This option enables you to do that: By setting B<IgnoreSelected> to I<true>
4168 the effect of B<Sensor> is inverted: All selected sensors are ignored and
4169 all other sensors are collected.
4170
4171 =item B<NotifySensorAdd> I<true>|I<false>
4172
4173 If a sensor appears after initialization time of a minute a notification
4174 is sent.
4175
4176 =item B<NotifySensorRemove> I<true>|I<false>
4177
4178 If a sensor disappears a notification is sent.
4179
4180 =item B<NotifySensorNotPresent> I<true>|I<false>
4181
4182 If you have for example dual power supply and one of them is (un)plugged then
4183 a notification is sent.
4184
4185 =item B<NotifyIPMIConnectionState> I<true>|I<false>
4186
4187 If a IPMI connection state changes after initialization time of a minute
4188 a notification is sent. Defaults to B<false>.
4189
4190 =item B<SELEnabled> I<true>|I<false>
4191
4192 If system event log (SEL) is enabled, plugin will listen for sensor threshold
4193 and discrete events. When event is received the notification is sent.
4194 SEL event filtering can be configured using B<SELSensor> and B<SELIgnoreSelected>
4195 config options.
4196 Defaults to B<false>.
4197
4198 =item B<SELSensor> I<SELSensor>
4199
4200 Selects sensors to get events from or to ignore, depending on B<SELIgnoreSelected>.
4201
4202 See F</"IGNORELISTS"> for details.
4203
4204 =item B<SELIgnoreSelected> I<true>|I<false>
4205
4206 If no configuration is given, the B<ipmi> plugin will pass events from all
4207 sensors. This option enables you to do that: By setting B<SELIgnoreSelected>
4208 to I<true> the effect of B<SELSensor> is inverted: All events from selected
4209 sensors are ignored and all events from other sensors are passed.
4210
4211 =item B<SELClearEvent> I<true>|I<false>
4212
4213 If SEL clear event is enabled, plugin will delete event from SEL list after
4214 it is received and successfully handled. In this case other tools that are
4215 subscribed for SEL events will receive an empty event.
4216 Defaults to B<false>.
4217
4218 =back
4219
4220 =head2 Plugin C<ipstats>
4221
4222 This plugin collects counts for ipv4 and ipv6 various types of packets passing
4223 through the system in total. At the moment it's only supported on FreeBSD.
4224
4225 The full list of options available to include in the counted statistics is:
4226 ip4receive IPv4 total packets received
4227 ip4badsum IPv4 checksum bad
4228 ip4tooshort IPv4 packet too short
4229 ip4toosmall IPv4 not enough data
4230 ip4badhlen IPv4 ip header length < data size
4231 ip4badlen IPv4 ip length < ip header length
4232 ip4fragment IPv4 fragments received
4233 ip4fragdrop IPv4 frags dropped (dups, out of space)
4234 ip4fragtimeout IPv4 fragments timed out
4235 ip4forward IPv4 packets forwarded
4236 ip4fastforward IPv4 packets fast forwarded
4237 ip4cantforward IPv4 packets rcvd for unreachable dest
4238 ip4redirectsent IPv4 packets forwarded on same net
4239 ip4noproto IPv4 unknown or unsupported protocol
4240 ip4deliver IPv4 datagrams delivered to upper level
4241 ip4transmit IPv4 total ip packets generated here
4242 ip4odrop IPv4 lost packets due to nobufs, etc.
4243 ip4reassemble IPv4 total packets reassembled ok
4244 ip4fragmented IPv4 datagrams successfully fragmented
4245 ip4ofragment IPv4 output fragments created
4246 ip4cantfrag IPv4 don't fragment flag was set, etc.
4247 ip4badoptions IPv4 error in option processing
4248 ip4noroute IPv4 packets discarded due to no route
4249 ip4badvers IPv4 ip version != 4
4250 ip4rawout IPv4 total raw ip packets generated
4251 ip4toolong IPv4 ip length > max ip packet size
4252 ip4notmember IPv4 multicasts for unregistered grps
4253 ip4nogif IPv4 no match gif found
4254 ip4badaddr IPv4 invalid address on header
4255
4256 ip6receive IPv6 total packets received
4257 ip6tooshort IPv6 packet too short
4258 ip6toosmall IPv6 not enough data
4259 ip6fragment IPv6 fragments received
4260 ip6fragdrop IPv6 frags dropped(dups, out of space)
4261 ip6fragtimeout IPv6 fragments timed out
4262 ip6fragoverflow IPv6 fragments that exceeded limit
4263 ip6forward IPv6 packets forwarded
4264 ip6cantforward IPv6 packets rcvd for unreachable dest
4265 ip6redirectsent IPv6 packets forwarded on same net
4266 ip6deliver IPv6 datagrams delivered to upper level
4267 ip6transmit IPv6 total ip packets generated here
4268 ip6odrop IPv6 lost packets due to nobufs, etc.
4269 ip6reassemble IPv6 total packets reassembled ok
4270 ip6fragmented IPv6 datagrams successfully fragmented
4271 ip6ofragment IPv6 output fragments created
4272 ip6cantfrag IPv6 don't fragment flag was set, etc.
4273 ip6badoptions IPv6 error in option processing
4274 ip6noroute IPv6 packets discarded due to no route
4275 ip6badvers IPv6 ip6 version != 6
4276 ip6rawout IPv6 total raw ip packets generated
4277 ip6badscope IPv6 scope error
4278 ip6notmember IPv6 don't join this multicast group
4279 ip6nogif IPv6 no match gif found
4280 ip6toomanyhdr IPv6 discarded due to too many headers
4281
4282 By default the following options are included in the counted packets:
4283
4284 - ip4receive
4285 - ip4forward
4286 - ip4transmit
4287
4288 - ip6receive
4289 - ip6forward
4290 - ip6transmit
4291
4292 For example to also count IPv4 and IPv6 fragments received, include the
4293 following configuration:
4294
4295 <Plugin ipstats>
4296 ip4fragment true
4297 ip6fragment true
4298 </Plugin>
4299
4300 =head2 Plugin C<iptables>
4301
4302 =over 4
4303
4304 =item B<Chain> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
4305
4306 =item B<Chain6> I<Table> I<Chain> [I<Comment|Number> [I<Name>]]
4307
4308 Select the iptables/ip6tables filter rules to count packets and bytes from.
4309
4310 If only I<Table> and I<Chain> are given, this plugin will collect the counters
4311 of all rules which have a comment-match. The comment is then used as
4312 type-instance.
4313
4314 If I<Comment> or I<Number> is given, only the rule with the matching comment or
4315 the I<n>th rule will be collected. Again, the comment (or the number) will be
4316 used as the type-instance.
4317
4318 If I<Name> is supplied, it will be used as the type-instance instead of the
4319 comment or the number.
4320
4321 =back
4322
4323 =head2 Plugin C<irq>
4324
4325 =over 4
4326
4327 =item B<Irq> I<Irq>
4328
4329 Select this irq. By default these irqs will then be collected. For a more
4330 detailed description see B<IgnoreSelected> below.
4331
4332 See F</"IGNORELISTS"> for details.
4333
4334 =item B<IgnoreSelected> I<true>|I<false>
4335
4336 If no configuration if given, the B<irq>-plugin will collect data from all
4337 irqs. This may not be practical, especially if no interrupts happen. Thus, you
4338 can use the B<Irq>-option to pick the interrupt you're interested in.
4339 Sometimes, however, it's easier/preferred to collect all interrupts I<except> a
4340 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
4341 I<true> the effect of B<Irq> is inverted: All selected interrupts are ignored
4342 and all other interrupts are collected.
4343
4344 =back
4345
4346 =head2 Plugin C<java>
4347
4348 The I<Java> plugin makes it possible to write extensions for collectd in Java.
4349 This section only discusses the syntax and semantic of the configuration
4350 options. For more in-depth information on the I<Java> plugin, please read
4351 L<collectd-java(5)>.
4352
4353 Synopsis:
4354
4355 <Plugin "java">
4356 JVMArg "-verbose:jni"
4357 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
4358 LoadPlugin "org.collectd.java.Foobar"
4359 <Plugin "org.collectd.java.Foobar">
4360 # To be parsed by the plugin
4361 </Plugin>
4362 </Plugin>
4363
4364 Available configuration options:
4365
4366 =over 4
4367
4368 =item B<JVMArg> I<Argument>
4369
4370 Argument that is to be passed to the I<Java Virtual Machine> (JVM). This works
4371 exactly the way the arguments to the I<java> binary on the command line work.
4372 Execute C<javaE<nbsp>--help> for details.
4373
4374 Please note that B<all> these options must appear B<before> (i.E<nbsp>e. above)
4375 any other options! When another option is found, the JVM will be started and
4376 later options will have to be ignored!
4377
4378 =item B<LoadPlugin> I<JavaClass>
4379
4380 Instantiates a new I<JavaClass> object. The constructor of this object very
4381 likely then registers one or more callback methods with the server.
4382
4383 See L<collectd-java(5)> for details.
4384
4385 When the first such option is found, the virtual machine (JVM) is created. This
4386 means that all B<JVMArg> options must appear before (i.E<nbsp>e. above) all
4387 B<LoadPlugin> options!
4388
4389 =item B<Plugin> I<Name>
4390
4391 The entire block is passed to the Java plugin as an
4392 I<org.collectd.api.OConfigItem> object.
4393
4394 For this to work, the plugin has to register a configuration callback first,
4395 see L<collectd-java(5)/"config callback">. This means, that the B<Plugin> block
4396 must appear after the appropriate B<LoadPlugin> block. Also note, that I<Name>
4397 depends on the (Java) plugin registering the callback and is completely
4398 independent from the I<JavaClass> argument passed to B<LoadPlugin>.
4399
4400 =back
4401
4402 =head2 Plugin C<load>
4403
4404 The I<Load plugin> collects the system load. These numbers give a rough overview
4405 over the utilization of a machine. The system load is defined as the number of
4406 runnable tasks in the run-queue and is provided by many operating systems as a
4407 one, five or fifteen minute average.
4408
4409 The following configuration options are available:
4410
4411 =over 4
4412
4413 =item B<ReportRelative> B<false>|B<true>
4414
4415 When enabled, system load divided by number of available CPU cores is reported
4416 for intervals 1 min, 5 min and 15 min. Defaults to false.
4417
4418 =back
4419
4420
4421 =head2 Plugin C<logfile>
4422
4423 =over 4
4424
4425 =item B<LogLevel> B<debug|info|notice|warning|err>
4426
4427 Sets the log-level. If, for example, set to B<notice>, then all events with
4428 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
4429
4430 Please note that B<debug> is only available if collectd has been compiled with
4431 debugging support.
4432
4433 =item B<File> I<File>
4434
4435 Sets the file to write log messages to. The special strings B<stdout> and
4436 B<stderr> can be used to write to the standard output and standard error
4437 channels, respectively. This, of course, only makes much sense when I<collectd>
4438 is running in foreground- or non-daemon-mode.
4439
4440 =item B<Timestamp> B<true>|B<false>
4441
4442 Prefix all lines printed by the current time. Defaults to B<true>.
4443
4444 =item B<PrintSeverity> B<true>|B<false>
4445
4446 When enabled, all lines are prefixed by the severity of the log message, for
4447 example "warning". Defaults to B<false>.
4448
4449 =back
4450
4451 B<Note>: There is no need to notify the daemon after moving or removing the
4452 log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
4453 for each line it writes.
4454
4455 =head2 Plugin C<logparser>
4456
4457 The I<logparser> plugin is used to parse different kinds of logs. Setting proper
4458 options you can choose strings to collect. Plugin searches the log file for
4459 messages which contain several matches (two or more). When all mandatory matches
4460 are found then it sends proper notification containing all fetched values.
4461
4462 B<Synopsis:>
4463
4464 <Plugin logparser>
4465 <Logfile "/var/log/syslog">
4466 FirstFullRead false
4467 <Message "pcie_errors">
4468 DefaultType "pcie_error"
4469 DefaultSeverity "warning"
4470 <Match "aer error">
4471 Regex "AER:.*error received"
4472 SubmatchIdx -1
4473 </Match>
4474 <Match "incident time">
4475 Regex "(... .. ..:..:..) .* pcieport.*AER"
4476 SubmatchIdx 1
4477 IsMandatory false
4478 </Match>
4479 <Match "root port">
4480 Regex "pcieport (.*): AER:"
4481 SubmatchIdx 1
4482 IsMandatory true
4483 </Match>
4484 <Match "device">
4485 PluginInstance true
4486 Regex " ([0-9a-fA-F:\\.]*): PCIe Bus Error"
4487 SubmatchIdx 1
4488 IsMandatory false
4489 </Match>
4490 <Match "severity_mandatory">
4491 Regex "severity="
4492 SubMatchIdx -1
4493 </Match>
4494 <Match "nonfatal">
4495 Regex "severity=.*\\([nN]on-[fF]atal"
4496 TypeInstance "non_fatal"
4497 IsMandatory false
4498 </Match>
4499 <Match "fatal">
4500 Regex "severity=.*\\([fF]atal"
4501 Severity "failure"
4502 TypeInstance "fatal"
4503 IsMandatory false
4504 </Match>
4505 <Match "corrected">
4506 Regex "severity=Corrected"
4507 TypeInstance "correctable"
4508 IsMandatory false
4509 </Match>
4510 <Match "error type">
4511 Regex "type=(.*),"
4512 SubmatchIdx 1
4513 IsMandatory false
4514 </Match>
4515 <Match "id">
4516 Regex ", id=(.*)"
4517 SubmatchIdx 1
4518 </Match>
4519 </Message>
4520 </Logfile>
4521 </Plugin>
4522
4523 B<Options:>
4524
4525 =over 4
4526
4527 =item B<Logfile> I<File>
4528
4529 The B<Logfile> block defines file to search. It may contain one or more
4530 B<Message> blocks which are defined below.
4531
4532 =item B<FirstFullRead> I<true>|I<false>
4533
4534 Set to true if the file has to be parsed from the beginning on the first read.
4535 If false only subsequent writes to log file will be parsed.
4536
4537 =item B<Message> I<Name>
4538
4539 B<Message> block contains matches to search the log file for. Each B<Message>
4540 block builds a notification message using matched elements if its mandatory
4541 B<Match> blocks are matched.
4542
4543 =item B<DefaultPluginInstance> I<String>
4544
4545 Sets the default value for the plugin instance of the notification.
4546
4547 =item B<DefaultType> I<String>
4548
4549 Sets the default value for the type of the notification.
4550
4551 =item B<DefaultTypeInstance> I<String>
4552
4553 Sets the default value for the type instance of the notification.
4554
4555 =item B<DefaultSeverity> I<String>
4556
4557 Sets the default severity. Must be set to "OK", "WARNING" or "FAILURE".
4558 Default value is "OK".
4559
4560 =item B<Match> I<Name>
4561
4562 Multiple I<Match> blocks define regular expression patterns for extracting or
4563 excluding specific string patterns from parsing. First and last I<Match> items
4564 in the same I<Message> set boundaries of multiline message and are mandatory.
4565 If these matches are not found then the whole message is discarded.
4566
4567 =item B<Regex> I<Regex>
4568
4569 Regular expression with pattern matching string. It may contain subexpressions,
4570 so next option B<SubmatchIdx> specifies which subexpression should be stored.
4571
4572 =item B<SubmatchIdx> I<Integer>
4573
4574 Index of subexpression to be used for notification. Multiple subexpressions are
4575 allowed. Index value 0 takes whole regular expression match as a result.
4576 Index value -1 does not add result to message item. Can be omitted, default
4577 value is 0.
4578
4579 =item B<Excluderegex> I<Regex>
4580
4581 Regular expression for excluding lines containing specific matching strings.
4582 This is processed before checking I<Regex> pattern. It is optional and can
4583 be omitted.
4584
4585 =item B<IsMandatory> I<true>|I<false>
4586
4587 Flag indicating if I<Match> item is mandatory for message validation. If set to
4588 true, whole message is discarded if it's missing. For false its presence is
4589 optional. Default value is set to true.
4590
4591 =item B<PluginInstance> I<true>|I<String>
4592
4593 If set to true, it sets plugin instance to string returned by regex. It can be
4594 overridden by user string.
4595
4596 =item B<Type> I<true>|I<String>
4597
4598 Sets notification type using rules like B<PluginInstance>.
4599
4600 =item B<TypeInstance> I<true>|I<String>
4601
4602 Sets notification type instance using rules like above.
4603
4604 =item B<Severity> I<String>
4605
4606 Sets notification severity to one of the options: "OK", "WARNING", "FAILURE".
4607
4608 =back
4609
4610 =head2 Plugin C<log_logstash>
4611
4612 The I<log logstash plugin> behaves like the logfile plugin but formats
4613 messages as JSON events for logstash to parse and input.
4614
4615 =over 4
4616
4617 =item B<LogLevel> B<debug|info|notice|warning|err>
4618
4619 Sets the log-level. If, for example, set to B<notice>, then all events with
4620 severity B<notice>, B<warning>, or B<err> will be written to the logfile.
4621
4622 Please note that B<debug> is only available if collectd has been compiled with
4623 debugging support.
4624
4625 =item B<File> I<File>
4626
4627 Sets the file to write log messages to. The special strings B<stdout> and
4628 B<stderr> can be used to write to the standard output and standard error
4629 channels, respectively. This, of course, only makes much sense when I<collectd>
4630 is running in foreground- or non-daemon-mode.
4631
4632 =back
4633
4634 B<Note>: There is no need to notify the daemon after moving or removing the
4635 log file (e.E<nbsp>g. when rotating the logs). The plugin reopens the file
4636 for each line it writes.
4637
4638 =head2 Plugin C<lpar>
4639
4640 The I<LPAR plugin> reads CPU statistics of I<Logical Partitions>, a
4641 virtualization technique for IBM POWER processors. It takes into account CPU
4642 time stolen from or donated to a partition, in addition to the usual user,
4643 system, I/O statistics.
4644
4645 The following configuration options are available:
4646
4647 =over 4
4648
4649 =item B<CpuPoolStats> B<false>|B<true>
4650
4651 When enabled, statistics about the processor pool are read, too. The partition
4652 needs to have pool authority in order to be able to acquire this information.
4653 Defaults to false.
4654
4655 =item B<ReportBySerial> B<false>|B<true>
4656
4657 If enabled, the serial of the physical machine the partition is currently
4658 running on is reported as I<hostname> and the logical hostname of the machine
4659 is reported in the I<plugin instance>. Otherwise, the logical hostname will be
4660 used (just like other plugins) and the I<plugin instance> will be empty.
4661 Defaults to false.
4662
4663 =back
4664
4665 =head2 Plugin C<lua>
4666
4667 This plugin embeds a Lua interpreter into collectd and provides an interface
4668 to collectd's plugin system. See L<collectd-lua(5)> for its documentation.
4669
4670
4671 =head2 Plugin C<mbmon>
4672
4673 The C<mbmon plugin> uses mbmon to retrieve temperature, voltage, etc.
4674
4675 Be default collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>. The
4676 B<Host> and B<Port> options can be used to change these values, see below.
4677 C<mbmon> has to be running to work correctly. If C<mbmon> is not running
4678 timeouts may appear which may interfere with other statistics..
4679
4680 C<mbmon> must be run with the -r option ("print TAG and Value format");
4681 Debian's F</etc/init.d/mbmon> script already does this, other people
4682 will need to ensure that this is the case.
4683
4684 =over 4
4685
4686 =item B<Host> I<Hostname>
4687
4688 Hostname to connect to. Defaults to B<127.0.0.1>.
4689
4690 =item B<Port> I<Port>
4691
4692 TCP-Port to connect to. Defaults to B<411>.
4693
4694 =back
4695
4696 =head2 Plugin C<mdevents >
4697
4698 The I< mdevents > plugin collects status changes from md (Linux software RAID) devices.
4699
4700 RAID arrays are meant to allow users/administrators to keep systems up and
4701 running, in case of common hardware problems (disk failure). Mdadm is the
4702 standard software RAID management tool for Linux. It provides the ability to
4703 monitor "metadata event" occurring such as disk failures, clean-to-dirty
4704 transitions, and etc. The kernel provides the ability to report such actions to
4705 the userspace via sysfs, and mdadm takes action accordingly with the monitoring
4706 capability. The mdmon polls the /sys looking for changes in the entries
4707 array_state, sync_action, and per disk state attribute files. This is meaningful
4708 for RAID1, 5 and 10 only.
4709
4710 Mdevents plugin is based on gathering RAID array events that are
4711 written to syslog by mdadm. After registering an event, it can send a collectd
4712 notification that contains mdadm event's data. Event consists of event type,
4713 raid array name and, for particular events, name of component device.
4714
4715 Example message:
4716
4717 C<Jan 17 05:24:27 pc1 mdadm[188]: NewArray event detected on md device /dev/md0>
4718
4719 Plugin also classifies gathered event. This means that a notification will have
4720 a different severity {OKAY, WARNING, FAILURE} for particular mdadm event.
4721
4722 For proper work, mdevents plugin needs syslog and mdadm utilities to be present on
4723 the running system. Otherwise it will not be compiled as a part of collectd.
4724
4725 B<Synopsis:>
4726
4727 <Plugin mdevents>
4728 Event ""
4729 IgnoreEvent False
4730 Array ""
4731 IgnoreArray False
4732 </Plugin>
4733
4734 B<Plugin configuration:>
4735
4736 Mdevents plugin's configuration is mostly based on IgnoreList, which is a collectd's
4737 utility. User can specify what particular events/RAID arrays lie in his interest.
4738 Setting of IgnoreEvent/IgnoreArray booleans won't take effect if Event/Array config
4739 lists are empty - plugin will accept entry anyway.
4740
4741 B<Options:>
4742
4743 =over 4
4744
4745 =item B<Event> I<"EventName">
4746
4747 Names of events to be monitored, separated by spaces. Possible events include:
4748
4749 Event Name | Class of event
4750 ------------------+---------------
4751 DeviceDisappeared | FAILURE
4752 RebuildStarted | OKAY
4753 RebuildNN | OKAY
4754 RebuildFinished | WARNING
4755 Fail | FAILURE
4756 FailSpare | WARNING
4757 SpareActive | OKAY
4758 NewArray | OKAY
4759 DegradedArray | FAILURE
4760 MoveSpare | WARNING
4761 SparesMissing | WARNING
4762 TestMessage | OKAY
4763
4764 User should set the events that should be monitored as a strings separated by spaces,
4765 for example Events "DeviceDisappeared Fail DegradedArray".
4766
4767 =item B<IgnoreEvent> I<false>|I<true>
4768
4769 If I<IgnoreEvent> is set to true, events specified in I<Events> will be ignored.
4770 If it's false, only specified events will be monitored.
4771
4772 =item B<Array> I<arrays>
4773
4774 User can specify an array or a group of arrays using regexp. Plugin will accept
4775 only RAID arrays names that start with "/dev/md".
4776
4777 =item B<IgnoreArray> I<false>|I<true>
4778
4779 If I<IgnoreArray> is set to true, arrays specified in I<Array> will be ignored.
4780 If it's false, only specified events will be monitored.
4781
4782 =back
4783
4784 =head2 Plugin C<mcelog>
4785
4786 The C<mcelog plugin> uses mcelog to retrieve machine check exceptions.
4787
4788 By default the plugin connects to B<"/var/run/mcelog-client"> to check if the
4789 mcelog server is running. When the server is running, the plugin will tail the
4790 specified logfile to retrieve machine check exception information and send a
4791 notification with the details from the logfile. The plugin will use the mcelog
4792 client protocol to retrieve memory related machine check exceptions. Note that
4793 for memory exceptions, notifications are only sent when there is a change in
4794 the number of corrected/uncorrected memory errors.
4795
4796 =head3 The Memory block
4797
4798 Note: these options cannot be used in conjunction with the logfile options, they are mutually
4799 exclusive.
4800
4801 =over 3
4802
4803 =item B<McelogClientSocket> I<Path>
4804 Connect to the mcelog client socket using the UNIX domain socket at I<Path>.
4805 Defaults to B<"/var/run/mcelog-client">.
4806
4807 =item B<PersistentNotification> B<true>|B<false>
4808 Override default configuration to only send notifications when sent when there
4809 is a change in the number of corrected/uncorrected memory errors. When set to
4810 true notifications will be sent for every read cycle. Default is false. Does
4811 not affect the stats being dispatched.
4812
4813 =back
4814
4815 =over 4
4816
4817 =item B<McelogLogfile> I<Path>
4818
4819 The mcelog file to parse. Defaults to B<"/var/log/mcelog">. Note: this option
4820 cannot be used in conjunction with the memory block options, they are mutually
4821 exclusive.
4822
4823 =back
4824
4825 =head2 Plugin C<md>
4826
4827 The C<md plugin> collects information from Linux Software-RAID devices (md).
4828
4829 All reported values are of the type C<md_disks>. Reported type instances are
4830 I<active>, I<failed> (present but not operational), I<spare> (hot stand-by) and
4831 I<missing> (physically absent) disks.
4832
4833 =over 4
4834
4835 =item B<Device> I<Device>
4836
4837 Select md devices based on device name. The I<device name> is the basename of
4838 the device, i.e. the name of the block device without the leading C</dev/>.
4839 See B<IgnoreSelected> for more details.
4840
4841 See F</"IGNORELISTS"> for details.
4842
4843 =item B<IgnoreSelected> B<true>|B<false>
4844
4845 Invert device selection: If set to B<true>, all md devices B<except> those
4846 listed using B<Device> are collected. If B<false> (the default), only those
4847 listed are collected. If no configuration is given, the B<md> plugin will
4848 collect data from all md devices.
4849
4850 =back
4851
4852 =head2 Plugin C<memcachec>
4853
4854 The C<memcachec plugin> connects to a memcached server, queries one or more
4855 given I<pages> and parses the returned data according to user specification.
4856 The I<matches> used are the same as the matches used in the C<curl> and C<tail>
4857 plugins.
4858
4859 In order to talk to the memcached server, this plugin uses the I<libmemcached>
4860 library. Please note that there is another library with a very similar name,
4861 libmemcache (notice the missing `d'), which is not applicable.
4862
4863 Synopsis of the configuration:
4864
4865 <Plugin "memcachec">
4866 <Page "plugin_instance">
4867 Server "localhost"
4868 Key "page_key"
4869 Plugin "plugin_name"
4870 <Match>
4871 Regex "(\\d+) bytes sent"
4872 DSType CounterAdd
4873 Type "ipt_octets"
4874 Instance "type_instance"
4875 </Match>
4876 </Page>
4877 </Plugin>
4878
4879 The configuration options are:
4880
4881 =over 4
4882
4883 =item E<lt>B<Page> I<Name>E<gt>
4884
4885 Each B<Page> block defines one I<page> to be queried from the memcached server.
4886 The block requires one string argument which is used as I<plugin instance>.
4887
4888 =item B<Server> I<Address>
4889
4890 Sets the server address to connect to when querying the page. Must be inside a
4891 B<Page> block.
4892
4893 =item B<Key> I<Key>
4894
4895 When connected to the memcached server, asks for the page I<Key>.
4896
4897 =item B<Plugin> I<Plugin>
4898
4899 Use I<Plugin> as the plugin name when submitting values.
4900 Defaults to C<memcachec>.
4901
4902 =item E<lt>B<Match>E<gt>
4903
4904 Match blocks define which strings to look for and how matches substrings are
4905 interpreted. For a description of match blocks, please see L<"Plugin tail">.
4906
4907 =back
4908
4909 =head2 Plugin C<memcached>
4910
4911 The B<memcached plugin> connects to a memcached server and queries statistics
4912 about cache utilization, memory and bandwidth used.
4913 L<http://memcached.org/>
4914
4915 <Plugin "memcached">
4916 <Instance "name">
4917 #Host "memcache.example.com"
4918 Address "127.0.0.1"
4919 Port 11211
4920 </Instance>
4921 </Plugin>
4922
4923 The plugin configuration consists of one or more B<Instance> blocks which
4924 specify one I<memcached> connection each. Within the B<Instance> blocks, the
4925 following options are allowed:
4926
4927 =over 4
4928
4929 =item B<Host> I<Hostname>
4930
4931 Sets the B<host> field of dispatched values. Defaults to the global hostname
4932 setting.
4933 For backwards compatibility, values are also dispatched with the global
4934 hostname when B<Host> is set to B<127.0.0.1> or B<localhost> and B<Address> is
4935 not set.
4936
4937 =item B<Address> I<Address>
4938
4939 Hostname or IP to connect to. For backwards compatibility, defaults to the
4940 value of B<Host> or B<127.0.0.1> if B<Host> is unset.
4941
4942 =item B<Port> I<Port>
4943
4944 TCP port to connect to. Defaults to B<11211>.
4945
4946 =item B<Socket> I<Path>
4947
4948 Connect to I<memcached> using the UNIX domain socket at I<Path>. If this
4949 setting is given, the B<Address> and B<Port> settings are ignored.
4950
4951 =back
4952
4953 =head2 Plugin C<mic>
4954
4955 The B<mic plugin> gathers CPU statistics, memory usage and temperatures from
4956 Intel's Many Integrated Core (MIC) systems.
4957
4958 B<Synopsis:>
4959
4960 <Plugin mic>
4961 ShowCPU true
4962 ShowCPUCores true
4963 ShowMemory true
4964
4965 ShowTemperatures true
4966 Temperature vddg
4967 Temperature vddq
4968 IgnoreSelectedTemperature true
4969
4970 ShowPower true
4971 Power total0
4972 Power total1
4973 IgnoreSelectedPower true
4974 </Plugin>
4975
4976 The following options are valid inside the B<PluginE<nbsp>mic> block:
4977
4978 =over 4
4979
4980 =item B<ShowCPU> B<true>|B<false>
4981
4982 If enabled (the default) a sum of the CPU usage across all cores is reported.
4983
4984 =item B<ShowCPUCores> B<true>|B<false>
4985
4986 If enabled (the default) per-core CPU usage is reported.
4987
4988 =item B<ShowMemory> B<true>|B<false>
4989
4990 If enabled (the default) the physical memory usage of the MIC system is
4991 reported.
4992
4993 =item B<ShowTemperatures> B<true>|B<false>
4994
4995 If enabled (the default) various temperatures of the MIC system are reported.
4996
4997 =item B<Temperature> I<Name>
4998
4999 This option controls which temperatures are being reported. Whether matching
5000 temperatures are being ignored or I<only> matching temperatures are reported
5001 depends on the B<IgnoreSelectedTemperature> setting below. By default I<all>
5002 temperatures are reported.
5003
5004 =item B<IgnoreSelectedTemperature> B<false>|B<true>
5005
5006 Controls the behavior of the B<Temperature> setting above. If set to B<false>
5007 (the default) only temperatures matching a B<Temperature> option are reported
5008 or, if no B<Temperature> option is specified, all temperatures are reported. If
5009 set to B<true>, matching temperatures are I<ignored> and all other temperatures
5010 are reported.
5011
5012 Known temperature names are:
5013
5014 =over 4
5015
5016 =item die
5017
5018 Die of the CPU
5019
5020 =item devmem
5021
5022 Device Memory
5023
5024 =item fin
5025
5026 Fan In
5027
5028 =item fout
5029
5030 Fan Out
5031
5032 =item vccp
5033
5034 Voltage ccp
5035
5036 =item vddg
5037
5038 Voltage ddg
5039
5040 =item vddq
5041
5042 Voltage ddq
5043
5044 =back
5045
5046 =item B<ShowPower> B<true>|B<false>
5047
5048 If enabled (the default) various temperatures of the MIC system are reported.
5049
5050 =item B<Power> I<Name>
5051
5052 This option controls which power readings are being reported. Whether matching
5053 power readings are being ignored or I<only> matching power readings are reported
5054 depends on the B<IgnoreSelectedPower> setting below. By default I<all>
5055 power readings are reported.
5056
5057 =item B<IgnoreSelectedPower> B<false>|B<true>
5058
5059 Controls the behavior of the B<Power> setting above. If set to B<false>
5060 (the default) only power readings matching a B<Power> option are reported
5061 or, if no B<Power> option is specified, all power readings are reported. If
5062 set to B<true>, matching power readings are I<ignored> and all other power readings
5063 are reported.
5064
5065 Known power names are:
5066
5067 =over 4
5068
5069 =item total0
5070
5071 Total power utilization averaged over Time Window 0 (uWatts).
5072
5073 =item total1
5074
5075 Total power utilization averaged over Time Window 0 (uWatts).
5076
5077 =item inst
5078
5079 Instantaneous power (uWatts).
5080
5081 =item imax
5082
5083 Max instantaneous power (uWatts).
5084
5085 =item pcie
5086
5087 PCI-E connector power (uWatts).
5088
5089 =item c2x3
5090
5091 2x3 connector power (uWatts).
5092
5093 =item c2x4
5094
5095 2x4 connector power (uWatts).
5096
5097 =item vccp
5098
5099 Core rail (uVolts).
5100
5101 =item vddg
5102
5103 Uncore rail (uVolts).
5104
5105 =item vddq
5106
5107 Memory subsystem rail (uVolts).
5108
5109 =back
5110
5111 =back
5112
5113 =head2 Plugin C<memory>
5114
5115 The I<memory plugin> provides the following configuration options:
5116
5117 =over 4
5118
5119 =item B<ValuesAbsolute> B<true>|B<false>
5120
5121 Enables or disables reporting of physical memory usage in absolute numbers,
5122 i.e. bytes. Defaults to B<true>.
5123
5124 =item B<ValuesPercentage> B<false>|B<true>
5125
5126 Enables or disables reporting of physical memory usage in percentages, e.g.
5127 percent of physical memory used. Defaults to B<false>.
5128
5129 This is useful for deploying I<collectd> in a heterogeneous environment in
5130 which the sizes of physical memory vary.
5131
5132 =back
5133
5134 =head2 Plugin C<modbus>
5135
5136 The B<modbus plugin> connects to a Modbus "slave" via Modbus/TCP or Modbus/RTU and
5137 reads register values. It supports reading single registers (unsigned 16E<nbsp>bit
5138 values), large integer values (unsigned 32E<nbsp>bit and 64E<nbsp>bit values) and
5139 floating point values (two registers interpreted as IEEE floats in big endian
5140 notation).
5141
5142 B<Synopsis:>
5143
5144 <Data "voltage-input-1">
5145 RegisterBase 0
5146 RegisterType float
5147 RegisterCmd ReadHolding
5148 Type voltage
5149 Instance "input-1"
5150 #Scale 1.0
5151 #Shift 0.0
5152 </Data>
5153
5154 <Data "voltage-input-2">
5155 RegisterBase 2
5156 RegisterType float
5157 RegisterCmd ReadHolding
5158 Type voltage
5159 Instance "input-2"
5160 </Data>
5161
5162 <Data "supply-temperature-1">
5163 RegisterBase 0
5164 RegisterType Int16
5165 RegisterCmd ReadHolding
5166 Type temperature
5167 Instance "temp-1"
5168 </Data>
5169
5170 <Host "modbus.example.com">
5171 Address "192.168.0.42"
5172 Port "502"
5173 Interval 60
5174
5175 <Slave 1>
5176 Instance "power-supply"
5177 Collect "voltage-input-1"
5178 Collect "voltage-input-2"
5179 </Slave>
5180 </Host>
5181
5182 <Host "localhost">
5183 Device "/dev/ttyUSB0"
5184 Baudrate 38400
5185 Interval 20
5186
5187 <Slave 1>
5188 Instance "temperature"
5189 Collect "supply-temperature-1"
5190 </Slave>
5191 </Host>
5192
5193 =over 4
5194
5195 =item E<lt>B<Data> I<Name>E<gt> blocks
5196
5197 Data blocks define a mapping between register numbers and the "types" used by
5198 I<collectd>.
5199
5200 Within E<lt>DataE<nbsp>/E<gt> blocks, the following options are allowed:
5201
5202 =over 4
5203
5204 =item B<RegisterBase> I<Number>
5205
5206 Configures the base register to read from the device. If the option
5207 B<RegisterType> has been set to B<Uint32> or B<Float>, this and the next
5208 register will be read (the register number is increased by one).
5209
5210 =item B<RegisterType> B<Int16>|B<Int32>|B<Int64>|B<Uint16>|B<Uint32>|B<UInt64>|B<Float>|B<Int32LE>|B<Uint32LE>|B<FloatLE>
5211
5212 Specifies what kind of data is returned by the device. This defaults to
5213 B<Uint16>. If the type is B<Int32>, B<Int32LE>, B<Uint32>, B<Uint32LE>,
5214 B<Float> or B<FloatLE>, two 16E<nbsp>bit registers at B<RegisterBase>
5215 and B<RegisterBase+1> will be read and the data is combined into one
5216 32E<nbsp>value. For B<Int32>, B<Uint32> and B<Float> the most significant
5217 16E<nbsp>bits are in the register at B<RegisterBase> and the least
5218 significant 16E<nbsp>bits are in the register at B<RegisterBase+1>.
5219 For B<Int32LE>, B<Uint32LE>, or B<Float32LE>, the high and low order
5220 registers are swapped with the most significant 16E<nbsp>bits in
5221 the B<RegisterBase+1> and the least significant 16E<nbsp>bits in
5222 B<RegisterBase>. If the type is B<Int64> or B<UInt64>, four 16E<nbsp>bit
5223 registers at B<RegisterBase>, B<RegisterBase+1>, B<RegisterBase+2> and
5224 B<RegisterBase+3> will be read and the data combined into one
5225 64E<nbsp>value.
5226
5227 =item B<RegisterCmd> B<ReadHolding>|B<ReadInput>
5228
5229 Specifies register type to be collected from device. Works only with libmodbus
5230 2.9.2 or higher. Defaults to B<ReadHolding>.
5231
5232 =item B<Type> I<Type>
5233
5234 Specifies the "type" (data set) to use when dispatching the value to
5235 I<collectd>. Currently, only data sets with exactly one data source are
5236 supported.
5237
5238 =item B<Instance> I<Instance>
5239
5240 Sets the type instance to use when dispatching the value to I<Instance>. If
5241 unset, an empty string (no type instance) is used.
5242
5243 =item B<Scale> I<Value>
5244
5245 The values taken from device are multiplied by I<Value>. The field is optional
5246 and the default is B<1.0>.
5247
5248 =item B<Shift> I<Value>
5249
5250 I<Value> is added to values from device after they have been multiplied by
5251 B<Scale> value. The field is optional and the default value is B<0.0>.
5252
5253 =back
5254
5255 =item E<lt>B<Host> I<Name>E<gt> blocks
5256
5257 Host blocks are used to specify to which hosts to connect and what data to read
5258 from their "slaves". The string argument I<Name> is used as hostname when
5259 dispatching the values to I<collectd>.
5260
5261 Within E<lt>HostE<nbsp>/E<gt> blocks, the following options are allowed:
5262
5263 =over 4
5264
5265 =item B<Address> I<Hostname>
5266
5267 For Modbus/TCP, specifies the node name (the actual network address) used to
5268 connect to the host. This may be an IP address or a hostname. Please note that
5269 the used I<libmodbus> library only supports IPv4 at the moment.
5270
5271 =item B<Port> I<Service>
5272
5273 for Modbus/TCP, specifies the port used to connect to the host. The port can
5274 either be given as a number or as a service name. Please note that the
5275 I<Service> argument must be a string, even if ports are given in their numerical
5276 form. Defaults to "502".
5277
5278 =item B<Device> I<Devicenode>
5279
5280 For Modbus/RTU, specifies the path to the serial device being used.
5281
5282 =item B<Baudrate> I<Baudrate>
5283
5284 For Modbus/RTU, specifies the baud rate of the serial device.
5285 Note, connections currently support only 8/N/1.
5286
5287 =item B<UARTType> I<UARTType>
5288
5289 For Modbus/RTU, specifies the type of the serial device.
5290 RS232, RS422 and RS485 are supported. Defaults to RS232.
5291 Available only on Linux systems with libmodbus>=2.9.4.
5292
5293 =item B<Interval> I<Interval>
5294
5295 Sets the interval (in seconds) in which the values will be collected from this
5296 host. By default the global B<Interval> setting will be used.
5297
5298 =item E<lt>B<Slave> I<ID>E<gt>
5299
5300 Over each connection, multiple Modbus devices may be reached. The slave ID
5301 is used to specify which device should be addressed. For each device you want
5302 to query, one B<Slave> block must be given.
5303
5304 Within E<lt>SlaveE<nbsp>/E<gt> blocks, the following options are allowed:
5305
5306 =over 4
5307
5308 =item B<Instance> I<Instance>
5309
5310 Specify the plugin instance to use when dispatching the values to I<collectd>.
5311 By default "slave_I<ID>" is used.
5312
5313 =item B<Collect> I<DataName>
5314
5315 Specifies which data to retrieve from the device. I<DataName> must be the same
5316 string as the I<Name> argument passed to a B<Data> block. You can specify this
5317 option multiple times to collect more than one value from a slave. At least one
5318 B<Collect> option is mandatory.
5319
5320 =back
5321
5322 =back
5323
5324 =back
5325
5326 =head2 Plugin C<mqtt>
5327
5328 The I<MQTT plugin> can send metrics to MQTT (B<Publish> blocks) and receive
5329 values from MQTT (B<Subscribe> blocks).
5330
5331 B<Synopsis:>
5332
5333 <Plugin mqtt>
5334 <Publish "name">
5335 Host "mqtt.example.com"
5336 Prefix "collectd"
5337 </Publish>
5338 <Subscribe "name">
5339 Host "mqtt.example.com"
5340 Topic "collectd/#"
5341 </Subscribe>
5342 </Plugin>
5343
5344 The plugin's configuration is in B<Publish> and/or B<Subscribe> blocks,
5345 configuring the sending and receiving direction respectively. The plugin will
5346 register a write callback named C<mqtt/I<name>> where I<name> is the string
5347 argument given to the B<Publish> block. Both types of blocks share many but not
5348 all of the following options. If an option is valid in only one of the blocks,
5349 it will be mentioned explicitly.
5350
5351 B<Options:>
5352
5353 =over 4
5354
5355 =item B<Host> I<Hostname>
5356
5357 Hostname of the MQTT broker to connect to.
5358
5359 =item B<Port> I<Service>
5360
5361 Port number or service name of the MQTT broker to connect to.
5362
5363 =item B<User> I<UserName>
5364
5365 Username used when authenticating to the MQTT broker.
5366
5367 =item B<Password> I<Password>
5368
5369 Password used when authenticating to the MQTT broker.
5370
5371 =item B<ClientId> I<ClientId>
5372
5373 MQTT client ID to use. Defaults to the hostname used by I<collectd>.
5374
5375 =item B<QoS> [B<0>-B<2>]
5376
5377 Sets the I<Quality of Service>, with the values C<0>, C<1> and C<2> meaning:
5378
5379 =over 4
5380
5381 =item B<0>
5382
5383 At most once
5384
5385 =item B<1>
5386
5387 At least once
5388
5389 =item B<2>
5390
5391 Exactly once
5392
5393 =back
5394
5395 In B<Publish> blocks, this option determines the QoS flag set on outgoing
5396 messages and defaults to B<0>. In B<Subscribe> blocks, determines the maximum
5397 QoS setting the client is going to accept and defaults to B<2>. If the QoS flag
5398 on a message is larger than the maximum accepted QoS of a subscriber, the
5399 message's QoS will be downgraded.
5400
5401 =item B<Prefix> I<Prefix> (Publish only)
5402
5403 This plugin will use one topic per I<value list> which will looks like a path.
5404 I<Prefix> is used as the first path element and defaults to B<collectd>.
5405
5406 An example topic name would be:
5407
5408 collectd/cpu-0/cpu-user
5409
5410 =item B<Retain> B<false>|B<true> (Publish only)
5411
5412 Controls whether the MQTT broker will retain (keep a copy of) the last message
5413 sent to each topic and deliver it to new subscribers. Defaults to B<false>.
5414
5415 =item B<StoreRates> B<true>|B<false> (Publish only)
5416
5417 Controls whether C<DERIVE> and C<COUNTER> metrics are converted to a I<rate>
5418 before sending. Defaults to B<true>.
5419
5420 =item B<CleanSession> B<true>|B<false> (Subscribe only)
5421
5422 Controls whether the MQTT "cleans" the session up after the subscriber
5423 disconnects or if it maintains the subscriber's subscriptions and all messages
5424 that arrive while the subscriber is disconnected. Defaults to B<true>.
5425
5426 =item B<Topic> I<TopicName> (Subscribe only)
5427
5428 Configures the topic(s) to subscribe to. You can use the single level C<+> and
5429 multi level C<#> wildcards. Defaults to B<collectd/#>, i.e. all topics beneath
5430 the B<collectd> branch.
5431
5432 =item B<CACert> I<file>
5433
5434 Path to the PEM-encoded CA certificate file. Setting this option enables TLS
5435 communication with the MQTT broker, and as such, B<Port> should be the TLS-enabled
5436 port of the MQTT broker.
5437 This option enables the use of TLS.
5438
5439 =item B<CertificateFile> I<file>
5440
5441 Path to the PEM-encoded certificate file to use as client certificate when
5442 connecting to the MQTT broker.
5443 Only valid if B<CACert> and B<CertificateKeyFile> are also set.
5444
5445 =item B<CertificateKeyFile> I<file>
5446
5447 Path to the unencrypted PEM-encoded key file corresponding to B<CertificateFile>.
5448 Only valid if B<CACert> and B<CertificateFile> are also set.
5449
5450 =item B<TLSProtocol> I<protocol>
5451
5452 If configured, this specifies the string protocol version (e.g. C<tlsv1>,
5453 C<tlsv1.2>) to use for the TLS connection to the broker. If not set a default
5454 version is used which depends on the version of OpenSSL the Mosquitto library
5455 was linked against.
5456 Only valid if B<CACert> is set.
5457
5458 =item B<CipherSuite> I<ciphersuite>
5459
5460 A string describing the ciphers available for use. See L<ciphers(1)> and the
5461 C<openssl ciphers> utility for more information. If unset, the default ciphers
5462 will be used.
5463 Only valid if B<CACert> is set.
5464
5465 =back
5466
5467 =head2 Plugin C<mysql>
5468
5469 The C<mysql plugin> requires B<mysqlclient> to be installed. It connects to
5470 one or more databases when started and keeps the connection up as long as
5471 possible. When the connection is interrupted for whatever reason it will try
5472 to re-connect. The plugin will complain loudly in case anything goes wrong.
5473
5474 This plugin issues the MySQL C<SHOW STATUS> / C<SHOW GLOBAL STATUS> command
5475 and collects information about MySQL network traffic, executed statements,
5476 requests, the query cache and threads by evaluating the
5477 C<Bytes_{received,sent}>, C<Com_*>, C<Handler_*>, C<Qcache_*> and C<Threads_*>
5478 return values. Please refer to the B<MySQL reference manual>, I<5.1.6. Server
5479 Status Variables> for an explanation of these values.
5480
5481 Optionally, master and slave statistics may be collected in a MySQL
5482 replication setup. In that case, information about the synchronization state
5483 of the nodes are collected by evaluating the C<Position> return value of the
5484 C<SHOW MASTER STATUS> command and the C<Seconds_Behind_Master>,
5485 C<Read_Master_Log_Pos> and C<Exec_Master_Log_Pos> return values of the
5486 C<SHOW SLAVE STATUS> command. See the B<MySQL reference manual>,
5487 I<12.5.5.21 SHOW MASTER STATUS Syntax> and
5488 I<12.5.5.31 SHOW SLAVE STATUS Syntax> for details.
5489
5490 Synopsis:
5491
5492 <Plugin mysql>
5493 <Database foo>
5494 Host "hostname"
5495 User "username"
5496 Password "password"
5497 Port "3306"
5498 MasterStats true
5499 ConnectTimeout 10
5500 SSLKey "/path/to/key.pem"
5501 SSLCert "/path/to/cert.pem"
5502 SSLCA "/path/to/ca.pem"
5503 SSLCAPath "/path/to/cas/"
5504 SSLCipher "DHE-RSA-AES256-SHA"
5505 </Database>
5506
5507 <Database bar>
5508 Alias "squeeze"
5509 Host "localhost"
5510 Socket "/var/run/mysql/mysqld.sock"
5511 SlaveStats true
5512 SlaveNotifications true
5513 </Database>
5514
5515 <Database galera>
5516 Alias "galera"
5517 Host "localhost"
5518 Socket "/var/run/mysql/mysqld.sock"
5519 WsrepStats true
5520 </Database>
5521 </Plugin>
5522
5523 A B<Database> block defines one connection to a MySQL database. It accepts a
5524 single argument which specifies the name of the database. None of the other
5525 options are required. MySQL will use default values as documented in the
5526 "mysql_real_connect()" and "mysql_ssl_set()" sections in the
5527 B<MySQL reference manual>.
5528
5529 =over 4
5530
5531 =item B<Alias> I<Alias>
5532
5533 Alias to use as sender instead of hostname when reporting. This may be useful
5534 when having cryptic hostnames.
5535
5536 =item B<Host> I<Hostname>
5537
5538 Hostname of the database server. Defaults to B<localhost>.
5539
5540 =item B<User> I<Username>
5541
5542 Username to use when connecting to the database. The user does not have to be
5543 granted any privileges (which is synonym to granting the C<USAGE> privilege),
5544 unless you want to collect replication statistics (see B<MasterStats> and
5545 B<SlaveStats> below). In this case, the user needs the C<REPLICATION CLIENT>
5546 (or C<SUPER>) privileges. Else, any existing MySQL user will do.
5547
5548 =item B<Password> I<Password>
5549
5550 Password needed to log into the database.
5551
5552 =item B<Database> I<Database>
5553
5554 Select this database. Defaults to I<no database> which is a perfectly reasonable
5555 option for what this plugin does.
5556
5557 =item B<Port> I<Port>
5558
5559 TCP-port to connect to. The port must be specified in its numeric form, but it
5560 must be passed as a string nonetheless. For example:
5561
5562 Port "3306"
5563
5564 If B<Host> is set to B<localhost> (the default), this setting has no effect.
5565 See the documentation for the C<mysql_real_connect> function for details.
5566
5567 =item B<Socket> I<Socket>
5568
5569 Specifies the path to the UNIX domain socket of the MySQL server. This option
5570 only has any effect, if B<Host> is set to B<localhost> (the default).
5571 Otherwise, use the B<Port> option above. See the documentation for the
5572 C<mysql_real_connect> function for details.
5573
5574 =item B<InnodbStats> I<true|false>
5575
5576 If enabled, metrics about the InnoDB storage engine are collected.
5577 Disabled by default.
5578
5579 =item B<MasterStats> I<true|false>
5580
5581 =item B<SlaveStats> I<true|false>
5582
5583 Enable the collection of master / slave statistics in a replication setup. In
5584 order to be able to get access to these statistics, the user needs special
5585 privileges. See the B<User> documentation above. Defaults to B<false>.
5586
5587 =item B<SlaveNotifications> I<true|false>
5588
5589 If enabled, the plugin sends a notification if the replication slave I/O and /
5590 or SQL threads are not running. Defaults to B<false>.
5591
5592 =item B<WsrepStats> I<true|false>
5593
5594 Enable the collection of wsrep plugin statistics, used in Master-Master
5595 replication setups like in MySQL Galera/Percona XtraDB Cluster.
5596 User needs only privileges to execute 'SHOW GLOBAL STATUS'.
5597 Defaults to B<false>.
5598
5599 =item B<ConnectTimeout> I<Seconds>
5600
5601 Sets the connect timeout for the MySQL client.
5602
5603 =item B<SSLKey> I<Path>
5604
5605 If provided, the X509 key in PEM format.
5606
5607 =item B<SSLCert> I<Path>
5608
5609 If provided, the X509 cert in PEM format.
5610
5611 =item B<SSLCA> I<Path>
5612
5613 If provided, the CA file in PEM format (check OpenSSL docs).
5614
5615 =item B<SSLCAPath> I<Path>
5616
5617 If provided, the CA directory (check OpenSSL docs).
5618
5619 =item B<SSLCipher> I<String>
5620
5621 If provided, the SSL cipher to use.
5622
5623 =back
5624
5625 =head2 Plugin C<netapp>
5626
5627 The netapp plugin can collect various performance and capacity information
5628 from a NetApp filer using the NetApp API.
5629
5630 Please note that NetApp has a wide line of products and a lot of different
5631 software versions for each of these products. This plugin was developed for a
5632 NetApp FAS3040 running OnTap 7.2.3P8 and tested on FAS2050 7.3.1.1L1,
5633 FAS3140 7.2.5.1 and FAS3020 7.2.4P9. It I<should> work for most combinations of
5634 model and software version but it is very hard to test this.
5635 If you have used this plugin with other models and/or software version, feel
5636 free to send us a mail to tell us about the results, even if it's just a short
5637 "It works".
5638
5639 To collect these data collectd will log in to the NetApp via HTTP(S) and HTTP
5640 basic authentication.
5641
5642 B<Do not use a regular user for this!> Create a special collectd user with just
5643 the minimum of capabilities needed. The user only needs the "login-http-admin"
5644 capability as well as a few more depending on which data will be collected.
5645 Required capabilities are documented below.
5646
5647 =head3 Synopsis
5648
5649 <Plugin "netapp">
5650 <Host "netapp1.example.com">
5651 Protocol "https"
5652 Address "10.0.0.1"
5653 Port 443
5654 User "username"
5655 Password "aef4Aebe"
5656 Interval 30
5657
5658 <WAFL>
5659 Interval 30
5660 GetNameCache true
5661 GetDirCache true
5662 GetBufferCache true
5663 GetInodeCache true
5664 </WAFL>
5665
5666 <Disks>
5667 Interval 30
5668 GetBusy true
5669 </Disks>
5670
5671 <VolumePerf>
5672 Interval 30
5673 GetIO "volume0"
5674 IgnoreSelectedIO false
5675 GetOps "volume0"
5676 IgnoreSelectedOps false
5677 GetLatency "volume0"
5678 IgnoreSelectedLatency false
5679 </VolumePerf>
5680
5681 <VolumeUsage>
5682 Interval 30
5683 GetCapacity "vol0"
5684 GetCapacity "vol1"
5685 IgnoreSelectedCapacity false
5686 GetSnapshot "vol1"
5687 GetSnapshot "vol3"
5688 IgnoreSelectedSnapshot false
5689 </VolumeUsage>
5690
5691 <Quota>
5692 Interval 60
5693 </Quota>
5694
5695 <Snapvault>
5696 Interval 30
5697 </Snapvault>
5698
5699 <System>
5700 Interval 30
5701 GetCPULoad true
5702 GetInterfaces true
5703 GetDiskOps true
5704 GetDiskIO true
5705 </System>
5706
5707 <VFiler vfilerA>
5708 Interval 60
5709
5710 SnapVault true
5711 # ...
5712 </VFiler>
5713 </Host>
5714 </Plugin>
5715
5716 The netapp plugin accepts the following configuration options:
5717
5718 =over 4
5719
5720 =item B<Host> I<Name>
5721
5722 A host block defines one NetApp filer. It will appear in collectd with the name
5723 you specify here which does not have to be its real name nor its hostname (see
5724 the B<Address> option below).
5725
5726 =item B<VFiler> I<Name>
5727
5728 A B<VFiler> block may only be used inside a host block. It accepts all the
5729 same options as the B<Host> block (except for cascaded B<VFiler> blocks) and
5730 will execute all NetApp API commands in the context of the specified
5731 VFiler(R). It will appear in collectd with the name you specify here which
5732 does not have to be its real name. The VFiler name may be specified using the
5733 B<VFilerName> option. If this is not specified, it will default to the name
5734 you specify here.
5735
5736 The VFiler block inherits all connection related settings from the surrounding
5737 B<Host> block (which appear before the B<VFiler> block) but they may be
5738 overwritten inside the B<VFiler> block.
5739
5740 This feature is useful, for example, when using a VFiler as SnapVault target
5741 (supported since OnTap 8.1). In that case, the SnapVault statistics are not
5742 available in the host filer (vfiler0) but only in the respective VFiler
5743 context.
5744
5745 =item B<Protocol> B<httpd>|B<http>
5746
5747 The protocol collectd will use to query this host.
5748
5749 Optional
5750
5751 Type: string
5752
5753 Default: https
5754
5755 Valid options: http, https
5756
5757 =item B<Address> I<Address>
5758
5759 The hostname or IP address of the host.
5760
5761 Optional
5762
5763 Type: string
5764
5765 Default: The "host" block's name.
5766
5767 =item B<Port> I<Port>
5768
5769 The TCP port to connect to on the host.
5770
5771 Optional
5772
5773 Type: integer
5774
5775 Default: 80 for protocol "http", 443 for protocol "https"
5776
5777 =item B<User> I<User>
5778
5779 =item B<Password> I<Password>
5780
5781 The username and password to use to login to the NetApp.
5782
5783 Mandatory
5784
5785 Type: string
5786
5787 =item B<VFilerName> I<Name>
5788
5789 The name of the VFiler in which context to execute API commands. If not
5790 specified, the name provided to the B<VFiler> block will be used instead.
5791
5792 Optional
5793
5794 Type: string
5795
5796 Default: name of the B<VFiler> block
5797
5798 B<Note:> This option may only be used inside B<VFiler> blocks.
5799
5800 =item B<Interval> I<Interval>
5801
5802 B<TODO>
5803
5804 =back
5805
5806 The following options decide what kind of data will be collected. You can
5807 either use them as a block and fine tune various parameters inside this block,
5808 use them as a single statement to just accept all default values, or omit it to
5809 not collect any data.
5810
5811 The following options are valid inside all blocks:
5812
5813 =over 4
5814
5815 =item B<Interval> I<Seconds>
5816
5817 Collect the respective statistics every I<Seconds> seconds. Defaults to the
5818 host specific setting.
5819
5820 =back
5821
5822 =head3 The System block
5823
5824 This will collect various performance data about the whole system.
5825
5826 B<Note:> To get this data the collectd user needs the
5827 "api-perf-object-get-instances" capability.
5828
5829 =over 4
5830
5831 =item B<Interval> I<Seconds>
5832
5833 Collect disk statistics every I<Seconds> seconds.
5834
5835 =item B<GetCPULoad> B<true>|B<false>
5836
5837 If you set this option to true the current CPU usage will be read. This will be
5838 the average usage between all CPUs in your NetApp without any information about
5839 individual CPUs.
5840
5841 B<Note:> These are the same values that the NetApp CLI command "sysstat"
5842 returns in the "CPU" field.
5843
5844 Optional
5845
5846 Type: boolean
5847
5848 Default: true
5849
5850 Result: Two value lists of type "cpu", and type instances "idle" and "system".
5851
5852 =item B<GetInterfaces> B<true>|B<false>
5853
5854 If you set this option to true the current traffic of the network interfaces
5855 will be read. This will be the total traffic over all interfaces of your NetApp
5856 without any information about individual interfaces.
5857
5858 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
5859 in the "Net kB/s" field.
5860
5861 B<Or is it?>
5862
5863 Optional
5864
5865 Type: boolean
5866
5867 Default: true
5868
5869 Result: One value list of type "if_octects".
5870
5871 =item B<GetDiskIO> B<true>|B<false>
5872
5873 If you set this option to true the current IO throughput will be read. This
5874 will be the total IO of your NetApp without any information about individual
5875 disks, volumes or aggregates.
5876
5877 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
5878 in the "DiskE<nbsp>kB/s" field.
5879
5880 Optional
5881
5882 Type: boolean
5883
5884 Default: true
5885
5886 Result: One value list of type "disk_octets".
5887
5888 =item B<GetDiskOps> B<true>|B<false>
5889
5890 If you set this option to true the current number of HTTP, NFS, CIFS, FCP,
5891 iSCSI, etc. operations will be read. This will be the total number of
5892 operations on your NetApp without any information about individual volumes or
5893 aggregates.
5894
5895 B<Note:> These are the same values that the NetApp CLI command "sysstat"
5896 returns in the "NFS", "CIFS", "HTTP", "FCP" and "iSCSI" fields.
5897
5898 Optional
5899
5900 Type: boolean
5901
5902 Default: true
5903
5904 Result: A variable number of value lists of type "disk_ops_complex". Each type
5905 of operation will result in one value list with the name of the operation as
5906 type instance.
5907
5908 =back
5909
5910 =head3 The WAFL block
5911
5912 This will collect various performance data about the WAFL file system. At the
5913 moment this just means cache performance.
5914
5915 B<Note:> To get this data the collectd user needs the
5916 "api-perf-object-get-instances" capability.
5917
5918 B<Note:> The interface to get these values is classified as "Diagnostics" by
5919 NetApp. This means that it is not guaranteed to be stable even between minor
5920 releases.
5921
5922 =over 4
5923
5924 =item B<Interval> I<Seconds>
5925
5926 Collect disk statistics every I<Seconds> seconds.
5927
5928 =item B<GetNameCache> B<true>|B<false>
5929
5930 Optional
5931
5932 Type: boolean
5933
5934 Default: true
5935
5936 Result: One value list of type "cache_ratio" and type instance
5937 "name_cache_hit".
5938
5939 =item B<GetDirCache> B<true>|B<false>
5940
5941 Optional
5942
5943 Type: boolean
5944
5945 Default: true
5946
5947 Result: One value list of type "cache_ratio" and type instance "find_dir_hit".
5948
5949 =item B<GetInodeCache> B<true>|B<false>
5950
5951 Optional
5952
5953 Type: boolean
5954
5955 Default: true
5956
5957 Result: One value list of type "cache_ratio" and type instance
5958 "inode_cache_hit".
5959
5960 =item B<GetBufferCache> B<true>|B<false>
5961
5962 B<Note:> This is the same value that the NetApp CLI command "sysstat" returns
5963 in the "Cache hit" field.
5964
5965 Optional
5966
5967 Type: boolean
5968
5969 Default: true
5970
5971 Result: One value list of type "cache_ratio" and type instance "buf_hash_hit".
5972
5973 =back
5974
5975 =head3 The Disks block
5976
5977 This will collect performance data about the individual disks in the NetApp.
5978
5979 B<Note:> To get this data the collectd user needs the
5980 "api-perf-object-get-instances" capability.
5981
5982 =over 4
5983
5984 =item B<Interval> I<Seconds>
5985
5986 Collect disk statistics every I<Seconds> seconds.
5987
5988 =item B<GetBusy> B<true>|B<false>
5989
5990 If you set this option to true the busy time of all disks will be calculated
5991 and the value of the busiest disk in the system will be written.
5992
5993 B<Note:> This is the same values that the NetApp CLI command "sysstat" returns
5994 in the "Disk util" field. Probably.
5995
5996 Optional
5997
5998 Type: boolean
5999
6000 Default: true
6001
6002 Result: One value list of type "percent" and type instance "disk_busy".
6003
6004 =back
6005
6006 =head3 The VolumePerf block
6007
6008 This will collect various performance data about the individual volumes.
6009
6010 You can select which data to collect about which volume using the following
6011 options. They follow the standard ignorelist semantic.
6012
6013 B<Note:> To get this data the collectd user needs the
6014 I<api-perf-object-get-instances> capability.
6015
6016 =over 4
6017
6018 =item B<Interval> I<Seconds>
6019
6020 Collect volume performance data every I<Seconds> seconds.
6021
6022 =item B<GetIO> I<Volume>
6023
6024 =item B<GetOps> I<Volume>
6025
6026 =item B<GetLatency> I<Volume>
6027
6028 Select the given volume for IO, operations or latency statistics collection.
6029 The argument is the name of the volume without the C</vol/> prefix.
6030
6031 Since the standard ignorelist functionality is used here, you can use a string
6032 starting and ending with a slash to specify regular expression matching: To
6033 match the volumes "vol0", "vol2" and "vol7", you can use this regular
6034 expression:
6035
6036 GetIO "/^vol[027]$/"
6037
6038 If no regular expression is specified, an exact match is required. Both,
6039 regular and exact matching are case sensitive.
6040
6041 If no volume was specified at all for either of the three options, that data
6042 will be collected for all available volumes.
6043
6044 See F</"IGNORELISTS"> for details.
6045
6046 =item B<IgnoreSelectedIO> B<true>|B<false>
6047
6048 =item B<IgnoreSelectedOps> B<true>|B<false>
6049
6050 =item B<IgnoreSelectedLatency> B<true>|B<false>
6051
6052 When set to B<true>, the volumes selected for IO, operations or latency
6053 statistics collection will be ignored and the data will be collected for all
6054 other volumes.
6055
6056 When set to B<false>, data will only be collected for the specified volumes and
6057 all other volumes will be ignored.
6058
6059 If no volumes have been specified with the above B<Get*> options, all volumes
6060 will be collected regardless of the B<IgnoreSelected*> option.
6061
6062 Defaults to B<false>
6063
6064 =back
6065
6066 =head3 The VolumeUsage block
6067
6068 This will collect capacity data about the individual volumes.
6069
6070 B<Note:> To get this data the collectd user needs the I<api-volume-list-info>
6071 capability.
6072
6073 =over 4
6074
6075 =item B<Interval> I<Seconds>
6076
6077 Collect volume usage statistics every I<Seconds> seconds.
6078
6079 =item B<GetCapacity> I<VolumeName>
6080
6081 The current capacity of the volume will be collected. This will result in two
6082 to four value lists, depending on the configuration of the volume. All data
6083 sources are of type "df_complex" with the name of the volume as
6084 plugin_instance.
6085
6086 There will be type_instances "used" and "free" for the number of used and
6087 available bytes on the volume. If the volume has some space reserved for
6088 snapshots, a type_instance "snap_reserved" will be available. If the volume
6089 has SIS enabled, a type_instance "sis_saved" will be available. This is the
6090 number of bytes saved by the SIS feature.
6091
6092 B<Note:> The current NetApp API has a bug that results in this value being
6093 reported as a 32E<nbsp>bit number. This plugin tries to guess the correct
6094 number which works most of the time. If you see strange values here, bug
6095 NetApp support to fix this.
6096
6097 Repeat this option to specify multiple volumes.
6098
6099 =item B<IgnoreSelectedCapacity> B<true>|B<false>
6100
6101 Specify whether to collect only the volumes selected by the B<GetCapacity>
6102 option or to ignore those volumes. B<IgnoreSelectedCapacity> defaults to
6103 B<false>. However, if no B<GetCapacity> option is specified at all, all
6104 capacities will be selected anyway.
6105
6106 =item B<GetSnapshot> I<VolumeName>
6107
6108 Select volumes from which to collect snapshot information.
6109
6110 Usually, the space used for snapshots is included in the space reported as
6111 "used". If snapshot information is collected as well, the space used for
6112 snapshots is subtracted from the used space.
6113
6114 To make things even more interesting, it is possible to reserve space to be
6115 used for snapshots. If the space required for snapshots is less than that
6116 reserved space, there is "reserved free" and "reserved used" space in addition
6117 to "free" and "used". If the space required for snapshots exceeds the reserved
6118 space, that part allocated in the normal space is subtracted from the "used"
6119 space again.
6120
6121 Repeat this option to specify multiple volumes.
6122
6123 =item B<IgnoreSelectedSnapshot>
6124
6125 Specify whether to collect only the volumes selected by the B<GetSnapshot>
6126 option or to ignore those volumes. B<IgnoreSelectedSnapshot> defaults to
6127 B<false>. However, if no B<GetSnapshot> option is specified at all, all
6128 capacities will be selected anyway.
6129
6130 =back
6131
6132 =head3 The Quota block
6133
6134 This will collect (tree) quota statistics (used disk space and number of used
6135 files). This mechanism is useful to get usage information for single qtrees.
6136 In case the quotas are not used for any other purpose, an entry similar to the
6137 following in C</etc/quotas> would be sufficient:
6138
6139 /vol/volA/some_qtree tree - - - - -
6140
6141 After adding the entry, issue C<quota on -w volA> on the NetApp filer.
6142
6143 =over 4
6144
6145 =item B<Interval> I<Seconds>
6146
6147 Collect SnapVault(R) statistics every I<Seconds> seconds.
6148
6149 =back
6150
6151 =head3 The SnapVault block
6152
6153 This will collect statistics about the time and traffic of SnapVault(R)
6154 transfers.
6155
6156 =over 4
6157
6158 =item B<Interval> I<Seconds>
6159
6160 Collect SnapVault(R) statistics every I<Seconds> seconds.
6161
6162 =back
6163
6164 =head2 Plugin C<netlink>
6165
6166 The C<netlink> plugin uses a netlink socket to query the Linux kernel about
6167 statistics of various interface and routing aspects.
6168
6169 =over 4
6170
6171 =item B<Interface> I<Interface>
6172
6173 =item B<VerboseInterface> I<Interface>
6174
6175 Instruct the plugin to collect interface statistics. This is basically the same
6176 as the statistics provided by the C<interface> plugin (see above) but
6177 potentially much more detailed.
6178
6179 When configuring with B<Interface> only the basic statistics will be collected,
6180 namely octets, packets, and errors. These statistics are collected by
6181 the C<interface> plugin, too, so using both at the same time is no benefit.
6182
6183 When configured with B<VerboseInterface> all counters B<except> the basic ones
6184 will be collected, so that no data needs to be collected twice if you use the
6185 C<interface> plugin.
6186 This includes dropped packets, received multicast packets, collisions and a
6187 whole zoo of differentiated RX and TX errors. You can try the following command
6188 to get an idea of what awaits you:
6189
6190 ip -s -s link list
6191
6192 If I<Interface> is B<All>, all interfaces will be selected.
6193
6194 It is possible to use regular expressions to match interface names, if the
6195 name is surrounded by I</.../> and collectd was compiled with support for
6196 regexps. This is useful if there's a need to collect (or ignore) data
6197 for a group of interfaces that are similarly named, without the need to
6198 explicitly list all of them (especially useful if the list is dynamic).
6199 Examples:
6200
6201 Interface "/^eth/"
6202 Interface "/^ens[1-4]$|^enp[0-3]$/"
6203 VerboseInterface "/^eno[0-9]+/"
6204
6205 This will match all interfaces with names starting with I<eth>, all interfaces
6206 in range I<ens1 - ens4> and I<enp0 - enp3>, and for verbose metrics all
6207 interfaces with names starting with I<eno> followed by at least one digit.
6208
6209 =item B<QDisc> I<Interface> [I<QDisc>]
6210
6211 =item B<Class> I<Interface> [I<Class>]
6212
6213 =item B<Filter> I<Interface> [I<Filter>]
6214
6215 Collect the octets and packets that pass a certain qdisc, class or filter.
6216
6217 QDiscs and classes are identified by their type and handle (or classid).
6218 Filters don't necessarily have a handle, therefore the parent's handle is used.
6219 The notation used in collectd differs from that used in tc(1) in that it
6220 doesn't skip the major or minor number if it's zero and doesn't print special
6221 ids by their name. So, for example, a qdisc may be identified by
6222 C<pfifo_fast-1:0> even though the minor number of B<all> qdiscs is zero and
6223 thus not displayed by tc(1).
6224
6225 If B<QDisc>, B<Class>, or B<Filter> is given without the second argument,
6226 i.E<nbsp>.e. without an identifier, all qdiscs, classes, or filters that are
6227 associated with that interface will be collected.
6228
6229 Since a filter itself doesn't necessarily have a handle, the parent's handle is
6230 used. This may lead to problems when more than one filter is attached to a
6231 qdisc or class. This isn't nice, but we don't know how this could be done any
6232 better. If you have a idea, please don't hesitate to tell us.
6233
6234 As with the B<Interface> option you can specify B<All> as the interface,
6235 meaning all interfaces.
6236
6237 Here are some examples to help you understand the above text more easily:
6238
6239 <Plugin netlink>
6240 VerboseInterface "All"
6241 QDisc "eth0" "pfifo_fast-1:0"
6242 QDisc "ppp0"
6243 Class "ppp0" "htb-1:10"
6244 Filter "ppp0" "u32-1:0"
6245 </Plugin>
6246
6247 See F</"IGNORELISTS"> for details.
6248
6249 =item B<IgnoreSelected>
6250
6251 The behavior is the same as with all other similar plugins: If nothing is
6252 selected at all, everything is collected. If some things are selected using the
6253 options described above, only these statistics are collected. If you set
6254 B<IgnoreSelected> to B<true>, this behavior is inverted, i.E<nbsp>e. the
6255 specified statistics will not be collected.
6256
6257 =item B<CollectVFStats> B<true|false>
6258
6259 Allow plugin to collect VF's statistics if there are Virtual Functions
6260 available for interfaces specified in B<Interface> or B<VerboseInterface>.
6261 All available stats are collected no matter if parent interface is set
6262 by B<Interface> or B<VerboseInterface>.
6263
6264 =back
6265
6266 =head2 Plugin C<network>
6267
6268 The Network plugin sends data to a remote instance of collectd, receives data
6269 from a remote instance, or both at the same time. Data which has been received
6270 from the network is usually not transmitted again, but this can be activated, see
6271 the B<Forward> option below.
6272
6273 The default IPv6 multicast group is C<ff18::efc0:4a42>. The default IPv4
6274 multicast group is C<239.192.74.66>. The default I<UDP> port is B<25826>.
6275
6276 Both, B<Server> and B<Listen> can be used as single option or as block. When
6277 used as block, given options are valid for this socket only. The following
6278 example will export the metrics twice: Once to an "internal" server (without
6279 encryption and signing) and one to an external server (with cryptographic
6280 signature):
6281
6282 <Plugin "network">
6283 # Export to an internal server
6284 # (demonstrates usage without additional options)
6285 Server "collectd.internal.tld"
6286
6287 # Export to an external server
6288 # (demonstrates usage with signature options)
6289 <Server "collectd.external.tld">
6290 SecurityLevel "sign"
6291 Username "myhostname"
6292 Password "ohl0eQue"
6293 </Server>
6294 </Plugin>
6295
6296 =over 4
6297
6298 =item B<E<lt>Server> I<Host> [I<Port>]B<E<gt>>
6299
6300 The B<Server> statement/block sets the server to send datagrams to. The
6301 statement may occur multiple times to send each datagram to multiple
6302 destinations.
6303
6304 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. The
6305 optional second argument specifies a port number or a service name. If not
6306 given, the default, B<25826>, is used.
6307
6308 The following options are recognized within B<Server> blocks:
6309
6310 =over 4
6311
6312 =item B<SecurityLevel> B<Encrypt>|B<Sign>|B<None>
6313
6314 Set the security you require for network communication. When the security level
6315 has been set to B<Encrypt>, data sent over the network will be encrypted using
6316 I<AES-256>. The integrity of encrypted packets is ensured using I<SHA-1>. When
6317 set to B<Sign>, transmitted data is signed using the I<HMAC-SHA-256> message
6318 authentication code. When set to B<None>, data is sent without any security.
6319
6320 This feature is only available if the I<network> plugin was linked with
6321 I<libgcrypt>.
6322
6323 =item B<Username> I<Username>
6324
6325 Sets the username to transmit. This is used by the server to lookup the
6326 password. See B<AuthFile> below. All security levels except B<None> require
6327 this setting.
6328
6329 This feature is only available if the I<network> plugin was linked with
6330 I<libgcrypt>.
6331
6332 =item B<Password> I<Password>
6333
6334 Sets a password (shared secret) for this socket. All security levels except
6335 B<None> require this setting.
6336
6337 This feature is only available if the I<network> plugin was linked with
6338 I<libgcrypt>.
6339
6340 =item B<Interface> I<Interface name>
6341
6342 Set the outgoing interface for IP packets. This applies at least
6343 to IPv6 packets and if possible to IPv4. If this option is not applicable,
6344 undefined or a non-existent interface name is specified, the default
6345 behavior is to let the kernel choose the appropriate interface. Be warned
6346 that the manual selection of an interface for unicast traffic is only
6347 necessary in rare cases.
6348
6349 =item B<BindAddress> I<IP Address>
6350
6351 Set the outgoing IP address for IP packets. This option can be used instead of
6352 the I<Interface> option to explicitly define the IP address which will be used
6353 to send Packets to the remote server.
6354
6355 =item B<ResolveInterval> I<Seconds>
6356
6357 Sets the interval at which to re-resolve the DNS for the I<Host>. This is
6358 useful to force a regular DNS lookup to support a high availability setup. If
6359 not specified, re-resolves are never attempted.
6360
6361 =back
6362
6363 =item B<E<lt>Listen> I<Host> [I<Port>]B<E<gt>>
6364
6365 The B<Listen> statement sets the interfaces to bind to. When multiple
6366 statements are found the daemon will bind to multiple interfaces.
6367
6368 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. If
6369 the argument is a multicast address the daemon will join that multicast group.
6370 The optional second argument specifies a port number or a service name. If not
6371 given, the default, B<25826>, is used.
6372
6373 The following options are recognized within C<E<lt>ListenE<gt>> blocks:
6374
6375 =over 4
6376
6377 =item B<SecurityLevel> B<Encrypt>|B<Sign>|B<None>
6378
6379 Set the security you require for network communication. When the security level
6380 has been set to B<Encrypt>, only encrypted data will be accepted. The integrity
6381 of encrypted packets is ensured using I<SHA-1>. When set to B<Sign>, only
6382 signed and encrypted data is accepted. When set to B<None>, all data will be
6383 accepted. If an B<AuthFile> option was given (see below), encrypted data is
6384 decrypted if possible.
6385
6386 This feature is only available if the I<network> plugin was linked with
6387 I<libgcrypt>.
6388
6389 =item B<AuthFile> I<Filename>
6390
6391 Sets a file in which usernames are mapped to passwords. These passwords are
6392 used to verify signatures and to decrypt encrypted network packets. If
6393 B<SecurityLevel> is set to B<None>, this is optional. If given, signed data is
6394 verified and encrypted packets are decrypted. Otherwise, signed data is
6395 accepted without checking the signature and encrypted data cannot be decrypted.
6396 For the other security levels this option is mandatory.
6397
6398 The file format is very simple: Each line consists of a username followed by a
6399 colon and any number of spaces followed by the password. To demonstrate, an
6400 example file could look like this:
6401
6402 user0: foo
6403 user1: bar
6404
6405 Each time a packet is received, the modification time of the file is checked
6406 using L<stat(2)>. If the file has been changed, the contents is re-read. While
6407 the file is being read, it is locked using L<fcntl(2)>.
6408
6409 =item B<Interface> I<Interface name>
6410
6411 Set the incoming interface for IP packets explicitly. This applies at least
6412 to IPv6 packets and if possible to IPv4. If this option is not applicable,
6413 undefined or a non-existent interface name is specified, the default
6414 behavior is, to let the kernel choose the appropriate interface. Thus incoming
6415 traffic gets only accepted, if it arrives on the given interface.
6416
6417 =back
6418
6419 =item B<TimeToLive> I<1-255>
6420
6421 Set the time-to-live of sent packets. This applies to all, unicast and
6422 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
6423 That means that multicast packets will be sent with a TTL of C<1> (one) on most
6424 operating systems.
6425
6426 =item B<MaxPacketSize> I<1024-65535>
6427
6428 Set the maximum size for datagrams received over the network. Packets larger
6429 than this will be truncated. Defaults to 1452E<nbsp>bytes, which is the maximum
6430 payload size that can be transmitted in one Ethernet frame using IPv6E<nbsp>/
6431 UDP.
6432
6433 On the server side, this limit should be set to the largest value used on
6434 I<any> client. Likewise, the value on the client must not be larger than the
6435 value on the server, or data will be lost.
6436
6437 B<Compatibility:> Versions prior to I<versionE<nbsp>4.8> used a fixed sized
6438 buffer of 1024E<nbsp>bytes. Versions I<4.8>, I<4.9> and I<4.10> used a default
6439 value of 1024E<nbsp>bytes to avoid problems when sending data to an older
6440 server.
6441
6442 =item B<Forward> I<true|false>
6443
6444 If set to I<true>, write packets that were received via the network plugin to
6445 the sending sockets. This should only be activated when the B<Listen>- and
6446 B<Server>-statements differ. Otherwise packets may be send multiple times to
6447 the same multicast group. While this results in more network traffic than
6448 necessary it's not a huge problem since the plugin has a duplicate detection,
6449 so the values will not loop.
6450
6451 =item B<ReportStats> B<true>|B<false>
6452
6453 The network plugin cannot only receive and send statistics, it can also create
6454 statistics about itself. Collectd data included the number of received and
6455 sent octets and packets, the length of the receive queue and the number of
6456 values handled. When set to B<true>, the I<Network plugin> will make these
6457 statistics available. Defaults to B<false>.
6458
6459 =back
6460
6461 =head2 Plugin C<nfs>
6462
6463 The I<nfs plugin> collects information about the usage of the Network File
6464 System (NFS). It counts the number of procedure calls for each procedure,
6465 grouped by version and whether the system runs as server or client.
6466
6467 It is possibly to omit metrics for a specific NFS version by setting one or
6468 more of the following options to B<false> (all of them default to B<true>).
6469
6470 =over 4
6471
6472 =item B<ReportV2> B<true>|B<false>
6473
6474 =item B<ReportV3> B<true>|B<false>
6475
6476 =item B<ReportV4> B<true>|B<false>
6477
6478 =back
6479
6480 =head2 Plugin C<nginx>
6481
6482 This plugin collects the number of connections and requests handled by the
6483 C<nginx daemon> (speak: engineE<nbsp>X), a HTTP and mail server/proxy. It
6484 queries the page provided by the C<ngx_http_stub_status_module> module, which
6485 isn't compiled by default. Please refer to
6486 L<http://wiki.codemongers.com/NginxStubStatusModule> for more information on
6487 how to compile and configure nginx and this module.
6488
6489 The following options are accepted by the C<nginx plugin>:
6490
6491 =over 4
6492
6493 =item B<URL> I<http://host/nginx_status>
6494
6495 Sets the URL of the C<ngx_http_stub_status_module> output.
6496
6497 =item B<User> I<Username>
6498
6499 Optional user name needed for authentication.
6500
6501 =item B<Password> I<Password>
6502
6503 Optional password needed for authentication.
6504
6505 =item B<VerifyPeer> B<true|false>
6506
6507 Enable or disable peer SSL certificate verification. See
6508 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
6509
6510 =item B<VerifyHost> B<true|false>
6511
6512 Enable or disable peer host name verification. If enabled, the plugin checks
6513 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
6514 certificate matches the host name provided by the B<URL> option. If this
6515 identity check fails, the connection is aborted. Obviously, only works when
6516 connecting to a SSL enabled server. Enabled by default.
6517
6518 =item B<CACert> I<File>
6519
6520 File that holds one or more SSL certificates. If you want to use HTTPS you will
6521 possibly need this option. What CA certificates come bundled with C<libcurl>
6522 and are checked by default depends on the distribution you use.
6523
6524 =item B<Timeout> I<Milliseconds>
6525
6526 The B<Timeout> option sets the overall timeout for HTTP requests to B<URL>, in
6527 milliseconds. By default, the configured B<Interval> is used to set the
6528 timeout.
6529
6530 =back
6531
6532 =head2 Plugin C<notify_desktop>
6533
6534 This plugin sends a desktop notification to a notification daemon, as defined
6535 in the Desktop Notification Specification. To actually display the
6536 notifications, B<notification-daemon> is required and B<collectd> has to be
6537 able to access the X server (i.E<nbsp>e., the C<DISPLAY> and C<XAUTHORITY>
6538 environment variables have to be set correctly) and the D-Bus message bus.
6539
6540 The Desktop Notification Specification can be found at
6541 L<http://www.galago-project.org/specs/notification/>.
6542
6543 =over 4
6544
6545 =item B<OkayTimeout> I<timeout>
6546
6547 =item B<WarningTimeout> I<timeout>
6548
6549 =item B<FailureTimeout> I<timeout>
6550
6551 Set the I<timeout>, in milliseconds, after which to expire the notification
6552 for C<OKAY>, C<WARNING> and C<FAILURE> severities respectively. If zero has
6553 been specified, the displayed notification will not be closed at all - the
6554 user has to do so herself. These options default to 5000. If a negative number
6555 has been specified, the default is used as well.
6556
6557 =back
6558
6559 =head2 Plugin C<notify_email>
6560
6561 The I<notify_email> plugin uses the I<ESMTP> library to send notifications to a
6562 configured email address.
6563
6564 I<libESMTP> is available from L<http://www.stafford.uklinux.net/libesmtp/>.
6565
6566 Available configuration options:
6567
6568 =over 4
6569
6570 =item B<From> I<Address>
6571
6572 Email address from which the emails should appear to come from.
6573
6574 Default: C<root@localhost>
6575
6576 =item B<Recipient> I<Address>
6577
6578 Configures the email address(es) to which the notifications should be mailed.
6579 May be repeated to send notifications to multiple addresses.
6580
6581 At least one B<Recipient> must be present for the plugin to work correctly.
6582
6583 =item B<SMTPServer> I<Hostname>
6584
6585 Hostname of the SMTP server to connect to.
6586
6587 Default: C<localhost>
6588
6589 =item B<SMTPPort> I<Port>
6590
6591 TCP port to connect to.
6592
6593 Default: C<25>
6594
6595 =item B<SMTPUser> I<Username>
6596
6597 Username for ASMTP authentication. Optional.
6598
6599 =item B<SMTPPassword> I<Password>
6600
6601 Password for ASMTP authentication. Optional.
6602
6603 =item B<Subject> I<Subject>
6604
6605 Subject-template to use when sending emails. There must be exactly two
6606 string-placeholders in the subject, given in the standard I<printf(3)> syntax,
6607 i.E<nbsp>e. C<%s>. The first will be replaced with the severity, the second
6608 with the hostname.
6609
6610 Default: C<Collectd notify: %s@%s>
6611
6612 =back
6613
6614 =head2 Plugin C<notify_nagios>
6615
6616 The I<notify_nagios> plugin writes notifications to Nagios' I<command file> as
6617 a I<passive service check result>.
6618
6619 Available configuration options:
6620
6621 =over 4
6622
6623 =item B<CommandFile> I<Path>
6624
6625 Sets the I<command file> to write to. Defaults to F</usr/local/nagios/var/rw/nagios.cmd>.
6626
6627 =back
6628
6629 =head2 Plugin C<ntpd>
6630
6631 The C<ntpd> plugin collects per-peer ntp data such as time offset and time
6632 dispersion.
6633
6634 For talking to B<ntpd>, it mimics what the B<ntpdc> control program does on
6635 the wire - using B<mode 7> specific requests. This mode is deprecated with
6636 newer B<ntpd> releases (4.2.7p230 and later). For the C<ntpd> plugin to work
6637 correctly with them, the ntp daemon must be explicitly configured to
6638 enable B<mode 7> (which is disabled by default). Refer to the I<ntp.conf(5)>
6639 manual page for details.
6640
6641 Available configuration options for the C<ntpd> plugin:
6642
6643 =over 4
6644
6645 =item B<Host> I<Hostname>
6646
6647 Hostname of the host running B<ntpd>. Defaults to B<localhost>.
6648
6649 =item B<Port> I<Port>
6650
6651 UDP-Port to connect to. Defaults to B<123>.
6652
6653 =item B<ReverseLookups> B<true>|B<false>
6654
6655 Sets whether or not to perform reverse lookups on peers. Since the name or
6656 IP-address may be used in a filename it is recommended to disable reverse
6657 lookups. The default is to do reverse lookups to preserve backwards
6658 compatibility, though.
6659
6660 =item B<IncludeUnitID> B<true>|B<false>
6661
6662 When a peer is a refclock, include the unit ID in the I<type instance>.
6663 Defaults to B<false> for backward compatibility.
6664
6665 If two refclock peers use the same driver and this is B<false>, the plugin will
6666 try to write simultaneous measurements from both to the same type instance.
6667 This will result in error messages in the log and only one set of measurements
6668 making it through.
6669
6670 =back
6671
6672 =head2 Plugin C<nut>
6673
6674 =over 4
6675
6676 =item B<UPS> I<upsname>B<@>I<hostname>[B<:>I<port>]
6677
6678 Add a UPS to collect data from. The format is identical to the one accepted by
6679 L<upsc(8)>.
6680
6681 =item B<ForceSSL> B<true>|B<false>
6682
6683 Stops connections from falling back to unsecured if an SSL connection
6684 cannot be established. Defaults to false if undeclared.
6685
6686 =item B<VerifyPeer> I<true>|I<false>
6687
6688 If set to true, requires a CAPath be provided. Will use the CAPath to find
6689 certificates to use as Trusted Certificates to validate a upsd server certificate.
6690 If validation of the upsd server certificate fails, the connection will not be
6691 established. If ForceSSL is undeclared or set to false, setting VerifyPeer to true
6692 will override and set ForceSSL to true.
6693
6694 =item B<CAPath> I/path/to/certs/folder
6695
6696 If VerifyPeer is set to true, this is required. Otherwise this is ignored.
6697 The folder pointed at must contain certificate(s) named according to their hash.
6698 Ex: XXXXXXXX.Y where X is the hash value of a cert and Y is 0. If name collisions
6699 occur because two different certs have the same hash value, Y can be incremented
6700 in order to avoid conflict. To create a symbolic link to a certificate the following
6701 command can be used from within the directory where the cert resides:
6702
6703 C<ln -s some.crt ./$(openssl x509 -hash -noout -in some.crt).0>
6704
6705 Alternatively, the package openssl-perl provides a command C<c_rehash> that will
6706 generate links like the one described above for ALL certs in a given folder.
6707 Example usage:
6708 C<c_rehash /path/to/certs/folder>
6709
6710 =item B<ConnectTimeout> I<Milliseconds>
6711
6712 The B<ConnectTimeout> option sets the connect timeout, in milliseconds.
6713 By default, the configured B<Interval> is used to set the timeout.
6714
6715 =back
6716
6717 =head2 Plugin C<olsrd>
6718
6719 The I<olsrd> plugin connects to the TCP port opened by the I<txtinfo> plugin of
6720 the Optimized Link State Routing daemon and reads information about the current
6721 state of the meshed network.
6722
6723 The following configuration options are understood:
6724
6725 =over 4
6726
6727 =item B<Host> I<Host>
6728
6729 Connect to I<Host>. Defaults to B<"localhost">.
6730
6731 =item B<Port> I<Port>
6732
6733 Specifies the port to connect to. This must be a string, even if you give the
6734 port as a number rather than a service name. Defaults to B<"2006">.
6735
6736 =item B<CollectLinks> B<No>|B<Summary>|B<Detail>
6737
6738 Specifies what information to collect about links, i.E<nbsp>e. direct
6739 connections of the daemon queried. If set to B<No>, no information is
6740 collected. If set to B<Summary>, the number of links and the average of all
6741 I<link quality> (LQ) and I<neighbor link quality> (NLQ) values is calculated.
6742 If set to B<Detail> LQ and NLQ are collected per link.
6743
6744 Defaults to B<Detail>.
6745
6746 =item B<CollectRoutes> B<No>|B<Summary>|B<Detail>
6747
6748 Specifies what information to collect about routes of the daemon queried. If
6749 set to B<No>, no information is collected. If set to B<Summary>, the number of
6750 routes and the average I<metric> and I<ETX> is calculated. If set to B<Detail>
6751 metric and ETX are collected per route.
6752
6753 Defaults to B<Summary>.
6754
6755 =item B<CollectTopology> B<No>|B<Summary>|B<Detail>
6756
6757 Specifies what information to collect about the global topology. If set to
6758 B<No>, no information is collected. If set to B<Summary>, the number of links
6759 in the entire topology and the average I<link quality> (LQ) is calculated.
6760 If set to B<Detail> LQ and NLQ are collected for each link in the entire topology.
6761
6762 Defaults to B<Summary>.
6763
6764 =back
6765
6766 =head2 Plugin C<onewire>
6767
6768 B<EXPERIMENTAL!> See notes below.
6769
6770 The C<onewire> plugin uses the B<owcapi> library from the B<owfs> project
6771 L<http://owfs.org/> to read sensors connected via the onewire bus.
6772
6773 It can be used in two possible modes - standard or advanced.
6774
6775 In the standard mode only temperature sensors (sensors with the family code
6776 C<10>, C<22> and C<28> - e.g. DS1820, DS18S20, DS1920) can be read. If you have
6777 other sensors you would like to have included, please send a sort request to
6778 the mailing list. You can select sensors to be read or to be ignored depending
6779 on the option B<IgnoreSelected>). When no list is provided the whole bus is
6780 walked and all sensors are read.
6781
6782 Hubs (the DS2409 chips) are working, but read the note, why this plugin is
6783 experimental, below.
6784
6785 In the advanced mode you can configure any sensor to be read (only numerical
6786 value) using full OWFS path (e.g. "/uncached/10.F10FCA000800/temperature").
6787 In this mode you have to list all the sensors. Neither default bus walk nor
6788 B<IgnoreSelected> are used here. Address and type (file) is extracted from
6789 the path automatically and should produce compatible structure with the "standard"
6790 mode (basically the path is expected as for example
6791 "/uncached/10.F10FCA000800/temperature" where it would extract address part
6792 "F10FCA000800" and the rest after the slash is considered the type - here
6793 "temperature").
6794 There are two advantages to this mode - you can access virtually any sensor
6795 (not just temperature), select whether to use cached or directly read values
6796 and it is slighlty faster. The downside is more complex configuration.
6797
6798 The two modes are distinguished automatically by the format of the address.
6799 It is not possible to mix the two modes. Once a full path is detected in any
6800 B<Sensor> then the whole addressing (all sensors) is considered to be this way
6801 (and as standard addresses will fail parsing they will be ignored).
6802
6803 =over 4
6804
6805 =item B<Device> I<Device>
6806
6807 Sets the device to read the values from. This can either be a "real" hardware
6808 device, such as a serial port or an USB port, or the address of the
6809 L<owserver(1)> socket, usually B<localhost:4304>.
6810
6811 Though the documentation claims to automatically recognize the given address
6812 format, with versionE<nbsp>2.7p4 we had to specify the type explicitly. So
6813 with that version, the following configuration worked for us:
6814
6815 <Plugin onewire>
6816 Device "-s localhost:4304"
6817 </Plugin>
6818
6819 This directive is B<required> and does not have a default value.
6820
6821 =item B<Sensor> I<Sensor>
6822
6823 In the standard mode selects sensors to collect or to ignore
6824 (depending on B<IgnoreSelected>, see below). Sensors are specified without
6825 the family byte at the beginning, so you have to use for example C<F10FCA000800>,
6826 and B<not> include the leading C<10.> family byte and point.
6827 When no B<Sensor> is configured the whole Onewire bus is walked and all supported
6828 sensors (see above) are read.
6829
6830 In the advanced mode the B<Sensor> specifies full OWFS path - e.g.
6831 C</uncached/10.F10FCA000800/temperature> (or when cached values are OK
6832 C</10.F10FCA000800/temperature>). B<IgnoreSelected> is not used.
6833
6834 As there can be multiple devices on the bus you can list multiple sensor (use
6835 multiple B<Sensor> elements).
6836
6837 See F</"IGNORELISTS"> for details.
6838
6839 =item B<IgnoreSelected> I<true>|I<false>
6840
6841 If no configuration is given, the B<onewire> plugin will collect data from all
6842 sensors found. This may not be practical, especially if sensors are added and
6843 removed regularly. Sometimes, however, it's easier/preferred to collect only
6844 specific sensors or all sensors I<except> a few specified ones. This option
6845 enables you to do that: By setting B<IgnoreSelected> to I<true> the effect of
6846 B<Sensor> is inverted: All selected interfaces are ignored and all other
6847 interfaces are collected.
6848
6849 Used only in the standard mode - see above.
6850
6851 =item B<Interval> I<Seconds>
6852
6853 Sets the interval in which all sensors should be read. If not specified, the
6854 global B<Interval> setting is used.
6855
6856 =back
6857
6858 B<EXPERIMENTAL!> The C<onewire> plugin is experimental, because it doesn't yet
6859 work with big setups. It works with one sensor being attached to one
6860 controller, but as soon as you throw in a couple more senors and maybe a hub
6861 or two, reading all values will take more than ten seconds (the default
6862 interval). We will probably add some separate thread for reading the sensors
6863 and some cache or something like that, but it's not done yet. We will try to
6864 maintain backwards compatibility in the future, but we can't promise. So in
6865 short: If it works for you: Great! But keep in mind that the config I<might>
6866 change, though this is unlikely. Oh, and if you want to help improving this
6867 plugin, just send a short notice to the mailing list. ThanksE<nbsp>:)
6868
6869 =head2 Plugin C<openldap>
6870
6871 To use the C<openldap> plugin you first need to configure the I<OpenLDAP>
6872 server correctly. The backend database C<monitor> needs to be loaded and
6873 working. See slapd-monitor(5) for the details.
6874
6875 The configuration of the C<openldap> plugin consists of one or more B<Instance>
6876 blocks. Each block requires one string argument as the instance name. For
6877 example:
6878
6879 <Plugin "openldap">
6880 <Instance "foo">
6881 URL "ldap://localhost/"
6882 </Instance>
6883 <Instance "bar">
6884 URL "ldaps://localhost/"
6885 </Instance>
6886 </Plugin>
6887
6888 The instance name will be used as the I<plugin instance>. To emulate the old
6889 (versionE<nbsp>4) behavior, you can use an empty string (""). In order for the
6890 plugin to work correctly, each instance name must be unique. This is not
6891 enforced by the plugin and it is your responsibility to ensure it is.
6892
6893 The following options are accepted within each B<Instance> block:
6894
6895 =over 4
6896
6897 =item B<URL> I<ldap://host/binddn>
6898
6899 Sets the URL to use to connect to the I<OpenLDAP> server. This option is
6900 I<mandatory>.
6901
6902 =item B<BindDN> I<BindDN>
6903
6904 Name in the form of an LDAP distinguished name intended to be used for
6905 authentication. Defaults to empty string to establish an anonymous authorization.
6906
6907 =item B<Password> I<Password>
6908
6909 Password for simple bind authentication. If this option is not set,
6910 unauthenticated bind operation is used.
6911
6912 =item B<StartTLS> B<true|false>
6913
6914 Defines whether TLS must be used when connecting to the I<OpenLDAP> server.
6915 Disabled by default.
6916
6917 =item B<VerifyHost> B<true|false>
6918
6919 Enables or disables peer host name verification. If enabled, the plugin checks
6920 if the C<Common Name> or a C<Subject Alternate Name> field of the SSL
6921 certificate matches the host name provided by the B<URL> option. If this
6922 identity check fails, the connection is aborted. Enabled by default.
6923
6924 =item B<CACert> I<File>
6925
6926 File that holds one or more SSL certificates. If you want to use TLS/SSL you
6927 may possibly need this option. What CA certificates are checked by default
6928 depends on the distribution you use and can be changed with the usual ldap
6929 client configuration mechanisms. See ldap.conf(5) for the details.
6930
6931 =item B<Timeout> I<Seconds>
6932
6933 Sets the timeout value for ldap operations, in seconds. By default, the
6934 configured B<Interval> is used to set the timeout. Use B<-1> to disable
6935 (infinite timeout).
6936
6937 =item B<Version> I<Version>
6938
6939 An integer which sets the LDAP protocol version number to use when connecting
6940 to the I<OpenLDAP> server. Defaults to B<3> for using I<LDAPv3>.
6941
6942 =back
6943
6944 =head2 Plugin C<openvpn>
6945
6946 The OpenVPN plugin reads a status file maintained by OpenVPN and gathers
6947 traffic statistics about connected clients.
6948
6949 To set up OpenVPN to write to the status file periodically, use the
6950 B<--status> option of OpenVPN.
6951
6952 So, in a nutshell you need:
6953
6954 openvpn $OTHER_OPTIONS \
6955 --status "/var/run/openvpn-status" 10
6956
6957 Available options:
6958
6959 =over 4
6960
6961 =item B<StatusFile> I<File>
6962
6963 Specifies the location of the status file.
6964
6965 =item B<ImprovedNamingSchema> B<true>|B<false>
6966
6967 When enabled, the filename of the status file will be used as plugin instance
6968 and the client's "common name" will be used as type instance. This is required
6969 when reading multiple status files. Enabling this option is recommended, but to
6970 maintain backwards compatibility this option is disabled by default.
6971
6972 =item B<CollectCompression> B<true>|B<false>
6973
6974 Sets whether or not statistics about the compression used by OpenVPN should be
6975 collected. This information is only available in I<single> mode. Enabled by
6976 default.
6977
6978 =item B<CollectIndividualUsers> B<true>|B<false>
6979
6980 Sets whether or not traffic information is collected for each connected client
6981 individually. If set to false, currently no traffic data is collected at all
6982 because aggregating this data in a save manner is tricky. Defaults to B<true>.
6983
6984 =item B<CollectUserCount> B<true>|B<false>
6985
6986 When enabled, the number of currently connected clients or users is collected.
6987 This is especially interesting when B<CollectIndividualUsers> is disabled, but
6988 can be configured independently from that option. Defaults to B<false>.
6989
6990 =back
6991
6992 =head2 Plugin C<oracle>
6993
6994 The "oracle" plugin uses the Oracle® Call Interface I<(OCI)> to connect to an
6995 Oracle® Database and lets you execute SQL statements there. It is very similar
6996 to the "dbi" plugin, because it was written around the same time. See the "dbi"
6997 plugin's documentation above for details.
6998
6999 <Plugin oracle>
7000 <Query "out_of_stock">
7001 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
7002 <Result>
7003 Type "gauge"
7004 # InstancePrefix "foo"
7005 InstancesFrom "category"
7006 ValuesFrom "value"
7007 </Result>
7008 </Query>
7009 <Database "product_information">
7010 #Plugin "warehouse"
7011 ConnectID "db01"
7012 Username "oracle"
7013 Password "secret"
7014 Query "out_of_stock"
7015 </Database>
7016 </Plugin>
7017
7018 =head3 B<Query> blocks
7019
7020 The Query blocks are handled identically to the Query blocks of the "dbi"
7021 plugin. Please see its documentation above for details on how to specify
7022 queries.
7023
7024 =head3 B<Database> blocks
7025
7026 Database blocks define a connection to a database and which queries should be
7027 sent to that database. Each database needs a "name" as string argument in the
7028 starting tag of the block. This name will be used as "PluginInstance" in the
7029 values submitted to the daemon. Other than that, that name is not used.
7030
7031 =over 4
7032
7033 =item B<Plugin> I<Plugin>
7034
7035 Use I<Plugin> as the plugin name when submitting query results from
7036 this B<Database>. Defaults to C<oracle>.
7037
7038 =item B<ConnectID> I<ID>
7039
7040 Defines the "database alias" or "service name" to connect to. Usually, these
7041 names are defined in the file named C<$ORACLE_HOME/network/admin/tnsnames.ora>.
7042
7043 =item B<Host> I<Host>
7044
7045 Hostname to use when dispatching values for this database. Defaults to using
7046 the global hostname of the I<collectd> instance.
7047
7048 =item B<Username> I<Username>
7049
7050 Username used for authentication.
7051
7052 =item B<Password> I<Password>
7053
7054 Password used for authentication.
7055
7056 =item B<Query> I<QueryName>
7057
7058 Associates the query named I<QueryName> with this database connection. The
7059 query needs to be defined I<before> this statement, i.E<nbsp>e. all query
7060 blocks you want to refer to must be placed above the database block you want to
7061 refer to them from.
7062
7063 =back
7064
7065 =head2 Plugin C<ovs_events>
7066
7067 The I<ovs_events> plugin monitors the link status of I<Open vSwitch> (OVS)
7068 connected interfaces, dispatches the values to collectd and sends the
7069 notification whenever the link state change occurs. This plugin uses OVS
7070 database to get a link state change notification.
7071
7072 B<Synopsis:>
7073
7074 <Plugin "ovs_events">
7075 Port 6640
7076 Address "127.0.0.1"
7077 Socket "/var/run/openvswitch/db.sock"
7078 Interfaces "br0" "veth0"
7079 SendNotification true
7080 DispatchValues false
7081 </Plugin>
7082
7083 The plugin provides the following configuration options:
7084
7085 =over 4
7086
7087 =item B<Address> I<node>
7088
7089 The address of the OVS DB server JSON-RPC interface used by the plugin. To
7090 enable the interface, OVS DB daemon should be running with C<--remote=ptcp:>
7091 option. See L<ovsdb-server(1)> for more details. The option may be either
7092 network hostname, IPv4 numbers-and-dots notation or IPv6 hexadecimal string
7093 format. Defaults to C<localhost>.
7094
7095 =item B<Port> I<service>
7096
7097 TCP-port to connect to. Either a service name or a port number may be given.
7098 Defaults to B<6640>.
7099
7100 =item B<Socket> I<path>
7101
7102 The UNIX domain socket path of OVS DB server JSON-RPC interface used by the
7103 plugin. To enable the interface, the OVS DB daemon should be running with
7104 C<--remote=punix:> option. See L<ovsdb-server(1)> for more details. If this
7105 option is set, B<Address> and B<Port> options are ignored.
7106
7107 =item B<Interfaces> [I<ifname> ...]
7108
7109 List of interface names to be monitored by this plugin. If this option is not
7110 specified or is empty then all OVS connected interfaces on all bridges are
7111 monitored.
7112
7113 Default: empty (all interfaces on all bridges are monitored)
7114
7115 =item B<SendNotification> I<true|false>
7116
7117 If set to true, OVS link notifications (interface status and OVS DB connection
7118 terminate) are sent to collectd. Default value is true.
7119
7120 =item B<DispatchValues> I<true|false>
7121
7122 Dispatch the OVS DB interface link status value with configured plugin interval.
7123 Defaults to false. Please note, if B<SendNotification> and B<DispatchValues>
7124 options are false, no OVS information will be provided by the plugin.
7125
7126 =back
7127
7128 B<Note:> By default, the global interval setting is used within which to
7129 retrieve the OVS link status. To configure a plugin-specific interval, please
7130 use B<Interval> option of the OVS B<LoadPlugin> block settings. For milliseconds
7131 simple divide the time by 1000 for example if the desired interval is 50ms, set
7132 interval to 0.05.
7133
7134 =head2 Plugin C<ovs_stats>
7135
7136 The I<ovs_stats> plugin collects statistics of OVS connected interfaces.
7137 This plugin uses OVSDB management protocol (RFC7047) monitor mechanism to get
7138 statistics from OVSDB
7139
7140 B<Synopsis:>
7141
7142 <Plugin "ovs_stats">
7143 Port 6640
7144 Address "127.0.0.1"
7145 Socket "/var/run/openvswitch/db.sock"
7146 Bridges "br0" "br_ext"
7147 InterfaceStats false
7148 </Plugin>
7149
7150 The plugin provides the following configuration options:
7151
7152 =over 4
7153
7154 =item B<Address> I<node>
7155
7156 The address of the OVS DB server JSON-RPC interface used by the plugin. To
7157 enable the interface, OVS DB daemon should be running with C<--remote=ptcp:>
7158 option. See L<ovsdb-server(1)> for more details. The option may be either
7159 network hostname, IPv4 numbers-and-dots notation or IPv6 hexadecimal string
7160 format. Defaults to C<localhost>.
7161
7162 =item B<Port> I<service>
7163
7164 TCP-port to connect to. Either a service name or a port number may be given.
7165 Defaults to B<6640>.
7166
7167 =item B<Socket> I<path>
7168
7169 The UNIX domain socket path of OVS DB server JSON-RPC interface used by the
7170 plugin. To enable the interface, the OVS DB daemon should be running with
7171 C<--remote=punix:> option. See L<ovsdb-server(1)> for more details. If this
7172 option is set, B<Address> and B<Port> options are ignored.
7173
7174 =item B<Bridges> [I<brname> ...]
7175
7176 List of OVS bridge names to be monitored by this plugin. If this option is
7177 omitted or is empty then all OVS bridges will be monitored.
7178
7179 Default: empty (monitor all bridges)
7180
7181 =item B<InterfaceStats> B<false>|B<true>
7182
7183 Indicates that the plugin should gather statistics for individual interfaces
7184 in addition to ports. This can be useful when monitoring an OVS setup with
7185 bond ports, where you might wish to know individual statistics for the
7186 interfaces included in the bonds. Defaults to B<false>.
7187
7188 =back
7189
7190 =head2 Plugin C<pcie_errors>
7191
7192 The I<pcie_errors> plugin collects PCI Express errors from Device Status in Capability
7193 structure and from Advanced Error Reporting Extended Capability where available.
7194 At every read it polls config space of PCI Express devices and dispatches
7195 notification for every error that is set. It checks for new errors at every read.
7196 The device is indicated in plugin_instance according to format "domain:bus:dev.fn".
7197 Errors are divided into categories indicated by type_instance: "correctable", and
7198 for uncorrectable errors "non_fatal" or "fatal".
7199 Fatal errors are reported as I<NOTIF_FAILURE> and all others as I<NOTIF_WARNING>.
7200
7201 B<Synopsis:>
7202
7203 <Plugin "pcie_errors">
7204 Source "sysfs"
7205 AccessDir "/sys/bus/pci"
7206 ReportMasked false
7207 PersistentNotifications false
7208 </Plugin>
7209
7210 B<Options:>
7211
7212 =over 4
7213
7214 =item B<Source> B<sysfs>|B<proc>
7215
7216 Use B<sysfs> or B<proc> to read data from /sysfs or /proc.
7217 The default value is B<sysfs>.
7218
7219 =item B<AccessDir> I<dir>
7220
7221 Directory used to access device config space. It is optional and defaults to
7222 /sys/bus/pci for B<sysfs> and to /proc/bus/pci for B<proc>.
7223
7224 =item B<ReportMasked> B<false>|B<true>
7225
7226 If true plugin will notify about errors that are set to masked in Error Mask register.
7227 Such errors are not reported to the PCI Express Root Complex. Defaults to B<false>.
7228
7229 =item B<PersistentNotifications> B<false>|B<true>
7230
7231 If false plugin will dispatch notification only on set/clear of error.
7232 The ones already reported will be ignored. Defaults to B<false>.
7233
7234 =back
7235
7236 =head2 Plugin C<perl>
7237
7238 This plugin embeds a Perl-interpreter into collectd and provides an interface
7239 to collectd's plugin system. See L<collectd-perl(5)> for its documentation.
7240
7241 =head2 Plugin C<pinba>
7242
7243 The I<Pinba plugin> receives profiling information from I<Pinba>, an extension
7244 for the I<PHP> interpreter. At the end of executing a script, i.e. after a
7245 PHP-based webpage has been delivered, the extension will send a UDP packet
7246 containing timing information, peak memory usage and so on. The plugin will
7247 wait for such packets, parse them and account the provided information, which
7248 is then dispatched to the daemon once per interval.
7249
7250 Synopsis:
7251
7252 <Plugin pinba>
7253 Address "::0"
7254 Port "30002"
7255 # Overall statistics for the website.
7256 <View "www-total">
7257 Server "www.example.com"
7258 </View>
7259 # Statistics for www-a only
7260 <View "www-a">
7261 Host "www-a.example.com"
7262 Server "www.example.com"
7263 </View>
7264 # Statistics for www-b only
7265 <View "www-b">
7266 Host "www-b.example.com"
7267 Server "www.example.com"
7268 </View>
7269 </Plugin>
7270
7271 The plugin provides the following configuration options:
7272
7273 =over 4
7274
7275 =item B<Address> I<Node>
7276
7277 Configures the address used to open a listening socket. By default, plugin will
7278 bind to the I<any> address C<::0>.
7279
7280 =item B<Port> I<Service>
7281
7282 Configures the port (service) to bind to. By default the default Pinba port
7283 "30002" will be used. The option accepts service names in addition to port
7284 numbers and thus requires a I<string> argument.
7285
7286 =item E<lt>B<View> I<Name>E<gt> block
7287
7288 The packets sent by the Pinba extension include the hostname of the server, the
7289 server name (the name of the virtual host) and the script that was executed.
7290 Using B<View> blocks it is possible to separate the data into multiple groups
7291 to get more meaningful statistics. Each packet is added to all matching groups,
7292 so that a packet may be accounted for more than once.
7293
7294 =over 4
7295
7296 =item B<Host> I<Host>
7297
7298 Matches the hostname of the system the webserver / script is running on. This
7299 will contain the result of the L<gethostname(2)> system call. If not
7300 configured, all hostnames will be accepted.
7301
7302 =item B<Server> I<Server>
7303
7304 Matches the name of the I<virtual host>, i.e. the contents of the
7305 C<$_SERVER["SERVER_NAME"]> variable when within PHP. If not configured, all
7306 server names will be accepted.
7307
7308 =item B<Script> I<Script>
7309
7310 Matches the name of the I<script name>, i.e. the contents of the
7311 C<$_SERVER["SCRIPT_NAME"]> variable when within PHP. If not configured, all
7312 script names will be accepted.
7313
7314 =back
7315
7316 =back
7317
7318 =head2 Plugin C<ping>
7319
7320 The I<Ping> plugin starts a new thread which sends ICMP "ping" packets to the
7321 configured hosts periodically and measures the network latency. Whenever the
7322 C<read> function of the plugin is called, it submits the average latency, the
7323 standard deviation and the drop rate for each host.
7324
7325 Available configuration options:
7326
7327 =over 4
7328
7329 =item B<Host> I<IP-address>
7330
7331 Host to ping periodically. This option may be repeated several times to ping
7332 multiple hosts.
7333
7334 =item B<Interval> I<Seconds>
7335
7336 Sets the interval in which to send ICMP echo packets to the configured hosts.
7337 This is B<not> the interval in which metrics are read from the plugin but the
7338 interval in which the hosts are "pinged". Therefore, the setting here should be
7339 smaller than or equal to the global B<Interval> setting. Fractional times, such
7340 as "1.24" are allowed.
7341
7342 Default: B<1.0>
7343
7344 =item B<Timeout> I<Seconds>
7345
7346 Time to wait for a response from the host to which an ICMP packet had been
7347 sent. If a reply was not received after I<Seconds> seconds, the host is assumed
7348 to be down or the packet to be dropped. This setting must be smaller than the
7349 B<Interval> setting above for the plugin to work correctly. Fractional
7350 arguments are accepted.
7351
7352 Default: B<0.9>
7353
7354 =item B<TTL> I<0-255>
7355
7356 Sets the Time-To-Live of generated ICMP packets.
7357
7358 =item B<Size> I<size>
7359
7360 Sets the size of the data payload in ICMP packet to specified I<size> (it
7361 will be filled with regular ASCII pattern). If not set, default 56 byte
7362 long string is used so that the packet size of an ICMPv4 packet is exactly
7363 64 bytes, similar to the behaviour of normal ping(1) command.
7364
7365 =item B<SourceAddress> I<host>
7366
7367 Sets the source address to use. I<host> may either be a numerical network
7368 address or a network hostname.
7369
7370 =item B<AddressFamily> I<af>
7371
7372 Sets the address family to use. I<af> may be "any", "ipv4" or "ipv6". This
7373 option will be ignored if you set a B<SourceAddress>.
7374
7375 =item B<Device> I<name>
7376
7377 Sets the outgoing network device to be used. I<name> has to specify an
7378 interface name (e.E<nbsp>g. C<eth0>). This might not be supported by all
7379 operating systems.
7380
7381 =item B<MaxMissed> I<Packets>
7382
7383 Trigger a DNS resolve after the host has not replied to I<Packets> packets. This
7384 enables the use of dynamic DNS services (like dyndns.org) with the ping plugin.
7385
7386 Default: B<-1> (disabled)
7387
7388 =back
7389
7390 =head2 Plugin C<postgresql>
7391
7392 The C<postgresql> plugin queries statistics from PostgreSQL databases. It
7393 keeps a persistent connection to all configured databases and tries to
7394 reconnect if the connection has been interrupted. A database is configured by
7395 specifying a B<Database> block as described below. The default statistics are
7396 collected from PostgreSQL's B<statistics collector> which thus has to be
7397 enabled for this plugin to work correctly. This should usually be the case by
7398 default. See the section "The Statistics Collector" of the B<PostgreSQL
7399 Documentation> for details.
7400
7401 By specifying custom database queries using a B<Query> block as described
7402 below, you may collect any data that is available from some PostgreSQL
7403 database. This way, you are able to access statistics of external daemons
7404 which are available in a PostgreSQL database or use future or special
7405 statistics provided by PostgreSQL without the need to upgrade your collectd
7406 installation.
7407
7408 Starting with version 5.2, the C<postgresql> plugin supports writing data to
7409 PostgreSQL databases as well. This has been implemented in a generic way. You
7410 need to specify an SQL statement which will then be executed by collectd in
7411 order to write the data (see below for details). The benefit of that approach
7412 is that there is no fixed database layout. Rather, the layout may be optimized
7413 for the current setup.
7414
7415 The B<PostgreSQL Documentation> manual can be found at
7416 L<http://www.postgresql.org/docs/manuals/>.
7417
7418 <Plugin postgresql>
7419 <Query magic>
7420 Statement "SELECT magic FROM wizard WHERE host = $1;"
7421 Param hostname
7422 <Result>
7423 Type gauge
7424 InstancePrefix "magic"
7425 ValuesFrom magic
7426 </Result>
7427 </Query>
7428
7429 <Query rt36_tickets>
7430 Statement "SELECT COUNT(type) AS count, type \
7431 FROM (SELECT CASE \
7432 WHEN resolved = 'epoch' THEN 'open' \
7433 ELSE 'resolved' END AS type \
7434 FROM tickets) type \
7435 GROUP BY type;"
7436 <Result>
7437 Type counter
7438 InstancePrefix "rt36_tickets"
7439 InstancesFrom "type"
7440 ValuesFrom "count"
7441 </Result>
7442 </Query>
7443
7444 <Writer sqlstore>
7445 Statement "SELECT collectd_insert($1, $2, $3, $4, $5, $6, $7, $8, $9);"
7446 StoreRates true
7447 </Writer>
7448
7449 <Database foo>
7450 Plugin "kingdom"
7451 Host "hostname"
7452 Port "5432"
7453 User "username"
7454 Password "secret"
7455 SSLMode "prefer"
7456 KRBSrvName "kerberos_service_name"
7457 Query magic
7458 </Database>
7459
7460 <Database bar>
7461 Interval 300
7462 Service "service_name"
7463 Query backends # predefined
7464 Query rt36_tickets
7465 </Database>
7466
7467 <Database qux>
7468 # ...
7469 Writer sqlstore
7470 CommitInterval 10
7471 </Database>
7472 </Plugin>
7473
7474 The B<Query> block defines one database query which may later be used by a
7475 database definition. It accepts a single mandatory argument which specifies
7476 the name of the query. The names of all queries have to be unique (see the
7477 B<MinVersion> and B<MaxVersion> options below for an exception to this
7478 rule).
7479
7480 In each B<Query> block, there is one or more B<Result> blocks. Multiple
7481 B<Result> blocks may be used to extract multiple values from a single query.
7482
7483 The following configuration options are available to define the query:
7484
7485 =over 4
7486
7487 =item B<Statement> I<sql query statement>
7488
7489 Specify the I<sql query statement> which the plugin should execute. The string
7490 may contain the tokens B<$1>, B<$2>, etc. which are used to reference the
7491 first, second, etc. parameter. The value of the parameters is specified by the
7492 B<Param> configuration option - see below for details. To include a literal
7493 B<$> character followed by a number, surround it with single quotes (B<'>).
7494
7495 Any SQL command which may return data (such as C<SELECT> or C<SHOW>) is
7496 allowed. Note, however, that only a single command may be used. Semicolons are
7497 allowed as long as a single non-empty command has been specified only.
7498
7499 The returned lines will be handled separately one after another.
7500
7501 =item B<Param> I<hostname>|I<database>|I<instance>|I<username>|I<interval>
7502
7503 Specify the parameters which should be passed to the SQL query. The parameters
7504 are referred to in the SQL query as B<$1>, B<$2>, etc. in the same order as
7505 they appear in the configuration file. The value of the parameter is
7506 determined depending on the value of the B<Param> option as follows:
7507
7508 =over 4
7509
7510 =item I<hostname>
7511
7512 The configured hostname of the database connection. If a UNIX domain socket is
7513 used, the parameter expands to "localhost".
7514
7515 =item I<database>
7516
7517 The name of the database of the current connection.
7518
7519 =item I<instance>
7520
7521 The name of the database plugin instance. See the B<Instance> option of the
7522 database specification below for details.
7523
7524 =item I<username>
7525
7526 The username used to connect to the database.
7527
7528 =item I<interval>
7529
7530 The interval with which this database is queried (as specified by the database
7531 specific or global B<Interval> options).
7532
7533 =back
7534
7535 Please note that parameters are only supported by PostgreSQL's protocol
7536 version 3 and above which was introduced in version 7.4 of PostgreSQL.
7537
7538 =item B<PluginInstanceFrom> I<column>
7539
7540 Specify how to create the "PluginInstance" for reporting this query results.
7541 Only one column is supported. You may concatenate fields and string values in
7542 the query statement to get the required results.
7543
7544 =item B<MinVersion> I<version>
7545
7546 =item B<MaxVersion> I<version>
7547
7548 Specify the minimum or maximum version of PostgreSQL that this query should be
7549 used with. Some statistics might only be available with certain versions of
7550 PostgreSQL. This allows you to specify multiple queries with the same name but
7551 which apply to different versions, thus allowing you to use the same
7552 configuration in a heterogeneous environment.
7553
7554 The I<version> has to be specified as the concatenation of the major, minor
7555 and patch-level versions, each represented as two-decimal-digit numbers. For
7556 example, version 8.2.3 will become 80203.
7557
7558 =back
7559
7560 The B<Result> block defines how to handle the values returned from the query.
7561 It defines which column holds which value and how to dispatch that value to
7562 the daemon.
7563
7564 =over 4
7565
7566 =item B<Type> I<type>
7567
7568 The I<type> name to be used when dispatching the values. The type describes
7569 how to handle the data and where to store it. See L<types.db(5)> for more
7570 details on types and their configuration. The number and type of values (as
7571 selected by the B<ValuesFrom> option) has to match the type of the given name.
7572
7573 This option is mandatory.
7574
7575 =item B<InstancePrefix> I<prefix>
7576
7577 =item B<InstancesFrom> I<column0> [I<column1> ...]
7578
7579 Specify how to create the "TypeInstance" for each data set (i.E<nbsp>e. line).
7580 B<InstancePrefix> defines a static prefix that will be prepended to all type
7581 instances. B<InstancesFrom> defines the column names whose values will be used
7582 to create the type instance. Multiple values will be joined together using the
7583 hyphen (C<->) as separation character.
7584
7585 The plugin itself does not check whether or not all built instances are
7586 different. It is your responsibility to assure that each is unique.
7587
7588 Both options are optional. If none is specified, the type instance will be
7589 empty.
7590
7591 =item B<ValuesFrom> I<column0> [I<column1> ...]
7592
7593 Names the columns whose content is used as the actual data for the data sets
7594 that are dispatched to the daemon. How many such columns you need is
7595 determined by the B<Type> setting as explained above. If you specify too many
7596 or not enough columns, the plugin will complain about that and no data will be
7597 submitted to the daemon.
7598
7599 The actual data type, as seen by PostgreSQL, is not that important as long as
7600 it represents numbers. The plugin will automatically cast the values to the
7601 right type if it know how to do that. For that, it uses the L<strtoll(3)> and
7602 L<strtod(3)> functions, so anything supported by those functions is supported
7603 by the plugin as well.
7604
7605 This option is required inside a B<Result> block and may be specified multiple
7606 times. If multiple B<ValuesFrom> options are specified, the columns are read
7607 in the given order.
7608
7609 =back
7610
7611 The following predefined queries are available (the definitions can be found
7612 in the F<postgresql_default.conf> file which, by default, is available at
7613 C<I<prefix>/share/collectd/>):
7614
7615 =over 4
7616
7617 =item B<backends>
7618
7619 This query collects the number of backends, i.E<nbsp>e. the number of
7620 connected clients.
7621
7622 =item B<transactions>
7623
7624 This query collects the numbers of committed and rolled-back transactions of
7625 the user tables.
7626
7627 =item B<queries>
7628
7629 This query collects the numbers of various table modifications (i.E<nbsp>e.
7630 insertions, updates, deletions) of the user tables.
7631
7632 =item B<query_plans>
7633
7634 This query collects the numbers of various table scans and returned tuples of
7635 the user tables.
7636
7637 =item B<table_states>
7638
7639 This query collects the numbers of live and dead rows in the user tables.
7640
7641 =item B<disk_io>
7642
7643 This query collects disk block access counts for user tables.
7644
7645 =item B<disk_usage>
7646
7647 This query collects the on-disk size of the database in bytes.
7648
7649 =back
7650
7651 In addition, the following detailed queries are available by default. Please
7652 note that each of those queries collects information B<by table>, thus,
7653 potentially producing B<a lot> of data. For details see the description of the
7654 non-by_table queries above.
7655
7656 =over 4
7657
7658 =item B<queries_by_table>
7659
7660 =item B<query_plans_by_table>
7661
7662 =item B<table_states_by_table>
7663
7664 =item B<disk_io_by_table>
7665
7666 =back
7667
7668 The B<Writer> block defines a PostgreSQL writer backend. It accepts a single
7669 mandatory argument specifying the name of the writer. This will then be used
7670 in the B<Database> specification in order to activate the writer instance. The
7671 names of all writers have to be unique. The following options may be
7672 specified:
7673
7674 =over 4
7675
7676 =item B<Statement> I<sql statement>
7677
7678 This mandatory option specifies the SQL statement that will be executed for
7679 each submitted value. A single SQL statement is allowed only. Anything after
7680 the first semicolon will be ignored.
7681
7682 Nine parameters will be passed to the statement and should be specified as
7683 tokens B<$1>, B<$2>, through B<$9> in the statement string. The following
7684 values are made available through those parameters:
7685
7686 =over 4
7687
7688 =item B<$1>
7689
7690 The timestamp of the queried value as an RFC 3339-formatted local time.
7691
7692 =item B<$2>
7693
7694 The hostname of the queried value.
7695
7696 =item B<$3>
7697
7698 The plugin name of the queried value.
7699
7700 =item B<$4>
7701
7702 The plugin instance of the queried value. This value may be B<NULL> if there
7703 is no plugin instance.
7704
7705 =item B<$5>
7706
7707 The type of the queried value (cf. L<types.db(5)>).
7708
7709 =item B<$6>
7710
7711 The type instance of the queried value. This value may be B<NULL> if there is
7712 no type instance.
7713
7714 =item B<$7>
7715
7716 An array of names for the submitted values (i.E<nbsp>e., the name of the data
7717 sources of the submitted value-list).
7718
7719 =item B<$8>
7720
7721 An array of types for the submitted values (i.E<nbsp>e., the type of the data
7722 sources of the submitted value-list; C<counter>, C<gauge>, ...). Note, that if
7723 B<StoreRates> is enabled (which is the default, see below), all types will be
7724 C<gauge>.
7725
7726 =item B<$9>
7727
7728 An array of the submitted values. The dimensions of the value name and value
7729 arrays match.
7730
7731 =back
7732
7733 In general, it is advisable to create and call a custom function in the
7734 PostgreSQL database for this purpose. Any procedural language supported by
7735 PostgreSQL will do (see chapter "Server Programming" in the PostgreSQL manual
7736 for details).
7737
7738 =item B<StoreRates> B<false>|B<true>
7739
7740 If set to B<true> (the default), convert counter values to rates. If set to
7741 B<false> counter values are stored as is, i.E<nbsp>e. as an increasing integer
7742 number.
7743
7744 =back
7745
7746 The B<Database> block defines one PostgreSQL database for which to collect
7747 statistics. It accepts a single mandatory argument which specifies the
7748 database name. None of the other options are required. PostgreSQL will use
7749 default values as documented in the section "CONNECTING TO A DATABASE" in the
7750 L<psql(1)> manpage. However, be aware that those defaults may be influenced by
7751 the user collectd is run as and special environment variables. See the manpage
7752 for details.
7753
7754 =over 4
7755
7756 =item B<Interval> I<seconds>
7757
7758 Specify the interval with which the database should be queried. The default is
7759 to use the global B<Interval> setting.
7760
7761 =item B<CommitInterval> I<seconds>
7762
7763 This option may be used for database connections which have "writers" assigned
7764 (see above). If specified, it causes a writer to put several updates into a
7765 single transaction. This transaction will last for the specified amount of
7766 time. By default, each update will be executed in a separate transaction. Each
7767 transaction generates a fair amount of overhead which can, thus, be reduced by
7768 activating this option. The draw-back is, that data covering the specified
7769 amount of time will be lost, for example, if a single statement within the
7770 transaction fails or if the database server crashes.
7771
7772 =item B<Plugin> I<Plugin>
7773
7774 Use I<Plugin> as the plugin name when submitting query results from
7775 this B<Database>. Defaults to C<postgresql>.
7776
7777 =item B<Instance> I<name>
7778
7779 Specify the plugin instance name that should be used instead of the database
7780 name (which is the default, if this option has not been specified). This
7781 allows one to query multiple databases of the same name on the same host (e.g.
7782 when running multiple database server versions in parallel).
7783 The plugin instance name can also be set from the query result using
7784 the B<PluginInstanceFrom> option in B<Query> block.
7785
7786 =item B<Host> I<hostname>
7787
7788 Specify the hostname or IP of the PostgreSQL server to connect to. If the
7789 value begins with a slash, it is interpreted as the directory name in which to
7790 look for the UNIX domain socket.
7791
7792 This option is also used to determine the hostname that is associated with a
7793 collected data set. If it has been omitted or either begins with with a slash
7794 or equals B<localhost> it will be replaced with the global hostname definition
7795 of collectd. Any other value will be passed literally to collectd when
7796 dispatching values. Also see the global B<Hostname> and B<FQDNLookup> options.
7797
7798 =item B<Port> I<port>
7799
7800 Specify the TCP port or the local UNIX domain socket file extension of the
7801 server.
7802
7803 =item B<User> I<username>
7804
7805 Specify the username to be used when connecting to the server.
7806
7807 =item B<Password> I<password>
7808
7809 Specify the password to be used when connecting to the server.
7810
7811 =item B<ExpireDelay> I<delay>
7812
7813 Skip expired values in query output.
7814
7815 =item B<SSLMode> I<disable>|I<allow>|I<prefer>|I<require>
7816
7817 Specify whether to use an SSL connection when contacting the server. The
7818 following modes are supported:
7819
7820 =over 4
7821
7822 =item I<disable>
7823
7824 Do not use SSL at all.
7825
7826 =item I<allow>
7827
7828 First, try to connect without using SSL. If that fails, try using SSL.
7829
7830 =item I<prefer> (default)
7831
7832 First, try to connect using SSL. If that fails, try without using SSL.
7833
7834 =item I<require>
7835
7836 Use SSL only.
7837
7838 =back
7839
7840 =item B<Instance> I<name>
7841
7842 Specify the plugin instance name that should be used instead of the database
7843 name (which is the default, if this option has not been specified). This
7844 allows one to query multiple databases of the same name on the same host (e.g.
7845 when running multiple database server versions in parallel).
7846
7847 =item B<KRBSrvName> I<kerberos_service_name>
7848
7849 Specify the Kerberos service name to use when authenticating with Kerberos 5
7850 or GSSAPI. See the sections "Kerberos authentication" and "GSSAPI" of the
7851 B<PostgreSQL Documentation> for details.
7852
7853 =item B<Service> I<service_name>
7854
7855 Specify the PostgreSQL service name to use for additional parameters. That
7856 service has to be defined in F<pg_service.conf> and holds additional
7857 connection parameters. See the section "The Connection Service File" in the
7858 B<PostgreSQL Documentation> for details.
7859
7860 =item B<Query> I<query>
7861
7862 Specifies a I<query> which should be executed in the context of the database
7863 connection. This may be any of the predefined or user-defined queries. If no
7864 such option is given, it defaults to "backends", "transactions", "queries",
7865 "query_plans", "table_states", "disk_io" and "disk_usage" (unless a B<Writer>
7866 has been specified). Else, the specified queries are used only.
7867
7868 =item B<Writer> I<writer>
7869
7870 Assigns the specified I<writer> backend to the database connection. This
7871 causes all collected data to be send to the database using the settings
7872 defined in the writer configuration (see the section "FILTER CONFIGURATION"
7873 below for details on how to selectively send data to certain plugins).
7874
7875 Each writer will register a flush callback which may be used when having long
7876 transactions enabled (see the B<CommitInterval> option above). When issuing
7877 the B<FLUSH> command (see L<collectd-unixsock(5)> for details) the current
7878 transaction will be committed right away. Two different kinds of flush
7879 callbacks are available with the C<postgresql> plugin:
7880
7881 =over 4
7882
7883 =item B<postgresql>
7884
7885 Flush all writer backends.
7886
7887 =item B<postgresql->I<database>
7888
7889 Flush all writers of the specified I<database> only.
7890
7891 =back
7892
7893 =back
7894
7895 =head2 Plugin C<powerdns>
7896
7897 The C<powerdns> plugin queries statistics from an authoritative PowerDNS
7898 nameserver and/or a PowerDNS recursor. Since both offer a wide variety of
7899 values, many of which are probably meaningless to most users, but may be useful
7900 for some. So you may chose which values to collect, but if you don't, some
7901 reasonable defaults will be collected.
7902
7903 <Plugin "powerdns">
7904 <Server "server_name">
7905 Collect "latency"
7906 Collect "udp-answers" "udp-queries"
7907 Socket "/var/run/pdns.controlsocket"
7908 </Server>
7909 <Recursor "recursor_name">
7910 Collect "questions"
7911 Collect "cache-hits" "cache-misses"
7912 Socket "/var/run/pdns_recursor.controlsocket"
7913 </Recursor>
7914 LocalSocket "/opt/collectd/var/run/collectd-powerdns"
7915 </Plugin>
7916
7917 =over 4
7918
7919 =item B<Server> and B<Recursor> block
7920
7921 The B<Server> block defines one authoritative server to query, the B<Recursor>
7922 does the same for an recursing server. The possible options in both blocks are
7923 the same, though. The argument defines a name for the serverE<nbsp>/ recursor
7924 and is required.
7925
7926 =over 4
7927
7928 =item B<Collect> I<Field>
7929
7930 Using the B<Collect> statement you can select which values to collect. Here,
7931 you specify the name of the values as used by the PowerDNS servers, e.E<nbsp>g.
7932 C<dlg-only-drops>, C<answers10-100>.
7933
7934 The method of getting the values differs for B<Server> and B<Recursor> blocks:
7935 When querying the server a C<SHOW *> command is issued in any case, because
7936 that's the only way of getting multiple values out of the server at once.
7937 collectd then picks out the values you have selected. When querying the
7938 recursor, a command is generated to query exactly these values. So if you
7939 specify invalid fields when querying the recursor, a syntax error may be
7940 returned by the daemon and collectd may not collect any values at all.
7941
7942 If no B<Collect> statement is given, the following B<Server> values will be
7943 collected:
7944
7945 =over 4
7946
7947 =item latency
7948
7949 =item packetcache-hit
7950
7951 =item packetcache-miss
7952
7953 =item packetcache-size
7954
7955 =item query-cache-hit
7956
7957 =item query-cache-miss
7958
7959 =item recursing-answers
7960
7961 =item recursing-questions
7962
7963 =item tcp-answers
7964
7965 =item tcp-queries
7966
7967 =item udp-answers
7968
7969 =item udp-queries
7970
7971 =back
7972
7973 The following B<Recursor> values will be collected by default:
7974
7975 =over 4
7976
7977 =item noerror-answers
7978
7979 =item nxdomain-answers
7980
7981 =item servfail-answers
7982
7983 =item sys-msec
7984
7985 =item user-msec
7986
7987 =item qa-latency
7988
7989 =item cache-entries
7990
7991 =item cache-hits
7992
7993 =item cache-misses
7994
7995 =item questions
7996
7997 =back
7998
7999 Please note that up to that point collectd doesn't know what values are
8000 available on the server and values that are added do not need a change of the
8001 mechanism so far. However, the values must be mapped to collectd's naming
8002 scheme, which is done using a lookup table that lists all known values. If
8003 values are added in the future and collectd does not know about them, you will
8004 get an error much like this:
8005
8006 powerdns plugin: submit: Not found in lookup table: foobar = 42
8007
8008 In this case please file a bug report with the collectd team.
8009
8010 =item B<Socket> I<Path>
8011
8012 Configures the path to the UNIX domain socket to be used when connecting to the
8013 daemon. By default C<${localstatedir}/run/pdns.controlsocket> will be used for
8014 an authoritative server and C<${localstatedir}/run/pdns_recursor.controlsocket>
8015 will be used for the recursor.
8016
8017 =back
8018
8019 =item B<LocalSocket> I<Path>
8020
8021 Querying the recursor is done using UDP. When using UDP over UNIX domain
8022 sockets, the client socket needs a name in the file system, too. You can set
8023 this local name to I<Path> using the B<LocalSocket> option. The default is
8024 C<I<prefix>/var/run/collectd-powerdns>.
8025
8026 =back
8027
8028 =head2 Plugin C<processes>
8029
8030 Collects information about processes of local system.
8031
8032 By default, with no process matches configured, only general statistics is
8033 collected: the number of processes in each state and fork rate.
8034
8035 Process matches can be configured by B<Process> and B<ProcessMatch> options.
8036 These may also be a block in which further options may be specified.
8037
8038 The statistics collected for matched processes are:
8039 - size of the resident segment size (RSS)
8040 - user- and system-time used
8041 - number of processes
8042 - number of threads
8043 - number of open files (under Linux)
8044 - number of memory mapped files (under Linux)
8045 - io data (where available)
8046 - context switches (under Linux)
8047 - minor and major pagefaults
8048 - Delay Accounting information (Linux only, requires libmnl)
8049
8050 B<Synopsis:>
8051
8052 <Plugin processes>
8053 CollectFileDescriptor true
8054 CollectContextSwitch true
8055 CollectDelayAccounting false
8056 Process "name"
8057 ProcessMatch "name" "regex"
8058 <Process "collectd">
8059 CollectFileDescriptor false
8060 CollectContextSwitch false
8061 CollectDelayAccounting true
8062 </Process>
8063 <ProcessMatch "name" "regex">
8064 CollectFileDescriptor false
8065 CollectContextSwitch true
8066 </ProcessMatch>
8067 </Plugin>
8068
8069 =over 4
8070
8071 =item B<Process> I<Name>
8072
8073 Select more detailed statistics of processes matching this name.
8074
8075 Some platforms have a limit on the length of process names.
8076 I<Name> must stay below this limit.
8077
8078 =item B<ProcessMatch> I<name> I<regex>
8079
8080 Select more detailed statistics of processes matching the specified I<regex>
8081 (see L<regex(7)> for details). The statistics of all matching processes are
8082 summed up and dispatched to the daemon using the specified I<name> as an
8083 identifier. This allows one to "group" several processes together.
8084 I<name> must not contain slashes.
8085
8086 =item B<CollectContextSwitch> I<Boolean>
8087
8088 Collect the number of context switches for matched processes.
8089 Disabled by default.
8090
8091 =item B<CollectDelayAccounting> I<Boolean>
8092
8093 If enabled, collect Linux Delay Accounding information for matching processes.
8094 Delay Accounting provides the time processes wait for the CPU to become
8095 available, for I/O operations to finish, for pages to be swapped in and for
8096 freed pages to be reclaimed. The metrics are reported as "seconds per second"
8097 using the C<delay_rate> type, e.g. C<delay_rate-delay-cpu>.
8098 Disabled by default.
8099
8100 This option is only available on Linux, requires the C<libmnl> library and
8101 requires the C<CAP_NET_ADMIN> capability at runtime.
8102
8103 =item B<CollectFileDescriptor> I<Boolean>
8104
8105 Collect number of file descriptors of matched processes.
8106 Disabled by default.
8107
8108 =item B<CollectMemoryMaps> I<Boolean>
8109
8110 Collect the number of memory mapped files of the process.
8111 The limit for this number is configured via F</proc/sys/vm/max_map_count> in
8112 the Linux kernel.
8113
8114 =back
8115
8116 The B<CollectContextSwitch>, B<CollectDelayAccounting>,
8117 B<CollectFileDescriptor> and B<CollectMemoryMaps> options may be used inside
8118 B<Process> and B<ProcessMatch> blocks. When used there, these options affect
8119 reporting the corresponding processes only. Outside of B<Process> and
8120 B<ProcessMatch> blocks these options set the default value for subsequent
8121 matches.
8122
8123 =head2 Plugin C<procevent>
8124
8125 The I<procevent> plugin monitors when processes start (EXEC) and stop (EXIT).
8126
8127 B<Synopsis:>
8128
8129 <Plugin procevent>
8130 BufferLength 10
8131 Process "name"
8132 ProcessRegex "regex"
8133 </Plugin>
8134
8135 B<Options:>
8136
8137 =over 4
8138
8139 =item B<BufferLength> I<length>
8140
8141 Maximum number of process events that can be stored in plugin's ring buffer.
8142 By default, this is set to 10. Once an event has been read, its location
8143 becomes available for storing a new event.
8144
8145 =item B<Process> I<name>
8146
8147 Enumerate a process name to monitor. All processes that match this exact
8148 name will be monitored for EXECs and EXITs.
8149
8150 =item B<ProcessRegex> I<regex>
8151
8152 Enumerate a process pattern to monitor. All processes that match this
8153 regular expression will be monitored for EXECs and EXITs.
8154
8155 =back
8156
8157 =head2 Plugin C<protocols>
8158
8159 Collects a lot of information about various network protocols, such as I<IP>,
8160 I<TCP>, I<UDP>, etc.
8161
8162 Available configuration options:
8163
8164 =over 4
8165
8166 =item B<Value> I<Selector>
8167
8168 Selects whether or not to select a specific value. The string being matched is
8169 of the form "I<Protocol>:I<ValueName>", where I<Protocol> will be used as the
8170 plugin instance and I<ValueName> will be used as type instance. An example of
8171 the string being used would be C<Tcp:RetransSegs>.
8172
8173 You can use regular expressions to match a large number of values with just one
8174 configuration option. To select all "extended" I<TCP> values, you could use the
8175 following statement:
8176
8177 Value "/^TcpExt:/"
8178
8179 Whether only matched values are selected or all matched values are ignored
8180 depends on the B<IgnoreSelected>. By default, only matched values are selected.
8181 If no value is configured at all, all values will be selected.
8182
8183 See F</"IGNORELISTS"> for details.
8184
8185 =item B<IgnoreSelected> B<true>|B<false>
8186
8187 If set to B<true>, inverts the selection made by B<Value>, i.E<nbsp>e. all
8188 matching values will be ignored.
8189
8190 =back
8191
8192 =head2 Plugin C<python>
8193
8194 This plugin embeds a Python-interpreter into collectd and provides an interface
8195 to collectd's plugin system. See L<collectd-python(5)> for its documentation.
8196
8197 =head2 Plugin C<redfish>
8198
8199 The C<redfish> plugin collects sensor data using REST protocol called
8200 Redfish.
8201
8202 B<Sample configuration:>
8203
8204 <Plugin redfish>
8205 <Query "fans">
8206 Endpoint "/redfish/v1/Chassis/Chassis-1/Thermal"
8207 <Resource "Fans">
8208 <Property "ReadingRPM">
8209 PluginInstance "chassis-1"
8210 Type "rpm"
8211 </Property>
8212 </Resource>
8213 </Query>
8214 <Query "temperatures">
8215 Endpoint "/redfish/v1/Chassis/Chassis-1/Thermal"
8216 <Resource "Temperatures">
8217 <Property "ReadingCelsius">
8218 PluginInstance "chassis-1"
8219 Type "degrees"
8220 </Property>
8221 </Resource>
8222 </Query>
8223 <Query "voltages">
8224 Endpoint "/redfish/v1/Chassis/Chassis-1/Power"
8225 <Resource "Voltages">
8226 <Property "ReadingVolts">
8227 PluginInstance "chassis-1"
8228 Type "volts"
8229 </Property>
8230 </Resource>
8231 </Query>
8232 <Service "local">
8233 Host "127.0.0.1:5000"
8234 User "user"
8235 Passwd "passwd"
8236 Queries "fans" "voltages" "temperatures"
8237 </Service>
8238 </Plugin>
8239
8240 =over 4
8241
8242 =item B<Query>
8243
8244 Section defining a query performed on Redfish interface
8245
8246 =item B<Endpoint>
8247
8248 URI of the REST API Endpoint for accessing the BMC
8249
8250 =item B<Resource>
8251
8252 Selects single resource or array to collect data.
8253
8254 =item B<Property>
8255
8256 Selects property from which data is gathered
8257
8258 =item B<PluginInstance>
8259
8260 Plugin instance of dispatched collectd metric
8261
8262 =item B<Type>
8263
8264 Type of dispatched collectd metric
8265
8266 =item B<TypeInstance>
8267
8268 Type instance of collectd metric
8269
8270 =item B<Service>
8271
8272 Section defining service to be sent requests
8273
8274 =item B<Username>
8275
8276 BMC username
8277
8278 =item B<Password>
8279
8280 BMC password
8281
8282 =item B<Queries>
8283
8284 Queries to run
8285
8286 =back
8287
8288 =head2 Plugin C<routeros>
8289
8290 The C<routeros> plugin connects to a device running I<RouterOS>, the
8291 Linux-based operating system for routers by I<MikroTik>. The plugin uses
8292 I<librouteros> to connect and reads information about the interfaces and
8293 wireless connections of the device. The configuration supports querying
8294 multiple routers:
8295
8296 <Plugin "routeros">
8297 <Router>
8298 Host "router0.example.com"
8299 User "collectd"
8300 Password "secr3t"
8301 CollectInterface true
8302 CollectCPULoad true
8303 CollectMemory true
8304 </Router>
8305 <Router>
8306 Host "router1.example.com"
8307 User "collectd"
8308 Password "5ecret"
8309 CollectInterface true
8310 CollectRegistrationTable true
8311 CollectDF true
8312 CollectDisk true
8313 CollectHealth true
8314 </Router>
8315 </Plugin>
8316
8317 As you can see above, the configuration of the I<routeros> plugin consists of
8318 one or more B<E<lt>RouterE<gt>> blocks. Within each block, the following
8319 options are understood:
8320
8321 =over 4
8322
8323 =item B<Host> I<Host>
8324
8325 Hostname or IP-address of the router to connect to.
8326
8327 =item B<Port> I<Port>
8328
8329 Port name or port number used when connecting. If left unspecified, the default
8330 will be chosen by I<librouteros>, currently "8728". This option expects a
8331 string argument, even when a numeric port number is given.
8332
8333 =item B<User> I<User>
8334
8335 Use the user name I<User> to authenticate. Defaults to "admin".
8336
8337 =item B<Password> I<Password>
8338
8339 Set the password used to authenticate.
8340
8341 =item B<CollectInterface> B<true>|B<false>
8342
8343 When set to B<true>, interface statistics will be collected for all interfaces
8344 present on the device. Defaults to B<false>.
8345
8346 =item B<CollectRegistrationTable> B<true>|B<false>
8347
8348 When set to B<true>, information about wireless LAN connections will be
8349 collected. Defaults to B<false>.
8350
8351 =item B<CollectCPULoad> B<true>|B<false>
8352
8353 When set to B<true>, information about the CPU usage will be collected. The
8354 number is a dimensionless value where zero indicates no CPU usage at all.
8355 Defaults to B<false>.
8356
8357 =item B<CollectMemory> B<true>|B<false>
8358
8359 When enabled, the amount of used and free memory will be collected. How used
8360 memory is calculated is unknown, for example whether or not caches are counted
8361 as used space.
8362 Defaults to B<false>.
8363
8364 =item B<CollectDF> B<true>|B<false>
8365
8366 When enabled, the amount of used and free disk space will be collected.
8367 Defaults to B<false>.
8368
8369 =item B<CollectDisk> B<true>|B<false>
8370
8371 When enabled, the number of sectors written and bad blocks will be collected.
8372 Defaults to B<false>.
8373
8374 =item B<CollectHealth> B<true>|B<false>
8375
8376 When enabled, the health statistics will be collected. This includes the
8377 voltage and temperature on supported hardware.
8378 Defaults to B<false>.
8379
8380 =back
8381
8382 =head2 Plugin C<redis>
8383
8384 The I<Redis plugin> connects to one or more Redis servers, gathers
8385 information about each server's state and executes user-defined queries.
8386 For each server there is a I<Node> block which configures the connection
8387 parameters and set of user-defined queries for this node.
8388
8389 <Plugin redis>
8390 <Node "example">
8391 Host "localhost"
8392 Port "6379"
8393 #Socket "/var/run/redis/redis.sock"
8394 Timeout 2000
8395 ReportCommandStats false
8396 ReportCpuUsage true
8397 <Query "LLEN myqueue">
8398 #Database 0
8399 Type "queue_length"
8400 Instance "myqueue"
8401 </Query>
8402 </Node>
8403 </Plugin>
8404
8405 =over 4
8406
8407 =item B<Node> I<Nodename>
8408
8409 The B<Node> block identifies a new Redis node, that is a new Redis instance
8410 running in an specified host and port. The name for node is a canonical
8411 identifier which is used as I<plugin instance>. It is limited to
8412 128E<nbsp>characters in length.
8413
8414 When no B<Node> is configured explicitly, plugin connects to "localhost:6379".
8415
8416 =item B<Host> I<Hostname>
8417
8418 The B<Host> option is the hostname or IP-address where the Redis instance is
8419 running on.
8420
8421 =item B<Port> I<Port>
8422
8423 The B<Port> option is the TCP port on which the Redis instance accepts
8424 connections. Either a service name of a port number may be given. Please note
8425 that numerical port numbers must be given as a string, too.
8426
8427 =item B<Socket> I<Path>
8428
8429 Connect to Redis using the UNIX domain socket at I<Path>. If this
8430 setting is given, the B<Hostname> and B<Port> settings are ignored.
8431
8432 =item B<Password> I<Password>
8433
8434 Use I<Password> to authenticate when connecting to I<Redis>.
8435
8436 =item B<Timeout> I<Milliseconds>
8437
8438 The B<Timeout> option set the socket timeout for node response. Since the Redis
8439 read function is blocking, you should keep this value as low as possible.
8440 It is expected what B<Timeout> values should be lower than B<Interval> defined
8441 globally.
8442
8443 Defaults to 2000 (2 seconds).
8444
8445 =item B<ReportCommandStats> B<false>|B<true>
8446
8447 Enables or disables reporting of statistics based on the command type, including
8448 rate of command calls and average CPU time consumed by command processing.
8449 Defaults to B<false>.
8450
8451 =item B<ReportCpuUsage> B<true>|B<false>
8452
8453 Enables or disables reporting of CPU consumption statistics.
8454 Defaults to B<true>.
8455
8456 =item B<Query> I<Querystring>
8457
8458 The B<Query> block identifies a query to execute against the redis server.
8459 There may be an arbitrary number of queries to execute. Each query should
8460 return single string or integer.
8461
8462 =item B<Type> I<Collectd type>
8463
8464 Within a query definition, a valid I<collectd type> to use as when submitting
8465 the result of the query. When not supplied, will default to B<gauge>.
8466
8467 Currently only types with one datasource are supported.
8468 See L<types.db(5)> for more details on types and their configuration.
8469
8470 =item B<Instance> I<Type instance>
8471
8472 Within a query definition, an optional type instance to use when submitting
8473 the result of the query. When not supplied will default to the escaped
8474 command, up to 128 chars.
8475
8476 =item B<Database> I<Index>
8477
8478 This index selects the Redis logical database to use for query. Defaults
8479 to C<0>.
8480
8481 =back
8482
8483 =head2 Plugin C<rrdcached>
8484
8485 The C<rrdcached> plugin uses the RRDtool accelerator daemon, L<rrdcached(1)>,
8486 to store values to RRD files in an efficient manner. The combination of the
8487 C<rrdcached> B<plugin> and the C<rrdcached> B<daemon> is very similar to the
8488 way the C<rrdtool> plugin works (see below). The added abstraction layer
8489 provides a number of benefits, though: Because the cache is not within
8490 C<collectd> anymore, it does not need to be flushed when C<collectd> is to be
8491 restarted. This results in much shorter (if any) gaps in graphs, especially
8492 under heavy load. Also, the C<rrdtool> command line utility is aware of the
8493 daemon so that it can flush values to disk automatically when needed. This
8494 allows one to integrate automated flushing of values into graphing solutions
8495 much more easily.
8496
8497 There are disadvantages, though: The daemon may reside on a different host, so
8498 it may not be possible for C<collectd> to create the appropriate RRD files
8499 anymore. And even if C<rrdcached> runs on the same host, it may run in a
8500 different base directory, so relative paths may do weird stuff if you're not
8501 careful.
8502
8503 So the B<recommended configuration> is to let C<collectd> and C<rrdcached> run
8504 on the same host, communicating via a UNIX domain socket. The B<DataDir>
8505 setting should be set to an absolute path, so that a changed base directory
8506 does not result in RRD files being createdE<nbsp>/ expected in the wrong place.
8507
8508 =over 4
8509
8510 =item B<DaemonAddress> I<Address>
8511
8512 Address of the daemon as understood by the C<rrdc_connect> function of the RRD
8513 library. See L<rrdcached(1)> for details. Example:
8514
8515 <Plugin "rrdcached">
8516 DaemonAddress "unix:/var/run/rrdcached.sock"
8517 </Plugin>
8518
8519 =item B<DataDir> I<Directory>
8520
8521 Set the base directory in which the RRD files reside. If this is a relative
8522 path, it is relative to the working base directory of the C<rrdcached> daemon!
8523 Use of an absolute path is recommended.
8524
8525 =item B<CreateFiles> B<true>|B<false>
8526
8527 Enables or disables the creation of RRD files. If the daemon is not running
8528 locally, or B<DataDir> is set to a relative path, this will not work as
8529 expected. Default is B<true>.
8530
8531 =item B<CreateFilesAsync> B<false>|B<true>
8532
8533 When enabled, new RRD files are enabled asynchronously, using a separate thread
8534 that runs in the background. This prevents writes to block, which is a problem
8535 especially when many hundreds of files need to be created at once. However,
8536 since the purpose of creating the files asynchronously is I<not> to block until
8537 the file is available, values before the file is available will be discarded.
8538 When disabled (the default) files are created synchronously, blocking for a
8539 short while, while the file is being written.
8540
8541 =item B<StepSize> I<Seconds>
8542
8543 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
8544 this setting is unset and the stepsize is set to the interval in which the data
8545 is collected. Do not use this option unless you absolutely have to for some
8546 reason. Setting this option may cause problems with the C<snmp plugin>, the
8547 C<exec plugin> or when the daemon is set up to receive data from other hosts.
8548
8549 =item B<HeartBeat> I<Seconds>
8550
8551 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
8552 in which case the heartbeat is set to twice the B<StepSize> which should equal
8553 the interval in which data is collected. Do not set this option unless you have
8554 a very good reason to do so.
8555
8556 =item B<RRARows> I<NumRows>
8557
8558 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
8559 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
8560 three times five RRAs, i. e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
8561 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
8562 week, one month, and one year.
8563
8564 So for each timespan, it calculates how many PDPs need to be consolidated into
8565 one CDP by calculating:
8566 number of PDPs = timespan / (stepsize * rrarows)
8567
8568 Bottom line is, set this no smaller than the width of you graphs in pixels. The
8569 default is 1200.
8570
8571 =item B<RRATimespan> I<Seconds>
8572
8573 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
8574 more then one RRA. If this option is never used, the built-in default of (3600,
8575 86400, 604800, 2678400, 31622400) is used.
8576
8577 For more information on how RRA-sizes are calculated see B<RRARows> above.
8578
8579 =item B<XFF> I<Factor>
8580
8581 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
8582 I<Factor> must be in the range C<[0.0-1.0)>, i.e. between zero (inclusive) and
8583 one (exclusive).
8584
8585 =item B<CollectStatistics> B<false>|B<true>
8586
8587 When set to B<true>, various statistics about the I<rrdcached> daemon will be
8588 collected, with "rrdcached" as the I<plugin name>. Defaults to B<false>.
8589
8590 Statistics are read via I<rrdcached>s socket using the STATS command.
8591 See L<rrdcached(1)> for details.
8592
8593 =back
8594
8595 =head2 Plugin C<rrdtool>
8596
8597 You can use the settings B<StepSize>, B<HeartBeat>, B<RRARows>, and B<XFF> to
8598 fine-tune your RRD-files. Please read L<rrdcreate(1)> if you encounter problems
8599 using these settings. If you don't want to dive into the depths of RRDtool, you
8600 can safely ignore these settings.
8601
8602 =over 4
8603
8604 =item B<DataDir> I<Directory>
8605
8606 Set the directory to store RRD files under. By default RRD files are generated
8607 beneath the daemon's working directory, i.e. the B<BaseDir>.
8608
8609 =item B<CreateFilesAsync> B<false>|B<true>
8610
8611 When enabled, new RRD files are enabled asynchronously, using a separate thread
8612 that runs in the background. This prevents writes to block, which is a problem
8613 especially when many hundreds of files need to be created at once. However,
8614 since the purpose of creating the files asynchronously is I<not> to block until
8615 the file is available, values before the file is available will be discarded.
8616 When disabled (the default) files are created synchronously, blocking for a
8617 short while, while the file is being written.
8618
8619 =item B<StepSize> I<Seconds>
8620
8621 B<Force> the stepsize of newly created RRD-files. Ideally (and per default)
8622 this setting is unset and the stepsize is set to the interval in which the data
8623 is collected. Do not use this option unless you absolutely have to for some
8624 reason. Setting this option may cause problems with the C<snmp plugin>, the
8625 C<exec plugin> or when the daemon is set up to receive data from other hosts.
8626
8627 =item B<HeartBeat> I<Seconds>
8628
8629 B<Force> the heartbeat of newly created RRD-files. This setting should be unset
8630 in which case the heartbeat is set to twice the B<StepSize> which should equal
8631 the interval in which data is collected. Do not set this option unless you have
8632 a very good reason to do so.
8633
8634 =item B<RRARows> I<NumRows>
8635
8636 The C<rrdtool plugin> calculates the number of PDPs per CDP based on the
8637 B<StepSize>, this setting and a timespan. This plugin creates RRD-files with
8638 three times five RRAs, i.e. five RRAs with the CFs B<MIN>, B<AVERAGE>, and
8639 B<MAX>. The five RRAs are optimized for graphs covering one hour, one day, one
8640 week, one month, and one year.
8641
8642 So for each timespan, it calculates how many PDPs need to be consolidated into
8643 one CDP by calculating:
8644 number of PDPs = timespan / (stepsize * rrarows)
8645
8646 Bottom line is, set this no smaller than the width of you graphs in pixels. The
8647 default is 1200.
8648
8649 =item B<RRATimespan> I<Seconds>
8650
8651 Adds an RRA-timespan, given in seconds. Use this option multiple times to have
8652 more then one RRA. If this option is never used, the built-in default of (3600,
8653 86400, 604800, 2678400, 31622400) is used.
8654
8655 For more information on how RRA-sizes are calculated see B<RRARows> above.
8656
8657 =item B<XFF> I<Factor>
8658
8659 Set the "XFiles Factor". The default is 0.1. If unsure, don't set this option.
8660 I<Factor> must be in the range C<[0.0-1.0)>, i.e. between zero (inclusive) and
8661 one (exclusive).
8662
8663 =item B<CacheFlush> I<Seconds>
8664
8665 When the C<rrdtool> plugin uses a cache (by setting B<CacheTimeout>, see below)
8666 it writes all values for a certain RRD-file if the oldest value is older than
8667 (or equal to) the number of seconds specified by B<CacheTimeout>.
8668 That check happens on new values arriwal. If some RRD-file is not updated
8669 anymore for some reason (the computer was shut down, the network is broken,
8670 etc.) some values may still be in the cache. If B<CacheFlush> is set, then
8671 every I<Seconds> seconds the entire cache is searched for entries older than
8672 B<CacheTimeout> + B<RandomTimeout> seconds. The entries found are written to
8673 disk. Since scanning the entire cache is kind of expensive and does nothing
8674 under normal circumstances, this value should not be too small. 900 seconds
8675 might be a good value, though setting this to 7200 seconds doesn't normally
8676 do much harm either.
8677
8678 Defaults to 10x B<CacheTimeout>.
8679 B<CacheFlush> must be larger than or equal to B<CacheTimeout>, otherwise the
8680 above default is used.
8681
8682 =item B<CacheTimeout> I<Seconds>
8683
8684 If this option is set to a value greater than zero, the C<rrdtool plugin> will
8685 save values in a cache, as described above. Writing multiple values at once
8686 reduces IO-operations and thus lessens the load produced by updating the files.
8687 The trade off is that the graphs kind of "drag behind" and that more memory is
8688 used.
8689
8690 =item B<WritesPerSecond> I<Updates>
8691
8692 When collecting many statistics with collectd and the C<rrdtool> plugin, you
8693 will run serious performance problems. The B<CacheFlush> setting and the
8694 internal update queue assert that collectd continues to work just fine even
8695 under heavy load, but the system may become very unresponsive and slow. This is
8696 a problem especially if you create graphs from the RRD files on the same
8697 machine, for example using the C<graph.cgi> script included in the
8698 C<contrib/collection3/> directory.
8699
8700 This setting is designed for very large setups. Setting this option to a value
8701 between 25 and 80 updates per second, depending on your hardware, will leave
8702 the server responsive enough to draw graphs even while all the cached values
8703 are written to disk. Flushed values, i.E<nbsp>e. values that are forced to disk
8704 by the B<FLUSH> command, are B<not> effected by this limit. They are still
8705 written as fast as possible, so that web frontends have up to date data when
8706 generating graphs.
8707
8708 For example: If you have 100,000 RRD files and set B<WritesPerSecond> to 30
8709 updates per second, writing all values to disk will take approximately
8710 56E<nbsp>minutes. Together with the flushing ability that's integrated into
8711 "collection3" you'll end up with a responsive and fast system, up to date
8712 graphs and basically a "backup" of your values every hour.
8713
8714 =item B<RandomTimeout> I<Seconds>
8715
8716 When set, the actual timeout for each value is chosen randomly between
8717 I<CacheTimeout>-I<RandomTimeout> and I<CacheTimeout>+I<RandomTimeout>. The
8718 intention is to avoid high load situations that appear when many values timeout
8719 at the same time. This is especially a problem shortly after the daemon starts,
8720 because all values were added to the internal cache at roughly the same time.
8721
8722 =back
8723
8724 =head2 Plugin C<sensors>
8725
8726 The I<Sensors plugin> uses B<lm_sensors> to retrieve sensor-values. This means
8727 that all the needed modules have to be loaded and lm_sensors has to be
8728 configured (most likely by editing F</etc/sensors.conf>. Read
8729 L<sensors.conf(5)> for details.
8730
8731 The B<lm_sensors> homepage can be found at
8732 L<http://secure.netroedge.com/~lm78/>.
8733
8734 =over 4
8735
8736 =item B<SensorConfigFile> I<File>
8737
8738 Read the I<lm_sensors> configuration from I<File>. When unset (recommended),
8739 the library's default will be used.
8740
8741 =item B<Sensor> I<chip-bus-address/type-feature>
8742
8743 Selects the name of the sensor which you want to collect or ignore, depending
8744 on the B<IgnoreSelected> below. For example, the option "B<Sensor>
8745 I<it8712-isa-0290/voltage-in1>" will cause collectd to gather data for the
8746 voltage sensor I<in1> of the I<it8712> on the isa bus at the address 0290.
8747
8748 The value passed to this option has the format
8749 "I<plugin_instance>/I<type>-I<type_instance>".
8750
8751 See F</"IGNORELISTS"> for details.
8752
8753 =item B<IgnoreSelected> I<true>|I<false>
8754
8755 If no configuration if given, the B<sensors>-plugin will collect data from all
8756 sensors. This may not be practical, especially for uninteresting sensors.
8757 Thus, you can use the B<Sensor>-option to pick the sensors you're interested
8758 in. Sometimes, however, it's easier/preferred to collect all sensors I<except> a
8759 few ones. This option enables you to do that: By setting B<IgnoreSelected> to
8760 I<true> the effect of B<Sensor> is inverted: All selected sensors are ignored
8761 and all other sensors are collected.
8762
8763 =item B<UseLabels> I<true>|I<false>
8764
8765 Configures how sensor readings are reported. When set to I<true>, sensor
8766 readings are reported using their descriptive label (e.g. "VCore"). When set to
8767 I<false> (the default) the sensor name is used ("in0").
8768
8769 =back
8770
8771 =head2 Plugin C<sigrok>
8772
8773 The I<sigrok plugin> uses I<libsigrok> to retrieve measurements from any device
8774 supported by the L<sigrok|http://sigrok.org/> project.
8775
8776 B<Synopsis>
8777
8778 <Plugin sigrok>
8779 LogLevel 3
8780 <Device "AC Voltage">
8781 Driver "fluke-dmm"
8782 MinimumInterval 10
8783 Conn "/dev/ttyUSB2"
8784 </Device>
8785 <Device "Sound Level">
8786 Driver "cem-dt-885x"
8787 Conn "/dev/ttyUSB1"
8788 </Device>
8789 </Plugin>
8790
8791 =over 4
8792
8793 =item B<LogLevel> B<0-5>
8794
8795 The I<sigrok> logging level to pass on to the I<collectd> log, as a number
8796 between B<0> and B<5> (inclusive). These levels correspond to C<None>,
8797 C<Errors>, C<Warnings>, C<Informational>, C<Debug >and C<Spew>, respectively.
8798 The default is B<2> (C<Warnings>). The I<sigrok> log messages, regardless of
8799 their level, are always submitted to I<collectd> at its INFO log level.
8800
8801 =item E<lt>B<Device> I<Name>E<gt>
8802
8803 A sigrok-supported device, uniquely identified by this section's options. The
8804 I<Name> is passed to I<collectd> as the I<plugin instance>.
8805
8806 =item B<Driver> I<DriverName>
8807
8808 The sigrok driver to use for this device.
8809
8810 =item B<Conn> I<ConnectionSpec>
8811
8812 If the device cannot be auto-discovered, or more than one might be discovered
8813 by the driver, I<ConnectionSpec> specifies the connection string to the device.
8814 It can be of the form of a device path (e.g.E<nbsp>C</dev/ttyUSB2>), or, in
8815 case of a non-serial USB-connected device, the USB I<VendorID>B<.>I<ProductID>
8816 separated by a period (e.g.E<nbsp>C<0403.6001>). A USB device can also be
8817 specified as I<Bus>B<.>I<Address> (e.g.E<nbsp>C<1.41>).
8818
8819 =item B<SerialComm> I<SerialSpec>
8820
8821 For serial devices with non-standard port settings, this option can be used
8822 to specify them in a form understood by I<sigrok>, e.g.E<nbsp>C<9600/8n1>.
8823 This should not be necessary; drivers know how to communicate with devices they
8824 support.
8825
8826 =item B<MinimumInterval> I<Seconds>
8827
8828 Specifies the minimum time between measurement dispatches to I<collectd>, in
8829 seconds. Since some I<sigrok> supported devices can acquire measurements many
8830 times per second, it may be necessary to throttle these. For example, the
8831 I<RRD plugin> cannot process writes more than once per second.
8832
8833 The default B<MinimumInterval> is B<0>, meaning measurements received from the
8834 device are always dispatched to I<collectd>. When throttled, unused
8835 measurements are discarded.
8836
8837 =back
8838
8839 =head2 Plugin C<slurm>
8840
8841 This plugin collects per-partition SLURM node and job state information, as
8842 well as internal health statistics.
8843 It takes no options. It should run on a node that is capable of running the
8844 I<sinfo> and I<squeue> commands, i.e. it has a running slurmd and a valid
8845 slurm.conf.
8846 Note that this plugin needs the B<Globals> option set to I<true> in order to
8847 function properly.
8848
8849 =head2 Plugin C<smart>
8850
8851 The C<smart> plugin collects SMART information from physical
8852 disks. Values collectd include temperature, power cycle count, poweron
8853 time and bad sectors. Also, all SMART attributes are collected along
8854 with the normalized current value, the worst value, the threshold and
8855 a human readable value. The plugin can also collect SMART attributes
8856 for NVMe disks (present in accordance with NVMe 1.4 spec) and Additional
8857 SMART Attributes from Intel® NVMe disks.
8858
8859 Using the following two options you can ignore some disks or configure the
8860 collection only of specific disks.
8861
8862 =over 4
8863
8864 =item B<Disk> I<Name>
8865
8866 Select the disk I<Name>. Whether it is collected or ignored depends on the
8867 B<IgnoreSelected> setting, see below. As with other plugins that use the
8868 daemon's ignorelist functionality, a string that starts and ends with a slash
8869 is interpreted as a regular expression. Examples:
8870
8871 Disk "sdd"
8872 Disk "/hda[34]/"
8873 Disk "nvme0n1"
8874
8875 See F</"IGNORELISTS"> for details.
8876
8877 =item B<IgnoreSelected> B<true>|B<false>
8878
8879 Sets whether selected disks, i.E<nbsp>e. the ones matches by any of the B<Disk>
8880 statements, are ignored or if all other disks are ignored. The behavior
8881 (hopefully) is intuitive: If no B<Disk> option is configured, all disks are
8882 collected. If at least one B<Disk> option is given and no B<IgnoreSelected> or
8883 set to B<false>, B<only> matching disks will be collected. If B<IgnoreSelected>
8884 is set to B<true>, all disks are collected B<except> the ones matched.
8885
8886 =item B<IgnoreSleepMode> B<true>|B<false>
8887
8888 Normally, the C<smart> plugin will ignore disks that are reported to be asleep.
8889 This option disables the sleep mode check and allows the plugin to collect data
8890 from these disks anyway. This is useful in cases where libatasmart mistakenly
8891 reports disks as asleep because it has not been updated to incorporate support
8892 for newer idle states in the ATA spec.
8893
8894 =item B<UseSerial> B<true>|B<false>
8895
8896 A disk's kernel name (e.g., sda) can change from one boot to the next. If this
8897 option is enabled, the C<smart> plugin will use the disk's serial number (e.g.,
8898 HGST_HUH728080ALE600_2EJ8VH8X) instead of the kernel name as the key for
8899 storing data. This ensures that the data for a given disk will be kept together
8900 even if the kernel name changes.
8901
8902 =back
8903
8904 =head2 Plugin C<snmp>
8905
8906 Since the configuration of the C<snmp plugin> is a little more complicated than
8907 other plugins, its documentation has been moved to an own manpage,
8908 L<collectd-snmp(5)>. Please see there for details.
8909
8910 =head2 Plugin C<snmp_agent>
8911
8912 The I<snmp_agent> plugin is an AgentX subagent that receives and handles queries
8913 from SNMP master agent and returns the data collected by read plugins.
8914 The I<snmp_agent> plugin handles requests only for OIDs specified in
8915 configuration file. To handle SNMP queries the plugin gets data from collectd
8916 and translates requested values from collectd's internal format to SNMP format.
8917 This plugin is a generic plugin and cannot work without configuration.
8918 For more details on AgentX subagent see
8919 <http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/>
8920
8921 B<Synopsis:>
8922
8923 <Plugin snmp_agent>
8924 <Data "memAvailReal">
8925 Plugin "memory"
8926 #PluginInstance "some"
8927 Type "memory"
8928 TypeInstance "free"
8929 OIDs "1.3.6.1.4.1.2021.4.6.0"
8930 </Data>
8931 <Table "ifTable">
8932 IndexOID "IF-MIB::ifIndex"
8933 SizeOID "IF-MIB::ifNumber"
8934 <Data "ifDescr">
8935 <IndexKey>
8936 Source "PluginInstance"
8937 </IndexKey>
8938 Plugin "interface"
8939 OIDs "IF-MIB::ifDescr"
8940 </Data>
8941 <Data "ifOctets">
8942 Plugin "interface"
8943 Type "if_octets"
8944 TypeInstance ""
8945 OIDs "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
8946 </Data>
8947 </Table>
8948 <Table "CPUAffinityTable">
8949 <Data "DomainName">
8950 <IndexKey>
8951 Source "PluginInstance"
8952 </IndexKey>
8953 Plugin "virt"
8954 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhAffinityDomainName"
8955 </Data>
8956 <Data "VCPU">
8957 Plugin "virt"
8958 <IndexKey>
8959 Source "TypeInstance"
8960 Regex "^vcpu_([0-9]{1,3})-cpu_[0-9]{1,3}$"
8961 Group 1
8962 </IndexKey>
8963 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhVCPUIndex"
8964 </Data>
8965 <Data "CPU">
8966 Plugin "virt"
8967 <IndexKey>
8968 Source "TypeInstance"
8969 Regex "^vcpu_[0-9]{1,3}-cpu_([0-9]{1,3})$"
8970 Group 1
8971 </IndexKey>
8972 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhCPUIndex"
8973 </Data>
8974 <Data "CPUAffinity">
8975 Plugin "virt"
8976 Type "cpu_affinity"
8977 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhCPUAffinity"
8978 </Data>
8979 </Table>
8980 </Plugin>
8981
8982 There are two types of blocks that can be contained in the
8983 C<E<lt>PluginE<nbsp> snmp_agentE<gt>> block: B<Data> and B<Table>:
8984
8985 =head3 B<Data> block
8986
8987 The B<Data> block defines a list OIDs that are to be handled. This block can
8988 define scalar or table OIDs. If B<Data> block is defined inside of B<Table>
8989 block it reperesents table OIDs.
8990 The following options can be set:
8991
8992 =over 4
8993
8994 =item B<IndexKey> block
8995
8996 B<IndexKey> block contains all data needed for proper index build of snmp table.
8997 In case more than
8998 one table B<Data> block has B<IndexKey> block present then multiple key index is
8999 built. If B<Data> block defines scalar data type B<IndexKey> has no effect and can
9000 be omitted.
9001
9002 =over 8
9003
9004 =item B<Source> I<String>
9005
9006 B<Source> can be set to one of the following values: "Hostname", "Plugin",
9007 "PluginInstance", "Type", "TypeInstance". This value indicates which field of
9008 corresponding collectd metric is taken as a SNMP table index.
9009
9010 =item B<Regex> I<String>
9011
9012 B<Regex> option can also be used to parse strings or numbers out of
9013 specific field. For example: type-instance field which is "vcpu1-cpu2" can be
9014 parsed into two numeric fields CPU = 2 and VCPU = 1 and can be later used
9015 as a table index.
9016
9017 =item B<Group> I<Number>
9018
9019 B<Group> number can be specified in case groups are used in regex.
9020
9021 =back
9022
9023 =item B<Plugin> I<String>
9024
9025 Read plugin name whose collected data will be mapped to specified OIDs.
9026
9027 =item B<PluginInstance> I<String>
9028
9029 Read plugin instance whose collected data will be mapped to specified OIDs.
9030 The field is optional and by default there is no plugin instance check.
9031 Allowed only if B<Data> block defines scalar data type.
9032
9033 =item B<Type> I<String>
9034
9035 Collectd's type that is to be used for specified OID, e.E<nbsp>g. "if_octets"
9036 for example. The types are read from the B<TypesDB> (see L<collectd.conf(5)>).
9037
9038 =item B<TypeInstance> I<String>
9039
9040 Collectd's type-instance that is to be used for specified OID.
9041
9042 =item B<OIDs> I<OID> [I<OID> ...]
9043
9044 Configures the OIDs to be handled by I<snmp_agent> plugin. Values for these OIDs
9045 are taken from collectd data type specified by B<Plugin>, B<PluginInstance>,
9046 B<Type>, B<TypeInstance> fields of this B<Data> block. Number of the OIDs
9047 configured should correspond to number of values in specified B<Type>.
9048 For example two OIDs "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets" can be mapped to
9049 "rx" and "tx" values of "if_octets" type.
9050
9051 =item B<Scale> I<Value>
9052
9053 The values taken from collectd are multiplied by I<Value>. The field is optional
9054 and the default is B<1.0>.
9055
9056 =item B<Shift> I<Value>
9057
9058 I<Value> is added to values from collectd after they have been multiplied by
9059 B<Scale> value. The field is optional and the default value is B<0.0>.
9060
9061 =back
9062
9063 =head3 The B<Table> block
9064
9065 The B<Table> block defines a collection of B<Data> blocks that belong to one
9066 snmp table. In addition to multiple B<Data> blocks the following options can be
9067 set:
9068
9069 =over 4
9070
9071 =item B<IndexOID> I<OID>
9072
9073 OID that is handled by the plugin and is mapped to numerical index value that is
9074 generated by the plugin for each table record.
9075
9076 =item B<SizeOID> I<OID>
9077
9078 OID that is handled by the plugin. Returned value is the number of records in
9079 the table. The field is optional.
9080
9081 =back
9082
9083 =head2 Plugin C<statsd>
9084
9085 The I<statsd plugin> listens to a UDP socket, reads "events" in the statsd
9086 protocol and dispatches rates or other aggregates of these numbers
9087 periodically.
9088
9089 The plugin implements the I<Counter>, I<Timer>, I<Gauge> and I<Set> types which
9090 are dispatched as the I<collectd> types C<derive>, C<latency>, C<gauge> and
9091 C<objects> respectively.
9092
9093 The following configuration options are valid:
9094
9095 =over 4
9096
9097 =item B<Host> I<Host>
9098
9099 Bind to the hostname / address I<Host>. By default, the plugin will bind to the
9100 "any" address, i.e. accept packets sent to any of the hosts addresses.
9101
9102 =item B<Port> I<Port>
9103
9104 UDP port to listen to. This can be either a service name or a port number.
9105 Defaults to C<8125>.
9106
9107 =item B<DeleteCounters> B<false>|B<true>
9108
9109 =item B<DeleteTimers> B<false>|B<true>
9110
9111 =item B<DeleteGauges> B<false>|B<true>
9112
9113 =item B<DeleteSets> B<false>|B<true>
9114
9115 These options control what happens if metrics are not updated in an interval.
9116 If set to B<False>, the default, metrics are dispatched unchanged, i.e. the
9117 rate of counters and size of sets will be zero, timers report C<NaN> and gauges
9118 are unchanged. If set to B<True>, the such metrics are not dispatched and
9119 removed from the internal cache.
9120
9121 =item B<CounterSum> B<false>|B<true>
9122
9123 When enabled, creates a C<count> metric which reports the change since the last
9124 read. This option primarily exists for compatibility with the I<statsd>
9125 implementation by Etsy.
9126
9127 =item B<TimerPercentile> I<Percent>
9128
9129 Calculate and dispatch the configured percentile, i.e. compute the latency, so
9130 that I<Percent> of all reported timers are smaller than or equal to the
9131 computed latency. This is useful for cutting off the long tail latency, as it's
9132 often done in I<Service Level Agreements> (SLAs).
9133
9134 Different percentiles can be calculated by setting this option several times.
9135 If none are specified, no percentiles are calculated / dispatched.
9136
9137 =item B<TimerLower> B<false>|B<true>
9138
9139 =item B<TimerUpper> B<false>|B<true>
9140
9141 =item B<TimerSum> B<false>|B<true>
9142
9143 =item B<TimerCount> B<false>|B<true>
9144
9145 Calculate and dispatch various values out of I<Timer> metrics received during
9146 an interval. If set to B<False>, the default, these values aren't calculated /
9147 dispatched.
9148
9149 Please note what reported timer values less than 0.001 are ignored in all B<Timer*> reports.
9150
9151 =back
9152
9153 =head2 Plugin C<swap>
9154
9155 The I<Swap plugin> collects information about used and available swap space. On
9156 I<Linux> and I<Solaris>, the following options are available:
9157
9158 =over 4
9159
9160 =item B<ReportByDevice> B<false>|B<true>
9161
9162 Configures how to report physical swap devices. If set to B<false> (the
9163 default), the summary over all swap devices is reported only, i.e. the globally
9164 used and available space over all devices. If B<true> is configured, the used
9165 and available space of each device will be reported separately.
9166
9167 This option is only available if the I<Swap plugin> can read C</proc/swaps>
9168 (under Linux) or use the L<swapctl(2)> mechanism (under I<Solaris>).
9169
9170 =item B<ReportBytes> B<false>|B<true>
9171
9172 When enabled, the I<swap I/O> is reported in bytes. When disabled, the default,
9173 I<swap I/O> is reported in pages. This option is available under Linux only.
9174
9175 =item B<ValuesAbsolute> B<true>|B<false>
9176
9177 Enables or disables reporting of absolute swap metrics, i.e. number of I<bytes>
9178 available and used. Defaults to B<true>.
9179
9180 =item B<ValuesPercentage> B<false>|B<true>
9181
9182 Enables or disables reporting of relative swap metrics, i.e. I<percent>
9183 available and free. Defaults to B<false>.
9184
9185 This is useful for deploying I<collectd> in a heterogeneous environment, where
9186 swap sizes differ and you want to specify generic thresholds or similar.
9187
9188 =item B<ReportIO> B<true>|B<false>
9189
9190 Enables or disables reporting swap IO. Defaults to B<true>.
9191
9192 This is useful for the cases when swap IO is not neccessary, is not available,
9193 or is not reliable.
9194
9195 =back
9196
9197 =head2 Plugin C<sysevent>
9198
9199 The I<sysevent> plugin monitors rsyslog messages.
9200
9201 B<Synopsis:>
9202
9203 <Plugin sysevent>
9204 Listen "192.168.0.2" "6666"
9205 BufferSize 1024
9206 BufferLength 10
9207 RegexFilter "regex"
9208 </Plugin>
9209
9210 rsyslog should be configured such that it sends data to the IP and port you
9211 include in the plugin configuration. For example, given the configuration
9212 above, something like this would be set in /etc/rsyslog.conf:
9213
9214 if $programname != 'collectd' then
9215 *.* @192.168.0.2:6666
9216
9217 This plugin is designed to consume JSON rsyslog data, so a more complete
9218 rsyslog configuration would look like so (where we define a JSON template
9219 and use it when sending data to our IP and port):
9220
9221 $template ls_json,"{%timestamp:::date-rfc3339,jsonf:@timestamp%, \
9222 %source:::jsonf:@source_host%,\"@source\":\"syslog://%fromhost-ip:::json%\", \
9223 \"@message\":\"%timestamp% %app-name%:%msg:::json%\",\"@fields\": \
9224 {%syslogfacility-text:::jsonf:facility%,%syslogseverity:::jsonf:severity-num%, \
9225 %syslogseverity-text:::jsonf:severity%,%programname:::jsonf:program%, \
9226 %procid:::jsonf:processid%}}"
9227
9228 if $programname != 'collectd' then
9229 *.* @192.168.0.2:6666;ls_json
9230
9231 Please note that these rsyslog.conf examples are *not* complete, as rsyslog
9232 requires more than these options in the configuration file. These examples
9233 are meant to demonstration the proper remote logging and JSON format syntax.
9234
9235 B<Options:>
9236
9237 =over 4
9238
9239 =item B<Listen> I<host> I<port>
9240
9241 Listen on this IP on this port for incoming rsyslog messages.
9242
9243 =item B<BufferSize> I<length>
9244
9245 Maximum allowed size for incoming rsyslog messages. Messages that exceed
9246 this number will be truncated to this size. Default is 4096 bytes.
9247
9248 =item B<BufferLength> I<length>
9249
9250 Maximum number of rsyslog events that can be stored in plugin's ring buffer.
9251 By default, this is set to 10. Once an event has been read, its location
9252 becomes available for storing a new event.
9253
9254 =item B<RegexFilter> I<regex>
9255
9256 Enumerate a regex filter to apply to all incoming rsyslog messages. If a
9257 message matches this filter, it will be published.
9258
9259 =back
9260
9261 =head2 Plugin C<syslog>
9262
9263 =over 4
9264
9265 =item B<LogLevel> B<debug|info|notice|warning|err>
9266
9267 Sets the log-level. If, for example, set to B<notice>, then all events with
9268 severity B<notice>, B<warning>, or B<err> will be submitted to the
9269 syslog-daemon.
9270
9271 Please note that B<debug> is only available if collectd has been compiled with
9272 debugging support.
9273
9274 =item B<NotifyLevel> B<OKAY>|B<WARNING>|B<FAILURE>
9275
9276 Controls which notifications should be sent to syslog. The default behaviour is
9277 not to send any. Less severe notifications always imply logging more severe
9278 notifications: Setting this to B<OKAY> means all notifications will be sent to
9279 syslog, setting this to B<WARNING> will send B<WARNING> and B<FAILURE>
9280 notifications but will dismiss B<OKAY> notifications. Setting this option to
9281 B<FAILURE> will only send failures to syslog.
9282
9283 =back
9284
9285 =head2 Plugin C<table>
9286
9287 The C<table plugin> provides generic means to parse tabular data and dispatch
9288 user specified values. Values are selected based on column numbers. For
9289 example, this plugin may be used to get values from the Linux L<proc(5)>
9290 filesystem or CSV (comma separated values) files.
9291
9292 <Plugin table>
9293 <Table "/proc/slabinfo">
9294 #Plugin "slab"
9295 Instance "slabinfo"
9296 Separator " "
9297 <Result>
9298 Type gauge
9299 InstancePrefix "active_objs"
9300 InstancesFrom 0
9301 ValuesFrom 1
9302 </Result>
9303 <Result>
9304 Type gauge
9305 InstancePrefix "objperslab"
9306 InstancesFrom 0
9307 ValuesFrom 4
9308 </Result>
9309 </Table>
9310 </Plugin>
9311
9312 The configuration consists of one or more B<Table> blocks, each of which
9313 configures one file to parse. Within each B<Table> block, there are one or
9314 more B<Result> blocks, which configure which data to select and how to
9315 interpret it.
9316
9317 The following options are available inside a B<Table> block:
9318
9319 =over 4
9320
9321 =item B<Plugin> I<Plugin>
9322
9323 If specified, I<Plugin> is used as the plugin name when submitting values.
9324 Defaults to B<table>.
9325
9326 =item B<Instance> I<instance>
9327
9328 If specified, I<instance> is used as the plugin instance. If omitted, the
9329 filename of the table is used instead, with all special characters replaced
9330 with an underscore (C<_>).
9331
9332 =item B<Separator> I<string>
9333
9334 Any character of I<string> is interpreted as a delimiter between the different
9335 columns of the table. A sequence of two or more contiguous delimiters in the
9336 table is considered to be a single delimiter, i.E<nbsp>e. there cannot be any
9337 empty columns. The plugin uses the L<strtok_r(3)> function to parse the lines
9338 of a table - see its documentation for more details. This option is mandatory.
9339
9340 A horizontal tab, newline and carriage return may be specified by C<\\t>,
9341 C<\\n> and C<\\r> respectively. Please note that the double backslashes are
9342 required because of collectd's config parsing.
9343
9344 =back
9345
9346 The following options are available inside a B<Result> block:
9347
9348 =over 4
9349
9350 =item B<Type> I<type>
9351
9352 Sets the type used to dispatch the values to the daemon. Detailed information
9353 about types and their configuration can be found in L<types.db(5)>. This
9354 option is mandatory.
9355
9356 =item B<InstancePrefix> I<prefix>
9357
9358 If specified, prepend I<prefix> to the type instance. If omitted, only the
9359 B<InstancesFrom> option is considered for the type instance.
9360
9361 =item B<InstancesFrom> I<column0> [I<column1> ...]
9362
9363 If specified, the content of the given columns (identified by the column
9364 number starting at zero) will be used to create the type instance for each
9365 row. Multiple values (and the instance prefix) will be joined together with
9366 dashes (I<->) as separation character. If omitted, only the B<InstancePrefix>
9367 option is considered for the type instance.
9368
9369 The plugin itself does not check whether or not all built instances are
9370 different. It’s your responsibility to assure that each is unique. This is
9371 especially true, if you do not specify B<InstancesFrom>: B<You> have to make
9372 sure that the table only contains one row.
9373
9374 If neither B<InstancePrefix> nor B<InstancesFrom> is given, the type instance
9375 will be empty.
9376
9377 =item B<ValuesFrom> I<column0> [I<column1> ...]
9378
9379 Specifies the columns (identified by the column numbers starting at zero)
9380 whose content is used as the actual data for the data sets that are dispatched
9381 to the daemon. How many such columns you need is determined by the B<Type>
9382 setting above. If you specify too many or not enough columns, the plugin will
9383 complain about that and no data will be submitted to the daemon. The plugin
9384 uses L<strtoll(3)> and L<strtod(3)> to parse counter and gauge values
9385 respectively, so anything supported by those functions is supported by the
9386 plugin as well. This option is mandatory.
9387
9388 =back
9389
9390 =head2 Plugin C<tail>
9391
9392 The C<tail plugin> follows logfiles, just like L<tail(1)> does, parses
9393 each line and dispatches found values. What is matched can be configured by the
9394 user using (extended) regular expressions, as described in L<regex(7)>.
9395
9396 <Plugin "tail">
9397 <File "/var/log/exim4/mainlog">
9398 Plugin "mail"
9399 Instance "exim"
9400 Interval 60
9401 <Match>
9402 Regex "S=([1-9][0-9]*)"
9403 DSType "CounterAdd"
9404 Type "ipt_bytes"
9405 Instance "total"
9406 </Match>
9407 <Match>
9408 Regex "\\<R=local_user\\>"
9409 ExcludeRegex "\\<R=local_user\\>.*mail_spool defer"
9410 DSType "CounterInc"
9411 Type "counter"
9412 Instance "local_user"
9413 </Match>
9414 <Match>
9415 Regex "l=([0-9]*\\.[0-9]*)"
9416 <DSType "Distribution">
9417 Percentile 99
9418 Bucket 0 100
9419 #BucketType "bucket"
9420 </DSType>
9421 Type "latency"
9422 Instance "foo"
9423 </Match>
9424 </File>
9425 </Plugin>
9426
9427 The config consists of one or more B<File> blocks, each of which configures one
9428 logfile to parse. Within each B<File> block, there are one or more B<Match>
9429 blocks, which configure a regular expression to search for.
9430
9431 The B<Plugin> and B<Instance> options in the B<File> block may be used to set
9432 the plugin name and instance respectively. So in the above example the plugin name
9433 C<mail-exim> would be used.
9434
9435 These options are applied for all B<Match> blocks that B<follow> it, until the
9436 next B<Plugin> or B<Instance> option. This way you can extract several plugin
9437 instances from one logfile, handy when parsing syslog and the like.
9438
9439 The B<Interval> option allows you to define the length of time between reads. If
9440 this is not set, the default Interval will be used.
9441
9442 Each B<Match> block has the following options to describe how the match should
9443 be performed:
9444
9445 =over 4
9446
9447 =item B<Regex> I<regex>
9448
9449 Sets the regular expression to use for matching against a line. The first
9450 subexpression has to match something that can be turned into a number by
9451 L<strtoll(3)> or L<strtod(3)>, depending on the value of C<CounterAdd>, see
9452 below. Because B<extended> regular expressions are used, you do not need to use
9453 backslashes for subexpressions! If in doubt, please consult L<regex(7)>. Due to
9454 collectd's config parsing you need to escape backslashes, though. So if you
9455 want to match literal parentheses you need to do the following:
9456
9457 Regex "SPAM \\(Score: (-?[0-9]+\\.[0-9]+)\\)"
9458
9459 =item B<ExcludeRegex> I<regex>
9460
9461 Sets an optional regular expression to use for excluding lines from the match.
9462 An example which excludes all connections from localhost from the match:
9463
9464 ExcludeRegex "127\\.0\\.0\\.1"
9465
9466 =item B<DSType> I<Type>
9467
9468 Sets how the values are cumulated. I<Type> is one of:
9469
9470 =over 4
9471
9472 =item B<GaugeAverage>
9473
9474 Calculate the average of all values matched during the interval.
9475
9476 =item B<GaugeMin>
9477
9478 Report the smallest value matched during the interval.
9479
9480 =item B<GaugeMax>
9481
9482 Report the greatest value matched during the interval.
9483
9484 =item B<GaugeLast>
9485
9486 Report the last value matched during the interval.
9487
9488 =item B<GaugePersist>
9489
9490 Report the last matching value. The metric is I<not> reset to C<NaN> at the end
9491 of an interval. It is continuously reported until another value is matched.
9492 This is intended for cases in which only state changes are reported, for
9493 example a thermometer that only reports the temperature when it changes.
9494
9495 =item B<CounterSet>
9496
9497 =item B<DeriveSet>
9498
9499 =item B<AbsoluteSet>
9500
9501 The matched number is a counter. Simply I<sets> the internal counter to this
9502 value. Variants exist for C<COUNTER>, C<DERIVE>, and C<ABSOLUTE> data sources.
9503
9504 =item B<GaugeAdd>
9505
9506 =item B<CounterAdd>
9507
9508 =item B<DeriveAdd>
9509
9510 Add the matched value to the internal counter. In case of B<DeriveAdd>, the
9511 matched number may be negative, which will effectively subtract from the
9512 internal counter.
9513
9514 =item B<GaugeInc>
9515
9516 =item B<CounterInc>
9517
9518 =item B<DeriveInc>
9519
9520 Increase the internal counter by one. These B<DSType> are the only ones that do
9521 not use the matched subexpression, but simply count the number of matched
9522 lines. Thus, you may use a regular expression without submatch in this case.
9523
9524 B<GaugeInc> is reset to I<zero> after every read, unlike other B<Gauge*>
9525 metrics which are reset to C<NaN>.
9526
9527 =item B<Distribution>
9528
9529 Type to do calculations based on the distribution of values, primarily
9530 calculating percentiles. This is primarily geared towards latency, but can be
9531 used for other metrics as well. The range of values tracked with this setting
9532 must be in the range (0–2^34) and can be fractional. Please note that neither
9533 zero nor 2^34 are inclusive bounds, i.e. zero I<cannot> be handled by a
9534 distribution.
9535
9536 This option must be used together with the B<Percentile> and/or B<Bucket>
9537 options.
9538
9539 B<Synopsis:>
9540
9541 <DSType "Distribution">
9542 Percentile 99
9543 Bucket 0 100
9544 BucketType "bucket"
9545 </DSType>
9546
9547 =over 4
9548
9549 =item B<Percentile> I<Percent>
9550
9551 Calculate and dispatch the configured percentile, i.e. compute the value, so
9552 that I<Percent> of all matched values are smaller than or equal to the computed
9553 latency.
9554
9555 Metrics are reported with the I<type> B<Type> (the value of the above option)
9556 and the I<type instance> C<[E<lt>InstanceE<gt>-]E<lt>PercentE<gt>>.
9557
9558 This option may be repeated to calculate more than one percentile.
9559
9560 =item B<Bucket> I<lower_bound> I<upper_bound>
9561
9562 Export the number of values (a C<DERIVE>) falling within the given range. Both,
9563 I<lower_bound> and I<upper_bound> may be a fractional number, such as B<0.5>.
9564 Each B<Bucket> option specifies an interval C<(I<lower_bound>,
9565 I<upper_bound>]>, i.e. the range I<excludes> the lower bound and I<includes>
9566 the upper bound. I<lower_bound> and I<upper_bound> may be zero, meaning no
9567 lower/upper bound.
9568
9569 To export the entire (0–inf) range without overlap, use the upper bound of the
9570 previous range as the lower bound of the following range. In other words, use
9571 the following schema:
9572
9573 Bucket 0 1
9574 Bucket 1 2
9575 Bucket 2 5
9576 Bucket 5 10
9577 Bucket 10 20
9578 Bucket 20 50
9579 Bucket 50 0
9580
9581 Metrics are reported with the I<type> set by B<BucketType> option (C<bucket>
9582 by default) and the I<type instance>
9583 C<E<lt>TypeE<gt>[-E<lt>InstanceE<gt>]-E<lt>lower_boundE<gt>_E<lt>upper_boundE<gt>>.
9584
9585 This option may be repeated to calculate more than one rate.
9586
9587 =item B<BucketType> I<Type>
9588
9589 Sets the type used to dispatch B<Bucket> metrics.
9590 Optional, by default C<bucket> will be used.
9591
9592 =back
9593
9594 =back
9595
9596 The B<Gauge*> and B<Distribution> types interpret the submatch as a floating
9597 point number, using L<strtod(3)>. The B<Counter*> and B<AbsoluteSet> types
9598 interpret the submatch as an unsigned integer using L<strtoull(3)>. The
9599 B<Derive*> types interpret the submatch as a signed integer using
9600 L<strtoll(3)>. B<CounterInc>, B<DeriveInc> and B<GaugeInc> do not use the
9601 submatch at all and it may be omitted in this case.
9602
9603 The B<Gauge*> types, unless noted otherwise, are reset to C<NaN> after being
9604 reported. In other words, B<GaugeAverage> reports the average of all values
9605 matched since the last metric was reported (or C<NaN> if there was no match).
9606
9607 =item B<Type> I<Type>
9608
9609 Sets the type used to dispatch this value. Detailed information about types and
9610 their configuration can be found in L<types.db(5)>.
9611
9612 =item B<Instance> I<TypeInstance>
9613
9614 This optional setting sets the type instance to use.
9615
9616 =back
9617
9618 =head2 Plugin C<tail_csv>
9619
9620 The I<tail_csv plugin> reads files in the CSV format, e.g. the statistics file
9621 written by I<Snort>.
9622
9623 B<Synopsis:>
9624
9625 <Plugin "tail_csv">
9626 <Metric "snort-dropped">
9627 Type "percent"
9628 Instance "dropped"
9629 ValueFrom 1
9630 </Metric>
9631 <File "/var/log/snort/snort.stats">
9632 Plugin "snortstats"
9633 Instance "eth0"
9634 Interval 600
9635 Collect "snort-dropped"
9636 FieldSeparator ","
9637 #TimeFrom 0
9638 </File>
9639 </Plugin>
9640
9641 The configuration consists of one or more B<Metric> blocks that define an index
9642 into the line of the CSV file and how this value is mapped to I<collectd's>
9643 internal representation. These are followed by one or more B<Instance> blocks
9644 which configure which file to read, in which interval and which metrics to
9645 extract.
9646
9647 =over 4
9648
9649 =item E<lt>B<Metric> I<Name>E<gt>
9650
9651 The B<Metric> block configures a new metric to be extracted from the statistics
9652 file and how it is mapped on I<collectd's> data model. The string I<Name> is
9653 only used inside the B<Instance> blocks to refer to this block, so you can use
9654 one B<Metric> block for multiple CSV files.
9655
9656 =over 4
9657
9658 =item B<Type> I<Type>
9659
9660 Configures which I<Type> to use when dispatching this metric. Types are defined
9661 in the L<types.db(5)> file, see the appropriate manual page for more
9662 information on specifying types. Only types with a single I<data source> are
9663 supported by the I<tail_csv plugin>. The information whether the value is an
9664 absolute value (i.e. a C<GAUGE>) or a rate (i.e. a C<DERIVE>) is taken from the
9665 I<Type's> definition.
9666
9667 =item B<Instance> I<TypeInstance>
9668
9669 If set, I<TypeInstance> is used to populate the type instance field of the
9670 created value lists. Otherwise, no type instance is used.
9671
9672 =item B<ValueFrom> I<Index>
9673
9674 Configure to read the value from the field with the zero-based index I<Index>.
9675 If the value is parsed as signed integer, unsigned integer or double depends on
9676 the B<Type> setting, see above.
9677
9678 =back
9679
9680 =item E<lt>B<File> I<Path>E<gt>
9681
9682 Each B<File> block represents one CSV file to read. There must be at least one
9683 I<File> block but there can be multiple if you have multiple CSV files.
9684
9685 =over 4
9686
9687 =item B<Plugin> I<Plugin>
9688
9689 Use I<Plugin> as the plugin name when submitting values.
9690 Defaults to C<tail_csv>.
9691
9692 =item B<Instance> I<PluginInstance>
9693
9694 Sets the I<plugin instance> used when dispatching the values.
9695
9696 =item B<Collect> I<Metric>
9697
9698 Specifies which I<Metric> to collect. This option must be specified at least
9699 once, and you can use this option multiple times to specify more than one
9700 metric to be extracted from this statistic file.
9701
9702 =item B<Interval> I<Seconds>
9703
9704 Configures the interval in which to read values from this instance / file.
9705 Defaults to the plugin's default interval.
9706
9707 =item B<TimeFrom> I<Index>
9708
9709 Rather than using the local time when dispatching a value, read the timestamp
9710 from the field with the zero-based index I<Index>. The value is interpreted as
9711 seconds since epoch. The value is parsed as a double and may be factional.
9712
9713 =item B<FieldSeparator> I<Character>
9714
9715 Specify the character to use as field separator while parsing the CSV.
9716 Defaults to ',' if not specified. The value can only be a single character.
9717
9718 =back
9719
9720 =back
9721
9722 =head2 Plugin C<teamspeak2>
9723
9724 The C<teamspeak2 plugin> connects to the query port of a teamspeak2 server and
9725 polls interesting global and virtual server data. The plugin can query only one
9726 physical server but unlimited virtual servers. You can use the following
9727 options to configure it:
9728
9729 =over 4
9730
9731 =item B<Host> I<hostname/ip>
9732
9733 The hostname or ip which identifies the physical server.
9734 Default: 127.0.0.1
9735
9736 =item B<Port> I<port>
9737
9738 The query port of the physical server. This needs to be a string.
9739 Default: "51234"
9740
9741 =item B<Server> I<port>
9742
9743 This option has to be added once for every virtual server the plugin should
9744 query. If you want to query the virtual server on port 8767 this is what the
9745 option would look like:
9746
9747 Server "8767"
9748
9749 This option, although numeric, needs to be a string, i.E<nbsp>e. you B<must>
9750 use quotes around it! If no such statement is given only global information
9751 will be collected.
9752
9753 =back
9754
9755 =head2 Plugin C<ted>
9756
9757 The I<TED> plugin connects to a device of "The Energy Detective", a device to
9758 measure power consumption. These devices are usually connected to a serial
9759 (RS232) or USB port. The plugin opens a configured device and tries to read the
9760 current energy readings. For more information on TED, visit
9761 L<http://www.theenergydetective.com/>.
9762
9763 Available configuration options:
9764
9765 =over 4
9766
9767 =item B<Device> I<Path>
9768
9769 Path to the device on which TED is connected. collectd will need read and write
9770 permissions on that file.
9771
9772 Default: B</dev/ttyUSB0>
9773
9774 =item B<Retries> I<Num>
9775
9776 Apparently reading from TED is not that reliable. You can therefore configure a
9777 number of retries here. You only configure the I<retries> here, to if you
9778 specify zero, one reading will be performed (but no retries if that fails); if
9779 you specify three, a maximum of four readings are performed. Negative values
9780 are illegal.
9781
9782 Default: B<0>
9783
9784 =back
9785
9786 =head2 Plugin C<tcpconns>
9787
9788 The C<tcpconns plugin> counts the number of currently established TCP
9789 connections based on the local port and/or the remote port. Since there may be
9790 a lot of connections the default if to count all connections with a local port,
9791 for which a listening socket is opened. You can use the following options to
9792 fine-tune the ports you are interested in:
9793
9794 =over 4
9795
9796 =item B<ListeningPorts> I<true>|I<false>
9797
9798 If this option is set to I<true>, statistics for all local ports for which a
9799 listening socket exists are collected. The default depends on B<LocalPort> and
9800 B<RemotePort> (see below): If no port at all is specifically selected, the
9801 default is to collect listening ports. If specific ports (no matter if local or
9802 remote ports) are selected, this option defaults to I<false>, i.E<nbsp>e. only
9803 the selected ports will be collected unless this option is set to I<true>
9804 specifically.
9805
9806 =item B<LocalPort> I<Port>
9807
9808 Count the connections to a specific local port. This can be used to see how
9809 many connections are handled by a specific daemon, e.E<nbsp>g. the mailserver.
9810 You have to specify the port in numeric form, so for the mailserver example
9811 you'd need to set B<25>.
9812
9813 =item B<RemotePort> I<Port>
9814
9815 Count the connections to a specific remote port. This is useful to see how
9816 much a remote service is used. This is most useful if you want to know how many
9817 connections a local service has opened to remote services, e.E<nbsp>g. how many
9818 connections a mail server or news server has to other mail or news servers, or
9819 how many connections a web proxy holds to web servers. You have to give the
9820 port in numeric form.
9821
9822 =item B<AllPortsSummary> I<true>|I<false>
9823
9824 If this option is set to I<true> a summary of statistics from all connections
9825 are collected. This option defaults to I<false>.
9826
9827 =back
9828
9829 =head2 Plugin C<thermal>
9830
9831 =over 4
9832
9833 =item B<ForceUseProcfs> I<true>|I<false>
9834
9835 By default, the I<Thermal plugin> tries to read the statistics from the Linux
9836 C<sysfs> interface. If that is not available, the plugin falls back to the
9837 C<procfs> interface. By setting this option to I<true>, you can force the
9838 plugin to use the latter. This option defaults to I<false>.
9839
9840 =item B<Device> I<Device>
9841
9842 Selects the name of the thermal device that you want to collect or ignore,
9843 depending on the value of the B<IgnoreSelected> option. This option may be
9844 used multiple times to specify a list of devices.
9845
9846 See F</"IGNORELISTS"> for details.
9847
9848 =item B<IgnoreSelected> I<true>|I<false>
9849
9850 Invert the selection: If set to true, all devices B<except> the ones that
9851 match the device names specified by the B<Device> option are collected. By
9852 default only selected devices are collected if a selection is made. If no
9853 selection is configured at all, B<all> devices are selected.
9854
9855 =back
9856
9857 =head2 Plugin C<threshold>
9858
9859 The I<Threshold plugin> checks values collected or received by I<collectd>
9860 against a configurable I<threshold> and issues I<notifications> if values are
9861 out of bounds.
9862
9863 Documentation for this plugin is available in the L<collectd-threshold(5)>
9864 manual page.
9865
9866 =head2 Plugin C<tokyotyrant>
9867
9868 The I<TokyoTyrant plugin> connects to a TokyoTyrant server and collects a
9869 couple metrics: number of records, and database size on disk.
9870
9871 =over 4
9872
9873 =item B<Host> I<Hostname/IP>
9874
9875 The hostname or IP which identifies the server.
9876 Default: B<127.0.0.1>
9877
9878 =item B<Port> I<Service/Port>
9879
9880 The query port of the server. This needs to be a string, even if the port is
9881 given in its numeric form.
9882 Default: B<1978>
9883
9884 =back
9885
9886 =head2 Plugin C<turbostat>
9887
9888 The I<Turbostat plugin> reads CPU frequency and C-state residency on modern
9889 Intel processors by using I<Model Specific Registers>.
9890
9891 =over 4
9892
9893 =item B<CoreCstates> I<Bitmask(Integer)>
9894
9895 Bit mask of the list of core C-states supported by the processor.
9896 This option should only be used if the automated detection fails.
9897 Default value extracted from the CPU model and family.
9898
9899 Currently supported C-states (by this plugin): 3, 6, 7
9900
9901 B<Example:>
9902
9903 All states (3, 6 and 7):
9904 (1<<3) + (1<<6) + (1<<7) = 392
9905
9906 =item B<PackageCstates> I<Bitmask(Integer)>
9907
9908 Bit mask of the list of packages C-states supported by the processor. This
9909 option should only be used if the automated detection fails. Default value
9910 extracted from the CPU model and family.
9911
9912 Currently supported C-states (by this plugin): 2, 3, 6, 7, 8, 9, 10
9913
9914 B<Example:>
9915
9916 States 2, 3, 6 and 7:
9917 (1<<2) + (1<<3) + (1<<6) + (1<<7) = 396
9918
9919 =item B<SystemManagementInterrupt> I<true>|I<false>
9920
9921 Boolean enabling the collection of the I/O System-Management Interrupt counter.
9922 This option should only be used if the automated detection fails or if you want
9923 to disable this feature.
9924
9925 =item B<DigitalTemperatureSensor> I<true>|I<false>
9926
9927 Boolean enabling the collection of the temperature of each core. This option
9928 should only be used if the automated detection fails or if you want to disable
9929 this feature.
9930
9931 =item B<TCCActivationTemp> I<Temperature>
9932
9933 I<Thermal Control Circuit Activation Temperature> of the installed CPU. This
9934 temperature is used when collecting the temperature of cores or packages. This
9935 option should only be used if the automated detection fails. Default value
9936 extracted from B<MSR_IA32_TEMPERATURE_TARGET>.
9937
9938 =item B<RunningAveragePowerLimit> I<Bitmask(Integer)>
9939
9940 Bit mask of the list of elements to be thermally monitored. This option should
9941 only be used if the automated detection fails or if you want to disable some
9942 collections. The different bits of this bit mask accepted by this plugin are:
9943
9944 =over 4
9945
9946 =item 0 ('1'): Package
9947
9948 =item 1 ('2'): DRAM
9949
9950 =item 2 ('4'): Cores
9951
9952 =item 3 ('8'): Embedded graphic device
9953
9954 =back
9955
9956 =item B<LogicalCoreNames> I<true>|I<false>
9957
9958 Boolean enabling the use of logical core numbering for per core statistics.
9959 When enabled, C<cpuE<lt>nE<gt>> is used as plugin instance, where I<n> is a
9960 dynamic number assigned by the kernel. Otherwise, C<coreE<lt>nE<gt>> is used
9961 if there is only one package and C<pkgE<lt>nE<gt>-coreE<lt>mE<gt>> if there is
9962 more than one, where I<n> is the n-th core of package I<m>.
9963
9964 =item B<RestoreAffinityPolicy> I<AllCPUs>|I<Restore>
9965
9966 Reading data from CPU has side-effect: collectd process's CPU affinity mask
9967 changes. After reading data is completed, affinity mask needs to be restored.
9968 This option allows to set restore policy.
9969
9970 B<AllCPUs> (the default): Restore the affinity by setting affinity to any/all
9971 CPUs.
9972
9973 B<Restore>: Save affinity using sched_getaffinity() before reading data and
9974 restore it after.
9975
9976 On some systems, sched_getaffinity() will fail due to inconsistency of the CPU
9977 set size between userspace and kernel. In these cases plugin will detect the
9978 unsuccessful call and fail with an error, preventing data collection.
9979 Most of configurations does not need to save affinity as Collectd process is
9980 allowed to run on any/all available CPUs.
9981
9982 If you need to save and restore affinity and get errors like 'Unable to save
9983 the CPU affinity', setting 'possible_cpus' kernel boot option may also help.
9984
9985 See following links for details:
9986
9987 L<https://github.com/collectd/collectd/issues/1593>
9988 L<https://sourceware.org/bugzilla/show_bug.cgi?id=15630>
9989 L<https://bugzilla.kernel.org/show_bug.cgi?id=151821>
9990
9991 =back
9992
9993 =head2 Plugin C<ubi>
9994
9995 The I<Ubi plugin> collects some statistics about the UBI (Unsorted Block Image).
9996 Values collected are the number of bad physical eraseblocks on the underlying MTD
9997 (Memory Technology Device) and the maximum erase counter value concerning one volume.
9998
9999 See following links for details:
10000
10001 L<http://www.linux-mtd.infradead.org/doc/ubi.html>
10002 L<http://www.linux-mtd.infradead.org/doc/ubifs.html>
10003 L<https://www.kernel.org/doc/Documentation/ABI/stable/sysfs-class-ubi>
10004
10005 =over 4
10006
10007 =item B<Device> I<Name>
10008
10009 Select the device I<Name> of the UBI volume. Whether it is collected or ignored
10010 depends on the B<IgnoreSelected> setting, see below.
10011
10012 See F</"IGNORELISTS"> for details.
10013
10014 =item B<IgnoreSelected> B<true>|B<false>
10015
10016 Sets whether selected devices, i.E<nbsp>e. the ones matches by any of the B<Device>
10017 statements, are ignored or if all other devices are ignored. If no B<Device> option
10018 is configured, all devices are collected. If at least one B<Device> is given and no
10019 B<IgnoreSelected> or set to B<false>, B<only> matching disks will be collected. If
10020 B<IgnoreSelected>is set to B<true>, all devices are collected B<except> the ones
10021 matched.
10022
10023 =back
10024
10025 =head2 Plugin C<unixsock>
10026
10027 =over 4
10028
10029 =item B<SocketFile> I<Path>
10030
10031 Sets the socket-file which is to be created.
10032
10033 =item B<SocketGroup> I<Group>
10034
10035 If running as root change the group of the UNIX-socket after it has been
10036 created. Defaults to B<collectd>.
10037
10038 =item B<SocketPerms> I<Permissions>
10039
10040 Change the file permissions of the UNIX-socket after it has been created. The
10041 permissions must be given as a numeric, octal value as you would pass to
10042 L<chmod(1)>. Defaults to B<0770>.
10043
10044 =item B<DeleteSocket> B<false>|B<true>
10045
10046 If set to B<true>, delete the socket file before calling L<bind(2)>, if a file
10047 with the given name already exists. If I<collectd> crashes a socket file may be
10048 left over, preventing the daemon from opening a new socket when restarted.
10049 Since this is potentially dangerous, this defaults to B<false>.
10050
10051 =back
10052
10053 =head2 Plugin C<uuid>
10054
10055 This plugin, if loaded, causes the Hostname to be taken from the machine's
10056 UUID. The UUID is a universally unique designation for the machine, usually
10057 taken from the machine's BIOS. This is most useful if the machine is running in
10058 a virtual environment such as Xen, in which case the UUID is preserved across
10059 shutdowns and migration.
10060
10061 The following methods are used to find the machine's UUID, in order:
10062
10063 =over 4
10064
10065 =item *
10066
10067 Check I</etc/uuid> (or I<UUIDFile>).
10068
10069 =item *
10070
10071 Check for UUID from HAL (L<http://www.freedesktop.org/wiki/Software/hal>) if
10072 present.
10073
10074 =item *
10075
10076 Check for UUID from C<dmidecode> / SMBIOS.
10077
10078 =item *
10079
10080 Check for UUID from Xen hypervisor.
10081
10082 =back
10083
10084 If no UUID can be found then the hostname is not modified.
10085
10086 =over 4
10087
10088 =item B<UUIDFile> I<Path>
10089
10090 Take the UUID from the given file (default I</etc/uuid>).
10091
10092 =back
10093
10094 =head2 Plugin C<varnish>
10095
10096 The I<varnish plugin> collects information about Varnish, an HTTP accelerator.
10097 It collects a subset of the values displayed by L<varnishstat(1)>, and
10098 organizes them in categories which can be enabled or disabled. Currently only
10099 metrics shown in L<varnishstat(1)>'s I<MAIN> section are collected. The exact
10100 meaning of each metric can be found in L<varnish-counters(7)>.
10101
10102 Synopsis:
10103
10104 <Plugin "varnish">
10105 <Instance "example">
10106 CollectBackend true
10107 CollectBan false
10108 CollectCache true
10109 CollectConnections true
10110 CollectDirectorDNS false
10111 CollectESI false
10112 CollectFetch false
10113 CollectHCB false
10114 CollectObjects false
10115 CollectPurge false
10116 CollectSession false
10117 CollectSHM true
10118 CollectSMA false
10119 CollectSMS false
10120 CollectSM false
10121 CollectStruct false
10122 CollectTotals false
10123 CollectUptime false
10124 CollectVCL false
10125 CollectVSM false
10126 CollectWorkers false
10127 CollectLock false
10128 CollectMempool false
10129 CollectManagement false
10130 CollectSMF false
10131 CollectVBE false
10132 CollectMSE false
10133 </Instance>
10134 </Plugin>
10135
10136 The configuration consists of one or more E<lt>B<Instance>E<nbsp>I<Name>E<gt>
10137 blocks. I<Name> is the parameter passed to "varnishd -n". If left empty, it
10138 will collectd statistics from the default "varnishd" instance (this should work
10139 fine in most cases).
10140
10141 Inside each E<lt>B<Instance>E<gt> blocks, the following options are recognized:
10142
10143 =over 4
10144
10145 =item B<CollectBackend> B<true>|B<false>
10146
10147 Back-end connection statistics, such as successful, reused,
10148 and closed connections. True by default.
10149
10150 =item B<CollectBan> B<true>|B<false>
10151
10152 Statistics about ban operations, such as number of bans added, retired, and
10153 number of objects tested against ban operations. Only available with Varnish
10154 3.x and above. False by default.
10155
10156 =item B<CollectCache> B<true>|B<false>
10157
10158 Cache hits and misses. True by default.
10159
10160 =item B<CollectConnections> B<true>|B<false>
10161
10162 Number of client connections received, accepted and dropped. True by default.
10163
10164 =item B<CollectDirectorDNS> B<true>|B<false>
10165
10166 DNS director lookup cache statistics. Only available with Varnish 3.x. False by
10167 default.
10168
10169 =item B<CollectESI> B<true>|B<false>
10170
10171 Edge Side Includes (ESI) parse statistics. False by default.
10172
10173 =item B<CollectFetch> B<true>|B<false>
10174
10175 Statistics about fetches (HTTP requests sent to the backend). False by default.
10176
10177 =item B<CollectHCB> B<true>|B<false>
10178
10179 Inserts and look-ups in the crit bit tree based hash. Look-ups are
10180 divided into locked and unlocked look-ups. False by default.
10181
10182 =item B<CollectObjects> B<true>|B<false>
10183
10184 Statistics on cached objects: number of objects expired, nuked (prematurely
10185 expired), saved, moved, etc. False by default.
10186
10187 =item B<CollectPurge> B<true>|B<false>
10188
10189 Statistics about purge operations, such as number of purges added, retired, and
10190 number of objects tested against purge operations. Only available with Varnish
10191 2.x. False by default.
10192
10193 =item B<CollectSession> B<true>|B<false>
10194
10195 Client session statistics. Number of past and current sessions, session herd and
10196 linger counters, etc. False by default. Note that if using Varnish 4.x, some
10197 metrics found in the Connections and Threads sections with previous versions of
10198 Varnish have been moved here.
10199
10200 =item B<CollectSHM> B<true>|B<false>
10201
10202 Statistics about the shared memory log, a memory region to store
10203 log messages which is flushed to disk when full. True by default.
10204
10205 =item B<CollectSMA> B<true>|B<false>
10206
10207 malloc or umem (umem_alloc(3MALLOC) based) storage statistics. The umem storage
10208 component is Solaris specific. Note: SMA, SMF and MSE share counters, enable
10209 only the one used by the Varnish instance. Available with Varnish 2.x,
10210 varnish 4.x and above (Not available in varnish 3.x).
10211 False by default.
10212
10213 =item B<CollectSMS> B<true>|B<false>
10214
10215 synth (synthetic content) storage statistics. This storage
10216 component is used internally only. False by default.
10217
10218 =item B<CollectSM> B<true>|B<false>
10219
10220 file (memory mapped file) storage statistics. Only available with Varnish 2.x,
10221 in varnish 4.x and above use CollectSMF.
10222 False by default.
10223
10224 =item B<CollectStruct> B<true>|B<false>
10225
10226 Current varnish internal state statistics. Number of current sessions, objects
10227 in cache store, open connections to backends (with Varnish 2.x), etc. False by
10228 default.
10229
10230 =item B<CollectTotals> B<true>|B<false>
10231
10232 Collects overview counters, such as the number of sessions created,
10233 the number of requests and bytes transferred. False by default.
10234
10235 =item B<CollectUptime> B<true>|B<false>
10236
10237 Varnish uptime. Only available with Varnish 3.x and above. False by default.
10238
10239 =item B<CollectVCL> B<true>|B<false>
10240
10241 Number of total (available + discarded) VCL (config files). False by default.
10242
10243 =item B<CollectVSM> B<true>|B<false>
10244
10245 Collect statistics about Varnish's shared memory usage (used by the logging and
10246 statistics subsystems). Only available with Varnish 4.x. False by default.
10247
10248 =item B<CollectWorkers> B<true>|B<false>
10249
10250 Collect statistics about worker threads. False by default.
10251
10252 =item B<CollectVBE> B<true>|B<false>
10253
10254 Backend counters. Only available with Varnish 4.x and above. False by default.
10255
10256 =item B<CollectSMF> B<true>|B<false>
10257
10258 file (memory mapped file) storage statistics. Only available with Varnish 4.x and above.
10259 Note: SMA, SMF and MSE share counters, enable only the one used by the Varnish
10260 instance. Used to be called SM in Varnish 2.x. False by default.
10261
10262 =item B<CollectManagement> B<true>|B<false>
10263
10264 Management process counters. Only available with Varnish 4.x and above. False by default.
10265
10266 =item B<CollectLock> B<true>|B<false>
10267
10268 Lock counters. Only available with Varnish 4.x and above. False by default.
10269
10270 =item B<CollectMempool> B<true>|B<false>
10271
10272 Memory pool counters. Only available with Varnish 4.x and above. False by default.
10273
10274 =item B<CollectMSE> B<true>|B<false>
10275
10276 Varnish Massive Storage Engine 2.0 (MSE2) is an improved storage backend for
10277 Varnish, replacing the traditional malloc and file storages. Only available
10278 with Varnish-Plus 4.x and above. Note: SMA, SMF and MSE share counters, enable only the
10279 one used by the Varnish instance. False by default.
10280
10281 =item B<CollectGOTO> B<true>|B<false>
10282
10283 vmod-goto counters. Only available with Varnish Plus 6.x. False by default.
10284
10285 =back
10286
10287 =head2 Plugin C<virt>
10288
10289 This plugin allows CPU, disk, network load and other metrics to be collected for
10290 virtualized guests on the machine. The statistics are collected through libvirt
10291 API (L<http://libvirt.org/>). Majority of metrics can be gathered without
10292 installing any additional software on guests, especially I<collectd>, which runs
10293 only on the host system.
10294
10295 Only I<Connection> is required.
10296
10297 Consider the following example config:
10298
10299 <Plugin "virt">
10300 Connection "qemu:///system"
10301 HostnameFormat "hostname"
10302 InterfaceFormat "address"
10303 PluginInstanceFormat "name"
10304 </Plugin>
10305
10306 It will generate the following values:
10307
10308 node42.example.com/virt-instance-0006f26c/disk_octets-vda
10309 node42.example.com/virt-instance-0006f26c/disk_ops-vda
10310 node42.example.com/virt-instance-0006f26c/if_dropped-ca:fe:ca:fe:ca:fe
10311 node42.example.com/virt-instance-0006f26c/if_errors-ca:fe:ca:fe:ca:fe
10312 node42.example.com/virt-instance-0006f26c/if_octets-ca:fe:ca:fe:ca:fe
10313 node42.example.com/virt-instance-0006f26c/if_packets-ca:fe:ca:fe:ca:fe
10314 node42.example.com/virt-instance-0006f26c/memory-actual_balloon
10315 node42.example.com/virt-instance-0006f26c/memory-available
10316 node42.example.com/virt-instance-0006f26c/memory-last_update
10317 node42.example.com/virt-instance-0006f26c/memory-major_fault
10318 node42.example.com/virt-instance-0006f26c/memory-minor_fault
10319 node42.example.com/virt-instance-0006f26c/memory-rss
10320 node42.example.com/virt-instance-0006f26c/memory-swap_in
10321 node42.example.com/virt-instance-0006f26c/memory-swap_out
10322 node42.example.com/virt-instance-0006f26c/memory-total
10323 node42.example.com/virt-instance-0006f26c/memory-unused
10324 node42.example.com/virt-instance-0006f26c/memory-usable
10325 node42.example.com/virt-instance-0006f26c/virt_cpu_total
10326 node42.example.com/virt-instance-0006f26c/virt_vcpu-0
10327
10328 You can get information on the metric's units from the online libvirt documentation.
10329 For instance, I<virt_cpu_total> is in nanoseconds.
10330
10331 =over 4
10332
10333 =item B<Connection> I<uri>
10334
10335 Connect to the hypervisor given by I<uri>. For example if using Xen use:
10336
10337 Connection "xen:///"
10338
10339 Details which URIs allowed are given at L<http://libvirt.org/uri.html>.
10340
10341 =item B<RefreshInterval> I<seconds>
10342
10343 Refresh the list of domains and devices every I<seconds>. The default is 60
10344 seconds. Setting this to be the same or smaller than the I<Interval> will cause
10345 the list of domains and devices to be refreshed on every iteration.
10346
10347 Refreshing the devices in particular is quite a costly operation, so if your
10348 virtualization setup is static you might consider increasing this. If this
10349 option is set to 0, refreshing is disabled completely.
10350
10351 =item B<Domain> I<name>
10352
10353 =item B<BlockDevice> I<name:dev>
10354
10355 =item B<InterfaceDevice> I<name:dev>
10356
10357 =item B<IgnoreSelected> B<true>|B<false>
10358
10359 Select which domains and devices are collected.
10360
10361 If I<IgnoreSelected> is not given or B<false> then only the listed domains and
10362 disk/network devices are collected.
10363
10364 If I<IgnoreSelected> is B<true> then the test is reversed and the listed
10365 domains and disk/network devices are ignored, while the rest are collected.
10366
10367 The domain name and device names may use a regular expression, if the name is
10368 surrounded by I</.../> and collectd was compiled with support for regexps.
10369
10370 The default is to collect statistics for all domains and all their devices.
10371
10372 B<Note:> B<BlockDevice> and B<InterfaceDevice> options are related to
10373 corresponding B<*Format> options. Specifically, B<BlockDevice> filtering depends
10374 on B<BlockDeviceFormat> setting - if user wants to filter block devices by
10375 'target' name then B<BlockDeviceFormat> option has to be set to 'target' and
10376 B<BlockDevice> option must be set to a valid block device target
10377 name("/:hdb/"). Mixing formats and filter values from different worlds (i.e.,
10378 using 'target' name as B<BlockDevice> value with B<BlockDeviceFormat> set to
10379 'source') may lead to unexpected results (all devices filtered out or all
10380 visible, depending on the value of B<IgnoreSelected> option).
10381 Similarly, option B<InterfaceDevice> is related to B<InterfaceFormat> setting
10382 (i.e., when user wants to use MAC address as a filter then B<InterfaceFormat>
10383 has to be set to 'address' - using wrong type here may filter out all of the
10384 interfaces).
10385
10386 B<Example 1:>
10387
10388 Ignore all I<hdb> devices on any domain, but other block devices (eg. I<hda>)
10389 will be collected:
10390
10391 BlockDevice "/:hdb/"
10392 IgnoreSelected "true"
10393 BlockDeviceFormat "target"
10394
10395 B<Example 2:>
10396
10397 Collect metrics only for block device on 'baremetal0' domain when its
10398 'source' matches given path:
10399
10400 BlockDevice "baremetal0:/var/lib/libvirt/images/baremetal0.qcow2"
10401 BlockDeviceFormat source
10402
10403 As you can see it is possible to filter devices/interfaces using
10404 various formats - for block devices 'target' or 'source' name can be
10405 used. Interfaces can be filtered using 'name', 'address' or 'number'.
10406
10407 B<Example 3:>
10408
10409 Collect metrics only for domains 'baremetal0' and 'baremetal1' and
10410 ignore any other domain:
10411
10412 Domain "baremetal0"
10413 Domain "baremetal1"
10414
10415 It is possible to filter multiple block devices/domains/interfaces by
10416 adding multiple filtering entries in separate lines.
10417
10418 =item B<BlockDeviceFormat> B<target>|B<source>
10419
10420 If I<BlockDeviceFormat> is set to B<target>, the default, then the device name
10421 seen by the guest will be used for reporting metrics.
10422 This corresponds to the C<E<lt>targetE<gt>> node in the XML definition of the
10423 domain.
10424
10425 If I<BlockDeviceFormat> is set to B<source>, then metrics will be reported
10426 using the path of the source, e.g. an image file.
10427 This corresponds to the C<E<lt>sourceE<gt>> node in the XML definition of the
10428 domain.
10429
10430 B<Example:>
10431
10432 If the domain XML have the following device defined:
10433
10434 <disk type='block' device='disk'>
10435 <driver name='qemu' type='raw' cache='none' io='native' discard='unmap'/>
10436 <source dev='/var/lib/libvirt/images/image1.qcow2'/>
10437 <target dev='sda' bus='scsi'/>
10438 <boot order='2'/>
10439 <address type='drive' controller='0' bus='0' target='0' unit='0'/>
10440 </disk>
10441
10442 Setting C<BlockDeviceFormat target> will cause the I<type instance> to be set
10443 to C<sda>.
10444 Setting C<BlockDeviceFormat source> will cause the I<type instance> to be set
10445 to C<var_lib_libvirt_images_image1.qcow2>.
10446
10447 B<Note:> this option determines also what field will be used for
10448 filtering over block devices (filter value in B<BlockDevice>
10449 will be applied to target or source). More info about filtering
10450 block devices can be found in the description of B<BlockDevice>.
10451
10452 =item B<BlockDeviceFormatBasename> B<false>|B<true>
10453
10454 The B<BlockDeviceFormatBasename> controls whether the full path or the
10455 L<basename(1)> of the source is being used as the I<type instance> when
10456 B<BlockDeviceFormat> is set to B<source>. Defaults to B<false>.
10457
10458 B<Example:>
10459
10460 Assume the device path (source tag) is C</var/lib/libvirt/images/image1.qcow2>.
10461 Setting C<BlockDeviceFormatBasename false> will cause the I<type instance> to
10462 be set to C<var_lib_libvirt_images_image1.qcow2>.
10463 Setting C<BlockDeviceFormatBasename true> will cause the I<type instance> to be
10464 set to C<image1.qcow2>.
10465
10466 =item B<HostnameFormat> B<name|uuid|hostname|metadata...>
10467
10468 When the virt plugin logs data, it sets the hostname of the collected data
10469 according to this setting. The default is to use the guest name as provided by
10470 the hypervisor, which is equal to setting B<name>.
10471
10472 B<uuid> means use the guest's UUID. This is useful if you want to track the
10473 same guest across migrations.
10474
10475 B<hostname> means to use the global B<Hostname> setting, which is probably not
10476 useful on its own because all guests will appear to have the same name. This is
10477 useful in conjunction with B<PluginInstanceFormat> though.
10478
10479 B<metadata> means use information from guest's metadata. Use
10480 B<HostnameMetadataNS> and B<HostnameMetadataXPath> to localize this information.
10481
10482 You can also specify combinations of these fields. For example B<name uuid>
10483 means to concatenate the guest name and UUID (with a literal colon character
10484 between, thus I<"foo:1234-1234-1234-1234">).
10485
10486 At the moment of writing (collectd-5.5), hostname string is limited to 62
10487 characters. In case when combination of fields exceeds 62 characters,
10488 hostname will be truncated without a warning.
10489
10490 =item B<InterfaceFormat> B<name>|B<address>|B<number>
10491
10492 When the virt plugin logs interface data, it sets the name of the collected
10493 data according to this setting. The default is to use the path as provided by
10494 the hypervisor (the "dev" property of the target node), which is equal to
10495 setting B<name>.
10496
10497 B<address> means use the interface's mac address. This is useful since the
10498 interface path might change between reboots of a guest or across migrations.
10499
10500 B<number> means use the interface's number in guest.
10501
10502 B<Note:> this option determines also what field will be used for
10503 filtering over interface device (filter value in B<InterfaceDevice>
10504 will be applied to name, address or number). More info about filtering
10505 interfaces can be found in the description of B<InterfaceDevice>.
10506
10507 =item B<PluginInstanceFormat> B<name|uuid|metadata|none>
10508
10509 When the virt plugin logs data, it sets the plugin_instance of the collected
10510 data according to this setting. The default is to not set the plugin_instance.
10511
10512 B<name> means use the guest's name as provided by the hypervisor.
10513 B<uuid> means use the guest's UUID.
10514 B<metadata> means use information from guest's metadata.
10515
10516 You can also specify combinations of the B<name> and B<uuid> fields.
10517 For example B<name uuid> means to concatenate the guest name and UUID
10518 (with a literal colon character between, thus I<"foo:1234-1234-1234-1234">).
10519
10520 =item B<HostnameMetadataNS> B<string>
10521
10522 When B<metadata> is used in B<HostnameFormat> or B<PluginInstanceFormat>, this
10523 selects in which metadata namespace we will pick the hostname. The default is
10524 I<http://openstack.org/xmlns/libvirt/nova/1.0>.
10525
10526 =item B<HostnameMetadataXPath> B<string>
10527
10528 When B<metadata> is used in B<HostnameFormat> or B<PluginInstanceFormat>, this
10529 describes where the hostname is located in the libvirt metadata. The default is
10530 I</instance/name/text()>.
10531
10532 =item B<ReportBlockDevices> B<true>|B<false>
10533
10534 Enabled by default. Allows to disable stats reporting of block devices for
10535 whole plugin.
10536
10537 =item B<ReportNetworkInterfaces> B<true>|B<false>
10538
10539 Enabled by default. Allows to disable stats reporting of network interfaces for
10540 whole plugin.
10541
10542 =item B<ExtraStats> B<string>
10543
10544 Report additional extra statistics. The default is no extra statistics, preserving
10545 the previous behaviour of the plugin. If unsure, leave the default. If enabled,
10546 allows the plugin to reported more detailed statistics about the behaviour of
10547 Virtual Machines. The argument is a space-separated list of selectors.
10548
10549 Currently supported selectors are:
10550
10551 =over 4
10552
10553 =item B<cpu_util>: report CPU utilization per domain in percentage.
10554
10555 =item B<disk>: report extra statistics like number of flush operations and total
10556 service time for read, write and flush operations. Requires libvirt API version
10557 I<0.9.5> or later.
10558
10559 =item B<disk_err>: report disk errors if any occured. Requires libvirt API version
10560 I<0.9.10> or later.
10561
10562 =item B<domain_state>: report domain state and reason as 'domain_state' metric.
10563
10564 =item B<fs_info>: report file system information as a notification. Requires
10565 libvirt API version I<1.2.11> or later. Can be collected only if I<Guest Agent>
10566 is installed and configured inside VM. Make sure that installed I<Guest Agent>
10567 version supports retrieving file system information.
10568
10569 =item B<job_stats_background>: report statistics about progress of a background
10570 job on a domain. Only one type of job statistics can be collected at the same time.
10571 Requires libvirt API version I<1.2.9> or later.
10572
10573 =item B<job_stats_completed>: report statistics about a recently completed job on
10574 a domain. Only one type of job statistics can be collected at the same time.
10575 Requires libvirt API version I<1.2.9> or later.
10576
10577 =item B<memory>: report statistics about memory usage details, provided
10578 by libvirt virDomainMemoryStats() function.
10579
10580 =item B<pcpu>: report the physical user/system cpu time consumed by the hypervisor, per-vm.
10581 Requires libvirt API version I<0.9.11> or later.
10582
10583 =item B<perf>: report performance monitoring events. To collect performance
10584 metrics they must be enabled for domain and supported by the platform. Requires
10585 libvirt API version I<1.3.3> or later.
10586 B<Note>: I<perf> metrics can't be collected if I<intel_rdt> plugin is enabled.
10587
10588 =item B<vcpu>: report domain virtual CPUs utilisation.
10589
10590 =item B<vcpupin>: report pinning of domain VCPUs to host physical CPUs.
10591
10592 =item B<disk_physical>: report 'disk_physical' statistic for disk device.
10593 B<Note>: This statistic is only reported for disk devices with 'source'
10594 property available.
10595
10596 =item B<disk_allocation>: report 'disk_allocation' statistic for disk device.
10597 B<Note>: This statistic is only reported for disk devices with 'source'
10598 property available.
10599
10600 =item B<disk_capacity>: report 'disk_capacity' statistic for disk device.
10601 B<Note>: This statistic is only reported for disk devices with 'source'
10602 property available.
10603
10604 =back
10605
10606 =item B<PersistentNotification> B<true>|B<false>
10607
10608 Override default configuration to only send notifications when there is a change
10609 in the lifecycle state of a domain. When set to true notifications will be sent
10610 for every read cycle. Default is false. Does not affect the stats being
10611 dispatched.
10612
10613 =item B<Instances> B<integer>
10614
10615 How many read instances you want to use for this plugin. The default is one,
10616 and the sensible setting is a multiple of the B<ReadThreads> value.
10617
10618 This option is only useful when domains are specially tagged.
10619 If you are not sure, just use the default setting.
10620
10621 The reader instance will only query the domains with attached matching tag.
10622 Tags should have the form of 'virt-X' where X is the reader instance number,
10623 starting from 0.
10624
10625 The special-purpose reader instance #0, guaranteed to be always present,
10626 will query all the domains with missing or unrecognized tag, so no domain will
10627 ever be left out.
10628
10629 Domain tagging is done with a custom attribute in the libvirt domain metadata
10630 section. Value is selected by an XPath I</domain/metadata/ovirtmap/tag/text()>
10631 expression in the I<http://ovirt.org/ovirtmap/tag/1.0> namespace.
10632 (XPath and namespace values are not configurable yet).
10633
10634 Tagging could be used by management applications to evenly spread the
10635 load among the reader threads, or to pin on the same threads all
10636 the libvirt domains which use the same shared storage, to minimize
10637 the disruption in presence of storage outages.
10638
10639 =back
10640
10641 =head2 Plugin C<vmem>
10642
10643 The C<vmem> plugin collects information about the usage of virtual memory.
10644 Since the statistics provided by the Linux kernel are very detailed, they are
10645 collected very detailed. However, to get all the details, you have to switch
10646 them on manually. Most people just want an overview over, such as the number of
10647 pages read from swap space.
10648
10649 =over 4
10650
10651 =item B<Verbose> B<true>|B<false>
10652
10653 Enables verbose collection of information. This will start collecting page
10654 "actions", e.E<nbsp>g. page allocations, (de)activations, steals and so on.
10655 Part of these statistics are collected on a "per zone" basis.
10656
10657 =back
10658
10659 =head2 Plugin C<vserver>
10660
10661 This plugin doesn't have any options. B<VServer> support is only available for
10662 Linux. It cannot yet be found in a vanilla kernel, though. To make use of this
10663 plugin you need a kernel that has B<VServer> support built in, i.E<nbsp>e. you
10664 need to apply the patches and compile your own kernel, which will then provide
10665 the F</proc/virtual> filesystem that is required by this plugin.
10666
10667 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
10668
10669 B<Note>: The traffic collected by this plugin accounts for the amount of
10670 traffic passing a socket which might be a lot less than the actual on-wire
10671 traffic (e.E<nbsp>g. due to headers and retransmission). If you want to
10672 collect on-wire traffic you could, for example, use the logging facilities of
10673 iptables to feed data for the guest IPs into the iptables plugin.
10674
10675 =head2 Plugin C<write_graphite>
10676
10677 The C<write_graphite> plugin writes data to I<Graphite>, an open-source metrics
10678 storage and graphing project. The plugin connects to I<Carbon>, the data layer
10679 of I<Graphite>, via I<TCP> or I<UDP> and sends data via the "line based"
10680 protocol (per default using portE<nbsp>2003). The data will be sent in blocks
10681 of at most 1428 bytes to minimize the number of network packets.
10682
10683 Synopsis:
10684
10685 <Plugin write_graphite>
10686 <Node "example">
10687 Host "localhost"
10688 Port "2003"
10689 Protocol "tcp"
10690 LogSendErrors true
10691 Prefix "collectd"
10692 UseTags false
10693 ReverseHost false
10694 </Node>
10695 </Plugin>
10696
10697 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
10698 blocks. Inside the B<Node> blocks, the following options are recognized:
10699
10700 =over 4
10701
10702 =item B<Host> I<Address>
10703
10704 Hostname or address to connect to. Defaults to C<localhost>.
10705
10706 =item B<Port> I<Service>
10707
10708 Service name or port number to connect to. Defaults to C<2003>.
10709
10710 =item B<Protocol> I<String>
10711
10712 Protocol to use when connecting to I<Graphite>. Defaults to C<tcp>.
10713
10714 =item B<ReconnectInterval> I<Seconds>
10715
10716 When set to non-zero, forces the connection to the Graphite backend to be
10717 closed and re-opend periodically. This behavior is desirable in environments
10718 where the connection to the Graphite backend is done through load balancers,
10719 for example. When set to zero, the default, the connetion is kept open for as
10720 long as possible.
10721
10722 =item B<LogSendErrors> B<false>|B<true>
10723
10724 If set to B<true> (the default), logs errors when sending data to I<Graphite>.
10725 If set to B<false>, it will not log the errors. This is especially useful when
10726 using Protocol UDP since many times we want to use the "fire-and-forget"
10727 approach and logging errors fills syslog with unneeded messages.
10728
10729 =item B<Prefix> I<String>
10730
10731 When B<UseTags> is I<false>, B<Prefix> value is added in front of the host name.
10732 When B<UseTags> is I<true>, B<Prefix> value is added in front of series name.
10733
10734 Dots and whitespace are I<not> escaped in this string (see B<EscapeCharacter>
10735 below).
10736
10737 =item B<Postfix> I<String>
10738
10739 When B<UseTags> is I<false>, B<Postfix> value appended to the host name.
10740 When B<UseTags> is I<true>, B<Postgix> value appended to the end of series name
10741 (before the first ; that separates the name from the tags).
10742
10743 Dots and whitespace are I<not> escaped in this string (see B<EscapeCharacter>
10744 below).
10745
10746 =item B<EscapeCharacter> I<Char>
10747
10748 I<Carbon> uses the dot (C<.>) as escape character and doesn't allow whitespace
10749 in the identifier. The B<EscapeCharacter> option determines which character
10750 dots, whitespace and control characters are replaced with. Defaults to
10751 underscore (C<_>).
10752
10753 =item B<StoreRates> B<false>|B<true>
10754
10755 If set to B<true> (the default), convert counter values to rates. If set to
10756 B<false> counter values are stored as is, i.E<nbsp>e. as an increasing integer
10757 number.
10758
10759 =item B<SeparateInstances> B<false>|B<true>
10760
10761 If set to B<true>, the plugin instance and type instance will be in their own
10762 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
10763 default), the plugin and plugin instance (and likewise the type and type
10764 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
10765
10766 Option value is not used when B<UseTags> is I<true>.
10767
10768 =item B<AlwaysAppendDS> B<false>|B<true>
10769
10770 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
10771 identifier. If set to B<false> (the default), this is only done when there is
10772 more than one DS.
10773
10774 =item B<PreserveSeparator> B<false>|B<true>
10775
10776 If set to B<false> (the default) the C<.> (dot) character is replaced with
10777 I<EscapeCharacter>. Otherwise, if set to B<true>, the C<.> (dot) character
10778 is preserved, i.e. passed through.
10779
10780 Option value is not used when B<UseTags> is I<true>.
10781
10782 =item B<DropDuplicateFields> B<false>|B<true>
10783
10784 If set to B<true>, detect and remove duplicate components in Graphite metric
10785 names. For example, the metric name C<host.load.load.shortterm> will
10786 be shortened to C<host.load.shortterm>.
10787
10788 =item B<UseTags> B<false>|B<true>
10789
10790 If set to B<true>, Graphite metric names will be generated as tagged series.
10791 This allows for much more flexibility than the traditional hierarchical layout.
10792
10793 Example:
10794 C<test.single;host=example.com;plugin=test;plugin_instance=foo;type=single;type_instance=bar>
10795
10796 You can use B<Postfix> option to add more tags by specifying it like
10797 C<;tag1=value1;tag2=value2>. Note what tagging support was added since Graphite
10798 version 1.1.x.
10799
10800 If set to B<true>, the B<SeparateInstances> and B<PreserveSeparator> settings
10801 are not used.
10802
10803 Default value: B<false>.
10804
10805 =item B<ReverseHost> B<false>|B<true>
10806
10807 If set to B<true>, the (dot separated) parts of the B<host> field of the
10808 I<value list> will be rewritten in reverse order. The rewrite happens I<before>
10809 special characters are replaced with the B<EscapeCharacter>.
10810
10811 This option might be convenient if the metrics are presented with Graphite in a
10812 DNS like tree structure (probably without replacing dots in hostnames).
10813
10814 Example:
10815 Hostname "node3.cluster1.example.com"
10816 LoadPlugin "cpu"
10817 LoadPlugin "write_graphite"
10818 <Plugin "write_graphite">
10819 <Node "graphite.example.com">
10820 EscapeCharacter "."
10821 ReverseHost true
10822 </Node>
10823 </Plugin>
10824
10825 result on the wire: com.example.cluster1.node3.cpu-0.cpu-idle 99.900993 1543010932
10826
10827 Default value: B<false>.
10828
10829 =back
10830
10831 =head2 Plugin C<write_log>
10832
10833 The C<write_log> plugin writes metrics as INFO log messages.
10834
10835 This plugin supports two output formats: I<Graphite> and I<JSON>.
10836
10837 Synopsis:
10838
10839 <Plugin write_log>
10840 Format Graphite
10841 </Plugin>
10842
10843 =over 4
10844
10845 =item B<Format> I<Format>
10846
10847 The output format to use. Can be one of C<Graphite> or C<JSON>.
10848
10849 =back
10850
10851 =head2 Plugin C<write_tsdb>
10852
10853 The C<write_tsdb> plugin writes data to I<OpenTSDB>, a scalable open-source
10854 time series database. The plugin connects to a I<TSD>, a masterless, no shared
10855 state daemon that ingests metrics and stores them in HBase. The plugin uses
10856 I<TCP> over the "line based" protocol with a default port 4242. The data will
10857 be sent in blocks of at most 1428 bytes to minimize the number of network
10858 packets.
10859
10860 Synopsis:
10861
10862 <Plugin write_tsdb>
10863 ResolveInterval 60
10864 ResolveJitter 60
10865 <Node "example">
10866 Host "tsd-1.my.domain"
10867 Port "4242"
10868 HostTags "status=production"
10869 </Node>
10870 </Plugin>
10871
10872 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
10873 blocks and global directives.
10874
10875 Global directives are:
10876
10877 =over 4
10878
10879 =item B<ResolveInterval> I<seconds>
10880
10881 =item B<ResolveJitter> I<seconds>
10882
10883 When I<collectd> connects to a TSDB node, it will request the hostname from
10884 DNS. This can become a problem if the TSDB node is unavailable or badly
10885 configured because collectd will request DNS in order to reconnect for every
10886 metric, which can flood your DNS. So you can cache the last value for
10887 I<ResolveInterval> seconds.
10888 Defaults to the I<Interval> of the I<write_tsdb plugin>, e.g. 10E<nbsp>seconds.
10889
10890 You can also define a jitter, a random interval to wait in addition to
10891 I<ResolveInterval>. This prevents all your collectd servers to resolve the
10892 hostname at the same time when the connection fails.
10893 Defaults to the I<Interval> of the I<write_tsdb plugin>, e.g. 10E<nbsp>seconds.
10894
10895 B<Note:> If the DNS resolution has already been successful when the socket
10896 closes, the plugin will try to reconnect immediately with the cached
10897 information. DNS is queried only when the socket is closed for a longer than
10898 I<ResolveInterval> + I<ResolveJitter> seconds.
10899
10900 =back
10901
10902 Inside the B<Node> blocks, the following options are recognized:
10903
10904 =over 4
10905
10906 =item B<Host> I<Address>
10907
10908 Hostname or address to connect to. Defaults to C<localhost>.
10909
10910 =item B<Port> I<Service>
10911
10912 Service name or port number to connect to. Defaults to C<4242>.
10913
10914
10915 =item B<HostTags> I<String>
10916
10917 When set, I<HostTags> is added to the end of the metric. It is intended to be
10918 used for name=value pairs that the TSD will tag the metric with. Dots and
10919 whitespace are I<not> escaped in this string.
10920
10921 =item B<StoreRates> B<false>|B<true>
10922
10923 If set to B<true>, convert counter values to rates. If set to B<false>
10924 (the default) counter values are stored as is, as an increasing
10925 integer number.
10926
10927 =item B<AlwaysAppendDS> B<false>|B<true>
10928
10929 If set the B<true>, append the name of the I<Data Source> (DS) to the "metric"
10930 identifier. If set to B<false> (the default), this is only done when there is
10931 more than one DS.
10932
10933 =back
10934
10935 =head2 Plugin C<write_mongodb>
10936
10937 The I<write_mongodb plugin> will send values to I<MongoDB>, a schema-less
10938 NoSQL database.
10939
10940 B<Synopsis:>
10941
10942 <Plugin "write_mongodb">
10943 <Node "default">
10944 Host "localhost"
10945 Port "27017"
10946 Timeout 1000
10947 StoreRates true
10948 </Node>
10949 </Plugin>
10950
10951 The plugin can send values to multiple instances of I<MongoDB> by specifying
10952 one B<Node> block for each instance. Within the B<Node> blocks, the following
10953 options are available:
10954
10955 =over 4
10956
10957 =item B<Host> I<Address>
10958
10959 Hostname or address to connect to. Defaults to C<localhost>.
10960
10961 =item B<Port> I<Service>
10962
10963 Service name or port number to connect to. Defaults to C<27017>.
10964
10965 =item B<Timeout> I<Milliseconds>
10966
10967 Set the timeout for each operation on I<MongoDB> to I<Timeout> milliseconds.
10968 Setting this option to zero means no timeout, which is the default.
10969
10970 =item B<StoreRates> B<false>|B<true>
10971
10972 If set to B<true> (the default), convert counter values to rates. If set to
10973 B<false> counter values are stored as is, i.e. as an increasing integer
10974 number.
10975
10976 =item B<Database> I<Database>
10977
10978 =item B<User> I<User>
10979
10980 =item B<Password> I<Password>
10981
10982 Sets the information used when authenticating to a I<MongoDB> database. The
10983 fields are optional (in which case no authentication is attempted), but if you
10984 want to use authentication all three fields must be set.
10985
10986 =back
10987
10988 =head2 Plugin C<write_prometheus>
10989
10990 The I<write_prometheus plugin> implements a tiny webserver that can be scraped
10991 using I<Prometheus>.
10992
10993 B<Options:>
10994
10995 =over 4
10996
10997 =item B<Host> I<Host>
10998
10999 Bind to the hostname / address I<Host>. By default, the plugin will bind to the
11000 "any" address, i.e. accept packets sent to any of the hosts addresses.
11001
11002 This option is supported only for libmicrohttpd newer than 0.9.0.
11003
11004 =item B<Port> I<Port>
11005
11006 Port the embedded webserver should listen on. Defaults to B<9103>.
11007
11008 =item B<StalenessDelta> I<Seconds>
11009
11010 Time in seconds after which I<Prometheus> considers a metric "stale" if it
11011 hasn't seen any update for it. This value must match the setting in Prometheus.
11012 It defaults to B<300> seconds (5 minutes), same as Prometheus.
11013
11014 B<Background:>
11015
11016 I<Prometheus> has a global setting, C<StalenessDelta>, which controls after
11017 which time a metric without updates is considered "stale". This setting
11018 effectively puts an upper limit on the interval in which metrics are reported.
11019
11020 When the I<write_prometheus plugin> encounters a metric with an interval
11021 exceeding this limit, it will inform you, the user, and provide the metric to
11022 I<Prometheus> B<without> a timestamp. That causes I<Prometheus> to consider the
11023 metric "fresh" each time it is scraped, with the time of the scrape being
11024 considered the time of the update. The result is that there appear more
11025 datapoints in I<Prometheus> than were actually created, but at least the metric
11026 doesn't disappear periodically.
11027
11028 =back
11029
11030 =head2 Plugin C<write_http>
11031
11032 This output plugin submits values to an HTTP server using POST requests and
11033 encoding metrics with JSON or using the C<PUTVAL> command described in
11034 L<collectd-unixsock(5)>.
11035
11036 Synopsis:
11037
11038 <Plugin "write_http">
11039 <Node "example">
11040 URL "http://example.com/post-collectd"
11041 User "collectd"
11042 Password "weCh3ik0"
11043 Format JSON
11044 </Node>
11045 </Plugin>
11046
11047 The plugin can send values to multiple HTTP servers by specifying one
11048 E<lt>B<Node>E<nbsp>I<Name>E<gt> block for each server. Within each B<Node>
11049 block, the following options are available:
11050
11051 =over 4
11052
11053 =item B<URL> I<URL>
11054
11055 URL to which the values are submitted to. Mandatory.
11056
11057 =item B<User> I<Username>
11058
11059 Optional user name needed for authentication.
11060
11061 =item B<Password> I<Password>
11062
11063 Optional password needed for authentication.
11064
11065 =item B<VerifyPeer> B<true>|B<false>
11066
11067 Enable or disable peer SSL certificate verification. See
11068 L<http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by default.
11069
11070 =item B<VerifyHost> B<true|false>
11071
11072 Enable or disable peer host name verification. If enabled, the plugin checks if
11073 the C<Common Name> or a C<Subject Alternate Name> field of the SSL certificate
11074 matches the host name provided by the B<URL> option. If this identity check
11075 fails, the connection is aborted. Obviously, only works when connecting to a
11076 SSL enabled server. Enabled by default.
11077
11078 =item B<CACert> I<File>
11079
11080 File that holds one or more SSL certificates. If you want to use HTTPS you will
11081 possibly need this option. What CA certificates come bundled with C<libcurl>
11082 and are checked by default depends on the distribution you use.
11083
11084 =item B<CAPath> I<Directory>
11085
11086 Directory holding one or more CA certificate files. You can use this if for
11087 some reason all the needed CA certificates aren't in the same file and can't be
11088 pointed to using the B<CACert> option. Requires C<libcurl> to be built against
11089 OpenSSL.
11090
11091 =item B<ClientKey> I<File>
11092
11093 File that holds the private key in PEM format to be used for certificate-based
11094 authentication.
11095
11096 =item B<ClientCert> I<File>
11097
11098 File that holds the SSL certificate to be used for certificate-based
11099 authentication.
11100
11101 =item B<ClientKeyPass> I<Password>
11102
11103 Password required to load the private key in B<ClientKey>.
11104
11105 =item B<Header> I<Header>
11106
11107 A HTTP header to add to the request. Multiple headers are added if this option is specified more than once. Example:
11108
11109 Header "X-Custom-Header: custom_value"
11110
11111 =item B<SSLVersion> B<SSLv2>|B<SSLv3>|B<TLSv1>|B<TLSv1_0>|B<TLSv1_1>|B<TLSv1_2>
11112
11113 Define which SSL protocol version must be used. By default C<libcurl> will
11114 attempt to figure out the remote SSL protocol version. See
11115 L<curl_easy_setopt(3)> for more details.
11116
11117 =item B<Format> B<Command>|B<JSON>|B<KAIROSDB>
11118
11119 Format of the output to generate. If set to B<Command>, will create output that
11120 is understood by the I<Exec> and I<UnixSock> plugins. When set to B<JSON>, will
11121 create output in the I<JavaScript Object Notation> (JSON). When set to KAIROSDB
11122 , will create output in the KairosDB format.
11123
11124 Defaults to B<Command>.
11125
11126 =item B<Attribute> I<String> I<String>
11127
11128 Only available for the KAIROSDB output format.
11129
11130 Consider the two given strings to be the key and value of an additional tag for
11131 each metric being sent out.
11132
11133 You can add multiple B<Attribute>.
11134
11135 =item B<TTL> I<Int>
11136
11137 Only available for the KAIROSDB output format.
11138
11139 Sets the Cassandra ttl for the data points.
11140
11141 Please refer to L<http://kairosdb.github.io/docs/build/html/restapi/AddDataPoints.html?highlight=ttl>
11142
11143 =item B<Prefix> I<String>
11144
11145 Only available for the KAIROSDB output format.
11146
11147 Sets the metrics prefix I<string>. Defaults to I<collectd>.
11148
11149 =item B<Metrics> B<true>|B<false>
11150
11151 Controls whether I<metrics> are POSTed to this location. Defaults to B<true>.
11152
11153 =item B<Notifications> B<false>|B<true>
11154
11155 Controls whether I<notifications> are POSTed to this location. Defaults to B<false>.
11156
11157 =item B<StoreRates> B<true|false>
11158
11159 If set to B<true>, convert counter values to rates. If set to B<false> (the
11160 default) counter values are stored as is, i.e. as an increasing integer number.
11161
11162 =item B<BufferSize> I<Bytes>
11163
11164 Sets the send buffer size to I<Bytes>. By increasing this buffer, less HTTP
11165 requests will be generated, but more metrics will be batched / metrics are
11166 cached for longer before being sent, introducing additional delay until they
11167 are available on the server side. I<Bytes> must be at least 1024 and cannot
11168 exceed the size of an C<int>, i.e. 2E<nbsp>GByte.
11169 Defaults to C<4096>.
11170
11171 =item B<LowSpeedLimit> I<Bytes per Second>
11172
11173 Sets the minimal transfer rate in I<Bytes per Second> below which the
11174 connection with the HTTP server will be considered too slow and aborted. All
11175 the data submitted over this connection will probably be lost. Defaults to 0,
11176 which means no minimum transfer rate is enforced.
11177
11178 =item B<Timeout> I<Timeout>
11179
11180 Sets the maximum time in milliseconds given for HTTP POST operations to
11181 complete. When this limit is reached, the POST operation will be aborted, and
11182 all the data in the current send buffer will probably be lost. Defaults to 0,
11183 which means the connection never times out.
11184
11185 =item B<LogHttpError> B<false>|B<true>
11186
11187 Enables printing of HTTP error code to log. Turned off by default.
11188
11189 =item E<lt>B<Statistics> I<Name>E<gt>
11190
11191 One B<Statistics> block can be used to specify cURL statistics to be collected
11192 for each request to the remote URL. See the section "cURL Statistics" above
11193 for details.
11194
11195 The C<write_http> plugin regularly submits the collected values to the HTTP
11196 server. How frequently this happens depends on how much data you are collecting
11197 and the size of B<BufferSize>. The optimal value to set B<Timeout> to is
11198 slightly below this interval, which you can estimate by monitoring the network
11199 traffic between collectd and the HTTP server.
11200
11201
11202 =back
11203
11204 =head2 Plugin C<write_influxdb_udp>
11205
11206 The write_influxdb_udp plugin sends data to a instance of InfluxDB using the
11207 "Line Protocol". Each plugin is sent as a measurement with a time precision of
11208 miliseconds while plugin instance, type and type instance are sent as tags.
11209
11210 <Plugin "write_influxdb_udp">
11211 Server "influxdb.internal.tld"
11212 StoreRates "yes"
11213 </Plugin>
11214
11215 =over 4
11216
11217 =item B<E<lt>Server> I<Host> [I<Port>]B<E<gt>>
11218
11219 The B<Server> statement sets the server to send datagrams to.
11220
11221 The argument I<Host> may be a hostname, an IPv4 address or an IPv6 address. The
11222 optional second argument specifies a port number or a service name. If not
11223 given, the default, B<8089>, is used.
11224
11225 =item B<TimeToLive> I<1-255>
11226
11227 Set the time-to-live of sent packets. This applies to all, unicast and
11228 multicast, and IPv4 and IPv6 packets. The default is to not change this value.
11229 That means that multicast packets will be sent with a TTL of C<1> (one) on most
11230 operating systems.
11231
11232 =item B<MaxPacketSize> I<1024-65535>
11233
11234 Set the maximum size for datagrams received over the network. Packets larger
11235 than this will be truncated. Defaults to 1452E<nbsp>bytes, which is the maximum
11236 payload size that can be transmitted in one Ethernet frame using IPv6E<nbsp>/
11237 UDP.
11238
11239 =item B<StoreRates> B<true|false>
11240
11241 If set to B<true>, convert absolute, counter and derive values to rates. If set
11242 to B<false> (the default) absolute, counter and derive values are sent as is.
11243
11244 =back
11245
11246 =head2 Plugin C<write_kafka>
11247
11248 The I<write_kafka plugin> will send values to a I<Kafka> topic, a distributed
11249 queue.
11250 Synopsis:
11251
11252 <Plugin "write_kafka">
11253 Property "metadata.broker.list" "broker1:9092,broker2:9092"
11254 <Topic "collectd">
11255 Format JSON
11256 </Topic>
11257 </Plugin>
11258
11259 The following options are understood by the I<write_kafka plugin>:
11260
11261 =over 4
11262
11263 =item E<lt>B<Topic> I<Name>E<gt>
11264
11265 The plugin's configuration consists of one or more B<Topic> blocks. Each block
11266 is given a unique I<Name> and specifies one kafka producer.
11267 Inside the B<Topic> block, the following per-topic options are
11268 understood:
11269
11270 =over 4
11271
11272 =item B<Property> I<String> I<String>
11273
11274 Configure the named property for the current topic. Properties are
11275 forwarded to the kafka producer library B<librdkafka>.
11276
11277 =item B<Key> I<String>
11278
11279 Use the specified string as a partitioning key for the topic. Kafka breaks
11280 topic into partitions and guarantees that for a given topology, the same
11281 consumer will be used for a specific key. The special (case insensitive)
11282 string B<Random> can be used to specify that an arbitrary partition should
11283 be used.
11284
11285 =item B<Format> B<Command>|B<JSON>|B<Graphite>
11286
11287 Selects the format in which messages are sent to the broker. If set to
11288 B<Command> (the default), values are sent as C<PUTVAL> commands which are
11289 identical to the syntax used by the I<Exec> and I<UnixSock plugins>.
11290
11291 If set to B<JSON>, the values are encoded in the I<JavaScript Object Notation>,
11292 an easy and straight forward exchange format.
11293
11294 If set to B<Graphite>, values are encoded in the I<Graphite> format, which is
11295 C<E<lt>metricE<gt> E<lt>valueE<gt> E<lt>timestampE<gt>\n>.
11296
11297 =item B<StoreRates> B<true>|B<false>
11298
11299 Determines whether or not C<COUNTER>, C<DERIVE> and C<ABSOLUTE> data sources
11300 are converted to a I<rate> (i.e. a C<GAUGE> value). If set to B<false> (the
11301 default), no conversion is performed. Otherwise the conversion is performed
11302 using the internal value cache.
11303
11304 Please note that currently this option is only used if the B<Format> option has
11305 been set to B<JSON>.
11306
11307 =item B<GraphitePrefix> (B<Format>=I<Graphite> only)
11308
11309 A prefix can be added in the metric name when outputting in the I<Graphite>
11310 format.
11311
11312 When B<GraphiteUseTags> is I<false>, prefix is added before the I<Host> name.
11313 Metric name will be
11314 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>>
11315
11316 When B<GraphiteUseTags> is I<true>, prefix is added in front of series name.
11317
11318 =item B<GraphitePostfix> (B<Format>=I<Graphite> only)
11319
11320 A postfix can be added in the metric name when outputting in the I<Graphite>
11321 format.
11322
11323 When B<GraphiteUseTags> is I<false>, postfix is added after the I<Host> name.
11324 Metric name will be
11325 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>>
11326
11327 When B<GraphiteUseTags> is I<true>, prefix value appended to the end of series
11328 name (before the first ; that separates the name from the tags).
11329
11330 =item B<GraphiteEscapeChar> (B<Format>=I<Graphite> only)
11331
11332 Specify a character to replace dots (.) in the host part of the metric name.
11333 In I<Graphite> metric name, dots are used as separators between different
11334 metric parts (host, plugin, type).
11335 Default is C<_> (I<Underscore>).
11336
11337 =item B<GraphiteSeparateInstances> B<false>|B<true>
11338
11339 If set to B<true>, the plugin instance and type instance will be in their own
11340 path component, for example C<host.cpu.0.cpu.idle>. If set to B<false> (the
11341 default), the plugin and plugin instance (and likewise the type and type
11342 instance) are put into one component, for example C<host.cpu-0.cpu-idle>.
11343
11344 Option value is not used when B<GraphiteUseTags> is I<true>.
11345
11346 =item B<GraphiteAlwaysAppendDS> B<true>|B<false>
11347
11348 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
11349 identifier. If set to B<false> (the default), this is only done when there is
11350 more than one DS.
11351
11352 =item B<GraphitePreserveSeparator> B<false>|B<true>
11353
11354 If set to B<false> (the default) the C<.> (dot) character is replaced with
11355 I<GraphiteEscapeChar>. Otherwise, if set to B<true>, the C<.> (dot) character
11356 is preserved, i.e. passed through.
11357
11358 Option value is not used when B<GraphiteUseTags> is I<true>.
11359
11360 =item B<GraphiteUseTags> B<false>|B<true>
11361
11362 If set to B<true> Graphite metric names will be generated as tagged series.
11363
11364 Default value: B<false>.
11365
11366 =item B<StoreRates> B<true>|B<false>
11367
11368 If set to B<true> (the default), convert counter values to rates. If set to
11369 B<false> counter values are stored as is, i.e. as an increasing integer number.
11370
11371 This will be reflected in the C<ds_type> tag: If B<StoreRates> is enabled,
11372 converted values will have "rate" appended to the data source type, e.g.
11373 C<ds_type:derive:rate>.
11374
11375 =back
11376
11377 =item B<Property> I<String> I<String>
11378
11379 Configure the kafka producer through properties, you almost always will
11380 want to set B<metadata.broker.list> to your Kafka broker list.
11381
11382 =back
11383
11384 =head2 Plugin C<write_redis>
11385
11386 The I<write_redis plugin> submits values to I<Redis>, a data structure server.
11387
11388 Synopsis:
11389
11390 <Plugin "write_redis">
11391 <Node "example">
11392 Host "localhost"
11393 Port "6379"
11394 Timeout 1000
11395 Prefix "collectd/"
11396 Database 1
11397 MaxSetSize -1
11398 MaxSetDuration -1
11399 StoreRates true
11400 </Node>
11401 </Plugin>
11402
11403 Values are submitted to I<Sorted Sets>, using the metric name as the key, and
11404 the timestamp as the score. Retrieving a date range can then be done using the
11405 C<ZRANGEBYSCORE> I<Redis> command. Additionally, all the identifiers of these
11406 I<Sorted Sets> are kept in a I<Set> called C<collectd/values> (or
11407 C<${prefix}/values> if the B<Prefix> option was specified) and can be retrieved
11408 using the C<SMEMBERS> I<Redis> command. You can specify the database to use
11409 with the B<Database> parameter (default is C<0>). See
11410 L<http://redis.io/commands#sorted_set> and L<http://redis.io/commands#set> for
11411 details.
11412
11413 The information shown in the synopsis above is the I<default configuration>
11414 which is used by the plugin if no configuration is present.
11415
11416 The plugin can send values to multiple instances of I<Redis> by specifying
11417 one B<Node> block for each instance. Within the B<Node> blocks, the following
11418 options are available:
11419
11420 =over 4
11421
11422 =item B<Node> I<Nodename>
11423
11424 The B<Node> block identifies a new I<Redis> node, that is a new I<Redis>
11425 instance running on a specified host and port. The node name is a
11426 canonical identifier which is used as I<plugin instance>. It is limited to
11427 51E<nbsp>characters in length.
11428
11429 =item B<Host> I<Hostname>
11430
11431 The B<Host> option is the hostname or IP-address where the I<Redis> instance is
11432 running on.
11433
11434 =item B<Port> I<Port>
11435
11436 The B<Port> option is the TCP port on which the Redis instance accepts
11437 connections. Either a service name of a port number may be given. Please note
11438 that numerical port numbers must be given as a string, too.
11439
11440 =item B<Timeout> I<Milliseconds>
11441
11442 The B<Timeout> option sets the socket connection timeout, in milliseconds.
11443
11444 =item B<Prefix> I<Prefix>
11445
11446 Prefix used when constructing the name of the I<Sorted Sets> and the I<Set>
11447 containing all metrics. Defaults to C<collectd/>, so metrics will have names
11448 like C<collectd/cpu-0/cpu-user>. When setting this to something different, it
11449 is recommended but not required to include a trailing slash in I<Prefix>.
11450
11451 =item B<Database> I<Index>
11452
11453 This index selects the redis database to use for writing operations. Defaults
11454 to C<0>.
11455
11456 =item B<MaxSetSize> I<Items>
11457
11458 The B<MaxSetSize> option limits the number of items that the I<Sorted Sets> can
11459 hold. Negative values for I<Items> sets no limit, which is the default behavior.
11460
11461 =item B<MaxSetDuration> I<Seconds>
11462
11463 The B<MaxSetDuration> option limits the duration of items that the
11464 I<Sorted Sets> can hold. Negative values for I<Items> sets no duration, which
11465 is the default behavior.
11466
11467 =item B<StoreRates> B<true>|B<false>
11468
11469 If set to B<true> (the default), convert counter values to rates. If set to
11470 B<false> counter values are stored as is, i.e. as an increasing integer number.
11471
11472 =back
11473
11474 =head2 Plugin C<write_riemann>
11475
11476 The I<write_riemann plugin> will send values to I<Riemann>, a powerful stream
11477 aggregation and monitoring system. The plugin sends I<Protobuf> encoded data to
11478 I<Riemann> using UDP packets.
11479
11480 Synopsis:
11481
11482 <Plugin "write_riemann">
11483 <Node "example">
11484 Host "localhost"
11485 Port "5555"
11486 Protocol UDP
11487 StoreRates true
11488 AlwaysAppendDS false
11489 TTLFactor 2.0
11490 </Node>
11491 Tag "foobar"
11492 Attribute "foo" "bar"
11493 </Plugin>
11494
11495 The following options are understood by the I<write_riemann plugin>:
11496
11497 =over 4
11498
11499 =item E<lt>B<Node> I<Name>E<gt>
11500
11501 The plugin's configuration consists of one or more B<Node> blocks. Each block
11502 is given a unique I<Name> and specifies one connection to an instance of
11503 I<Riemann>. Indise the B<Node> block, the following per-connection options are
11504 understood:
11505
11506 =over 4
11507
11508 =item B<Host> I<Address>
11509
11510 Hostname or address to connect to. Defaults to C<localhost>.
11511
11512 =item B<Port> I<Service>
11513
11514 Service name or port number to connect to. Defaults to C<5555>.
11515
11516 =item B<Protocol> B<UDP>|B<TCP>|B<TLS>
11517
11518 Specify the protocol to use when communicating with I<Riemann>. Defaults to
11519 B<TCP>.
11520
11521 =item B<TLSCertFile> I<Path>
11522
11523 When using the B<TLS> protocol, path to a PEM certificate to present
11524 to remote host.
11525
11526 =item B<TLSCAFile> I<Path>
11527
11528 When using the B<TLS> protocol, path to a PEM CA certificate to
11529 use to validate the remote hosts's identity.
11530
11531 =item B<TLSKeyFile> I<Path>
11532
11533 When using the B<TLS> protocol, path to a PEM private key associated
11534 with the certificate defined by B<TLSCertFile>.
11535
11536 =item B<Batch> B<true>|B<false>
11537
11538 If set to B<true> and B<Protocol> is set to B<TCP>,
11539 events will be batched in memory and flushed at
11540 regular intervals or when B<BatchMaxSize> is exceeded.
11541
11542 Notifications are not batched and sent as soon as possible.
11543
11544 When enabled, it can occur that events get processed by the Riemann server
11545 close to or after their expiration time. Tune the B<TTLFactor> and
11546 B<BatchMaxSize> settings according to the amount of values collected, if this
11547 is an issue.
11548
11549 Defaults to true
11550
11551 =item B<BatchMaxSize> I<size>
11552
11553 Maximum payload size for a riemann packet. Defaults to 8192
11554
11555 =item B<BatchFlushTimeout> I<seconds>
11556
11557 Maximum amount of seconds to wait in between to batch flushes.
11558 No timeout by default.
11559
11560 =item B<StoreRates> B<true>|B<false>
11561
11562 If set to B<true> (the default), convert counter values to rates. If set to
11563 B<false> counter values are stored as is, i.e. as an increasing integer number.
11564
11565 This will be reflected in the C<ds_type> tag: If B<StoreRates> is enabled,
11566 converted values will have "rate" appended to the data source type, e.g.
11567 C<ds_type:derive:rate>.
11568
11569 =item B<AlwaysAppendDS> B<false>|B<true>
11570
11571 If set to B<true>, append the name of the I<Data Source> (DS) to the
11572 "service", i.e. the field that, together with the "host" field, uniquely
11573 identifies a metric in I<Riemann>. If set to B<false> (the default), this is
11574 only done when there is more than one DS.
11575
11576 =item B<TTLFactor> I<Factor>
11577
11578 I<Riemann> events have a I<Time to Live> (TTL) which specifies how long each
11579 event is considered active. I<collectd> populates this field based on the
11580 metrics interval setting. This setting controls the factor with which the
11581 interval is multiplied to set the TTL. The default value is B<2.0>. Unless you
11582 know exactly what you're doing, you should only increase this setting from its
11583 default value.
11584
11585 =item B<Notifications> B<false>|B<true>
11586
11587 If set to B<true>, create riemann events for notifications. This is B<true>
11588 by default. When processing thresholds from write_riemann, it might prove
11589 useful to avoid getting notification events.
11590
11591 =item B<CheckThresholds> B<false>|B<true>
11592
11593 If set to B<true>, attach state to events based on thresholds defined
11594 in the B<Threshold> plugin. Defaults to B<false>.
11595
11596 =item B<EventServicePrefix> I<String>
11597
11598 Add the given string as a prefix to the event service name.
11599 If B<EventServicePrefix> not set or set to an empty string (""),
11600 no prefix will be used.
11601
11602 =back
11603
11604 =item B<Tag> I<String>
11605
11606 Add the given string as an additional tag to the metric being sent to
11607 I<Riemann>.
11608
11609 =item B<Attribute> I<String> I<String>
11610
11611 Consider the two given strings to be the key and value of an additional
11612 attribute for each metric being sent out to I<Riemann>.
11613
11614 =back
11615
11616 =head2 Plugin C<write_sensu>
11617
11618 The I<write_sensu plugin> will send values to I<Sensu>, a powerful stream
11619 aggregation and monitoring system. The plugin sends I<JSON> encoded data to
11620 a local I<Sensu> client using a TCP socket.
11621
11622 Synopsis:
11623
11624 <Plugin "write_sensu">
11625 <Node "example">
11626 Host "localhost"
11627 Port "3030"
11628 StoreRates true
11629 AlwaysAppendDS false
11630 IncludeSource false
11631 MetricHandler "influx"
11632 MetricHandler "default"
11633 NotificationHandler "flapjack"
11634 NotificationHandler "howling_monkey"
11635 Notifications true
11636 </Node>
11637 Tag "foobar"
11638 Attribute "foo" "bar"
11639 </Plugin>
11640
11641 The following options are understood by the I<write_sensu plugin>:
11642
11643 =over 4
11644
11645 =item E<lt>B<Node> I<Name>E<gt>
11646
11647 The plugin's configuration consists of one or more B<Node> blocks. Each block
11648 is given a unique I<Name> and specifies one connection to an instance of
11649 I<Sensu>. Inside the B<Node> block, the following per-connection options are
11650 understood:
11651
11652 =over 4
11653
11654 =item B<Host> I<Address>
11655
11656 Hostname or address to connect to. Defaults to C<localhost>.
11657
11658 =item B<Port> I<Service>
11659
11660 Service name or port number to connect to. Defaults to C<3030>.
11661
11662 =item B<StoreRates> B<true>|B<false>
11663
11664 If set to B<true> (the default), convert counter values to rates. If set to
11665 B<false> counter values are stored as is, i.e. as an increasing integer number.
11666
11667 This will be reflected in the C<collectd_data_source_type> tag: If
11668 B<StoreRates> is enabled, converted values will have "rate" appended to the
11669 data source type, e.g. C<collectd_data_source_type:derive:rate>.
11670
11671 =item B<AlwaysAppendDS> B<false>|B<true>
11672
11673 If set the B<true>, append the name of the I<Data Source> (DS) to the
11674 "service", i.e. the field that, together with the "host" field, uniquely
11675 identifies a metric in I<Sensu>. If set to B<false> (the default), this is
11676 only done when there is more than one DS.
11677
11678 =item B<Notifications> B<false>|B<true>
11679
11680 If set to B<true>, create I<Sensu> events for notifications. This is B<false>
11681 by default. At least one of B<Notifications> or B<Metrics> should be enabled.
11682
11683 =item B<Metrics> B<false>|B<true>
11684
11685 If set to B<true>, create I<Sensu> events for metrics. This is B<false>
11686 by default. At least one of B<Notifications> or B<Metrics> should be enabled.
11687
11688
11689 =item B<Separator> I<String>
11690
11691 Sets the separator for I<Sensu> metrics name or checks. Defaults to "/".
11692
11693 =item B<MetricHandler> I<String>
11694
11695 Add a handler that will be set when metrics are sent to I<Sensu>. You can add
11696 several of them, one per line. Defaults to no handler.
11697
11698 =item B<NotificationHandler> I<String>
11699
11700 Add a handler that will be set when notifications are sent to I<Sensu>. You can
11701 add several of them, one per line. Defaults to no handler.
11702
11703 =item B<EventServicePrefix> I<String>
11704
11705 Add the given string as a prefix to the event service name.
11706 If B<EventServicePrefix> not set or set to an empty string (""),
11707 no prefix will be used.
11708
11709 =back
11710
11711 =item B<Tag> I<String>
11712
11713 Add the given string as an additional tag to the metric being sent to
11714 I<Sensu>.
11715
11716 =item B<Attribute> I<String> I<String>
11717
11718 Consider the two given strings to be the key and value of an additional
11719 attribute for each metric being sent out to I<Sensu>.
11720
11721 =item B<IncludeSource> B<false>|B<true>
11722
11723 If set to B<true>, then the source host of the metrics/notification is passed
11724 on to sensu using the source attribute. This may register the host as a proxy
11725 client in sensu.
11726
11727 If set to B<false> (the default), then the hostname is discarded, making it appear
11728 as if the event originated from the connected sensu agent.
11729
11730 =back
11731
11732 =head2 Plugin C<write_stackdriver>
11733
11734 The C<write_stackdriver> plugin writes metrics to the
11735 I<Google Stackdriver Monitoring> service.
11736
11737 This plugin supports two authentication methods: When configured, credentials
11738 are read from the JSON credentials file specified with B<CredentialFile>.
11739 Alternatively, when running on
11740 I<Google Compute Engine> (GCE), an I<OAuth> token is retrieved from the
11741 I<metadata server> and used to authenticate to GCM.
11742
11743 B<Synopsis:>
11744
11745 <Plugin write_stackdriver>
11746 CredentialFile "/path/to/service_account.json"
11747 <Resource "global">
11748 Label "project_id" "monitored_project"
11749 </Resource>
11750 </Plugin>
11751
11752 =over 4
11753
11754 =item B<CredentialFile> I<file>
11755
11756 Path to a JSON credentials file holding the credentials for a GCP service
11757 account.
11758
11759 If B<CredentialFile> is not specified, the plugin uses I<Application Default
11760 Credentials>. That means which credentials are used depends on the environment:
11761
11762 =over 4
11763
11764 =item
11765
11766 The environment variable C<GOOGLE_APPLICATION_CREDENTIALS> is checked. If this
11767 variable is specified it should point to a JSON file that defines the
11768 credentials.
11769
11770 =item
11771
11772 The path C<${HOME}/.config/gcloud/application_default_credentials.json> is
11773 checked. This where credentials used by the I<gcloud> command line utility are
11774 stored. You can use C<gcloud auth application-default login> to create these
11775 credentials.
11776
11777 Please note that these credentials are often of your personal account, not a
11778 service account, and are therefore unfit to be used in a production
11779 environment.
11780
11781 =item
11782
11783 When running on GCE, the built-in service account associated with the virtual
11784 machine instance is used.
11785 See also the B<Email> option below.
11786
11787 =back
11788
11789 =item B<Project> I<Project>
11790
11791 The I<Project ID> or the I<Project Number> of the I<Stackdriver Account>. The
11792 I<Project ID> is a string identifying the GCP project, which you can chose
11793 freely when creating a new project. The I<Project Number> is a 12-digit decimal
11794 number. You can look up both on the I<Developer Console>.
11795
11796 This setting is optional. If not set, the project ID is read from the
11797 credentials file or determined from the GCE's metadata service.
11798
11799 =item B<Email> I<Email> (GCE only)
11800
11801 Choses the GCE I<Service Account> used for authentication.
11802
11803 Each GCE instance has a C<default> I<Service Account> but may also be
11804 associated with additional I<Service Accounts>. This is often used to restrict
11805 the permissions of services running on the GCE instance to the required
11806 minimum. The I<write_stackdriver plugin> requires the
11807 C<https://www.googleapis.com/auth/monitoring> scope. When multiple I<Service
11808 Accounts> are available, this option selects which one is used by
11809 I<write_stackdriver plugin>.
11810
11811 =item B<Resource> I<ResourceType>
11812
11813 Configures the I<Monitored Resource> to use when storing metrics.
11814 More information on I<Monitored Resources> and I<Monitored Resource Types> are
11815 available at L<https://cloud.google.com/monitoring/api/resources>.
11816
11817 This block takes one string argument, the I<ResourceType>. Inside the block are
11818 one or more B<Label> options which configure the resource labels.
11819
11820 This block is optional. The default value depends on the runtime environment:
11821 on GCE, the C<gce_instance> resource type is used, otherwise the C<global>
11822 resource type ist used:
11823
11824 =over 4
11825
11826 =item
11827
11828 B<On GCE>, defaults to the equivalent of this config:
11829
11830 <Resource "gce_instance">
11831 Label "project_id" "<project_id>"
11832 Label "instance_id" "<instance_id>"
11833 Label "zone" "<zone>"
11834 </Resource>
11835
11836 The values for I<project_id>, I<instance_id> and I<zone> are read from the GCE
11837 metadata service.
11838
11839 =item
11840
11841 B<Elsewhere>, i.e. not on GCE, defaults to the equivalent of this config:
11842
11843 <Resource "global">
11844 Label "project_id" "<Project>"
11845 </Resource>
11846
11847 Where I<Project> refers to the value of the B<Project> option or the project ID
11848 inferred from the B<CredentialFile>.
11849
11850 =back
11851
11852 =item B<Url> I<Url>
11853
11854 URL of the I<Stackdriver Monitoring> API. Defaults to
11855 C<https://monitoring.googleapis.com/v3>.
11856
11857 =back
11858
11859 =head2 Plugin C<write_syslog>
11860
11861 The C<write_syslog> plugin writes data in I<syslog> format log messages.
11862 It implements the basic syslog protocol, RFC 5424, extends it with
11863 content-based filtering, rich filtering capabilities,
11864 flexible configuration options and adds features such as using TCP for transport.
11865 The plugin can connect to a I<Syslog> daemon, like syslog-ng and rsyslog, that will
11866 ingest metrics, transform and ship them to the specified output.
11867 The plugin uses I<TCP> over the "line based" protocol with a default port 44514.
11868 The data will be sent in blocks of at most 1428 bytes to minimize the number of
11869 network packets.
11870
11871 Synopsis:
11872
11873 <Plugin write_syslog>
11874 ResolveInterval 60
11875 ResolveJitter 60
11876 <Node "example">
11877 Host "syslog-1.my.domain"
11878 Port "44514"
11879 Prefix "collectd"
11880 MessageFormat "human"
11881 HostTags ""
11882 </Node>
11883 </Plugin>
11884
11885 The configuration consists of one or more E<lt>B<Node>E<nbsp>I<Name>E<gt>
11886 blocks and global directives.
11887
11888 Global directives are:
11889
11890 =over 4
11891
11892 =item B<ResolveInterval> I<seconds>
11893
11894 =item B<ResolveJitter> I<seconds>
11895
11896 When I<collectd> connects to a syslog node, it will request the hostname from
11897 DNS. This can become a problem if the syslog node is unavailable or badly
11898 configured because collectd will request DNS in order to reconnect for every
11899 metric, which can flood your DNS. So you can cache the last value for
11900 I<ResolveInterval> seconds.
11901 Defaults to the I<Interval> of the I<write_syslog plugin>, e.g. 10E<nbsp>seconds.
11902
11903 You can also define a jitter, a random interval to wait in addition to
11904 I<ResolveInterval>. This prevents all your collectd servers to resolve the
11905 hostname at the same time when the connection fails.
11906 Defaults to the I<Interval> of the I<write_syslog plugin>, e.g. 10E<nbsp>seconds.
11907
11908 B<Note:> If the DNS resolution has already been successful when the socket
11909 closes, the plugin will try to reconnect immediately with the cached
11910 information. DNS is queried only when the socket is closed for a longer than
11911 I<ResolveInterval> + I<ResolveJitter> seconds.
11912
11913 =back
11914
11915 Inside the B<Node> blocks, the following options are recognized:
11916
11917 =over 4
11918
11919 =item B<Host> I<Address>
11920
11921 Hostname or address to connect to. Defaults to C<localhost>.
11922
11923 =item B<Port> I<Service>
11924
11925 Service name or port number to connect to. Defaults to C<44514>.
11926
11927
11928 =item B<HostTags> I<String>
11929
11930 When set, I<HostTags> is added to the end of the metric.
11931 It is intended to be used for adding additional metadata to tag the metric with.
11932 Dots and whitespace are I<not> escaped in this string.
11933
11934 Examples:
11935
11936 When MessageFormat is set to "human".
11937
11938 ["prefix1" "example1"="example1_v"]["prefix2" "example2"="example2_v"]"
11939
11940 When MessageFormat is set to "JSON", text should be in JSON format.
11941 Escaping the quotation marks is required.
11942
11943 HostTags "\"prefix1\": {\"example1\":\"example1_v\",\"example2\":\"example2_v\"}"
11944
11945 =item B<MessageFormat> I<String>
11946
11947 I<MessageFormat> selects the format in which messages are sent to the
11948 syslog deamon, human or JSON. Defaults to human.
11949
11950 Syslog message format:
11951
11952 <priority>VERSION ISOTIMESTAMP HOSTNAME APPLICATION PID MESSAGEID STRUCTURED-DATA MSG
11953
11954 The difference between the message formats are in the STRUCTURED-DATA and MSG parts.
11955
11956 Human format:
11957
11958 <166>1 ISOTIMESTAMP HOSTNAME collectd PID MESSAGEID
11959 ["collectd" "value": "v1" "plugin"="plugin_v" "plugin_instance"="plugin_instance_v"
11960 "type_instance"="type_instance_v" "type"="type_v" "ds_name"="ds_name_v" "interval"="interval_v" ]
11961 "host_tag_example"="host_tag_example_v" plugin_v.type_v.ds_name_v="v1"
11962
11963 JSON format:
11964
11965 <166>1 ISOTIMESTAMP HOSTNAME collectd PID MESSAGEID STRUCTURED-DATA
11966 {
11967 "collectd": {
11968 "time": time_as_epoch, "interval": interval_v, "plugin": "plugin_v",
11969 "plugin_instance": "plugin_instance_v", "type":"type_v",
11970 "type_instance": "type_instance_v", "plugin_v": {"type_v": v1}
11971 } , "host":"host_v", "host_tag_example": "host_tag_example_v"
11972 }
11973
11974 =item B<StoreRates> B<false>|B<true>
11975
11976 If set to B<true>, convert counter values to rates. If set to B<false>
11977 (the default) counter values are stored as is, as an increasing
11978 integer number.
11979
11980 =item B<AlwaysAppendDS> B<false>|B<true>
11981
11982 If set to B<true>, append the name of the I<Data Source> (DS) to the "metric"
11983 identifier. If set to B<false> (the default), this is only done when there is
11984 more than one DS.
11985
11986 =item B<Prefix> I<String>
11987
11988 When set, I<Prefix> is added to all metrics names as a prefix. It is intended in
11989 case you want to be able to define the source of the specific metric. Dots and
11990 whitespace are I<not> escaped in this string.
11991
11992 =back
11993
11994 =head2 Plugin C<xencpu>
11995
11996 This plugin collects metrics of hardware CPU load for machine running Xen
11997 hypervisor. Load is calculated from 'idle time' value, provided by Xen.
11998 Result is reported using the C<percent> type, for each CPU (core).
11999
12000 This plugin doesn't have any options (yet).
12001
12002 =head2 Plugin C<zookeeper>
12003
12004 The I<zookeeper plugin> will collect statistics from a I<Zookeeper> server
12005 using the mntr command. It requires Zookeeper 3.4.0+ and access to the
12006 client port.
12007
12008 B<Synopsis:>
12009
12010 <Plugin "zookeeper">
12011 Host "127.0.0.1"
12012 Port "2181"
12013 </Plugin>
12014
12015 =over 4
12016
12017 =item B<Host> I<Address>
12018
12019 Hostname or address to connect to. Defaults to C<localhost>.
12020
12021 =item B<Port> I<Service>
12022
12023 Service name or port number to connect to. Defaults to C<2181>.
12024
12025 =back
12026
12027 =head1 THRESHOLD CONFIGURATION
12028
12029 Starting with version C<4.3.0> collectd has support for B<monitoring>. By that
12030 we mean that the values are not only stored or sent somewhere, but that they
12031 are judged and, if a problem is recognized, acted upon. The only action
12032 collectd takes itself is to generate and dispatch a "notification". Plugins can
12033 register to receive notifications and perform appropriate further actions.
12034
12035 Since systems and what you expect them to do differ a lot, you can configure
12036 B<thresholds> for your values freely. This gives you a lot of flexibility but
12037 also a lot of responsibility.
12038
12039 Every time a value is out of range a notification is dispatched. This means
12040 that the idle percentage of your CPU needs to be less then the configured
12041 threshold only once for a notification to be generated. There's no such thing
12042 as a moving average or similar - at least not now.
12043
12044 Also, all values that match a threshold are considered to be relevant or
12045 "interesting". As a consequence collectd will issue a notification if they are
12046 not received for B<Timeout> iterations. The B<Timeout> configuration option is
12047 explained in section L<"GLOBAL OPTIONS">. If, for example, B<Timeout> is set to
12048 "2" (the default) and some hosts sends it's CPU statistics to the server every
12049 60 seconds, a notification will be dispatched after about 120 seconds. It may
12050 take a little longer because the timeout is checked only once each B<Interval>
12051 on the server.
12052
12053 When a value comes within range again or is received after it was missing, an
12054 "OKAY-notification" is dispatched.
12055
12056 Here is a configuration example to get you started. Read below for more
12057 information.
12058
12059 <Plugin threshold>
12060 <Type "foo">
12061 WarningMin 0.00
12062 WarningMax 1000.00
12063 FailureMin 0.00
12064 FailureMax 1200.00
12065 Invert false
12066 Instance "bar"
12067 </Type>
12068
12069 <Plugin "interface">
12070 Instance "eth0"
12071 <Type "if_octets">
12072 FailureMax 10000000
12073 DataSource "rx"
12074 </Type>
12075 </Plugin>
12076
12077 <Host "hostname">
12078 <Type "cpu">
12079 Instance "idle"
12080 FailureMin 10
12081 </Type>
12082
12083 <Plugin "memory">
12084 <Type "memory">
12085 Instance "cached"
12086 WarningMin 100000000
12087 </Type>
12088 </Plugin>
12089 </Host>
12090 </Plugin>
12091
12092 There are basically two types of configuration statements: The C<Host>,
12093 C<Plugin>, and C<Type> blocks select the value for which a threshold should be
12094 configured. The C<Plugin> and C<Type> blocks may be specified further using the
12095 C<Instance> option. You can combine the block by nesting the blocks, though
12096 they must be nested in the above order, i.E<nbsp>e. C<Host> may contain either
12097 C<Plugin> and C<Type> blocks, C<Plugin> may only contain C<Type> blocks and
12098 C<Type> may not contain other blocks. If multiple blocks apply to the same
12099 value the most specific block is used.
12100
12101 The other statements specify the threshold to configure. They B<must> be
12102 included in a C<Type> block. Currently the following statements are recognized:
12103
12104 =over 4
12105
12106 =item B<FailureMax> I<Value>
12107
12108 =item B<WarningMax> I<Value>
12109
12110 Sets the upper bound of acceptable values. If unset defaults to positive
12111 infinity. If a value is greater than B<FailureMax> a B<FAILURE> notification
12112 will be created. If the value is greater than B<WarningMax> but less than (or
12113 equal to) B<FailureMax> a B<WARNING> notification will be created.
12114
12115 =item B<FailureMin> I<Value>
12116
12117 =item B<WarningMin> I<Value>
12118
12119 Sets the lower bound of acceptable values. If unset defaults to negative
12120 infinity. If a value is less than B<FailureMin> a B<FAILURE> notification will
12121 be created. If the value is less than B<WarningMin> but greater than (or equal
12122 to) B<FailureMin> a B<WARNING> notification will be created.
12123
12124 =item B<DataSource> I<DSName>
12125
12126 Some data sets have more than one "data source". Interesting examples are the
12127 C<if_octets> data set, which has received (C<rx>) and sent (C<tx>) bytes and
12128 the C<disk_ops> data set, which holds C<read> and C<write> operations. The
12129 system load data set, C<load>, even has three data sources: C<shortterm>,
12130 C<midterm>, and C<longterm>.
12131
12132 Normally, all data sources are checked against a configured threshold. If this
12133 is undesirable, or if you want to specify different limits for each data
12134 source, you can use the B<DataSource> option to have a threshold apply only to
12135 one data source.
12136
12137 =item B<Invert> B<true>|B<false>
12138
12139 If set to B<true> the range of acceptable values is inverted, i.E<nbsp>e.
12140 values between B<FailureMin> and B<FailureMax> (B<WarningMin> and
12141 B<WarningMax>) are not okay. Defaults to B<false>.
12142
12143 =item B<Persist> B<true>|B<false>
12144
12145 Sets how often notifications are generated. If set to B<true> one notification
12146 will be generated for each value that is out of the acceptable range. If set to
12147 B<false> (the default) then a notification is only generated if a value is out
12148 of range but the previous value was okay.
12149
12150 This applies to missing values, too: If set to B<true> a notification about a
12151 missing value is generated once every B<Interval> seconds. If set to B<false>
12152 only one such notification is generated until the value appears again.
12153
12154 =item B<Percentage> B<true>|B<false>
12155
12156 If set to B<true>, the minimum and maximum values given are interpreted as
12157 percentage value, relative to the other data sources. This is helpful for
12158 example for the "df" type, where you may want to issue a warning when less than
12159 5E<nbsp>% of the total space is available. Defaults to B<false>.
12160
12161 =item B<Hits> I<Number>
12162
12163 Delay creating the notification until the threshold has been passed I<Number>
12164 times. When a notification has been generated, or when a subsequent value is
12165 inside the threshold, the counter is reset. If, for example, a value is
12166 collected once every 10E<nbsp>seconds and B<Hits> is set to 3, a notification
12167 will be dispatched at most once every 30E<nbsp>seconds.
12168
12169 This is useful when short bursts are not a problem. If, for example, 100% CPU
12170 usage for up to a minute is normal (and data is collected every
12171 10E<nbsp>seconds), you could set B<Hits> to B<6> to account for this.
12172
12173 =item B<Hysteresis> I<Number>
12174
12175 When set to non-zero, a hysteresis value is applied when checking minimum and
12176 maximum bounds. This is useful for values that increase slowly and fluctuate a
12177 bit while doing so. When these values come close to the threshold, they may
12178 "flap", i.e. switch between failure / warning case and okay case repeatedly.
12179
12180 If, for example, the threshold is configures as
12181
12182 WarningMax 100.0
12183 Hysteresis 1.0
12184
12185 then a I<Warning> notification is created when the value exceeds I<101> and the
12186 corresponding I<Okay> notification is only created once the value falls below
12187 I<99>, thus avoiding the "flapping".
12188
12189 =back
12190
12191 =head1 FILTER CONFIGURATION
12192
12193 Starting with collectd 4.6 there is a powerful filtering infrastructure
12194 implemented in the daemon. The concept has mostly been copied from
12195 I<ip_tables>, the packet filter infrastructure for Linux. We'll use a similar
12196 terminology, so that users that are familiar with iptables feel right at home.
12197
12198 =head2 Terminology
12199
12200 The following are the terms used in the remainder of the filter configuration
12201 documentation. For an ASCII-art schema of the mechanism, see
12202 L<"General structure"> below.
12203
12204 =over 4
12205
12206 =item B<Match>
12207
12208 A I<match> is a criteria to select specific values. Examples are, of course, the
12209 name of the value or it's current value.
12210
12211 Matches are implemented in plugins which you have to load prior to using the
12212 match. The name of such plugins starts with the "match_" prefix.
12213
12214 =item B<Target>
12215
12216 A I<target> is some action that is to be performed with data. Such actions
12217 could, for example, be to change part of the value's identifier or to ignore
12218 the value completely.
12219
12220 Some of these targets are built into the daemon, see L<"Built-in targets">
12221 below. Other targets are implemented in plugins which you have to load prior to
12222 using the target. The name of such plugins starts with the "target_" prefix.
12223
12224 =item B<Rule>
12225
12226 The combination of any number of matches and at least one target is called a
12227 I<rule>. The target actions will be performed for all values for which B<all>
12228 matches apply. If the rule does not have any matches associated with it, the
12229 target action will be performed for all values.
12230
12231 =item B<Chain>
12232
12233 A I<chain> is a list of rules and possibly default targets. The rules are tried
12234 in order and if one matches, the associated target will be called. If a value
12235 is handled by a rule, it depends on the target whether or not any subsequent
12236 rules are considered or if traversal of the chain is aborted, see
12237 L<"Flow control"> below. After all rules have been checked, the default targets
12238 will be executed.
12239
12240 =back
12241
12242 =head2 General structure
12243
12244 The following shows the resulting structure:
12245
12246 +---------+
12247 ! Chain !
12248 +---------+
12249 !
12250 V
12251 +---------+ +---------+ +---------+ +---------+
12252 ! Rule !->! Match !->! Match !->! Target !
12253 +---------+ +---------+ +---------+ +---------+
12254 !
12255 V
12256 +---------+ +---------+ +---------+
12257 ! Rule !->! Target !->! Target !
12258 +---------+ +---------+ +---------+
12259 !
12260 V
12261 :
12262 :
12263 !
12264 V
12265 +---------+ +---------+ +---------+
12266 ! Rule !->! Match !->! Target !
12267 +---------+ +---------+ +---------+
12268 !
12269 V
12270 +---------+
12271 ! Default !
12272 ! Target !
12273 +---------+
12274
12275 =head2 Flow control
12276
12277 There are four ways to control which way a value takes through the filter
12278 mechanism:
12279
12280 =over 4
12281
12282 =item B<jump>
12283
12284 The built-in B<jump> target can be used to "call" another chain, i.E<nbsp>e.
12285 process the value with another chain. When the called chain finishes, usually
12286 the next target or rule after the jump is executed.
12287
12288 =item B<stop>
12289
12290 The stop condition, signaled for example by the built-in target B<stop>, causes
12291 all processing of the value to be stopped immediately.
12292
12293 =item B<return>
12294
12295 Causes processing in the current chain to be aborted, but processing of the
12296 value generally will continue. This means that if the chain was called via
12297 B<Jump>, the next target or rule after the jump will be executed. If the chain
12298 was not called by another chain, control will be returned to the daemon and it
12299 may pass the value to another chain.
12300
12301 =item B<continue>
12302
12303 Most targets will signal the B<continue> condition, meaning that processing
12304 should continue normally. There is no special built-in target for this
12305 condition.
12306
12307 =back
12308
12309 =head2 Synopsis
12310
12311 The configuration reflects this structure directly:
12312
12313 PostCacheChain "PostCache"
12314 <Chain "PostCache">
12315 <Rule "ignore_mysql_show">
12316 <Match "regex">
12317 Plugin "^mysql$"
12318 Type "^mysql_command$"
12319 TypeInstance "^show_"
12320 </Match>
12321 <Target "stop">
12322 </Target>
12323 </Rule>
12324 <Target "write">
12325 Plugin "rrdtool"
12326 </Target>
12327 </Chain>
12328
12329 The above configuration example will ignore all values where the plugin field
12330 is "mysql", the type is "mysql_command" and the type instance begins with
12331 "show_". All other values will be sent to the C<rrdtool> write plugin via the
12332 default target of the chain. Since this chain is run after the value has been
12333 added to the cache, the MySQL C<show_*> command statistics will be available
12334 via the C<unixsock> plugin.
12335
12336 =head2 List of configuration options
12337
12338 =over 4
12339
12340 =item B<PreCacheChain> I<ChainName>
12341
12342 =item B<PostCacheChain> I<ChainName>
12343
12344 Configure the name of the "pre-cache chain" and the "post-cache chain". The
12345 argument is the name of a I<chain> that should be executed before and/or after
12346 the values have been added to the cache.
12347
12348 To understand the implications, it's important you know what is going on inside
12349 I<collectd>. The following diagram shows how values are passed from the
12350 read-plugins to the write-plugins:
12351
12352 +---------------+
12353 ! Read-Plugin !
12354 +-------+-------+
12355 !
12356 + - - - - V - - - - +
12357 : +---------------+ :
12358 : ! Pre-Cache ! :
12359 : ! Chain ! :
12360 : +-------+-------+ :
12361 : ! :
12362 : V :
12363 : +-------+-------+ : +---------------+
12364 : ! Cache !--->! Value Cache !
12365 : ! insert ! : +---+---+-------+
12366 : +-------+-------+ : ! !
12367 : ! ,------------' !
12368 : V V : V
12369 : +-------+---+---+ : +-------+-------+
12370 : ! Post-Cache +--->! Write-Plugins !
12371 : ! Chain ! : +---------------+
12372 : +---------------+ :
12373 : :
12374 : dispatch values :
12375 + - - - - - - - - - +
12376
12377 After the values are passed from the "read" plugins to the dispatch functions,
12378 the pre-cache chain is run first. The values are added to the internal cache
12379 afterwards. The post-cache chain is run after the values have been added to the
12380 cache. So why is it such a huge deal if chains are run before or after the
12381 values have been added to this cache?
12382
12383 Targets that change the identifier of a value list should be executed before
12384 the values are added to the cache, so that the name in the cache matches the
12385 name that is used in the "write" plugins. The C<unixsock> plugin, too, uses
12386 this cache to receive a list of all available values. If you change the
12387 identifier after the value list has been added to the cache, this may easily
12388 lead to confusion, but it's not forbidden of course.
12389
12390 The cache is also used to convert counter values to rates. These rates are, for
12391 example, used by the C<value> match (see below). If you use the rate stored in
12392 the cache B<before> the new value is added, you will use the old, B<previous>
12393 rate. Write plugins may use this rate, too, see the C<csv> plugin, for example.
12394 The C<unixsock> plugin uses these rates too, to implement the C<GETVAL>
12395 command.
12396
12397 Last but not last, the B<stop> target makes a difference: If the pre-cache
12398 chain returns the stop condition, the value will not be added to the cache and
12399 the post-cache chain will not be run.
12400
12401 =item B<Chain> I<Name>
12402
12403 Adds a new chain with a certain name. This name can be used to refer to a
12404 specific chain, for example to jump to it.
12405
12406 Within the B<Chain> block, there can be B<Rule> blocks and B<Target> blocks.
12407
12408 =item B<Rule> [I<Name>]
12409
12410 Adds a new rule to the current chain. The name of the rule is optional and
12411 currently has no meaning for the daemon.
12412
12413 Within the B<Rule> block, there may be any number of B<Match> blocks and there
12414 must be at least one B<Target> block.
12415
12416 =item B<Match> I<Name>
12417
12418 Adds a match to a B<Rule> block. The name specifies what kind of match should
12419 be performed. Available matches depend on the plugins that have been loaded.
12420
12421 The arguments inside the B<Match> block are passed to the plugin implementing
12422 the match, so which arguments are valid here depends on the plugin being used.
12423 If you do not need any to pass any arguments to a match, you can use the
12424 shorter syntax:
12425
12426 Match "foobar"
12427
12428 Which is equivalent to:
12429
12430 <Match "foobar">
12431 </Match>
12432
12433 =item B<Target> I<Name>
12434
12435 Add a target to a rule or a default target to a chain. The name specifies what
12436 kind of target is to be added. Which targets are available depends on the
12437 plugins being loaded.
12438
12439 The arguments inside the B<Target> block are passed to the plugin implementing
12440 the target, so which arguments are valid here depends on the plugin being used.
12441 If you do not need any to pass any arguments to a target, you can use the
12442 shorter syntax:
12443
12444 Target "stop"
12445
12446 This is the same as writing:
12447
12448 <Target "stop">
12449 </Target>
12450
12451 =back
12452
12453 =head2 Built-in targets
12454
12455 The following targets are built into the core daemon and therefore need no
12456 plugins to be loaded:
12457
12458 =over 4
12459
12460 =item B<return>
12461
12462 Signals the "return" condition, see the L<"Flow control"> section above. This
12463 causes the current chain to stop processing the value and returns control to
12464 the calling chain. The calling chain will continue processing targets and rules
12465 just after the B<jump> target (see below). This is very similar to the
12466 B<RETURN> target of iptables, see L<iptables(8)>.
12467
12468 This target does not have any options.
12469
12470 Example:
12471
12472 Target "return"
12473
12474 =item B<stop>
12475
12476 Signals the "stop" condition, see the L<"Flow control"> section above. This
12477 causes processing of the value to be aborted immediately. This is similar to
12478 the B<DROP> target of iptables, see L<iptables(8)>.
12479
12480 This target does not have any options.
12481
12482 Example:
12483
12484 Target "stop"
12485
12486 =item B<write>
12487
12488 Sends the value to "write" plugins.
12489
12490 Available options:
12491
12492 =over 4
12493
12494 =item B<Plugin> I<Name>
12495
12496 Name of the write plugin to which the data should be sent. This option may be
12497 given multiple times to send the data to more than one write plugin. If the
12498 plugin supports multiple instances, the plugin's instance(s) must also be
12499 specified.
12500
12501 =back
12502
12503 If no plugin is explicitly specified, the values will be sent to all available
12504 write plugins.
12505
12506 Single-instance plugin example:
12507
12508 <Target "write">
12509 Plugin "rrdtool"
12510 </Target>
12511
12512 Multi-instance plugin example:
12513
12514 <Plugin "write_graphite">
12515 <Node "foo">
12516 ...
12517 </Node>
12518 <Node "bar">
12519 ...
12520 </Node>
12521 </Plugin>
12522 ...
12523 <Target "write">
12524 Plugin "write_graphite/foo"
12525 </Target>
12526
12527 =item B<jump>
12528
12529 Starts processing the rules of another chain, see L<"Flow control"> above. If
12530 the end of that chain is reached, or a stop condition is encountered,
12531 processing will continue right after the B<jump> target, i.E<nbsp>e. with the
12532 next target or the next rule. This is similar to the B<-j> command line option
12533 of iptables, see L<iptables(8)>.
12534
12535 Available options:
12536
12537 =over 4
12538
12539 =item B<Chain> I<Name>
12540
12541 Jumps to the chain I<Name>. This argument is required and may appear only once.
12542
12543 =back
12544
12545 Example:
12546
12547 <Target "jump">
12548 Chain "foobar"
12549 </Target>
12550
12551 =back
12552
12553 =head2 Available matches
12554
12555 =over 4
12556
12557 =item B<regex>
12558
12559 Matches a value using regular expressions.
12560
12561 Available options:
12562
12563 =over 4
12564
12565 =item B<Host> I<Regex>
12566
12567 =item B<Plugin> I<Regex>
12568
12569 =item B<PluginInstance> I<Regex>
12570
12571 =item B<Type> I<Regex>
12572
12573 =item B<TypeInstance> I<Regex>
12574
12575 =item B<MetaData> I<String> I<Regex>
12576
12577 Match values where the given regular expressions match the various fields of
12578 the identifier of a value. If multiple regular expressions are given, B<all>
12579 regexen must match for a value to match.
12580
12581 =item B<Invert> B<false>|B<true>
12582
12583 When set to B<true>, the result of the match is inverted, i.e. all value lists
12584 where all regular expressions apply are not matched, all other value lists are
12585 matched. Defaults to B<false>.
12586
12587 =back
12588
12589 Example:
12590
12591 <Match "regex">
12592 Host "customer[0-9]+"
12593 Plugin "^foobar$"
12594 </Match>
12595
12596 =item B<timediff>
12597
12598 Matches values that have a time which differs from the time on the server.
12599
12600 This match is mainly intended for servers that receive values over the
12601 C<network> plugin and write them to disk using the C<rrdtool> plugin. RRDtool
12602 is very sensitive to the timestamp used when updating the RRD files. In
12603 particular, the time must be ever increasing. If a misbehaving client sends one
12604 packet with a timestamp far in the future, all further packets with a correct
12605 time will be ignored because of that one packet. What's worse, such corrupted
12606 RRD files are hard to fix.
12607
12608 This match lets one match all values B<outside> a specified time range
12609 (relative to the server's time), so you can use the B<stop> target (see below)
12610 to ignore the value, for example.
12611
12612 Available options:
12613
12614 =over 4
12615
12616 =item B<Future> I<Seconds>
12617
12618 Matches all values that are I<ahead> of the server's time by I<Seconds> or more
12619 seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
12620 non-zero.
12621
12622 =item B<Past> I<Seconds>
12623
12624 Matches all values that are I<behind> of the server's time by I<Seconds> or
12625 more seconds. Set to zero for no limit. Either B<Future> or B<Past> must be
12626 non-zero.
12627
12628 =back
12629
12630 Example:
12631
12632 <Match "timediff">
12633 Future 300
12634 Past 3600
12635 </Match>
12636
12637 This example matches all values that are five minutes or more ahead of the
12638 server or one hour (or more) lagging behind.
12639
12640 =item B<value>
12641
12642 Matches the actual value of data sources against given minimumE<nbsp>/ maximum
12643 values. If a data-set consists of more than one data-source, all data-sources
12644 must match the specified ranges for a positive match.
12645
12646 Available options:
12647
12648 =over 4
12649
12650 =item B<Min> I<Value>
12651
12652 Sets the smallest value which still results in a match. If unset, behaves like
12653 negative infinity.
12654
12655 =item B<Max> I<Value>
12656
12657 Sets the largest value which still results in a match. If unset, behaves like
12658 positive infinity.
12659
12660 =item B<Invert> B<true>|B<false>
12661
12662 Inverts the selection. If the B<Min> and B<Max> settings result in a match,
12663 no-match is returned and vice versa. Please note that the B<Invert> setting
12664 only effects how B<Min> and B<Max> are applied to a specific value. Especially
12665 the B<DataSource> and B<Satisfy> settings (see below) are not inverted.
12666
12667 =item B<DataSource> I<DSName> [I<DSName> ...]
12668
12669 Select one or more of the data sources. If no data source is configured, all
12670 data sources will be checked. If the type handled by the match does not have a
12671 data source of the specified name(s), this will always result in no match
12672 (independent of the B<Invert> setting).
12673
12674 =item B<Satisfy> B<Any>|B<All>
12675
12676 Specifies how checking with several data sources is performed. If set to
12677 B<Any>, the match succeeds if one of the data sources is in the configured
12678 range. If set to B<All> the match only succeeds if all data sources are within
12679 the configured range. Default is B<All>.
12680
12681 Usually B<All> is used for positive matches, B<Any> is used for negative
12682 matches. This means that with B<All> you usually check that all values are in a
12683 "good" range, while with B<Any> you check if any value is within a "bad" range
12684 (or outside the "good" range).
12685
12686 =back
12687
12688 Either B<Min> or B<Max>, but not both, may be unset.
12689
12690 Example:
12691
12692 # Match all values smaller than or equal to 100. Matches only if all data
12693 # sources are below 100.
12694 <Match "value">
12695 Max 100
12696 Satisfy "All"
12697 </Match>
12698
12699 # Match if the value of any data source is outside the range of 0 - 100.
12700 <Match "value">
12701 Min 0
12702 Max 100
12703 Invert true
12704 Satisfy "Any"
12705 </Match>
12706
12707 =item B<empty_counter>
12708
12709 Matches all values with one or more data sources of type B<COUNTER> and where
12710 all counter values are zero. These counters usually I<never> increased since
12711 they started existing (and are therefore uninteresting), or got reset recently
12712 or overflowed and you had really, I<really> bad luck.
12713
12714 Please keep in mind that ignoring such counters can result in confusing
12715 behavior: Counters which hardly ever increase will be zero for long periods of
12716 time. If the counter is reset for some reason (machine or service restarted,
12717 usually), the graph will be empty (NAN) for a long time. People may not
12718 understand why.
12719
12720 =item B<hashed>
12721
12722 Calculates a hash value of the host name and matches values according to that
12723 hash value. This makes it possible to divide all hosts into groups and match
12724 only values that are in a specific group. The intended use is in load
12725 balancing, where you want to handle only part of all data and leave the rest
12726 for other servers.
12727
12728 The hashing function used tries to distribute the hosts evenly. First, it
12729 calculates a 32E<nbsp>bit hash value using the characters of the hostname:
12730
12731 hash_value = 0;
12732 for (i = 0; host[i] != 0; i++)
12733 hash_value = (hash_value * 251) + host[i];
12734
12735 The constant 251 is a prime number which is supposed to make this hash value
12736 more random. The code then checks the group for this host according to the
12737 I<Total> and I<Match> arguments:
12738
12739 if ((hash_value % Total) == Match)
12740 matches;
12741 else
12742 does not match;
12743
12744 Please note that when you set I<Total> to two (i.E<nbsp>e. you have only two
12745 groups), then the least significant bit of the hash value will be the XOR of
12746 all least significant bits in the host name. One consequence is that when you
12747 have two hosts, "server0.example.com" and "server1.example.com", where the host
12748 name differs in one digit only and the digits differ by one, those hosts will
12749 never end up in the same group.
12750
12751 Available options:
12752
12753 =over 4
12754
12755 =item B<Match> I<Match> I<Total>
12756
12757 Divide the data into I<Total> groups and match all hosts in group I<Match> as
12758 described above. The groups are numbered from zero, i.E<nbsp>e. I<Match> must
12759 be smaller than I<Total>. I<Total> must be at least one, although only values
12760 greater than one really do make any sense.
12761
12762 You can repeat this option to match multiple groups, for example:
12763
12764 Match 3 7
12765 Match 5 7
12766
12767 The above config will divide the data into seven groups and match groups three
12768 and five. One use would be to keep every value on two hosts so that if one
12769 fails the missing data can later be reconstructed from the second host.
12770
12771 =back
12772
12773 Example:
12774
12775 # Operate on the pre-cache chain, so that ignored values are not even in the
12776 # global cache.
12777 <Chain "PreCache">
12778 <Rule>
12779 <Match "hashed">
12780 # Divide all received hosts in seven groups and accept all hosts in
12781 # group three.
12782 Match 3 7
12783 </Match>
12784 # If matched: Return and continue.
12785 Target "return"
12786 </Rule>
12787 # If not matched: Return and stop.
12788 Target "stop"
12789 </Chain>
12790
12791 =back
12792
12793 =head2 Available targets
12794
12795 =over 4
12796
12797 =item B<notification>
12798
12799 Creates and dispatches a notification.
12800
12801 Available options:
12802
12803 =over 4
12804
12805 =item B<Message> I<String>
12806
12807 This required option sets the message of the notification. The following
12808 placeholders will be replaced by an appropriate value:
12809
12810 =over 4
12811
12812 =item B<%{host}>
12813
12814 =item B<%{plugin}>
12815
12816 =item B<%{plugin_instance}>
12817
12818 =item B<%{type}>
12819
12820 =item B<%{type_instance}>
12821
12822 These placeholders are replaced by the identifier field of the same name.
12823
12824 =item B<%{ds:>I<name>B<}>
12825
12826 These placeholders are replaced by a (hopefully) human readable representation
12827 of the current rate of this data source. If you changed the instance name
12828 (using the B<set> or B<replace> targets, see below), it may not be possible to
12829 convert counter values to rates.
12830
12831 =back
12832
12833 Please note that these placeholders are B<case sensitive>!
12834
12835 =item B<Severity> B<"FAILURE">|B<"WARNING">|B<"OKAY">
12836
12837 Sets the severity of the message. If omitted, the severity B<"WARNING"> is
12838 used.
12839
12840 =back
12841
12842 Example:
12843
12844 <Target "notification">
12845 Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
12846 Severity "WARNING"
12847 </Target>
12848
12849 =item B<replace>
12850
12851 Replaces parts of the identifier using regular expressions.
12852
12853 Available options:
12854
12855 =over 4
12856
12857 =item B<Host> I<Regex> I<Replacement>
12858
12859 =item B<Plugin> I<Regex> I<Replacement>
12860
12861 =item B<PluginInstance> I<Regex> I<Replacement>
12862
12863 =item B<TypeInstance> I<Regex> I<Replacement>
12864
12865 =item B<MetaData> I<String> I<Regex> I<Replacement>
12866
12867 =item B<DeleteMetaData> I<String> I<Regex>
12868
12869 Match the appropriate field with the given regular expression I<Regex>. If the
12870 regular expression matches, that part that matches is replaced with
12871 I<Replacement>. If multiple places of the input buffer match a given regular
12872 expression, only the first occurrence will be replaced.
12873
12874 You can specify each option multiple times to use multiple regular expressions
12875 one after another.
12876
12877 =back
12878
12879 Example:
12880
12881 <Target "replace">
12882 # Replace "example.net" with "example.com"
12883 Host "\\<example.net\\>" "example.com"
12884
12885 # Strip "www." from hostnames
12886 Host "\\<www\\." ""
12887 </Target>
12888
12889 =item B<set>
12890
12891 Sets part of the identifier of a value to a given string.
12892
12893 Available options:
12894
12895 =over 4
12896
12897 =item B<Host> I<String>
12898
12899 =item B<Plugin> I<String>
12900
12901 =item B<PluginInstance> I<String>
12902
12903 =item B<TypeInstance> I<String>
12904
12905 =item B<MetaData> I<String> I<String>
12906
12907 Set the appropriate field to the given string. The strings for plugin instance,
12908 type instance, and meta data may be empty, the strings for host and plugin may
12909 not be empty. It's currently not possible to set the type of a value this way.
12910
12911 The following placeholders will be replaced by an appropriate value:
12912
12913 =over 4
12914
12915 =item B<%{host}>
12916
12917 =item B<%{plugin}>
12918
12919 =item B<%{plugin_instance}>
12920
12921 =item B<%{type}>
12922
12923 =item B<%{type_instance}>
12924
12925 These placeholders are replaced by the identifier field of the same name.
12926
12927 =item B<%{meta:>I<name>B<}>
12928
12929 These placeholders are replaced by the meta data value with the given name.
12930
12931 =back
12932
12933 Please note that these placeholders are B<case sensitive>!
12934
12935 =item B<DeleteMetaData> I<String>
12936
12937 Delete the named meta data field.
12938
12939 =back
12940
12941 Example:
12942
12943 <Target "set">
12944 PluginInstance "coretemp"
12945 TypeInstance "core3"
12946 </Target>
12947
12948 =back
12949
12950 =head2 Backwards compatibility
12951
12952 If you use collectd with an old configuration, i.E<nbsp>e. one without a
12953 B<Chain> block, it will behave as it used to. This is equivalent to the
12954 following configuration:
12955
12956 <Chain "PostCache">
12957 Target "write"
12958 </Chain>
12959
12960 If you specify a B<PostCacheChain>, the B<write> target will not be added
12961 anywhere and you will have to make sure that it is called where appropriate. We
12962 suggest to add the above snippet as default target to your "PostCache" chain.
12963
12964 =head2 Examples
12965
12966 Ignore all values, where the hostname does not contain a dot, i.E<nbsp>e. can't
12967 be an FQDN.
12968
12969 <Chain "PreCache">
12970 <Rule "no_fqdn">
12971 <Match "regex">
12972 Host "^[^\.]*$"
12973 </Match>
12974 Target "stop"
12975 </Rule>
12976 Target "write"
12977 </Chain>
12978
12979 =head1 IGNORELISTS
12980
12981 B<Ignorelists> are a generic framework to either ignore some metrics or report
12982 specific metrics only. Plugins usually provide one or more options to specify
12983 the items (mounts points, devices, ...) and the boolean option
12984 C<IgnoreSelected>.
12985
12986 =over 4
12987
12988 =item B<Select> I<String>
12989
12990 Selects the item I<String>. This option often has a plugin specific name, e.g.
12991 B<Sensor> in the C<sensors> plugin. It is also plugin specific what this string
12992 is compared to. For example, the C<df> plugin's B<MountPoint> compares it to a
12993 mount point and the C<sensors> plugin's B<Sensor> compares it to a sensor name.
12994
12995 By default, this option is doing a case-sensitive full-string match. The
12996 following config will match C<foo>, but not C<Foo>:
12997
12998 Select "foo"
12999
13000 If I<String> starts and ends with C</> (a slash), the string is compiled as a
13001 I<regular expression>. For example, so match all item starting with C<foo>, use
13002 could use the following syntax:
13003
13004 Select "/^foo/"
13005
13006 The regular expression is I<not> anchored, i.e. the following config will match
13007 C<foobar>, C<barfoo> and C<AfooZ>:
13008
13009 Select "/foo/"
13010
13011 The B<Select> option may be repeated to select multiple items.
13012
13013 =item B<IgnoreSelected> B<true>|B<false>
13014
13015 If set to B<true>, matching metrics are I<ignored> and all other metrics are
13016 collected. If set to B<false>, matching metrics are I<collected> and all other
13017 metrics are ignored.
13018
13019 =back
13020
13021 =head1 SEE ALSO
13022
13023 L<collectd(1)>,
13024 L<collectd-exec(5)>,
13025 L<collectd-perl(5)>,
13026 L<collectd-unixsock(5)>,
13027 L<types.db(5)>,
13028 L<hddtemp(8)>,
13029 L<iptables(8)>,
13030 L<kstat(3KSTAT)>,
13031 L<mbmon(1)>,
13032 L<psql(1)>,
13033 L<regex(7)>,
13034 L<rrdtool(1)>,
13035 L<sensors(1)>
13036
13037 =head1 AUTHOR
13038
13039 Florian Forster E<lt>[email protected]<gt>
13040
13041 =cut