1COLLECTD.CONF(5) collectd COLLECTD.CONF(5)
2
6 collectd.conf - Configuration for the system statistics collection
7 daemon collectd
8
10 BaseDir "/var/lib/collectd"
11 PIDFile "/run/collectd.pid"
12 Interval 10.0
13 LoadPlugin cpu
15 LoadPlugin load
16 <LoadPlugin df>
18 Interval 3600
19 </LoadPlugin>
20 <Plugin df>
21 ValuesPercentage true
22 </Plugin>
23 LoadPlugin ping
25 <Plugin ping>
26 Host "example.org"
27 Host "provider.net"
28 </Plugin>
29
31 This config file controls how the system statistics collection daemon
32 collectd behaves. The most significant option is LoadPlugin, which
33 controls which plugins to load. These plugins ultimately define
34 collectd's behavior. If the AutoLoadPlugin option has been enabled, the
35 explicit LoadPlugin lines may be omitted for all plugins with a
36 configuration block, i.e. a "<Plugin ...>" block.
37 The syntax of this config file is similar to the config file of the
39 famous Apache webserver. Each line contains either an option (a key and
40 a list of one or more values) or a section-start or -end. Empty lines
41 and everything after a non-quoted hash-symbol ("#") are ignored. Keys
42 are unquoted strings, consisting only of alphanumeric characters and
43 the underscore ("_") character. Keys are handled case insensitive by
44 collectd itself and all plugins included with it. Values can either be
45 an unquoted string, a quoted string (enclosed in double-quotes) a
46 number or a boolean expression. Unquoted strings consist of only
47 alphanumeric characters and underscores ("_") and do not need to be
48 quoted. Quoted strings are enclosed in double quotes ("""). You can use
49 the backslash character ("\") to include double quotes as part of the
50 string. Numbers can be specified in decimal and floating point format
51 (using a dot "." as decimal separator), hexadecimal when using the "0x"
52 prefix and octal with a leading zero (0). Boolean values are either
53 true or false.
54 Lines may be wrapped by using "\" as the last character before the
56 newline. This allows long lines to be split into multiple lines.
57 Quoted strings may be wrapped as well. However, those are treated
58 special in that whitespace at the beginning of the following lines will
59 be ignored, which allows for nicely indenting the wrapped lines.
60 The configuration is read and processed in order, i.e. from top to
62 bottom. So the plugins are loaded in the order listed in this config
63 file. It is a good idea to load any logging plugins first in order to
64 catch messages from plugins during configuration. Also, unless
65 AutoLoadPlugin is enabled, the LoadPlugin option must occur before the
66 appropriate "<Plugin ...>" block.
67
69 BaseDir Directory
70 Sets the base directory. This is the directory beneath which all
71 RRD-files are created. Possibly more subdirectories are created.
72 This is also the working directory for the daemon.
73 LoadPlugin Plugin
75 Loads the plugin Plugin. This is required to load plugins, unless
76 the AutoLoadPlugin option is enabled (see below). Without any
77 loaded plugins, collectd will be mostly useless.
78 Only the first LoadPlugin statement or block for a given plugin
80 name has any effect. This is useful when you want to split up the
81 configuration into smaller files and want each file to be "self
82 contained", i.e. it contains a Plugin block and the appropriate
83 LoadPlugin statement. The downside is that if you have multiple
84 conflicting LoadPlugin blocks, e.g. when they specify different
85 intervals, only one of them (the first one encountered) will take
86 effect and all others will be silently ignored.
87 LoadPlugin may either be a simple configuration statement or a
89 block with additional options, affecting the behavior of
90 LoadPlugin. A simple statement looks like this:
91 LoadPlugin "cpu"
93 Options inside a LoadPlugin block can override default settings and
95 influence the way plugins are loaded, e.g.:
96 <LoadPlugin perl>
98 Interval 60
99 </LoadPlugin>
100 The following options are valid inside LoadPlugin blocks:
102 Globals true|false
104 If enabled, collectd will export all global symbols of the
105 plugin (and of all libraries loaded as dependencies of the
106 plugin) and, thus, makes those symbols available for resolving
107 unresolved symbols in subsequently loaded plugins if that is
108 supported by your system.
109 This is useful (or possibly even required), e.g., when loading
111 a plugin that embeds some scripting language into the daemon
112 (e.g. the Perl and Python plugins). Scripting languages usually
113 provide means to load extensions written in C. Those extensions
114 require symbols provided by the interpreter, which is loaded as
115 a dependency of the respective collectd plugin. See the
116 documentation of those plugins (e.g., collectd-perl(5) or
117 collectd-python(5)) for details.
118 By default, this is disabled. As a special exception, if the
120 plugin name is either "perl" or "python", the default is
121 changed to enabled in order to keep the average user from ever
122 having to deal with this low level linking stuff.
123 Interval Seconds
125 Sets a plugin-specific interval for collecting metrics. This
126 overrides the global Interval setting. If a plugin provides its
127 own support for specifying an interval, that setting will take
128 precedence.
129 FlushInterval Seconds
131 Specifies the interval, in seconds, to call the flush callback
132 if it's defined in this plugin. By default, this is disabled.
133 FlushTimeout Seconds
135 Specifies the value of the timeout argument of the flush
136 callback.
137 AutoLoadPlugin false|true
139 When set to false (the default), each plugin needs to be loaded
140 explicitly, using the LoadPlugin statement documented above. If a
141 <Plugin ...> block is encountered and no configuration handling
142 callback for this plugin has been registered, a warning is logged
143 and the block is ignored.
144 When set to true, explicit LoadPlugin statements are not required.
146 Each <Plugin ...> block acts as if it was immediately preceded by a
147 LoadPlugin statement. LoadPlugin statements are still required for
148 plugins that don't provide any configuration, e.g. the Load plugin.
149 CollectInternalStats false|true
151 When set to true, various statistics about the collectd daemon will
152 be collected, with "collectd" as the plugin name. Defaults to
153 false.
154 The following metrics are reported:
156 "collectd-write_queue/queue_length"
158 The number of metrics currently in the write queue. You can
159 limit the queue length with the WriteQueueLimitLow and
160 WriteQueueLimitHigh options.
161 "collectd-write_queue/derive-dropped"
163 The number of metrics dropped due to a queue length limitation.
164 If this value is non-zero, your system can't handle all
165 incoming metrics and protects itself against overload by
166 dropping metrics.
167 "collectd-cache/cache_size"
169 The number of elements in the metric cache (the cache you can
170 interact with using collectd-unixsock(5)).
171 Include Path [pattern]
173 If Path points to a file, includes that file. If Path points to a
174 directory, recursively includes all files within that directory and
175 its subdirectories. If the "wordexp" function is available on your
176 system, shell-like wildcards are expanded before files are
177 included. This means you can use statements like the following:
178 Include "/etc/collectd.d/*.conf"
180 Starting with version 5.3, this may also be a block in which
182 further options affecting the behavior of Include may be specified.
183 The following option is currently allowed:
184 <Include "/etc/collectd.d">
186 Filter "*.conf"
187 </Include>
188 Filter pattern
190 If the "fnmatch" function is available on your system, a shell-
191 like wildcard pattern may be specified to filter which files to
192 include. This may be used in combination with recursively
193 including a directory to easily be able to arbitrarily mix
194 configuration files and other documents (e.g. README files).
195 The given example is similar to the first example above but
196 includes all files matching "*.conf" in any subdirectory of
197 "/etc/collectd.d".
198 If more than one file is included by a single Include option, the
200 files will be included in lexicographical order (as defined by the
201 "strcmp" function). Thus, you can e. g. use numbered prefixes to
202 specify the order in which the files are loaded.
203 To prevent loops and shooting yourself in the foot in interesting
205 ways the nesting is limited to a depth of 8 levels, which should be
206 sufficient for most uses. Since symlinks are followed it is still
207 possible to crash the daemon by looping symlinks. In our opinion
208 significant stupidity should result in an appropriate amount of
209 pain.
210 It is no problem to have a block like "<Plugin foo>" in more than
212 one file, but you cannot include files from within blocks.
213 PIDFile File
215 Sets where to write the PID file to. This file is overwritten when
216 it exists and deleted when the program is stopped. Some init-
217 scripts might override this setting using the -P command-line
218 option.
219 PluginDir Directory
221 Path to the plugins (shared objects) of collectd.
222 TypesDB File [File ...]
224 Set one or more files that contain the data-set descriptions. See
225 types.db(5) for a description of the format of this file.
226 If this option is not specified, a default file is read. If you
228 need to define custom types in addition to the types defined in the
229 default file, you need to explicitly load both. In other words, if
230 the TypesDB option is encountered the default behavior is disabled
231 and if you need the default types you have to also explicitly load
232 them.
233 Interval Seconds
235 Configures the interval in which to query the read plugins.
236 Obviously smaller values lead to a higher system load produced by
237 collectd, while higher values lead to more coarse statistics.
238 Warning: You should set this once and then never touch it again. If
240 you do, you will have to delete all your RRD files or know some
241 serious RRDtool magic! (Assuming you're using the RRDtool or
242 RRDCacheD plugin.)
243 MaxReadInterval Seconds
245 A read plugin doubles the interval between queries after each
246 failed attempt to get data.
247 This options limits the maximum value of the interval. The default
249 value is 86400.
250 Timeout Iterations
252 Consider a value list "missing" when no update has been read or
253 received for Iterations iterations. By default, collectd considers
254 a value list missing when no update has been received for twice the
255 update interval. Since this setting uses iterations, the maximum
256 allowed time without update depends on the Interval information
257 contained in each value list. This is used in the Threshold
258 configuration to dispatch notifications about missing values, see
259 collectd-threshold(5) for details.
260 ReadThreads Num
262 Number of threads to start for reading plugins. The default value
263 is 5, but you may want to increase this if you have more than five
264 plugins that take a long time to read. Mostly those are plugins
265 that do network-IO. Setting this to a value higher than the number
266 of registered read callbacks is not recommended.
267 WriteThreads Num
269 Number of threads to start for dispatching value lists to write
270 plugins. The default value is 5, but you may want to increase this
271 if you have more than five plugins that may take relatively long to
272 write to.
273 WriteQueueLimitHigh HighNum
275 WriteQueueLimitLow LowNum
276 Metrics are read by the read threads and then put into a queue to
277 be handled by the write threads. If one of the write plugins is
278 slow (e.g. network timeouts, I/O saturation of the disk) this queue
279 will grow. In order to avoid running into memory issues in such a
280 case, you can limit the size of this queue.
281 By default, there is no limit and memory may grow indefinitely.
283 This is most likely not an issue for clients, i.e. instances that
284 only handle the local metrics. For servers it is recommended to set
285 this to a non-zero value, though.
286 You can set the limits using WriteQueueLimitHigh and
288 WriteQueueLimitLow. Each of them takes a numerical argument which
289 is the number of metrics in the queue. If there are HighNum metrics
290 in the queue, any new metrics will be dropped. If there are less
291 than LowNum metrics in the queue, all new metrics will be enqueued.
292 If the number of metrics currently in the queue is between LowNum
293 and HighNum, the metric is dropped with a probability that is
294 proportional to the number of metrics in the queue (i.e. it
295 increases linearly until it reaches 100%.)
296 If WriteQueueLimitHigh is set to non-zero and WriteQueueLimitLow is
298 unset, the latter will default to half of WriteQueueLimitHigh.
299 If you do not want to randomly drop values when the queue size is
301 between LowNum and HighNum, set WriteQueueLimitHigh and
302 WriteQueueLimitLow to the same value.
303 Enabling the CollectInternalStats option is of great help to figure
305 out the values to set WriteQueueLimitHigh and WriteQueueLimitLow
306 to.
307 Hostname Name
309 Sets the hostname that identifies a host. If you omit this setting,
310 the hostname will be determined using the gethostname(2) system
311 call.
312 FQDNLookup true|false
314 If Hostname is determined automatically this setting controls
315 whether or not the daemon should try to figure out the "fully
316 qualified domain name", FQDN. This is done using a lookup of the
317 name returned by "gethostname". This option is enabled by default.
318 PreCacheChain ChainName
320 PostCacheChain ChainName
321 Configure the name of the "pre-cache chain" and the "post-cache
322 chain". Please see "FILTER CONFIGURATION" below on information on
323 chains and how these setting change the daemon's behavior.
324
326 Some plugins may register own options. These options must be enclosed
327 in a "Plugin"-Section. Which options exist depends on the plugin used.
328 Some plugins require external configuration, too. The "apache plugin",
329 for example, required "mod_status" to be configured in the webserver
330 you're going to collect data from. These plugins are listed below as
331 well, even if they don't require any configuration within collectd's
332 configuration file.
333 A list of all plugins and a short summary for each plugin can be found
335 in the README file shipped with the sourcecode and hopefully binary
336 packets as well.
337 Plugin "aggregation"
339 The Aggregation plugin makes it possible to aggregate several values
340 into one using aggregation functions such as sum, average, min and max.
341 This can be put to a wide variety of uses, e.g. average and total CPU
342 statistics for your entire fleet.
343 The grouping is powerful but, as with many powerful tools, may be a bit
345 difficult to wrap your head around. The grouping will therefore be
346 demonstrated using an example: The average and sum of the CPU usage
347 across all CPUs of each host is to be calculated.
348 To select all the affected values for our example, set "Plugin cpu" and
350 "Type cpu". The other values are left unspecified, meaning "all
351 values". The Host, Plugin, PluginInstance, Type and TypeInstance
352 options work as if they were specified in the "WHERE" clause of an
353 "SELECT" SQL statement.
354 Plugin "cpu"
356 Type "cpu"
357 Although the Host, PluginInstance (CPU number, i.e. 0, 1, 2, ...) and
359 TypeInstance (idle, user, system, ...) fields are left unspecified in
360 the example, the intention is to have a new value for each host / type
361 instance pair. This is achieved by "grouping" the values using the
362 "GroupBy" option. It can be specified multiple times to group by more
363 than one field.
364 GroupBy "Host"
366 GroupBy "TypeInstance"
367 We do neither specify nor group by plugin instance (the CPU number), so
369 all metrics that differ in the CPU number only will be aggregated. Each
370 aggregation needs at least one such field, otherwise no aggregation
371 would take place.
372 The full example configuration looks like this:
374 <Plugin "aggregation">
376 <Aggregation>
377 Plugin "cpu"
378 Type "cpu"
379 GroupBy "Host"
381 GroupBy "TypeInstance"
382 CalculateSum true
384 CalculateAverage true
385 </Aggregation>
386 </Plugin>
387 There are a couple of limitations you should be aware of:
389 · The Type cannot be left unspecified, because it is not reasonable
391 to add apples to oranges. Also, the internal lookup structure won't
392 work if you try to group by type.
393 · There must be at least one unspecified, ungrouped field. Otherwise
395 nothing will be aggregated.
396 As you can see in the example above, each aggregation has its own
398 Aggregation block. You can have multiple aggregation blocks and
399 aggregation blocks may match the same values, i.e. one value list can
400 update multiple aggregations. The following options are valid inside
401 Aggregation blocks:
402 Host Host
404 Plugin Plugin
405 PluginInstance PluginInstance
406 Type Type
407 TypeInstance TypeInstance
408 Selects the value lists to be added to this aggregation. Type must
409 be a valid data set name, see types.db(5) for details.
410 If the string starts with and ends with a slash ("/"), the string
412 is interpreted as a regular expression. The regex flavor used are
413 POSIX extended regular expressions as described in regex(7).
414 Example usage:
415 Host "/^db[0-9]\\.example\\.com$/"
417 GroupBy Host|Plugin|PluginInstance|TypeInstance
419 Group valued by the specified field. The GroupBy option may be
420 repeated to group by multiple fields.
421 SetHost Host
423 SetPlugin Plugin
424 SetPluginInstance PluginInstance
425 SetTypeInstance TypeInstance
426 Sets the appropriate part of the identifier to the provided string.
427 The PluginInstance should include the placeholder "%{aggregation}"
429 which will be replaced with the aggregation function, e.g.
430 "average". Not including the placeholder will result in duplication
431 warnings and/or messed up values if more than one aggregation
432 function are enabled.
433 The following example calculates the average usage of all "even"
435 CPUs:
436 <Plugin "aggregation">
438 <Aggregation>
439 Plugin "cpu"
440 PluginInstance "/[0,2,4,6,8]$/"
441 Type "cpu"
442 SetPlugin "cpu"
444 SetPluginInstance "even-%{aggregation}"
445 GroupBy "Host"
447 GroupBy "TypeInstance"
448 CalculateAverage true
450 </Aggregation>
451 </Plugin>
452 This will create the files:
454 · foo.example.com/cpu-even-average/cpu-idle
456 · foo.example.com/cpu-even-average/cpu-system
458 · foo.example.com/cpu-even-average/cpu-user
460 · ...
462 CalculateNum true|false
464 CalculateSum true|false
465 CalculateAverage true|false
466 CalculateMinimum true|false
467 CalculateMaximum true|false
468 CalculateStddev true|false
469 Boolean options for enabling calculation of the number of value
470 lists, their sum, average, minimum, maximum and / or standard
471 deviation. All options are disabled by default.
472 Plugin "amqp"
474 The AMQP plugin can be used to communicate with other instances of
475 collectd or third party applications using an AMQP 0.9.1 message
476 broker. Values are sent to or received from the broker, which handles
477 routing, queueing and possibly filtering out messages.
478 Synopsis:
480 <Plugin "amqp">
482 # Send values to an AMQP broker
483 <Publish "some_name">
484 Host "localhost"
485 Port "5672"
486 VHost "/"
487 User "guest"
488 Password "guest"
489 Exchange "amq.fanout"
490 # ExchangeType "fanout"
491 # RoutingKey "collectd"
492 # Persistent false
493 # ConnectionRetryDelay 0
494 # Format "command"
495 # StoreRates false
496 # GraphitePrefix "collectd."
497 # GraphiteEscapeChar "_"
498 # GraphiteSeparateInstances false
499 # GraphiteAlwaysAppendDS false
500 # GraphitePreserveSeparator false
501 </Publish>
502 # Receive values from an AMQP broker
504 <Subscribe "some_name">
505 Host "localhost"
506 Port "5672"
507 VHost "/"
508 User "guest"
509 Password "guest"
510 Exchange "amq.fanout"
511 # ExchangeType "fanout"
512 # Queue "queue_name"
513 # QueueDurable false
514 # QueueAutoDelete true
515 # RoutingKey "collectd.#"
516 # ConnectionRetryDelay 0
517 </Subscribe>
518 </Plugin>
519 The plugin's configuration consists of a number of Publish and
521 Subscribe blocks, which configure sending and receiving of values
522 respectively. The two blocks are very similar, so unless otherwise
523 noted, an option can be used in either block. The name given in the
524 blocks starting tag is only used for reporting messages, but may be
525 used to support flushing of certain Publish blocks in the future.
526 Host Host
528 Hostname or IP-address of the AMQP broker. Defaults to the default
529 behavior of the underlying communications library, rabbitmq-c,
530 which is "localhost".
531 Port Port
533 Service name or port number on which the AMQP broker accepts
534 connections. This argument must be a string, even if the numeric
535 form is used. Defaults to "5672".
536 VHost VHost
538 Name of the virtual host on the AMQP broker to use. Defaults to
539 "/".
540 User User
542 Password Password
543 Credentials used to authenticate to the AMQP broker. By default
544 "guest"/"guest" is used.
545 Exchange Exchange
547 In Publish blocks, this option specifies the exchange to send
548 values to. By default, "amq.fanout" will be used.
549 In Subscribe blocks this option is optional. If given, a binding
551 between the given exchange and the queue is created, using the
552 routing key if configured. See the Queue and RoutingKey options
553 below.
554 ExchangeType Type
556 If given, the plugin will try to create the configured exchange
557 with this type after connecting. When in a Subscribe block, the
558 queue will then be bound to this exchange.
559 Queue Queue (Subscribe only)
561 Configures the queue name to subscribe to. If no queue name was
562 configured explicitly, a unique queue name will be created by the
563 broker.
564 QueueDurable true|false (Subscribe only)
566 Defines if the queue subscribed to is durable (saved to persistent
567 storage) or transient (will disappear if the AMQP broker is
568 restarted). Defaults to "false".
569 This option should be used in conjunction with the Persistent
571 option on the publish side.
572 QueueAutoDelete true|false (Subscribe only)
574 Defines if the queue subscribed to will be deleted once the last
575 consumer unsubscribes. Defaults to "true".
576 RoutingKey Key
578 In Publish blocks, this configures the routing key to set on all
579 outgoing messages. If not given, the routing key will be computed
580 from the identifier of the value. The host, plugin, type and the
581 two instances are concatenated together using dots as the separator
582 and all containing dots replaced with slashes. For example
583 "collectd.host/example/com.cpu.0.cpu.user". This makes it possible
584 to receive only specific values using a "topic" exchange.
585 In Subscribe blocks, configures the routing key used when creating
587 a binding between an exchange and the queue. The usual wildcards
588 can be used to filter messages when using a "topic" exchange. If
589 you're only interested in CPU statistics, you could use the routing
590 key "collectd.*.cpu.#" for example.
591 Persistent true|false (Publish only)
593 Selects the delivery method to use. If set to true, the persistent
594 mode will be used, i.e. delivery is guaranteed. If set to false
595 (the default), the transient delivery mode will be used, i.e.
596 messages may be lost due to high load, overflowing queues or
597 similar issues.
598 ConnectionRetryDelay Delay
600 When the connection to the AMQP broker is lost, defines the time in
601 seconds to wait before attempting to reconnect. Defaults to 0,
602 which implies collectd will attempt to reconnect at each read
603 interval (in Subscribe mode) or each time values are ready for
604 submission (in Publish mode).
605 Format Command|JSON|Graphite (Publish only)
607 Selects the format in which messages are sent to the broker. If set
608 to Command (the default), values are sent as "PUTVAL" commands
609 which are identical to the syntax used by the Exec and UnixSock
610 plugins. In this case, the "Content-Type" header field will be set
611 to "text/collectd".
612 If set to JSON, the values are encoded in the JavaScript Object
614 Notation, an easy and straight forward exchange format. The
615 "Content-Type" header field will be set to "application/json".
616 If set to Graphite, values are encoded in the Graphite format,
618 which is "<metric> <value> <timestamp>\n". The "Content-Type"
619 header field will be set to "text/graphite".
620 A subscribing client should use the "Content-Type" header field to
622 determine how to decode the values. Currently, the AMQP plugin
623 itself can only decode the Command format.
624 StoreRates true|false (Publish only)
626 Determines whether or not "COUNTER", "DERIVE" and "ABSOLUTE" data
627 sources are converted to a rate (i.e. a "GAUGE" value). If set to
628 false (the default), no conversion is performed. Otherwise the
629 conversion is performed using the internal value cache.
630 Please note that currently this option is only used if the Format
632 option has been set to JSON.
633 GraphitePrefix (Publish and Format=Graphite only)
635 A prefix can be added in the metric name when outputting in the
636 Graphite format. It's added before the Host name. Metric name
637 will be "<prefix><host><postfix><plugin><type><name>"
638 GraphitePostfix (Publish and Format=Graphite only)
640 A postfix can be added in the metric name when outputting in the
641 Graphite format. It's added after the Host name. Metric name will
642 be "<prefix><host><postfix><plugin><type><name>"
643 GraphiteEscapeChar (Publish and Format=Graphite only)
645 Specify a character to replace dots (.) in the host part of the
646 metric name. In Graphite metric name, dots are used as separators
647 between different metric parts (host, plugin, type). Default is
648 "_" (Underscore).
649 GraphiteSeparateInstances true|false
651 If set to true, the plugin instance and type instance will be in
652 their own path component, for example "host.cpu.0.cpu.idle". If set
653 to false (the default), the plugin and plugin instance (and
654 likewise the type and type instance) are put into one component,
655 for example "host.cpu-0.cpu-idle".
656 GraphiteAlwaysAppendDS true|false
658 If set to true, append the name of the Data Source (DS) to the
659 "metric" identifier. If set to false (the default), this is only
660 done when there is more than one DS.
661 GraphitePreserveSeparator false|true
663 If set to false (the default) the "." (dot) character is replaced
664 with GraphiteEscapeChar. Otherwise, if set to true, the "." (dot)
665 character is preserved, i.e. passed through.
666 Plugin "amqp1"
668 The AMQP1 plugin can be used to communicate with other instances of
669 collectd or third party applications using an AMQP 1.0 message
670 intermediary. Metric values or notifications are sent to the messaging
671 intermediary which may handle direct messaging or queue based transfer.
672 Synopsis:
674 <Plugin "amqp1">
676 # Send values to an AMQP 1.0 intermediary
677 <Transport "name">
678 Host "localhost"
679 Port "5672"
680 User "guest"
681 Password "guest"
682 Address "collectd"
683 # RetryDelay 1
684 <Instance "some_name">
685 Format "command"
686 PreSettle false
687 Notify false
688 # StoreRates false
689 # GraphitePrefix "collectd."
690 # GraphiteEscapeChar "_"
691 # GraphiteSeparateInstances false
692 # GraphiteAlwaysAppendDS false
693 # GraphitePreserveSeparator false
694 </Instance>
695 </Transport>
696 </Plugin>
697 The plugin's configuration consists of a Transport that configures
699 communications to the AMQP 1.0 messaging bus and one or more Instance
700 corresponding to metric or event publishers to the messaging system.
701 The address in the Transport block concatenated with the name given in
703 the Instance block starting tag will be used as the send-to address for
704 communications over the messaging link.
705 The following options are accepted within each Transport block:
707 Host Host
709 Hostname or IP-address of the AMQP 1.0 intermediary. Defaults to
710 the default behavior of the underlying communications library,
711 libqpid-proton, which is "localhost".
712 Port Port
714 Service name or port number on which the AMQP 1.0 intermediary
715 accepts connections. This argument must be a string, even if the
716 numeric form is used. Defaults to "5672".
717 User User
719 Password Password
720 Credentials used to authenticate to the AMQP 1.0 intermediary. By
721 default "guest"/"guest" is used.
722 Address Address
724 This option specifies the prefix for the send-to value in the
725 message. By default, "collectd" will be used.
726 RetryDelay RetryDelay
728 When the AMQP1 connection is lost, defines the time in seconds to
729 wait before attempting to reconnect. Defaults to 1, which implies
730 attempt to reconnect at 1 second intervals.
731 The following options are accepted within each Instance block:
733 Format Command|JSON|Graphite
735 Selects the format in which messages are sent to the intermediary.
736 If set to Command (the default), values are sent as "PUTVAL"
737 commands which are identical to the syntax used by the Exec and
738 UnixSock plugins. In this case, the "Content-Type" header field
739 will be set to "text/collectd".
740 If set to JSON, the values are encoded in the JavaScript Object
742 Notation, an easy and straight forward exchange format. The
743 "Content-Type" header field will be set to "application/json".
744 If set to Graphite, values are encoded in the Graphite format,
746 which is "<metric> <value> <timestamp>\n". The "Content-Type"
747 header field will be set to "text/graphite".
748 A subscribing client should use the "Content-Type" header field to
750 determine how to decode the values.
751 PreSettle true|false
753 If set to false (the default), the plugin will wait for a message
754 acknowledgement from the messaging bus before sending the next
755 message. This indicates transfer of ownership to the messaging
756 system. If set to true, the plugin will not wait for a message
757 acknowledgement and the message may be dropped prior to transfer of
758 ownership.
759 Notify true|false
761 If set to false (the default), the plugin will service the instance
762 write call back as a value list. If set to true the plugin will
763 service the instance as a write notification callback for alert
764 formatting.
765 StoreRates true|false
767 Determines whether or not "COUNTER", "DERIVE" and "ABSOLUTE" data
768 sources are converted to a rate (i.e. a "GAUGE" value). If set to
769 false (the default), no conversion is performed. Otherwise the
770 conversion is performed using the internal value cache.
771 Please note that currently this option is only used if the Format
773 option has been set to JSON.
774 GraphitePrefix
776 A prefix can be added in the metric name when outputting in the
777 Graphite format. It's added before the Host name. Metric name
778 will be "<prefix><host><postfix><plugin><type><name>"
779 GraphitePostfix
781 A postfix can be added in the metric name when outputting in the
782 Graphite format. It's added after the Host name. Metric name will
783 be "<prefix><host><postfix><plugin><type><name>"
784 GraphiteEscapeChar
786 Specify a character to replace dots (.) in the host part of the
787 metric name. In Graphite metric name, dots are used as separators
788 between different metric parts (host, plugin, type). Default is
789 "_" (Underscore).
790 GraphiteSeparateInstances true|false
792 If set to true, the plugin instance and type instance will be in
793 their own path component, for example "host.cpu.0.cpu.idle". If set
794 to false (the default), the plugin and plugin instance (and
795 likewise the type and type instance) are put into one component,
796 for example "host.cpu-0.cpu-idle".
797 GraphiteAlwaysAppendDS true|false
799 If set to true, append the name of the Data Source (DS) to the
800 "metric" identifier. If set to false (the default), this is only
801 done when there is more than one DS.
802 GraphitePreserveSeparator false|true
804 If set to false (the default) the "." (dot) character is replaced
805 with GraphiteEscapeChar. Otherwise, if set to true, the "." (dot)
806 character is preserved, i.e. passed through.
807 Plugin "apache"
809 To configure the "apache"-plugin you first need to configure the Apache
810 webserver correctly. The Apache-plugin "mod_status" needs to be loaded
811 and working and the "ExtendedStatus" directive needs to be enabled. You
812 can use the following snipped to base your Apache config upon:
813 ExtendedStatus on
815 <IfModule mod_status.c>
816 <Location /mod_status>
817 SetHandler server-status
818 </Location>
819 </IfModule>
820 Since its "mod_status" module is very similar to Apache's, lighttpd is
822 also supported. It introduces a new field, called "BusyServers", to
823 count the number of currently connected clients. This field is also
824 supported.
825 The configuration of the Apache plugin consists of one or more
827 "<Instance />" blocks. Each block requires one string argument as the
828 instance name. For example:
829 <Plugin "apache">
831 <Instance "www1">
832 URL "http://www1.example.com/mod_status?auto"
833 </Instance>
834 <Instance "www2">
835 URL "http://www2.example.com/mod_status?auto"
836 </Instance>
837 </Plugin>
838 The instance name will be used as the plugin instance. To emulate the
840 old (version 4) behavior, you can use an empty string (""). In order
841 for the plugin to work correctly, each instance name must be unique.
842 This is not enforced by the plugin and it is your responsibility to
843 ensure it.
844 The following options are accepted within each Instance block:
846 URL http://host/mod_status?auto
848 Sets the URL of the "mod_status" output. This needs to be the
849 output generated by "ExtendedStatus on" and it needs to be the
850 machine readable output generated by appending the "?auto"
851 argument. This option is mandatory.
852 User Username
854 Optional user name needed for authentication.
855 Password Password
857 Optional password needed for authentication.
858 VerifyPeer true|false
860 Enable or disable peer SSL certificate verification. See
861 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
862 default.
863 VerifyHost true|false
865 Enable or disable peer host name verification. If enabled, the
866 plugin checks if the "Common Name" or a "Subject Alternate Name"
867 field of the SSL certificate matches the host name provided by the
868 URL option. If this identity check fails, the connection is
869 aborted. Obviously, only works when connecting to a SSL enabled
870 server. Enabled by default.
871 CACert File
873 File that holds one or more SSL certificates. If you want to use
874 HTTPS you will possibly need this option. What CA certificates come
875 bundled with "libcurl" and are checked by default depends on the
876 distribution you use.
877 SSLCiphers list of ciphers
879 Specifies which ciphers to use in the connection. The list of
880 ciphers must specify valid ciphers. See
881 <http://www.openssl.org/docs/apps/ciphers.html> for details.
882 Timeout Milliseconds
884 The Timeout option sets the overall timeout for HTTP requests to
885 URL, in milliseconds. By default, the configured Interval is used
886 to set the timeout.
887 Plugin "apcups"
889 Host Hostname
890 Hostname of the host running apcupsd. Defaults to localhost. Please
891 note that IPv6 support has been disabled unless someone can confirm
892 or decline that apcupsd can handle it.
893 Port Port
895 TCP-Port to connect to. Defaults to 3551.
896 ReportSeconds true|false
898 If set to true, the time reported in the "timeleft" metric will be
899 converted to seconds. This is the recommended setting. If set to
900 false, the default for backwards compatibility, the time will be
901 reported in minutes.
902 PersistentConnection true|false
904 The plugin is designed to keep the connection to apcupsd open
905 between reads. If plugin poll interval is greater than 15 seconds
906 (hardcoded socket close timeout in apcupsd NIS), then this option
907 is false by default.
908 You can instruct the plugin to close the connection after each read
910 by setting this option to false or force keeping the connection by
911 setting it to true.
912 If apcupsd appears to close the connection due to inactivity quite
914 quickly, the plugin will try to detect this problem and switch to
915 an open-read-close mode.
916 Plugin "aquaero"
918 This plugin collects the value of the available sensors in an Aquaero 5
919 board. Aquaero 5 is a water-cooling controller board, manufactured by
920 Aqua Computer GmbH <http://www.aquacomputer.de/>, with a USB2
921 connection for monitoring and configuration. The board can handle
922 multiple temperature sensors, fans, water pumps and water level sensors
923 and adjust the output settings such as fan voltage or power used by the
924 water pump based on the available inputs using a configurable
925 controller included in the board. This plugin collects all the
926 available inputs as well as some of the output values chosen by this
927 controller. The plugin is based on the libaquaero5 library provided by
928 aquatools-ng.
929 Device DevicePath
931 Device path of the Aquaero 5's USB HID (human interface device),
932 usually in the form "/dev/usb/hiddevX". If this option is no set
933 the plugin will try to auto-detect the Aquaero 5 USB device based
934 on vendor-ID and product-ID.
935 Plugin "ascent"
937 This plugin collects information about an Ascent server, a free server
938 for the "World of Warcraft" game. This plugin gathers the information
939 by fetching the XML status page using "libcurl" and parses it using
940 "libxml2".
941 The configuration options are the same as for the "apache" plugin
943 above:
944 URL http://localhost/ascent/status/
946 Sets the URL of the XML status output.
947 User Username
949 Optional user name needed for authentication.
950 Password Password
952 Optional password needed for authentication.
953 VerifyPeer true|false
955 Enable or disable peer SSL certificate verification. See
956 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
957 default.
958 VerifyHost true|false
960 Enable or disable peer host name verification. If enabled, the
961 plugin checks if the "Common Name" or a "Subject Alternate Name"
962 field of the SSL certificate matches the host name provided by the
963 URL option. If this identity check fails, the connection is
964 aborted. Obviously, only works when connecting to a SSL enabled
965 server. Enabled by default.
966 CACert File
968 File that holds one or more SSL certificates. If you want to use
969 HTTPS you will possibly need this option. What CA certificates come
970 bundled with "libcurl" and are checked by default depends on the
971 distribution you use.
972 Timeout Milliseconds
974 The Timeout option sets the overall timeout for HTTP requests to
975 URL, in milliseconds. By default, the configured Interval is used
976 to set the timeout.
977 Plugin "barometer"
979 This plugin reads absolute air pressure using digital barometer sensor
980 on a I2C bus. Supported sensors are:
981 MPL115A2 from Freescale, see
983 <http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL115A>.
984 MPL3115 from Freescale see
985 <http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MPL3115A2>.
986 BMP085 from Bosch Sensortec
987 The sensor type - one of the above - is detected automatically by the
989 plugin and indicated in the plugin_instance (you will see subdirectory
990 "barometer-mpl115" or "barometer-mpl3115", or "barometer-bmp085"). The
991 order of detection is BMP085 -> MPL3115 -> MPL115A2, the first one
992 found will be used (only one sensor can be used by the plugin).
993 The plugin provides absolute barometric pressure, air pressure reduced
995 to sea level (several possible approximations) and as an auxiliary
996 value also internal sensor temperature. It uses (expects/provides)
997 typical metric units - pressure in [hPa], temperature in [C], altitude
998 in [m].
999 It was developed and tested under Linux only. The only platform
1001 dependency is the standard Linux i2c-dev interface (the particular bus
1002 driver has to support the SM Bus command subset).
1003 The reduction or normalization to mean sea level pressure requires
1005 (depending on selected method/approximation) also altitude and
1006 reference to temperature sensor(s). When multiple temperature sensors
1007 are configured the minimum of their values is always used (expecting
1008 that the warmer ones are affected by e.g. direct sun light at that
1009 moment).
1010 Synopsis:
1012 <Plugin "barometer">
1014 Device "/dev/i2c-0";
1015 Oversampling 512
1016 PressureOffset 0.0
1017 TemperatureOffset 0.0
1018 Normalization 2
1019 Altitude 238.0
1020 TemperatureSensor "myserver/onewire-F10FCA000800/temperature"
1021 </Plugin>
1022 Device device
1024 The only mandatory configuration parameter.
1025 Device name of the I2C bus to which the sensor is connected. Note
1027 that typically you need to have loaded the i2c-dev module. Using
1028 i2c-tools you can check/list i2c buses available on your system by:
1029 i2cdetect -l
1031 Then you can scan for devices on given bus. E.g. to scan the whole
1033 bus 0 use:
1034 i2cdetect -y -a 0
1036 This way you should be able to verify that the pressure sensor
1038 (either type) is connected and detected on address 0x60.
1039 Oversampling value
1041 Optional parameter controlling the oversampling/accuracy. Default
1042 value is 1 providing fastest and least accurate reading.
1043 For MPL115 this is the size of the averaging window. To filter out
1045 sensor noise a simple averaging using floating window of this
1046 configurable size is used. The plugin will use average of the last
1047 "value" measurements (value of 1 means no averaging). Minimal size
1048 is 1, maximal 1024.
1049 For MPL3115 this is the oversampling value. The actual oversampling
1051 is performed by the sensor and the higher value the higher accuracy
1052 and longer conversion time (although nothing to worry about in the
1053 collectd context). Supported values are: 1, 2, 4, 8, 16, 32, 64
1054 and 128. Any other value is adjusted by the plugin to the closest
1055 supported one.
1056 For BMP085 this is the oversampling value. The actual oversampling
1058 is performed by the sensor and the higher value the higher accuracy
1059 and longer conversion time (although nothing to worry about in the
1060 collectd context). Supported values are: 1, 2, 4, 8. Any other
1061 value is adjusted by the plugin to the closest supported one.
1062 PressureOffset offset
1064 Optional parameter for MPL3115 only.
1065 You can further calibrate the sensor by supplying pressure and/or
1067 temperature offsets. This is added to the measured/caclulated
1068 value (i.e. if the measured value is too high then use negative
1069 offset). In hPa, default is 0.0.
1070 TemperatureOffset offset
1072 Optional parameter for MPL3115 only.
1073 You can further calibrate the sensor by supplying pressure and/or
1075 temperature offsets. This is added to the measured/caclulated
1076 value (i.e. if the measured value is too high then use negative
1077 offset). In C, default is 0.0.
1078 Normalization method
1080 Optional parameter, default value is 0.
1081 Normalization method - what approximation/model is used to compute
1083 the mean sea level pressure from the air absolute pressure.
1084 Supported values of the "method" (integer between from 0 to 2) are:
1086 0 - no conversion, absolute pressure is simply copied over. For
1088 this method you do not need to configure "Altitude" or
1089 "TemperatureSensor".
1090 1 - international formula for conversion , See
1091 <http://en.wikipedia.org/wiki/Atmospheric_pressure#Altitude_atmospheric_pressure_variation>.
1092 For this method you have to configure "Altitude" but do not need
1093 "TemperatureSensor" (uses fixed global temperature average
1094 instead).
1095 2 - formula as recommended by the Deutsche Wetterdienst (German
1096 Meteorological Service). See
1097 <http://de.wikipedia.org/wiki/Barometrische_H%C3%B6henformel#Theorie>
1098 For this method you have to configure both "Altitude" and
1099 "TemperatureSensor".
1100 Altitude altitude
1101 The altitude (in meters) of the location where you meassure the
1102 pressure.
1103 TemperatureSensor reference
1105 Temperature sensor(s) which should be used as a reference when
1106 normalizing the pressure using "Normalization" method 2. When
1107 specified more sensors a minimum is found and used each time. The
1108 temperature reading directly from this pressure sensor/plugin is
1109 typically not suitable as the pressure sensor will be probably
1110 inside while we want outside temperature. The collectd reference
1111 name is something like
1112 <hostname>/<plugin_name>-<plugin_instance>/<type>-<type_instance>
1113 (<type_instance> is usually omitted when there is just single value
1114 type). Or you can figure it out from the path of the output data
1115 files.
1116 Plugin "battery"
1118 The battery plugin reports the remaining capacity, power and voltage of
1119 laptop batteries.
1120 ValuesPercentage false|true
1122 When enabled, remaining capacity is reported as a percentage, e.g.
1123 "42% capacity remaining". Otherwise the capacity is stored as
1124 reported by the battery, most likely in "Wh". This option does not
1125 work with all input methods, in particular when only "/proc/pmu" is
1126 available on an old Linux system. Defaults to false.
1127 ReportDegraded false|true
1129 Typical laptop batteries degrade over time, meaning the capacity
1130 decreases with recharge cycles. The maximum charge of the previous
1131 charge cycle is tracked as "last full capacity" and used to
1132 determine that a battery is "fully charged".
1133 When this option is set to false, the default, the battery plugin
1135 will only report the remaining capacity. If the ValuesPercentage
1136 option is enabled, the relative remaining capacity is calculated as
1137 the ratio of the "remaining capacity" and the "last full capacity".
1138 This is what most tools, such as the status bar of desktop
1139 environments, also do.
1140 When set to true, the battery plugin will report three values:
1142 charged (remaining capacity), discharged (difference between "last
1143 full capacity" and "remaining capacity") and degraded (difference
1144 between "design capacity" and "last full capacity").
1145 QueryStateFS false|true
1147 When set to true, the battery plugin will only read statistics
1148 related to battery performance as exposed by StateFS at /run/state.
1149 StateFS is used in Mer-based Sailfish OS, for example.
1150 Plugin "bind"
1152 Starting with BIND 9.5.0, the most widely used DNS server software
1153 provides extensive statistics about queries, responses and lots of
1154 other information. The bind plugin retrieves this information that's
1155 encoded in XML and provided via HTTP and submits the values to
1156 collectd.
1157 To use this plugin, you first need to tell BIND to make this
1159 information available. This is done with the "statistics-channels"
1160 configuration option:
1161 statistics-channels {
1163 inet localhost port 8053;
1164 };
1165 The configuration follows the grouping that can be seen when looking at
1167 the data with an XSLT compatible viewer, such as a modern web browser.
1168 It's probably a good idea to make yourself familiar with the provided
1169 values, so you can understand what the collected statistics actually
1170 mean.
1171 Synopsis:
1173 <Plugin "bind">
1175 URL "http://localhost:8053/"
1176 ParseTime false
1177 OpCodes true
1178 QTypes true
1179 ServerStats true
1181 ZoneMaintStats true
1182 ResolverStats false
1183 MemoryStats true
1184 <View "_default">
1186 QTypes true
1187 ResolverStats true
1188 CacheRRSets true
1189 Zone "127.in-addr.arpa/IN"
1191 </View>
1192 </Plugin>
1193 The bind plugin accepts the following configuration options:
1195 URL URL
1197 URL from which to retrieve the XML data. If not specified,
1198 "http://localhost:8053/" will be used.
1199 ParseTime true|false
1201 When set to true, the time provided by BIND will be parsed and used
1202 to dispatch the values. When set to false, the local time source is
1203 queried.
1204 This setting is set to true by default for backwards compatibility;
1206 setting this to false is recommended to avoid problems with
1207 timezones and localization.
1208 OpCodes true|false
1210 When enabled, statistics about the "OpCodes", for example the
1211 number of "QUERY" packets, are collected.
1212 Default: Enabled.
1214 QTypes true|false
1216 When enabled, the number of incoming queries by query types (for
1217 example "A", "MX", "AAAA") is collected.
1218 Default: Enabled.
1220 ServerStats true|false
1222 Collect global server statistics, such as requests received over
1223 IPv4 and IPv6, successful queries, and failed updates.
1224 Default: Enabled.
1226 ZoneMaintStats true|false
1228 Collect zone maintenance statistics, mostly information about
1229 notifications (zone updates) and zone transfers.
1230 Default: Enabled.
1232 ResolverStats true|false
1234 Collect resolver statistics, i. e. statistics about outgoing
1235 requests (e. g. queries over IPv4, lame servers). Since the global
1236 resolver counters apparently were removed in BIND 9.5.1 and 9.6.0,
1237 this is disabled by default. Use the ResolverStats option within a
1238 View "_default" block instead for the same functionality.
1239 Default: Disabled.
1241 MemoryStats
1243 Collect global memory statistics.
1244 Default: Enabled.
1246 Timeout Milliseconds
1248 The Timeout option sets the overall timeout for HTTP requests to
1249 URL, in milliseconds. By default, the configured Interval is used
1250 to set the timeout.
1251 View Name
1253 Collect statistics about a specific "view". BIND can behave
1254 different, mostly depending on the source IP-address of the
1255 request. These different configurations are called "views". If you
1256 don't use this feature, you most likely are only interested in the
1257 "_default" view.
1258 Within a <View name> block, you can specify which information you
1260 want to collect about a view. If no View block is configured, no
1261 detailed view statistics will be collected.
1262 QTypes true|false
1264 If enabled, the number of outgoing queries by query type (e. g.
1265 "A", "MX") is collected.
1266 Default: Enabled.
1268 ResolverStats true|false
1270 Collect resolver statistics, i. e. statistics about outgoing
1271 requests (e. g. queries over IPv4, lame servers).
1272 Default: Enabled.
1274 CacheRRSets true|false
1276 If enabled, the number of entries ("RR sets") in the view's
1277 cache by query type is collected. Negative entries (queries
1278 which resulted in an error, for example names that do not
1279 exist) are reported with a leading exclamation mark, e. g.
1280 "!A".
1281 Default: Enabled.
1283 Zone Name
1285 When given, collect detailed information about the given zone
1286 in the view. The information collected if very similar to the
1287 global ServerStats information (see above).
1288 You can repeat this option to collect detailed information
1290 about multiple zones.
1291 By default no detailed zone information is collected.
1293 Plugin "ceph"
1295 The ceph plugin collects values from JSON data to be parsed by libyajl
1296 (<https://lloyd.github.io/yajl/>) retrieved from ceph daemon admin
1297 sockets.
1298 A separate Daemon block must be configured for each ceph daemon to be
1300 monitored. The following example will read daemon statistics from four
1301 separate ceph daemons running on the same device (two OSDs, one MON,
1302 one MDS) :
1303 <Plugin ceph>
1305 LongRunAvgLatency false
1306 ConvertSpecialMetricTypes true
1307 <Daemon "osd.0">
1308 SocketPath "/var/run/ceph/ceph-osd.0.asok"
1309 </Daemon>
1310 <Daemon "osd.1">
1311 SocketPath "/var/run/ceph/ceph-osd.1.asok"
1312 </Daemon>
1313 <Daemon "mon.a">
1314 SocketPath "/var/run/ceph/ceph-mon.ceph1.asok"
1315 </Daemon>
1316 <Daemon "mds.a">
1317 SocketPath "/var/run/ceph/ceph-mds.ceph1.asok"
1318 </Daemon>
1319 </Plugin>
1320 The ceph plugin accepts the following configuration options:
1322 LongRunAvgLatency true|false
1324 If enabled, latency values(sum,count pairs) are calculated as the
1325 long run average - average since the ceph daemon was started = (sum
1326 / count). When disabled, latency values are calculated as the
1327 average since the last collection = (sum_now - sum_last) /
1328 (count_now - count_last).
1329 Default: Disabled
1331 ConvertSpecialMetricTypes true|false
1333 If enabled, special metrics (metrics that differ in type from
1334 similar counters) are converted to the type of those similar
1335 counters. This currently only applies to filestore.journal_wr_bytes
1336 which is a counter for OSD daemons. The ceph schema reports this
1337 metric type as a sum,count pair while similar counters are treated
1338 as derive types. When converted, the sum is used as the counter
1339 value and is treated as a derive type. When disabled, all metrics
1340 are treated as the types received from the ceph schema.
1341 Default: Enabled
1343 Each Daemon block must have a string argument for the plugin instance
1345 name. A SocketPath is also required for each Daemon block:
1346 Daemon DaemonName
1348 Name to be used as the instance name for this daemon.
1349 SocketPath SocketPath
1351 Specifies the path to the UNIX admin socket of the ceph daemon.
1352 Plugin "cgroups"
1354 This plugin collects the CPU user/system time for each cgroup by
1355 reading the cpuacct.stat files in the first cpuacct-mountpoint
1356 (typically /sys/fs/cgroup/cpu.cpuacct on machines using systemd).
1357 CGroup Directory
1359 Select cgroup based on the name. Whether only matching cgroups are
1360 collected or if they are ignored is controlled by the
1361 IgnoreSelected option; see below.
1362 See /"IGNORELISTS" for details.
1364 IgnoreSelected true|false
1366 Invert the selection: If set to true, all cgroups except the ones
1367 that match any one of the criteria are collected. By default only
1368 selected cgroups are collected if a selection is made. If no
1369 selection is configured at all, all cgroups are selected.
1370 Plugin "chrony"
1372 The "chrony" plugin collects ntp data from a chronyd server, such as
1373 clock skew and per-peer stratum.
1374 For talking to chronyd, it mimics what the chronyc control program does
1376 on the wire.
1377 Available configuration options for the "chrony" plugin:
1379 Host Hostname
1381 Hostname of the host running chronyd. Defaults to localhost.
1382 Port Port
1384 UDP-Port to connect to. Defaults to 323.
1385 Timeout Timeout
1387 Connection timeout in seconds. Defaults to 2.
1388 Plugin "conntrack"
1390 This plugin collects IP conntrack statistics.
1391 OldFiles
1393 Assume the conntrack_count and conntrack_max files to be found in
1394 /proc/sys/net/ipv4/netfilter instead of /proc/sys/net/netfilter/.
1395 Plugin "cpu"
1397 The CPU plugin collects CPU usage metrics. By default, CPU usage is
1398 reported as Jiffies, using the "cpu" type. Two aggregations are
1399 available:
1400 · Sum, per-state, over all CPUs installed in the system; and
1402 · Sum, per-CPU, over all non-idle states of a CPU, creating an
1404 "active" state.
1405 The two aggregations can be combined, leading to collectd only emitting
1407 a single "active" metric for the entire system. As soon as one of these
1408 aggregations (or both) is enabled, the cpu plugin will report a
1409 percentage, rather than Jiffies. In addition, you can request
1410 individual, per-state, per-CPU metrics to be reported as percentage.
1411 The following configuration options are available:
1413 ReportByState true|false
1415 When set to true, the default, reports per-state metrics, e.g.
1416 "system", "user" and "idle". When set to false, aggregates (sums)
1417 all non-idle states into one "active" metric.
1418 ReportByCpu true|false
1420 When set to true, the default, reports per-CPU (per-core) metrics.
1421 When set to false, instead of reporting metrics for individual
1422 CPUs, only a global sum of CPU states is emitted.
1423 ValuesPercentage false|true
1425 This option is only considered when both, ReportByCpu and
1426 ReportByState are set to true. In this case, by default, metrics
1427 will be reported as Jiffies. By setting this option to true, you
1428 can request percentage values in the un-aggregated (per-CPU, per-
1429 state) mode as well.
1430 ReportNumCpu false|true
1432 When set to true, reports the number of available CPUs. Defaults
1433 to false.
1434 ReportGuestState false|true
1436 When set to true, reports the "guest" and "guest_nice" CPU states.
1437 Defaults to false.
1438 SubtractGuestState false|true
1440 This option is only considered when ReportGuestState is set to
1441 true. "guest" and "guest_nice" are included in respectively "user"
1442 and "nice". If set to true, "guest" will be subtracted from "user"
1443 and "guest_nice" will be subtracted from "nice". Defaults to true.
1444 Plugin "cpufreq"
1446 This plugin is available on Linux and FreeBSD only. It doesn't have
1447 any options. On Linux it reads
1448 /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq (for the first
1449 CPU installed) to get the current CPU frequency. If this file does not
1450 exist make sure cpufreqd (<http://cpufreqd.sourceforge.net/>) or a
1451 similar tool is installed and an "cpu governor" (that's a kernel
1452 module) is loaded.
1453 On Linux, if the system has the cpufreq-stats kernel module loaded,
1455 this plugin reports the rate of p-state (cpu frequency) transitions and
1456 the percentage of time spent in each p-state.
1457 On FreeBSD it does a sysctl dev.cpu.0.freq and submits this as instance
1459 0. At this time FreeBSD only has one frequency setting for all cores.
1460 See the BUGS section in the FreeBSD man page for cpufreq(4) for more
1461 details.
1462 On FreeBSD the plugin checks the success of sysctl dev.cpu.0.freq and
1464 unregisters the plugin when this fails. A message will be logged to
1465 indicate this.
1466 Plugin "cpusleep"
1468 This plugin doesn't have any options. It reads CLOCK_BOOTTIME and
1469 CLOCK_MONOTONIC and reports the difference between these clocks. Since
1470 BOOTTIME clock increments while device is suspended and MONOTONIC clock
1471 does not, the derivative of the difference between these clocks gives
1472 the relative amount of time the device has spent in suspend state. The
1473 recorded value is in milliseconds of sleep per seconds of wall clock.
1474 Plugin "csv"
1476 DataDir Directory
1477 Set the directory to store CSV-files under. Per default CSV-files
1478 are generated beneath the daemon's working directory, i. e. the
1479 BaseDir. The special strings stdout and stderr can be used to
1480 write to the standard output and standard error channels,
1481 respectively. This, of course, only makes much sense when collectd
1482 is running in foreground- or non-daemon-mode.
1483 StoreRates true|false
1485 If set to true, convert counter values to rates. If set to false
1486 (the default) counter values are stored as is, i. e. as an
1487 increasing integer number.
1488 cURL Statistics
1490 All cURL-based plugins support collection of generic, request-based
1491 statistics. These are disabled by default and can be enabled
1492 selectively for each page or URL queried from the curl, curl_json, or
1493 curl_xml plugins. See the documentation of those plugins for specific
1494 information. This section describes the available metrics that can be
1495 configured for each plugin. All options are disabled by default.
1496 See <http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html> for more
1498 details.
1499 TotalTime true|false
1501 Total time of the transfer, including name resolving, TCP connect,
1502 etc.
1503 NamelookupTime true|false
1505 Time it took from the start until name resolving was completed.
1506 ConnectTime true|false
1508 Time it took from the start until the connect to the remote host
1509 (or proxy) was completed.
1510 AppconnectTime true|false
1512 Time it took from the start until the SSL/SSH connect/handshake to
1513 the remote host was completed.
1514 PretransferTime true|false
1516 Time it took from the start until just before the transfer begins.
1517 StarttransferTime true|false
1519 Time it took from the start until the first byte was received.
1520 RedirectTime true|false
1522 Time it took for all redirection steps include name lookup,
1523 connect, pre-transfer and transfer before final transaction was
1524 started.
1525 RedirectCount true|false
1527 The total number of redirections that were actually followed.
1528 SizeUpload true|false
1530 The total amount of bytes that were uploaded.
1531 SizeDownload true|false
1533 The total amount of bytes that were downloaded.
1534 SpeedDownload true|false
1536 The average download speed that curl measured for the complete
1537 download.
1538 SpeedUpload true|false
1540 The average upload speed that curl measured for the complete
1541 upload.
1542 HeaderSize true|false
1544 The total size of all the headers received.
1545 RequestSize true|false
1547 The total size of the issued requests.
1548 ContentLengthDownload true|false
1550 The content-length of the download.
1551 ContentLengthUpload true|false
1553 The specified size of the upload.
1554 NumConnects true|false
1556 The number of new connections that were created to achieve the
1557 transfer.
1558 Plugin "curl"
1560 The curl plugin uses the libcurl (<http://curl.haxx.se/>) to read web
1561 pages and the match infrastructure (the same code used by the tail
1562 plugin) to use regular expressions with the received data.
1563 The following example will read the current value of AMD stock from
1565 Google's finance page and dispatch the value to collectd.
1566 <Plugin curl>
1568 <Page "stock_quotes">
1569 Plugin "quotes"
1570 URL "http://finance.google.com/finance?q=NYSE%3AAMD"
1571 AddressFamily "any"
1572 User "foo"
1573 Password "bar"
1574 Digest false
1575 VerifyPeer true
1576 VerifyHost true
1577 CACert "/path/to/ca.crt"
1578 Header "X-Custom-Header: foobar"
1579 Post "foo=bar"
1580 MeasureResponseTime false
1582 MeasureResponseCode false
1583 <Match>
1585 Regex "<span +class=\"pr\"[^>]*> *([0-9]*\\.[0-9]+) *</span>"
1586 DSType "GaugeAverage"
1587 # Note: `stock_value' is not a standard type.
1588 Type "stock_value"
1589 Instance "AMD"
1590 </Match>
1591 </Page>
1592 </Plugin>
1593 In the Plugin block, there may be one or more Page blocks, each
1595 defining a web page and one or more "matches" to be performed on the
1596 returned data. The string argument to the Page block is used as plugin
1597 instance.
1598 The following options are valid within Page blocks:
1600 Plugin Plugin
1602 Use Plugin as the plugin name when submitting values. Defaults to
1603 "curl".
1604 URL URL
1606 URL of the web site to retrieve. Since a regular expression will be
1607 used to extract information from this data, non-binary data is a
1608 big plus here ;)
1609 AddressFamily Type
1611 IP version to resolve URL to. Useful in cases when hostname in URL
1612 resolves to both IPv4 and IPv6 addresses, and you are interested in
1613 using one of them specifically. Use "ipv4" to enforce IPv4, "ipv6"
1614 to enforce IPv6, or "any" to keep the default behavior of resolving
1615 addresses to all IP versions your system allows. If "libcurl" is
1616 compiled without IPv6 support, using "ipv6" will result in a
1617 warning and fallback to "any". If "Type" cannot be parsed, a
1618 warning will be printed and the whole Page block will be ignored.
1619 User Name
1621 Username to use if authorization is required to read the page.
1622 Password Password
1624 Password to use if authorization is required to read the page.
1625 Digest true|false
1627 Enable HTTP digest authentication.
1628 VerifyPeer true|false
1630 Enable or disable peer SSL certificate verification. See
1631 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
1632 default.
1633 VerifyHost true|false
1635 Enable or disable peer host name verification. If enabled, the
1636 plugin checks if the "Common Name" or a "Subject Alternate Name"
1637 field of the SSL certificate matches the host name provided by the
1638 URL option. If this identity check fails, the connection is
1639 aborted. Obviously, only works when connecting to a SSL enabled
1640 server. Enabled by default.
1641 CACert file
1643 File that holds one or more SSL certificates. If you want to use
1644 HTTPS you will possibly need this option. What CA certificates come
1645 bundled with "libcurl" and are checked by default depends on the
1646 distribution you use.
1647 Header Header
1649 A HTTP header to add to the request. Multiple headers are added if
1650 this option is specified more than once.
1651 Post Body
1653 Specifies that the HTTP operation should be a POST instead of a
1654 GET. The complete data to be posted is given as the argument. This
1655 option will usually need to be accompanied by a Header option to
1656 set an appropriate "Content-Type" for the post body (e.g. to
1657 "application/x-www-form-urlencoded").
1658 MeasureResponseTime true|false
1660 Measure response time for the request. If this setting is enabled,
1661 Match blocks (see below) are optional. Disabled by default.
1662 Beware that requests will get aborted if they take too long to
1664 complete. Adjust Timeout accordingly if you expect
1665 MeasureResponseTime to report such slow requests.
1666 This option is similar to enabling the TotalTime statistic but it's
1668 measured by collectd instead of cURL.
1669 MeasureResponseCode true|false
1671 Measure response code for the request. If this setting is enabled,
1672 Match blocks (see below) are optional. Disabled by default.
1673 <Statistics>
1675 One Statistics block can be used to specify cURL statistics to be
1676 collected for each request to the remote web site. See the section
1677 "cURL Statistics" above for details. If this setting is enabled,
1678 Match blocks (see below) are optional.
1679 <Match>
1681 One or more Match blocks that define how to match information in
1682 the data returned by "libcurl". The "curl" plugin uses the same
1683 infrastructure that's used by the "tail" plugin, so please see the
1684 documentation of the "tail" plugin below on how matches are
1685 defined. If the MeasureResponseTime or MeasureResponseCode options
1686 are set to true, Match blocks are optional.
1687 Interval Interval
1689 Sets the interval (in seconds) in which the values will be
1690 collected from this URL. By default the global Interval setting
1691 will be used.
1692 Timeout Milliseconds
1694 The Timeout option sets the overall timeout for HTTP requests to
1695 URL, in milliseconds. By default, the configured Interval is used
1696 to set the timeout. Prior to version 5.5.0, there was no timeout
1697 and requests could hang indefinitely. This legacy behaviour can be
1698 achieved by setting the value of Timeout to 0.
1699 If Timeout is 0 or bigger than the Interval, keep in mind that each
1701 slow network connection will stall one read thread. Adjust the
1702 ReadThreads global setting accordingly to prevent this from
1703 blocking other plugins.
1704 Plugin "curl_json"
1706 The curl_json plugin collects values from JSON data to be parsed by
1707 libyajl (<https://lloyd.github.io/yajl/>) retrieved via either libcurl
1708 (<http://curl.haxx.se/>) or read directly from a unix socket. The
1709 former can be used, for example, to collect values from CouchDB
1710 documents (which are stored JSON notation), and the latter to collect
1711 values from a uWSGI stats socket.
1712 The following example will collect several values from the built-in
1714 "_stats" runtime statistics module of CouchDB
1715 (<http://wiki.apache.org/couchdb/Runtime_Statistics>).
1716 <Plugin curl_json>
1718 <URL "http://localhost:5984/_stats">
1719 AddressFamily "any"
1720 Instance "httpd"
1721 <Key "httpd/requests/count">
1722 Type "http_requests"
1723 </Key>
1724 <Key "httpd_request_methods/*/count">
1726 Type "http_request_methods"
1727 </Key>
1728 <Key "httpd_status_codes/*/count">
1730 Type "http_response_codes"
1731 </Key>
1732 </URL>
1733 </Plugin>
1734 This example will collect data directly from a uWSGI "Stats Server"
1736 socket.
1737 <Plugin curl_json>
1739 <Sock "/var/run/uwsgi.stats.sock">
1740 Instance "uwsgi"
1741 <Key "workers/*/requests">
1742 Type "http_requests"
1743 </Key>
1744 <Key "workers/*/apps/*/requests">
1746 Type "http_requests"
1747 </Key>
1748 </Sock>
1749 </Plugin>
1750 In the Plugin block, there may be one or more URL blocks, each defining
1752 a URL to be fetched via HTTP (using libcurl) or Sock blocks defining a
1753 unix socket to read JSON from directly. Each of these blocks may have
1754 one or more Key blocks.
1755 The Key string argument must be in a path format. Each component is
1757 used to match the key from a JSON map or the index of an JSON array. If
1758 a path component of a Key is a * wildcard, the values for all map keys
1759 or array indices will be collectd.
1760 The following options are valid within URL blocks:
1762 AddressFamily Type
1764 IP version to resolve URL to. Useful in cases when hostname in URL
1765 resolves to both IPv4 and IPv6 addresses, and you are interested in
1766 using one of them specifically. Use "ipv4" to enforce IPv4, "ipv6"
1767 to enforce IPv6, or "any" to keep the default behavior of resolving
1768 addresses to all IP versions your system allows. If "libcurl" is
1769 compiled without IPv6 support, using "ipv6" will result in a
1770 warning and fallback to "any". If "Type" cannot be parsed, a
1771 warning will be printed and the whole URL block will be ignored.
1772 Host Name
1774 Use Name as the host name when submitting values. Defaults to the
1775 global host name setting.
1776 Plugin Plugin
1778 Use Plugin as the plugin name when submitting values. Defaults to
1779 "curl_json".
1780 Instance Instance
1782 Sets the plugin instance to Instance.
1783 Interval Interval
1785 Sets the interval (in seconds) in which the values will be
1786 collected from this URL. By default the global Interval setting
1787 will be used.
1788 User Name
1790 Password Password
1791 Digest true|false
1792 VerifyPeer true|false
1793 VerifyHost true|false
1794 CACert file
1795 Header Header
1796 Post Body
1797 Timeout Milliseconds
1798 These options behave exactly equivalent to the appropriate options
1799 of the cURL plugin. Please see there for a detailed description.
1800 <Statistics>
1802 One Statistics block can be used to specify cURL statistics to be
1803 collected for each request to the remote URL. See the section "cURL
1804 Statistics" above for details.
1805 The following options are valid within Key blocks:
1807 Type Type
1809 Sets the type used to dispatch the values to the daemon. Detailed
1810 information about types and their configuration can be found in
1811 types.db(5). This option is mandatory.
1812 Instance Instance
1814 Type-instance to use. Defaults to the current map key or current
1815 string array element value.
1816 Plugin "curl_xml"
1818 The curl_xml plugin uses libcurl (<http://curl.haxx.se/>) and libxml2
1819 (<http://xmlsoft.org/>) to retrieve XML data via cURL.
1820 <Plugin "curl_xml">
1822 <URL "http://localhost/stats.xml">
1823 AddressFamily "any"
1824 Host "my_host"
1825 #Plugin "curl_xml"
1826 Instance "some_instance"
1827 User "collectd"
1828 Password "thaiNg0I"
1829 VerifyPeer true
1830 VerifyHost true
1831 CACert "/path/to/ca.crt"
1832 Header "X-Custom-Header: foobar"
1833 Post "foo=bar"
1834 <XPath "table[@id=\"magic_level\"]/tr">
1836 Type "magic_level"
1837 #InstancePrefix "prefix-"
1838 InstanceFrom "td[1]"
1839 #PluginInstanceFrom "td[1]"
1840 ValuesFrom "td[2]/span[@class=\"level\"]"
1841 </XPath>
1842 </URL>
1843 </Plugin>
1844 In the Plugin block, there may be one or more URL blocks, each defining
1846 a URL to be fetched using libcurl. Within each URL block there are
1847 options which specify the connection parameters, for example
1848 authentication information, and one or more XPath blocks.
1849 Each XPath block specifies how to get one type of information. The
1851 string argument must be a valid XPath expression which returns a list
1852 of "base elements". One value is dispatched for each "base element".
1853 The type instance and values are looked up using further XPath
1854 expressions that should be relative to the base element.
1855 Within the URL block the following options are accepted:
1857 AddressFamily Type
1859 IP version to resolve URL to. Useful in cases when hostname in URL
1860 resolves to both IPv4 and IPv6 addresses, and you are interested in
1861 using one of them specifically. Use "ipv4" to enforce IPv4, "ipv6"
1862 to enforce IPv6, or "any" to keep the default behavior of resolving
1863 addresses to all IP versions your system allows. If "libcurl" is
1864 compiled without IPv6 support, using "ipv6" will result in a
1865 warning and fallback to "any". If "Type" cannot be parsed, a
1866 warning will be printed and the whole URL block will be ignored.
1867 Host Name
1869 Use Name as the host name when submitting values. Defaults to the
1870 global host name setting.
1871 Plugin Plugin
1873 Use Plugin as the plugin name when submitting values. Defaults to
1874 'curl_xml'.
1875 Instance Instance
1877 Use Instance as the plugin instance when submitting values. May be
1878 overridden by PluginInstanceFrom option inside XPath blocks.
1879 Defaults to an empty string (no plugin instance).
1880 Interval Interval
1882 Sets the interval (in seconds) in which the values will be
1883 collected from this URL. By default the global Interval setting
1884 will be used.
1885 Namespace Prefix URL
1887 If an XPath expression references namespaces, they must be
1888 specified with this option. Prefix is the "namespace prefix" used
1889 in the XML document. URL is the "namespace name", an URI reference
1890 uniquely identifying the namespace. The option can be repeated to
1891 register multiple namespaces.
1892 Examples:
1894 Namespace "s" "http://schemas.xmlsoap.org/soap/envelope/"
1896 Namespace "m" "http://www.w3.org/1998/Math/MathML"
1897 User User
1899 Password Password
1900 Digest true|false
1901 VerifyPeer true|false
1902 VerifyHost true|false
1903 CACert CA Cert File
1904 Header Header
1905 Post Body
1906 Timeout Milliseconds
1907 These options behave exactly equivalent to the appropriate options
1908 of the cURL plugin. Please see there for a detailed description.
1909 <Statistics>
1911 One Statistics block can be used to specify cURL statistics to be
1912 collected for each request to the remote URL. See the section "cURL
1913 Statistics" above for details.
1914 <XPath XPath-expression>
1916 Within each URL block, there must be one or more XPath blocks. Each
1917 XPath block specifies how to get one type of information. The
1918 string argument must be a valid XPath expression which returns a
1919 list of "base elements". One value is dispatched for each "base
1920 element".
1921 Within the XPath block the following options are accepted:
1923 Type Type
1925 Specifies the Type used for submitting patches. This determines
1926 the number of values that are required / expected and whether
1927 the strings are parsed as signed or unsigned integer or as
1928 double values. See types.db(5) for details. This option is
1929 required.
1930 InstancePrefix InstancePrefix
1932 Prefix the type instance with InstancePrefix. The values are
1933 simply concatenated together without any separator. This
1934 option is optional.
1935 InstanceFrom InstanceFrom
1937 Specifies a XPath expression to use for determining the type
1938 instance. The XPath expression must return exactly one element.
1939 The element's value is then used as type instance, possibly
1940 prefixed with InstancePrefix (see above).
1941 PluginInstanceFrom PluginInstanceFrom
1943 Specifies a XPath expression to use for determining the plugin
1944 instance. The XPath expression must return exactly one element.
1945 The element's value is then used as plugin instance.
1946 If the "base XPath expression" (the argument to the XPath block)
1948 returns exactly one argument, then InstanceFrom and
1949 PluginInstanceFrom may be omitted. Otherwise, at least one of
1950 InstanceFrom or PluginInstanceFrom is required.
1951 ValuesFrom ValuesFrom [ValuesFrom ...]
1953 Specifies one or more XPath expression to use for reading the
1954 values. The number of XPath expressions must match the number
1955 of data sources in the type specified with Type (see above).
1956 Each XPath expression must return exactly one element. The
1957 element's value is then parsed as a number and used as value
1958 for the appropriate value in the value list dispatched to the
1959 daemon. This option is required.
1960 Plugin "dbi"
1962 This plugin uses the dbi library (<http://libdbi.sourceforge.net/>) to
1963 connect to various databases, execute SQL statements and read back the
1964 results. dbi is an acronym for "database interface" in case you were
1965 wondering about the name. You can configure how each column is to be
1966 interpreted and the plugin will generate one or more data sets from
1967 each row returned according to these rules.
1968 Because the plugin is very generic, the configuration is a little more
1970 complex than those of other plugins. It usually looks something like
1971 this:
1972 <Plugin dbi>
1974 <Query "out_of_stock">
1975 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
1976 # Use with MySQL 5.0.0 or later
1977 MinVersion 50000
1978 <Result>
1979 Type "gauge"
1980 InstancePrefix "out_of_stock"
1981 InstancesFrom "category"
1982 ValuesFrom "value"
1983 </Result>
1984 </Query>
1985 <Database "product_information">
1986 #Plugin "warehouse"
1987 Driver "mysql"
1988 Interval 120
1989 DriverOption "host" "localhost"
1990 DriverOption "username" "collectd"
1991 DriverOption "password" "aZo6daiw"
1992 DriverOption "dbname" "prod_info"
1993 SelectDB "prod_info"
1994 Query "out_of_stock"
1995 </Database>
1996 </Plugin>
1997 The configuration above defines one query with one result and one
1999 database. The query is then linked to the database with the Query
2000 option within the <Database> block. You can have any number of queries
2001 and databases and you can also use the Include statement to split up
2002 the configuration file in multiple, smaller files. However, the <Query>
2003 block must precede the <Database> blocks, because the file is
2004 interpreted from top to bottom!
2005 The following is a complete list of options:
2007 Query blocks
2009 Query blocks define SQL statements and how the returned data should be
2011 interpreted. They are identified by the name that is given in the
2012 opening line of the block. Thus the name needs to be unique. Other than
2013 that, the name is not used in collectd.
2014 In each Query block, there is one or more Result blocks. Result blocks
2016 define which column holds which value or instance information. You can
2017 use multiple Result blocks to create multiple values from one returned
2018 row. This is especially useful, when queries take a long time and
2019 sending almost the same query again and again is not desirable.
2020 Example:
2022 <Query "environment">
2024 Statement "select station, temperature, humidity from environment"
2025 <Result>
2026 Type "temperature"
2027 # InstancePrefix "foo"
2028 InstancesFrom "station"
2029 ValuesFrom "temperature"
2030 </Result>
2031 <Result>
2032 Type "humidity"
2033 InstancesFrom "station"
2034 ValuesFrom "humidity"
2035 </Result>
2036 </Query>
2037 The following options are accepted:
2039 Statement SQL
2041 Sets the statement that should be executed on the server. This is
2042 not interpreted by collectd, but simply passed to the database
2043 server. Therefore, the SQL dialect that's used depends on the
2044 server collectd is connected to.
2045 The query has to return at least two columns, one for the instance
2047 and one value. You cannot omit the instance, even if the statement
2048 is guaranteed to always return exactly one line. In that case, you
2049 can usually specify something like this:
2050 Statement "SELECT \"instance\", COUNT(*) AS value FROM table"
2052 (That works with MySQL but may not be valid SQL according to the
2054 spec. If you use a more strict database server, you may have to
2055 select from a dummy table or something.)
2056 Please note that some databases, for example Oracle, will fail if
2058 you include a semicolon at the end of the statement.
2059 MinVersion Version
2061 MaxVersion Value
2062 Only use this query for the specified database version. You can use
2063 these options to provide multiple queries with the same name but
2064 with a slightly different syntax. The plugin will use only those
2065 queries, where the specified minimum and maximum versions fit the
2066 version of the database in use.
2067 The database version is determined by
2069 "dbi_conn_get_engine_version", see the libdbi documentation
2070 <http://libdbi.sourceforge.net/docs/programmers-guide/reference-
2071 conn.html#DBI-CONN-GET-ENGINE-VERSION> for details. Basically, each
2072 part of the version is assumed to be in the range from 00 to 99 and
2073 all dots are removed. So version "4.1.2" becomes "40102", version
2074 "5.0.42" becomes "50042".
2075 Warning: The plugin will use all matching queries, so if you
2077 specify multiple queries with the same name and overlapping ranges,
2078 weird stuff will happen. Don't to it! A valid example would be
2079 something along these lines:
2080 MinVersion 40000
2082 MaxVersion 49999
2083 ...
2084 MinVersion 50000
2085 MaxVersion 50099
2086 ...
2087 MinVersion 50100
2088 # No maximum
2089 In the above example, there are three ranges that don't overlap.
2091 The last one goes from version "5.1.0" to infinity, meaning "all
2092 later versions". Versions before "4.0.0" are not specified.
2093 Type Type
2095 The type that's used for each line returned. See types.db(5) for
2096 more details on how types are defined. In short: A type is a
2097 predefined layout of data and the number of values and type of
2098 values has to match the type definition.
2099 If you specify "temperature" here, you need exactly one gauge
2101 column. If you specify "if_octets", you will need two counter
2102 columns. See the ValuesFrom setting below.
2103 There must be exactly one Type option inside each Result block.
2105 InstancePrefix prefix
2107 Prepends prefix to the type instance. If InstancesFrom (see below)
2108 is not given, the string is simply copied. If InstancesFrom is
2109 given, prefix and all strings returned in the appropriate columns
2110 are concatenated together, separated by dashes ("-").
2111 InstancesFrom column0 [column1 ...]
2113 Specifies the columns whose values will be used to create the
2114 "type-instance" for each row. If you specify more than one column,
2115 the value of all columns will be joined together with dashes ("-")
2116 as separation characters.
2117 The plugin itself does not check whether or not all built instances
2119 are different. It's your responsibility to assure that each is
2120 unique. This is especially true, if you do not specify
2121 InstancesFrom: You have to make sure that only one row is returned
2122 in this case.
2123 If neither InstancePrefix nor InstancesFrom is given, the type-
2125 instance will be empty.
2126 ValuesFrom column0 [column1 ...]
2128 Names the columns whose content is used as the actual data for the
2129 data sets that are dispatched to the daemon. How many such columns
2130 you need is determined by the Type setting above. If you specify
2131 too many or not enough columns, the plugin will complain about that
2132 and no data will be submitted to the daemon.
2133 The actual data type in the columns is not that important. The
2135 plugin will automatically cast the values to the right type if it
2136 know how to do that. So it should be able to handle integer an
2137 floating point types, as well as strings (if they include a number
2138 at the beginning).
2139 There must be at least one ValuesFrom option inside each Result
2141 block.
2142 MetadataFrom [column0 column1 ...]
2144 Names the columns whose content is used as metadata for the data
2145 sets that are dispatched to the daemon.
2146 The actual data type in the columns is not that important. The
2148 plugin will automatically cast the values to the right type if it
2149 know how to do that. So it should be able to handle integer an
2150 floating point types, as well as strings (if they include a number
2151 at the beginning).
2152 Database blocks
2154 Database blocks define a connection to a database and which queries
2156 should be sent to that database. Since the used "dbi" library can
2157 handle a wide variety of databases, the configuration is very generic.
2158 If in doubt, refer to libdbi's documentation - we stick as close to the
2159 terminology used there.
2160 Each database needs a "name" as string argument in the starting tag of
2162 the block. This name will be used as "PluginInstance" in the values
2163 submitted to the daemon. Other than that, that name is not used.
2164 Plugin Plugin
2166 Use Plugin as the plugin name when submitting query results from
2167 this Database. Defaults to "dbi".
2168 Interval Interval
2170 Sets the interval (in seconds) in which the values will be
2171 collected from this database. By default the global Interval
2172 setting will be used.
2173 Driver Driver
2175 Specifies the driver to use to connect to the database. In many
2176 cases those drivers are named after the database they can connect
2177 to, but this is not a technical necessity. These drivers are
2178 sometimes referred to as "DBD", DataBase Driver, and some
2179 distributions ship them in separate packages. Drivers for the "dbi"
2180 library are developed by the libdbi-drivers project at
2181 <http://libdbi-drivers.sourceforge.net/>.
2182 You need to give the driver name as expected by the "dbi" library
2184 here. You should be able to find that in the documentation for each
2185 driver. If you mistype the driver name, the plugin will dump a list
2186 of all known driver names to the log.
2187 DriverOption Key Value
2189 Sets driver-specific options. What option a driver supports can be
2190 found in the documentation for each driver, somewhere at
2191 <http://libdbi-drivers.sourceforge.net/>. However, the options
2192 "host", "username", "password", and "dbname" seem to be de facto
2193 standards.
2194 DBDs can register two types of options: String options and numeric
2196 options. The plugin will use the "dbi_conn_set_option" function
2197 when the configuration provides a string and the
2198 "dbi_conn_require_option_numeric" function when the configuration
2199 provides a number. So these two lines will actually result in
2200 different calls being used:
2201 DriverOption "Port" 1234 # numeric
2203 DriverOption "Port" "1234" # string
2204 Unfortunately, drivers are not too keen to report errors when an
2206 unknown option is passed to them, so invalid settings here may go
2207 unnoticed. This is not the plugin's fault, it will report errors if
2208 it gets them from the library / the driver. If a driver complains
2209 about an option, the plugin will dump a complete list of all
2210 options understood by that driver to the log. There is no way to
2211 programmatically find out if an option expects a string or a
2212 numeric argument, so you will have to refer to the appropriate
2213 DBD's documentation to find this out. Sorry.
2214 SelectDB Database
2216 In some cases, the database name you connect with is not the
2217 database name you want to use for querying data. If this option is
2218 set, the plugin will "select" (switch to) that database after the
2219 connection is established.
2220 Query QueryName
2222 Associates the query named QueryName with this database connection.
2223 The query needs to be defined before this statement, i. e. all
2224 query blocks you want to refer to must be placed above the database
2225 block you want to refer to them from.
2226 Host Hostname
2228 Sets the host field of value lists to Hostname when dispatching
2229 values. Defaults to the global hostname setting.
2230 Plugin "df"
2232 Device Device
2233 Select partitions based on the devicename.
2234 See /"IGNORELISTS" for details.
2236 MountPoint Directory
2238 Select partitions based on the mountpoint.
2239 See /"IGNORELISTS" for details.
2241 FSType FSType
2243 Select partitions based on the filesystem type.
2244 See /"IGNORELISTS" for details.
2246 IgnoreSelected true|false
2248 Invert the selection: If set to true, all partitions except the
2249 ones that match any one of the criteria are collected. By default
2250 only selected partitions are collected if a selection is made. If
2251 no selection is configured at all, all partitions are selected.
2252 ReportByDevice true|false
2254 Report using the device name rather than the mountpoint. i.e. with
2255 this false, (the default), it will report a disk as "root", but
2256 with it true, it will be "sda1" (or whichever).
2257 ReportInodes true|false
2259 Enables or disables reporting of free, reserved and used inodes.
2260 Defaults to inode collection being disabled.
2261 Enable this option if inodes are a scarce resource for you, usually
2263 because many small files are stored on the disk. This is a usual
2264 scenario for mail transfer agents and web caches.
2265 ValuesAbsolute true|false
2267 Enables or disables reporting of free and used disk space in
2268 1K-blocks. Defaults to true.
2269 ValuesPercentage false|true
2271 Enables or disables reporting of free and used disk space in
2272 percentage. Defaults to false.
2273 This is useful for deploying collectd on the cloud, where machines
2275 with different disk size may exist. Then it is more practical to
2276 configure thresholds based on relative disk size.
2277 Plugin "disk"
2279 The "disk" plugin collects information about the usage of physical
2280 disks and logical disks (partitions). Values collected are the number
2281 of octets written to and read from a disk or partition, the number of
2282 read/write operations issued to the disk and a rather complex "time" it
2283 took for these commands to be issued.
2284 Using the following two options you can ignore some disks or configure
2286 the collection only of specific disks.
2287 Disk Name
2289 Select the disk Name. Whether it is collected or ignored depends on
2290 the IgnoreSelected setting, see below. As with other plugins that
2291 use the daemon's ignorelist functionality, a string that starts and
2292 ends with a slash is interpreted as a regular expression. Examples:
2293 Disk "sdd"
2295 Disk "/hda[34]/"
2296 See /"IGNORELISTS" for details.
2298 IgnoreSelected true|false
2300 Sets whether selected disks, i. e. the ones matches by any of the
2301 Disk statements, are ignored or if all other disks are ignored. The
2302 behavior (hopefully) is intuitive: If no Disk option is configured,
2303 all disks are collected. If at least one Disk option is given and
2304 no IgnoreSelected or set to false, only matching disks will be
2305 collected. If IgnoreSelected is set to true, all disks are
2306 collected except the ones matched.
2307 UseBSDName true|false
2309 Whether to use the device's "BSD Name", on Mac OS X, instead of the
2310 default major/minor numbers. Requires collectd to be built with
2311 Apple's IOKitLib support.
2312 UdevNameAttr Attribute
2314 Attempt to override disk instance name with the value of a
2315 specified udev attribute when built with libudev. If the attribute
2316 is not defined for the given device, the default name is used.
2317 Example:
2318 UdevNameAttr "DM_NAME"
2320 Plugin "dns"
2322 Interface Interface
2323 The dns plugin uses libpcap to capture dns traffic and analyzes it.
2324 This option sets the interface that should be used. If this option
2325 is not set, or set to "any", the plugin will try to get packets
2326 from all interfaces. This may not work on certain platforms, such
2327 as Mac OS X.
2328 IgnoreSource IP-address
2330 Ignore packets that originate from this address.
2331 SelectNumericQueryTypes true|false
2333 Enabled by default, collects unknown (and thus presented as numeric
2334 only) query types.
2335 Plugin "dpdkevents"
2337 The dpdkevents plugin collects events from DPDK such as link status of
2338 network ports and Keep Alive status of DPDK logical cores. In order to
2339 get Keep Alive events following requirements must be met: - DPDK >=
2340 16.07 - support for Keep Alive implemented in DPDK application. More
2341 details can be found here:
2342 http://dpdk.org/doc/guides/sample_app_ug/keep_alive.html
2343 Synopsis:
2345 <Plugin "dpdkevents">
2347 <EAL>
2348 Coremask "0x1"
2349 MemoryChannels "4"
2350 FilePrefix "rte"
2351 </EAL>
2352 <Event "link_status">
2353 SendEventsOnUpdate true
2354 EnabledPortMask 0xffff
2355 PortName "interface1"
2356 PortName "interface2"
2357 SendNotification false
2358 </Event>
2359 <Event "keep_alive">
2360 SendEventsOnUpdate true
2361 LCoreMask "0xf"
2362 KeepAliveShmName "/dpdk_keepalive_shm_name"
2363 SendNotification false
2364 </Event>
2365 </Plugin>
2366 Options:
2368 The EAL block
2370 Coremask Mask
2372 Memorychannels Channels
2373 Number of memory channels per processor socket.
2374 FilePrefix File
2376 The prefix text used for hugepage filenames. The filename will be
2377 set to /var/run/.<prefix>_config where prefix is what is passed in
2378 by the user.
2379 The Event block
2381 The Event block defines configuration for specific event. It accepts a
2383 single argument which specifies the name of the event.
2384 Link Status event
2386 SendEventOnUpdate true|false
2388 If set to true link status value will be dispatched only when it is
2389 different from previously read value. This is an optional argument
2390 - default value is true.
2391 EnabledPortMask Mask
2393 A hexidecimal bit mask of the DPDK ports which should be enabled. A
2394 mask of 0x0 means that all ports will be disabled. A bitmask of all
2395 F's means that all ports will be enabled. This is an optional
2396 argument - by default all ports are enabled.
2397 PortName Name
2399 A string containing an optional name for the enabled DPDK ports.
2400 Each PortName option should contain only one port name; specify as
2401 many PortName options as desired. Default naming convention will be
2402 used if PortName is blank. If there are less PortName options than
2403 there are enabled ports, the default naming convention will be used
2404 for the additional ports.
2405 SendNotification true|false
2407 If set to true, link status notifications are sent, instead of link
2408 status being collected as a statistic. This is an optional argument
2409 - default value is false.
2410 Keep Alive event
2412 SendEventOnUpdate true|false
2414 If set to true keep alive value will be dispatched only when it is
2415 different from previously read value. This is an optional argument
2416 - default value is true.
2417 LCoreMask Mask
2419 An hexadecimal bit mask of the logical cores to monitor keep alive
2420 state.
2421 KeepAliveShmName Name
2423 Shared memory name identifier that is used by secondary process to
2424 monitor the keep alive cores state.
2425 SendNotification true|false
2427 If set to true, keep alive notifications are sent, instead of keep
2428 alive information being collected as a statistic. This is an
2429 optional argument - default value is false.
2430 Plugin "dpdkstat"
2432 The dpdkstat plugin collects information about DPDK interfaces using
2433 the extended NIC stats API in DPDK.
2434 Synopsis:
2436 <Plugin "dpdkstat">
2438 <EAL>
2439 Coremask "0x4"
2440 MemoryChannels "4"
2441 FilePrefix "rte"
2442 SocketMemory "1024"
2443 LogLevel "7"
2444 RteDriverLibPath "/usr/lib/dpdk-pmd"
2445 </EAL>
2446 SharedMemObj "dpdk_collectd_stats_0"
2447 EnabledPortMask 0xffff
2448 PortName "interface1"
2449 PortName "interface2"
2450 </Plugin>
2451 Options:
2453 The EAL block
2455 Coremask Mask
2457 A string containing an hexadecimal bit mask of the cores to run on.
2458 Note that core numbering can change between platforms and should be
2459 determined beforehand.
2460 Memorychannels Channels
2462 A string containing a number of memory channels per processor
2463 socket.
2464 FilePrefix File
2466 The prefix text used for hugepage filenames. The filename will be
2467 set to /var/run/.<prefix>_config where prefix is what is passed in
2468 by the user.
2469 SocketMemory MB
2471 A string containing amount of Memory to allocate from hugepages on
2472 specific sockets in MB. This is an optional value.
2473 LogLevel LogLevel_number
2475 A string containing log level number. This parameter is optional.
2476 If parameter is not present then default value "7" - (INFO) is
2477 used. Value "8" - (DEBUG) can be set to enable debug traces.
2478 RteDriverLibPath Path
2480 A string containing path to shared pmd driver lib or path to
2481 directory, where shared pmd driver libs are available. This
2482 parameter is optional. This parameter enable loading of shared pmd
2483 driver libs from defined path. E.g.:
2484 "/usr/lib/dpdk-pmd/librte_pmd_i40e.so" or "/usr/lib/dpdk-pmd"
2485 SharedMemObj Mask
2487 A string containing the name of the shared memory object that should
2488 be used to share stats from the DPDK secondary process to the
2489 collectd dpdkstat plugin. Defaults to dpdk_collectd_stats if no
2490 other value is configured.
2491 EnabledPortMask Mask
2493 A hexidecimal bit mask of the DPDK ports which should be enabled. A
2494 mask of 0x0 means that all ports will be disabled. A bitmask of all
2495 Fs means that all ports will be enabled. This is an optional
2496 argument - default is all ports enabled.
2497 PortName Name
2499 A string containing an optional name for the enabled DPDK ports.
2500 Each PortName option should contain only one port name; specify as
2501 many PortName options as desired. Default naming convention will be
2502 used if PortName is blank. If there are less PortName options than
2503 there are enabled ports, the default naming convention will be used
2504 for the additional ports.
2505 Plugin "email"
2507 SocketFile Path
2508 Sets the socket-file which is to be created.
2509 SocketGroup Group
2511 If running as root change the group of the UNIX-socket after it has
2512 been created. Defaults to collectd.
2513 SocketPerms Permissions
2515 Change the file permissions of the UNIX-socket after it has been
2516 created. The permissions must be given as a numeric, octal value as
2517 you would pass to chmod(1). Defaults to 0770.
2518 MaxConns Number
2520 Sets the maximum number of connections that can be handled in
2521 parallel. Since this many threads will be started immediately
2522 setting this to a very high value will waste valuable resources.
2523 Defaults to 5 and will be forced to be at most 16384 to prevent
2524 typos and dumb mistakes.
2525 Plugin "ethstat"
2527 The ethstat plugin collects information about network interface cards
2528 (NICs) by talking directly with the underlying kernel driver using
2529 ioctl(2).
2530 Synopsis:
2532 <Plugin "ethstat">
2534 Interface "eth0"
2535 Map "rx_csum_offload_errors" "if_rx_errors" "checksum_offload"
2536 Map "multicast" "if_multicast"
2537 </Plugin>
2538 Options:
2540 Interface Name
2542 Collect statistical information about interface Name.
2543 Map Name Type [TypeInstance]
2545 By default, the plugin will submit values as type "derive" and type
2546 instance set to Name, the name of the metric as reported by the
2547 driver. If an appropriate Map option exists, the given Type and,
2548 optionally, TypeInstance will be used.
2549 MappedOnly true|false
2551 When set to true, only metrics that can be mapped to a type will be
2552 collected, all other metrics will be ignored. Defaults to false.
2553 Plugin "exec"
2555 Please make sure to read collectd-exec(5) before using this plugin. It
2556 contains valuable information on when the executable is executed and
2557 the output that is expected from it.
2558 Exec User[:[Group]] Executable [<arg> [<arg> ...]]
2560 NotificationExec User[:[Group]] Executable [<arg> [<arg> ...]]
2561 Execute the executable Executable as user User. If the user name is
2562 followed by a colon and a group name, the effective group is set to
2563 that group. The real group and saved-set group will be set to the
2564 default group of that user. If no group is given the effective
2565 group ID will be the same as the real group ID.
2566 Please note that in order to change the user and/or group the
2568 daemon needs superuser privileges. If the daemon is run as an
2569 unprivileged user you must specify the same user/group here. If the
2570 daemon is run with superuser privileges, you must supply a non-root
2571 user here.
2572 The executable may be followed by optional arguments that are
2574 passed to the program. Please note that due to the configuration
2575 parsing numbers and boolean values may be changed. If you want to
2576 be absolutely sure that something is passed as-is please enclose it
2577 in quotes.
2578 The Exec and NotificationExec statements change the semantics of
2580 the programs executed, i. e. the data passed to them and the
2581 response expected from them. This is documented in great detail in
2582 collectd-exec(5).
2583 Plugin "fhcount"
2585 The "fhcount" plugin provides statistics about used, unused and total
2586 number of file handles on Linux.
2587 The fhcount plugin provides the following configuration options:
2589 ValuesAbsolute true|false
2591 Enables or disables reporting of file handles usage in absolute
2592 numbers, e.g. file handles used. Defaults to true.
2593 ValuesPercentage false|true
2595 Enables or disables reporting of file handles usage in percentages,
2596 e.g. percent of file handles used. Defaults to false.
2597 Plugin "filecount"
2599 The "filecount" plugin counts the number of files in a certain
2600 directory (and its subdirectories) and their combined size. The
2601 configuration is very straight forward:
2602 <Plugin "filecount">
2604 <Directory "/var/qmail/queue/mess">
2605 Instance "qmail-message"
2606 </Directory>
2607 <Directory "/var/qmail/queue/todo">
2608 Instance "qmail-todo"
2609 </Directory>
2610 <Directory "/var/lib/php5">
2611 Instance "php5-sessions"
2612 Name "sess_*"
2613 </Directory>
2614 </Plugin>
2615 The example above counts the number of files in QMail's queue
2617 directories and the number of PHP5 sessions. Jfiy: The "todo" queue
2618 holds the messages that QMail has not yet looked at, the "message"
2619 queue holds the messages that were classified into "local" and
2620 "remote".
2621 As you can see, the configuration consists of one or more "Directory"
2623 blocks, each of which specifies a directory in which to count the
2624 files. Within those blocks, the following options are recognized:
2625 Plugin Plugin
2627 Use Plugin as the plugin name when submitting values. Defaults to
2628 filecount.
2629 Instance Instance
2631 Sets the plugin instance to Instance. If not given, the instance is
2632 set to the directory name with all slashes replaced by underscores
2633 and all leading underscores removed. Empty value is allowed.
2634 Name Pattern
2636 Only count files that match Pattern, where Pattern is a shell-like
2637 wildcard as understood by fnmatch(3). Only the filename is checked
2638 against the pattern, not the entire path. In case this makes it
2639 easier for you: This option has been named after the -name
2640 parameter to find(1).
2641 MTime Age
2643 Count only files of a specific age: If Age is greater than zero,
2644 only files that haven't been touched in the last Age seconds are
2645 counted. If Age is a negative number, this is inversed. For
2646 example, if -60 is specified, only files that have been modified in
2647 the last minute will be counted.
2648 The number can also be followed by a "multiplier" to easily specify
2650 a larger timespan. When given in this notation, the argument must
2651 in quoted, i. e. must be passed as string. So the -60 could also
2652 be written as "-1m" (one minute). Valid multipliers are "s"
2653 (second), "m" (minute), "h" (hour), "d" (day), "w" (week), and "y"
2654 (year). There is no "month" multiplier. You can also specify
2655 fractional numbers, e. g. "0.5d" is identical to "12h".
2656 Size Size
2658 Count only files of a specific size. When Size is a positive
2659 number, only files that are at least this big are counted. If Size
2660 is a negative number, this is inversed, i. e. only files smaller
2661 than the absolute value of Size are counted.
2662 As with the MTime option, a "multiplier" may be added. For a
2664 detailed description see above. Valid multipliers here are "b"
2665 (byte), "k" (kilobyte), "m" (megabyte), "g" (gigabyte), "t"
2666 (terabyte), and "p" (petabyte). Please note that there are 1000
2667 bytes in a kilobyte, not 1024.
2668 Recursive true|false
2670 Controls whether or not to recurse into subdirectories. Enabled by
2671 default.
2672 IncludeHidden true|false
2674 Controls whether or not to include "hidden" files and directories
2675 in the count. "Hidden" files and directories are those, whose name
2676 begins with a dot. Defaults to false, i.e. by default hidden files
2677 and directories are ignored.
2678 RegularOnly true|false
2680 Controls whether or not to include only regular files in the count.
2681 Defaults to true, i.e. by default non regular files are ignored.
2682 FilesSizeType Type
2684 Sets the type used to dispatch files combined size. Empty value
2685 ("") disables reporting. Defaults to bytes.
2686 FilesCountType Type
2688 Sets the type used to dispatch number of files. Empty value ("")
2689 disables reporting. Defaults to files.
2690 TypeInstance Instance
2692 Sets the type instance used to dispatch values. Defaults to an
2693 empty string (no plugin instance).
2694 Plugin "GenericJMX"
2696 The GenericJMX plugin is written in Java and therefore documented in
2697 collectd-java(5).
2698 Plugin "gmond"
2700 The gmond plugin received the multicast traffic sent by gmond, the
2701 statistics collection daemon of Ganglia. Mappings for the standard
2702 "metrics" are built-in, custom mappings may be added via Metric blocks,
2703 see below.
2704 Synopsis:
2706 <Plugin "gmond">
2708 MCReceiveFrom "239.2.11.71" "8649"
2709 <Metric "swap_total">
2710 Type "swap"
2711 TypeInstance "total"
2712 DataSource "value"
2713 </Metric>
2714 <Metric "swap_free">
2715 Type "swap"
2716 TypeInstance "free"
2717 DataSource "value"
2718 </Metric>
2719 </Plugin>
2720 The following metrics are built-in:
2722 · load_one, load_five, load_fifteen
2724 · cpu_user, cpu_system, cpu_idle, cpu_nice, cpu_wio
2726 · mem_free, mem_shared, mem_buffers, mem_cached, mem_total
2728 · bytes_in, bytes_out
2730 · pkts_in, pkts_out
2732 Available configuration options:
2734 MCReceiveFrom MCGroup [Port]
2736 Sets sets the multicast group and UDP port to which to subscribe.
2737 Default: 239.2.11.71 / 8649
2739 <Metric Name>
2741 These blocks add a new metric conversion to the internal table.
2742 Name, the string argument to the Metric block, is the metric name
2743 as used by Ganglia.
2744 Type Type
2746 Type to map this metric to. Required.
2747 TypeInstance Instance
2749 Type-instance to use. Optional.
2750 DataSource Name
2752 Data source to map this metric to. If the configured type has
2753 exactly one data source, this is optional. Otherwise the option
2754 is required.
2755 Plugin "gps"
2757 The "gps plugin" connects to gpsd on the host machine. The host, port,
2758 timeout and pause are configurable.
2759 This is useful if you run an NTP server using a GPS for source and you
2761 want to monitor it.
2762 Mind your GPS must send $--GSA for having the data reported!
2764 The following elements are collected:
2766 satellites
2768 Number of satellites used for fix (type instance "used") and in
2769 view (type instance "visible"). 0 means no GPS satellites are
2770 visible.
2771 dilution_of_precision
2773 Vertical and horizontal dilution (type instance "horizontal" or
2774 "vertical"). It should be between 0 and 3. Look at the
2775 documentation of your GPS to know more.
2776 Synopsis:
2778 LoadPlugin gps
2780 <Plugin "gps">
2781 # Connect to localhost on gpsd regular port:
2782 Host "127.0.0.1"
2783 Port "2947"
2784 # 15 ms timeout
2785 Timeout 0.015
2786 # PauseConnect of 5 sec. between connection attempts.
2787 PauseConnect 5
2788 </Plugin>
2789 Available configuration options:
2791 Host Host
2793 The host on which gpsd daemon runs. Defaults to localhost.
2794 Port Port
2796 Port to connect to gpsd on the host machine. Defaults to 2947.
2797 Timeout Seconds
2799 Timeout in seconds (default 0.015 sec).
2800 The GPS data stream is fetch by the plugin form the daemon. It
2802 waits for data to be available, if none arrives it times out and
2803 loop for another reading. Mind to put a low value gpsd expects
2804 value in the micro-seconds area (recommended is 500 us) since the
2805 waiting function is blocking. Value must be between 500 us and 5
2806 sec., if outside that range the default value is applied.
2807 This only applies from gpsd release-2.95.
2809 PauseConnect Seconds
2811 Pause to apply between attempts of connection to gpsd in seconds
2812 (default 5 sec).
2813 Plugin "gpu_nvidia"
2815 Efficiently collects various statistics from the system's NVIDIA GPUs
2816 using the NVML library. Currently collected are fan speed, core
2817 temperature, percent load, percent memory used, compute and memory
2818 frequencies, and power consumption.
2819 GPUIndex
2821 If one or more of these options is specified, only GPUs at that
2822 index (as determined by nvidia-utils through nvidia-smi) have
2823 statistics collected. If no instance of this option is specified,
2824 all GPUs are monitored.
2825 IgnoreSelected
2827 If set to true, all detected GPUs except the ones at indices
2828 specified by GPUIndex entries are collected. For greater clarity,
2829 setting IgnoreSelected without any GPUIndex directives will result
2830 in no statistics being collected.
2831 Plugin "grpc"
2833 The grpc plugin provides an RPC interface to submit values to or query
2834 values from collectd based on the open source gRPC framework. It
2835 exposes an end-point for dispatching values to the daemon.
2836 The gRPC homepage can be found at <https://grpc.io/>.
2838 Server Host Port
2840 The Server statement sets the address of a server to which to send
2841 metrics via the "DispatchValues" function.
2842 The argument Host may be a hostname, an IPv4 address, or an IPv6
2844 address.
2845 Optionally, Server may be specified as a configuration block which
2847 supports the following options:
2848 EnableSSL false|true
2850 Whether to require SSL for outgoing connections. Default:
2851 false.
2852 SSLCACertificateFile Filename
2854 SSLCertificateFile Filename
2855 SSLCertificateKeyFile Filename
2856 Filenames specifying SSL certificate and key material to be
2857 used with SSL connections.
2858 Listen Host Port
2860 The Listen statement sets the network address to bind to. When
2861 multiple statements are specified, the daemon will bind to all of
2862 them. If none are specified, it defaults to 0.0.0.0:50051.
2863 The argument Host may be a hostname, an IPv4 address, or an IPv6
2865 address.
2866 Optionally, Listen may be specified as a configuration block which
2868 supports the following options:
2869 EnableSSL true|false
2871 Whether to enable SSL for incoming connections. Default: false.
2872 SSLCACertificateFile Filename
2874 SSLCertificateFile Filename
2875 SSLCertificateKeyFile Filename
2876 Filenames specifying SSL certificate and key material to be
2877 used with SSL connections.
2878 VerifyPeer true|false
2880 When enabled, a valid client certificate is required to connect
2881 to the server. When disabled, a client certifiacte is not
2882 requested and any unsolicited client certificate is accepted.
2883 Enabled by default.
2884 Plugin "hddtemp"
2886 To get values from hddtemp collectd connects to localhost (127.0.0.1),
2887 port 7634/tcp. The Host and Port options can be used to change these
2888 default values, see below. "hddtemp" has to be running to work
2889 correctly. If "hddtemp" is not running timeouts may appear which may
2890 interfere with other statistics..
2891 The hddtemp homepage can be found at
2893 <http://www.guzu.net/linux/hddtemp.php>.
2894 Host Hostname
2896 Hostname to connect to. Defaults to 127.0.0.1.
2897 Port Port
2899 TCP-Port to connect to. Defaults to 7634.
2900 Plugin "hugepages"
2902 To collect hugepages information, collectd reads directories
2903 "/sys/devices/system/node/*/hugepages" and "/sys/kernel/mm/hugepages".
2904 Reading of these directories can be disabled by the following options
2905 (default is enabled).
2906 ReportPerNodeHP true|false
2908 If enabled, information will be collected from the hugepage
2909 counters in "/sys/devices/system/node/*/hugepages". This is used
2910 to check the per-node hugepage statistics on a NUMA system.
2911 ReportRootHP true|false
2913 If enabled, information will be collected from the hugepage
2914 counters in "/sys/kernel/mm/hugepages". This can be used on both
2915 NUMA and non-NUMA systems to check the overall hugepage statistics.
2916 ValuesPages true|false
2918 Whether to report hugepages metrics in number of pages. Defaults
2919 to true.
2920 ValuesBytes false|true
2922 Whether to report hugepages metrics in bytes. Defaults to false.
2923 ValuesPercentage false|true
2925 Whether to report hugepages metrics as percentage. Defaults to
2926 false.
2927 Plugin "intel_pmu"
2929 The intel_pmu plugin collects performance counters data on Intel CPUs
2930 using Linux perf interface. All events are reported on a per core
2931 basis.
2932 Synopsis:
2934 <Plugin intel_pmu>
2936 ReportHardwareCacheEvents true
2937 ReportKernelPMUEvents true
2938 ReportSoftwareEvents true
2939 EventList "/var/cache/pmu/GenuineIntel-6-2D-core.json"
2940 HardwareEvents "L2_RQSTS.CODE_RD_HIT,L2_RQSTS.CODE_RD_MISS" "L2_RQSTS.ALL_CODE_RD"
2941 Cores "0-3" "4,6" "[12-15]"
2942 </Plugin>
2943 Options:
2945 ReportHardwareCacheEvents false|true
2947 Enable or disable measuring of hardware CPU cache events:
2948 - L1-dcache-loads
2949 - L1-dcache-load-misses
2950 - L1-dcache-stores
2951 - L1-dcache-store-misses
2952 - L1-dcache-prefetches
2953 - L1-dcache-prefetch-misses
2954 - L1-icache-loads
2955 - L1-icache-load-misses
2956 - L1-icache-prefetches
2957 - L1-icache-prefetch-misses
2958 - LLC-loads
2959 - LLC-load-misses
2960 - LLC-stores
2961 - LLC-store-misses
2962 - LLC-prefetches
2963 - LLC-prefetch-misses
2964 - dTLB-loads
2965 - dTLB-load-misses
2966 - dTLB-stores
2967 - dTLB-store-misses
2968 - dTLB-prefetches
2969 - dTLB-prefetch-misses
2970 - iTLB-loads
2971 - iTLB-load-misses
2972 - branch-loads
2973 - branch-load-misses
2974 ReportKernelPMUEvents false|true
2976 Enable or disable measuring of the following events:
2977 - cpu-cycles
2978 - instructions
2979 - cache-references
2980 - cache-misses
2981 - branches
2982 - branch-misses
2983 - bus-cycles
2984 ReportSoftwareEvents false|true
2986 Enable or disable measuring of software events provided by kernel:
2987 - cpu-clock
2988 - task-clock
2989 - context-switches
2990 - cpu-migrations
2991 - page-faults
2992 - minor-faults
2993 - major-faults
2994 - alignment-faults
2995 - emulation-faults
2996 EventList filename
2998 JSON performance counter event list file name. To be able to
2999 monitor all Intel CPU specific events JSON event list file should
3000 be downloaded. Use the pmu-tools event_download.py script to
3001 download event list for current CPU.
3002 HardwareEvents events
3004 This field is a list of event names or groups of comma separated
3005 event names. This option requires EventList option to be
3006 configured.
3007 Cores cores groups
3009 All events are reported on a per core basis. Monitoring of the
3010 events can be configured for a group of cores (aggregated
3011 statistics). This field defines groups of cores on which to monitor
3012 supported events. The field is represented as list of strings with
3013 core group values. Each string represents a list of cores in a
3014 group. If a group is enclosed in square brackets each core is added
3015 individually to a separate group (that is statistics are not
3016 aggregated). Allowed formats are:
3017 0,1,2,3
3018 0-10,20-18
3019 1,3,5-8,10,0x10-12
3020 [4-15,32-63]
3021 If an empty string is provided as value for this field default
3023 cores configuration is applied - that is separate group is created
3024 for each core.
3025 Plugin "intel_rdt"
3027 The intel_rdt plugin collects information provided by monitoring
3028 features of Intel Resource Director Technology (Intel(R) RDT) like
3029 Cache Monitoring Technology (CMT), Memory Bandwidth Monitoring (MBM).
3030 These features provide information about utilization of shared
3031 resources. CMT monitors last level cache occupancy (LLC). MBM supports
3032 two types of events reporting local and remote memory bandwidth. Local
3033 memory bandwidth (MBL) reports the bandwidth of accessing memory
3034 associated with the local socket. Remote memory bandwidth (MBR) reports
3035 the bandwidth of accessing the remote socket. Also this technology
3036 allows to monitor instructions per clock (IPC). Monitor events are
3037 hardware dependant. Monitoring capabilities are detected on plugin
3038 initialization and only supported events are monitored.
3039 Note: intel_rdt plugin is using model-specific registers (MSRs), which
3041 require an additional capability to be enabled if collectd is run as a
3042 service. Please refer to contrib/systemd.collectd.service file for
3043 more details.
3044 Synopsis:
3046 <Plugin "intel_rdt">
3048 Cores "0-2" "3,4,6" "8-10,15"
3049 Processes "sshd,qemu-system-x86" "bash"
3050 </Plugin>
3051 Options:
3053 Interval seconds
3055 The interval within which to retrieve statistics on monitored
3056 events in seconds. For milliseconds divide the time by 1000 for
3057 example if the desired interval is 50ms, set interval to 0.05. Due
3058 to limited capacity of counters it is not recommended to set
3059 interval higher than 1 sec.
3060 Cores cores groups
3062 Monitoring of the events can be configured for group of cores
3063 (aggregated statistics). This field defines groups of cores on
3064 which to monitor supported events. The field is represented as list
3065 of strings with core group values. Each string represents a list of
3066 cores in a group. Allowed formats are:
3067 0,1,2,3
3068 0-10,20-18
3069 1,3,5-8,10,0x10-12
3070 If an empty string is provided as value for this field default
3072 cores configuration is applied - a separate group is created for
3073 each core.
3074 Processes process names groups
3076 Monitoring of the events can be configured for group of processes
3077 (aggregated statistics). This field defines groups of processes on
3078 which to monitor supported events. The field is represented as list
3079 of strings with process names group values. Each string represents
3080 a list of processes in a group. Allowed format is:
3081 sshd,bash,qemu
3082 Note: By default global interval is used to retrieve statistics on
3084 monitored events. To configure a plugin specific interval use Interval
3085 option of the intel_rdt <LoadPlugin> block. For milliseconds divide the
3086 time by 1000 for example if the desired interval is 50ms, set interval
3087 to 0.05. Due to limited capacity of counters it is not recommended to
3088 set interval higher than 1 sec.
3089 Plugin "interface"
3091 Interface Interface
3092 Select this interface. By default these interfaces will then be
3093 collected. For a more detailed description see IgnoreSelected
3094 below.
3095 See /"IGNORELISTS" for details.
3097 IgnoreSelected true|false
3099 If no configuration is given, the interface-plugin will collect
3100 data from all interfaces. This may not be practical, especially for
3101 loopback- and similar interfaces. Thus, you can use the
3102 Interface-option to pick the interfaces you're interested in.
3103 Sometimes, however, it's easier/preferred to collect all interfaces
3104 except a few ones. This option enables you to do that: By setting
3105 IgnoreSelected to true the effect of Interface is inverted: All
3106 selected interfaces are ignored and all other interfaces are
3107 collected.
3108 It is possible to use regular expressions to match interface names,
3110 if the name is surrounded by /.../ and collectd was compiled with
3111 support for regexps. This is useful if there's a need to collect
3112 (or ignore) data for a group of interfaces that are similarly
3113 named, without the need to explicitly list all of them (especially
3114 useful if the list is dynamic). Example:
3115 Interface "lo"
3117 Interface "/^veth/"
3118 Interface "/^tun[0-9]+/"
3119 IgnoreSelected "true"
3120 This will ignore the loopback interface, all interfaces with names
3122 starting with veth and all interfaces with names starting with tun
3123 followed by at least one digit.
3124 ReportInactive true|false
3126 When set to false, only interfaces with non-zero traffic will be
3127 reported. Note that the check is done by looking into whether a
3128 package was sent at any time from boot and the corresponding
3129 counter is non-zero. So, if the interface has been sending data in
3130 the past since boot, but not during the reported time-interval, it
3131 will still be reported.
3132 The default value is true and results in collection of the data
3134 from all interfaces that are selected by Interface and
3135 IgnoreSelected options.
3136 UniqueName true|false
3138 Interface name is not unique on Solaris (KSTAT), interface name is
3139 unique only within a module/instance. Following tuple is considered
3140 unique:
3141 (ks_module, ks_instance, ks_name) If this option is set to true,
3142 interface name contains above three fields separated by an
3143 underscore. For more info on KSTAT, visit
3144 <http://docs.oracle.com/cd/E23824_01/html/821-1468/kstat-3kstat.html#REFMAN3Ekstat-3kstat>
3145 This option is only available on Solaris.
3147 Plugin "ipmi"
3149 The ipmi plugin allows to monitor server platform status using the
3150 Intelligent Platform Management Interface (IPMI). Local and remote
3151 interfaces are supported.
3152 The plugin configuration consists of one or more Instance blocks which
3154 specify one ipmi connection each. Each block requires one unique string
3155 argument as the instance name. If instances are not configured, an
3156 instance with the default option values will be created.
3157 For backwards compatibility, any option other than Instance block will
3159 trigger legacy config handling and it will be treated as an option
3160 within Instance block. This support will go away in the next major
3161 version of Collectd.
3162 Within the Instance blocks, the following options are allowed:
3164 Address Address
3166 Hostname or IP to connect to. If not specified, plugin will try to
3167 connect to local management controller (BMC).
3168 Username Username
3170 Password Password
3171 The username and the password to use for the connection to remote
3172 BMC.
3173 AuthType MD5|rmcp+
3175 Forces the authentication type to use for the connection to remote
3176 BMC. By default most secure type is seleted.
3177 Host Hostname
3179 Sets the host field of dispatched values. Defaults to the global
3180 hostname setting.
3181 Sensor Sensor
3183 Selects sensors to collect or to ignore, depending on
3184 IgnoreSelected.
3185 See /"IGNORELISTS" for details.
3187 IgnoreSelected true|false
3189 If no configuration if given, the ipmi plugin will collect data
3190 from all sensors found of type "temperature", "voltage", "current"
3191 and "fanspeed". This option enables you to do that: By setting
3192 IgnoreSelected to true the effect of Sensor is inverted: All
3193 selected sensors are ignored and all other sensors are collected.
3194 NotifySensorAdd true|false
3196 If a sensor appears after initialization time of a minute a
3197 notification is sent.
3198 NotifySensorRemove true|false
3200 If a sensor disappears a notification is sent.
3201 NotifySensorNotPresent true|false
3203 If you have for example dual power supply and one of them is
3204 (un)plugged then a notification is sent.
3205 NotifyIPMIConnectionState true|false
3207 If a IPMI connection state changes after initialization time of a
3208 minute a notification is sent. Defaults to false.
3209 SELEnabled true|false
3211 If system event log (SEL) is enabled, plugin will listen for sensor
3212 threshold and discrete events. When event is received the
3213 notification is sent. SEL event filtering can be configured using
3214 SELSensor and SELIgnoreSelected config options. Defaults to false.
3215 SELSensor SELSensor
3217 Selects sensors to get events from or to ignore, depending on
3218 SELIgnoreSelected.
3219 See /"IGNORELISTS" for details.
3221 SELIgnoreSelected true|false
3223 If no configuration is given, the ipmi plugin will pass events from
3224 all sensors. This option enables you to do that: By setting
3225 SELIgnoreSelected to true the effect of SELSensor is inverted: All
3226 events from selected sensors are ignored and all events from other
3227 sensors are passed.
3228 SELClearEvent true|false
3230 If SEL clear event is enabled, plugin will delete event from SEL
3231 list after it is received and successfully handled. In this case
3232 other tools that are subscribed for SEL events will receive an
3233 empty event. Defaults to false.
3234 Plugin "iptables"
3236 Chain Table Chain [Comment|Number [Name]]
3237 Chain6 Table Chain [Comment|Number [Name]]
3238 Select the iptables/ip6tables filter rules to count packets and
3239 bytes from.
3240 If only Table and Chain are given, this plugin will collect the
3242 counters of all rules which have a comment-match. The comment is
3243 then used as type-instance.
3244 If Comment or Number is given, only the rule with the matching
3246 comment or the nth rule will be collected. Again, the comment (or
3247 the number) will be used as the type-instance.
3248 If Name is supplied, it will be used as the type-instance instead
3250 of the comment or the number.
3251 Plugin "irq"
3253 Irq Irq
3254 Select this irq. By default these irqs will then be collected. For
3255 a more detailed description see IgnoreSelected below.
3256 See /"IGNORELISTS" for details.
3258 IgnoreSelected true|false
3260 If no configuration if given, the irq-plugin will collect data from
3261 all irqs. This may not be practical, especially if no interrupts
3262 happen. Thus, you can use the Irq-option to pick the interrupt
3263 you're interested in. Sometimes, however, it's easier/preferred to
3264 collect all interrupts except a few ones. This option enables you
3265 to do that: By setting IgnoreSelected to true the effect of Irq is
3266 inverted: All selected interrupts are ignored and all other
3267 interrupts are collected.
3268 Plugin "java"
3270 The Java plugin makes it possible to write extensions for collectd in
3271 Java. This section only discusses the syntax and semantic of the
3272 configuration options. For more in-depth information on the Java
3273 plugin, please read collectd-java(5).
3274 Synopsis:
3276 <Plugin "java">
3278 JVMArg "-verbose:jni"
3279 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
3280 LoadPlugin "org.collectd.java.Foobar"
3281 <Plugin "org.collectd.java.Foobar">
3282 # To be parsed by the plugin
3283 </Plugin>
3284 </Plugin>
3285 Available configuration options:
3287 JVMArg Argument
3289 Argument that is to be passed to the Java Virtual Machine (JVM).
3290 This works exactly the way the arguments to the java binary on the
3291 command line work. Execute "java --help" for details.
3292 Please note that all these options must appear before (i. e. above)
3294 any other options! When another option is found, the JVM will be
3295 started and later options will have to be ignored!
3296 LoadPlugin JavaClass
3298 Instantiates a new JavaClass object. The constructor of this object
3299 very likely then registers one or more callback methods with the
3300 server.
3301 See collectd-java(5) for details.
3303 When the first such option is found, the virtual machine (JVM) is
3305 created. This means that all JVMArg options must appear before
3306 (i. e. above) all LoadPlugin options!
3307 Plugin Name
3309 The entire block is passed to the Java plugin as an
3310 org.collectd.api.OConfigItem object.
3311 For this to work, the plugin has to register a configuration
3313 callback first, see "config callback" in collectd-java(5). This
3314 means, that the Plugin block must appear after the appropriate
3315 LoadPlugin block. Also note, that Name depends on the (Java) plugin
3316 registering the callback and is completely independent from the
3317 JavaClass argument passed to LoadPlugin.
3318 Plugin "load"
3320 The Load plugin collects the system load. These numbers give a rough
3321 overview over the utilization of a machine. The system load is defined
3322 as the number of runnable tasks in the run-queue and is provided by
3323 many operating systems as a one, five or fifteen minute average.
3324 The following configuration options are available:
3326 ReportRelative false|true
3328 When enabled, system load divided by number of available CPU cores
3329 is reported for intervals 1 min, 5 min and 15 min. Defaults to
3330 false.
3331 Plugin "logfile"
3333 LogLevel debug|info|notice|warning|err
3334 Sets the log-level. If, for example, set to notice, then all events
3335 with severity notice, warning, or err will be written to the
3336 logfile.
3337 Please note that debug is only available if collectd has been
3339 compiled with debugging support.
3340 File File
3342 Sets the file to write log messages to. The special strings stdout
3343 and stderr can be used to write to the standard output and standard
3344 error channels, respectively. This, of course, only makes much
3345 sense when collectd is running in foreground- or non-daemon-mode.
3346 Timestamp true|false
3348 Prefix all lines printed by the current time. Defaults to true.
3349 PrintSeverity true|false
3351 When enabled, all lines are prefixed by the severity of the log
3352 message, for example "warning". Defaults to false.
3353 Note: There is no need to notify the daemon after moving or removing
3355 the log file (e. g. when rotating the logs). The plugin reopens the
3356 file for each line it writes.
3357 Plugin "log_logstash"
3359 The log logstash plugin behaves like the logfile plugin but formats
3360 messages as JSON events for logstash to parse and input.
3361 LogLevel debug|info|notice|warning|err
3363 Sets the log-level. If, for example, set to notice, then all events
3364 with severity notice, warning, or err will be written to the
3365 logfile.
3366 Please note that debug is only available if collectd has been
3368 compiled with debugging support.
3369 File File
3371 Sets the file to write log messages to. The special strings stdout
3372 and stderr can be used to write to the standard output and standard
3373 error channels, respectively. This, of course, only makes much
3374 sense when collectd is running in foreground- or non-daemon-mode.
3375 Note: There is no need to notify the daemon after moving or removing
3377 the log file (e. g. when rotating the logs). The plugin reopens the
3378 file for each line it writes.
3379 Plugin "lpar"
3381 The LPAR plugin reads CPU statistics of Logical Partitions, a
3382 virtualization technique for IBM POWER processors. It takes into
3383 account CPU time stolen from or donated to a partition, in addition to
3384 the usual user, system, I/O statistics.
3385 The following configuration options are available:
3387 CpuPoolStats false|true
3389 When enabled, statistics about the processor pool are read, too.
3390 The partition needs to have pool authority in order to be able to
3391 acquire this information. Defaults to false.
3392 ReportBySerial false|true
3394 If enabled, the serial of the physical machine the partition is
3395 currently running on is reported as hostname and the logical
3396 hostname of the machine is reported in the plugin instance.
3397 Otherwise, the logical hostname will be used (just like other
3398 plugins) and the plugin instance will be empty. Defaults to false.
3399 Plugin "lua"
3401 This plugin embeds a Lua interpreter into collectd and provides an
3402 interface to collectd's plugin system. See collectd-lua(5) for its
3403 documentation.
3404 Plugin "mbmon"
3406 The "mbmon plugin" uses mbmon to retrieve temperature, voltage, etc.
3407 Be default collectd connects to localhost (127.0.0.1), port 411/tcp.
3409 The Host and Port options can be used to change these values, see
3410 below. "mbmon" has to be running to work correctly. If "mbmon" is not
3411 running timeouts may appear which may interfere with other statistics..
3412 "mbmon" must be run with the -r option ("print TAG and Value format");
3414 Debian's /etc/init.d/mbmon script already does this, other people will
3415 need to ensure that this is the case.
3416 Host Hostname
3418 Hostname to connect to. Defaults to 127.0.0.1.
3419 Port Port
3421 TCP-Port to connect to. Defaults to 411.
3422 Plugin "mcelog"
3424 The "mcelog plugin" uses mcelog to retrieve machine check exceptions.
3425 By default the plugin connects to "/var/run/mcelog-client" to check if
3427 the mcelog server is running. When the server is running, the plugin
3428 will tail the specified logfile to retrieve machine check exception
3429 information and send a notification with the details from the logfile.
3430 The plugin will use the mcelog client protocol to retrieve memory
3431 related machine check exceptions. Note that for memory exceptions,
3432 notifications are only sent when there is a change in the number of
3433 corrected/uncorrected memory errors.
3434 The Memory block
3436 Note: these options cannot be used in conjunction with the logfile
3438 options, they are mutually exclusive.
3439 McelogClientSocket Path Connect to the mcelog client socket using the
3441 UNIX domain socket at Path. Defaults to "/var/run/mcelog-client".
3442 PersistentNotification true|false Override default configuration to
3443 only send notifications when sent when there is a change in the number
3444 of corrected/uncorrected memory errors. When set to true notifications
3445 will be sent for every read cycle. Default is false. Does not affect
3446 the stats being dispatched.
3447 McelogLogfile Path
3448 The mcelog file to parse. Defaults to "/var/log/mcelog". Note: this
3449 option cannot be used in conjunction with the memory block options,
3450 they are mutually exclusive.
3451 Plugin "md"
3453 The "md plugin" collects information from Linux Software-RAID devices
3454 (md).
3455 All reported values are of the type "md_disks". Reported type instances
3457 are active, failed (present but not operational), spare (hot stand-by)
3458 and missing (physically absent) disks.
3459 Device Device
3461 Select md devices based on device name. The device name is the
3462 basename of the device, i.e. the name of the block device without
3463 the leading "/dev/". See IgnoreSelected for more details.
3464 See /"IGNORELISTS" for details.
3466 IgnoreSelected true|false
3468 Invert device selection: If set to true, all md devices except
3469 those listed using Device are collected. If false (the default),
3470 only those listed are collected. If no configuration is given, the
3471 md plugin will collect data from all md devices.
3472 Plugin "memcachec"
3474 The "memcachec plugin" connects to a memcached server, queries one or
3475 more given pages and parses the returned data according to user
3476 specification. The matches used are the same as the matches used in
3477 the "curl" and "tail" plugins.
3478 In order to talk to the memcached server, this plugin uses the
3480 libmemcached library. Please note that there is another library with a
3481 very similar name, libmemcache (notice the missing `d'), which is not
3482 applicable.
3483 Synopsis of the configuration:
3485 <Plugin "memcachec">
3487 <Page "plugin_instance">
3488 Server "localhost"
3489 Key "page_key"
3490 Plugin "plugin_name"
3491 <Match>
3492 Regex "(\\d+) bytes sent"
3493 DSType CounterAdd
3494 Type "ipt_octets"
3495 Instance "type_instance"
3496 </Match>
3497 </Page>
3498 </Plugin>
3499 The configuration options are:
3501 <Page Name>
3503 Each Page block defines one page to be queried from the memcached
3504 server. The block requires one string argument which is used as
3505 plugin instance.
3506 Server Address
3508 Sets the server address to connect to when querying the page. Must
3509 be inside a Page block.
3510 Key Key
3512 When connected to the memcached server, asks for the page Key.
3513 Plugin Plugin
3515 Use Plugin as the plugin name when submitting values. Defaults to
3516 "memcachec".
3517 <Match>
3519 Match blocks define which strings to look for and how matches
3520 substrings are interpreted. For a description of match blocks,
3521 please see "Plugin tail".
3522 Plugin "memcached"
3524 The memcached plugin connects to a memcached server and queries
3525 statistics about cache utilization, memory and bandwidth used.
3526 <http://memcached.org/>
3527 <Plugin "memcached">
3529 <Instance "name">
3530 #Host "memcache.example.com"
3531 Address "127.0.0.1"
3532 Port 11211
3533 </Instance>
3534 </Plugin>
3535 The plugin configuration consists of one or more Instance blocks which
3537 specify one memcached connection each. Within the Instance blocks, the
3538 following options are allowed:
3539 Host Hostname
3541 Sets the host field of dispatched values. Defaults to the global
3542 hostname setting. For backwards compatibility, values are also
3543 dispatched with the global hostname when Host is set to 127.0.0.1
3544 or localhost and Address is not set.
3545 Address Address
3547 Hostname or IP to connect to. For backwards compatibility, defaults
3548 to the value of Host or 127.0.0.1 if Host is unset.
3549 Port Port
3551 TCP port to connect to. Defaults to 11211.
3552 Socket Path
3554 Connect to memcached using the UNIX domain socket at Path. If this
3555 setting is given, the Address and Port settings are ignored.
3556 Plugin "mic"
3558 The mic plugin gathers CPU statistics, memory usage and temperatures
3559 from Intel's Many Integrated Core (MIC) systems.
3560 Synopsis:
3562 <Plugin mic>
3564 ShowCPU true
3565 ShowCPUCores true
3566 ShowMemory true
3567 ShowTemperatures true
3569 Temperature vddg
3570 Temperature vddq
3571 IgnoreSelectedTemperature true
3572 ShowPower true
3574 Power total0
3575 Power total1
3576 IgnoreSelectedPower true
3577 </Plugin>
3578 The following options are valid inside the Plugin mic block:
3580 ShowCPU true|false
3582 If enabled (the default) a sum of the CPU usage across all cores is
3583 reported.
3584 ShowCPUCores true|false
3586 If enabled (the default) per-core CPU usage is reported.
3587 ShowMemory true|false
3589 If enabled (the default) the physical memory usage of the MIC
3590 system is reported.
3591 ShowTemperatures true|false
3593 If enabled (the default) various temperatures of the MIC system are
3594 reported.
3595 Temperature Name
3597 This option controls which temperatures are being reported. Whether
3598 matching temperatures are being ignored or only matching
3599 temperatures are reported depends on the IgnoreSelectedTemperature
3600 setting below. By default all temperatures are reported.
3601 IgnoreSelectedTemperature false|true
3603 Controls the behavior of the Temperature setting above. If set to
3604 false (the default) only temperatures matching a Temperature option
3605 are reported or, if no Temperature option is specified, all
3606 temperatures are reported. If set to true, matching temperatures
3607 are ignored and all other temperatures are reported.
3608 Known temperature names are:
3610 die Die of the CPU
3612 devmem
3614 Device Memory
3615 fin Fan In
3617 fout
3619 Fan Out
3620 vccp
3622 Voltage ccp
3623 vddg
3625 Voltage ddg
3626 vddq
3628 Voltage ddq
3629 ShowPower true|false
3631 If enabled (the default) various temperatures of the MIC system are
3632 reported.
3633 Power Name
3635 This option controls which power readings are being reported.
3636 Whether matching power readings are being ignored or only matching
3637 power readings are reported depends on the IgnoreSelectedPower
3638 setting below. By default all power readings are reported.
3639 IgnoreSelectedPower false|true
3641 Controls the behavior of the Power setting above. If set to false
3642 (the default) only power readings matching a Power option are
3643 reported or, if no Power option is specified, all power readings
3644 are reported. If set to true, matching power readings are ignored
3645 and all other power readings are reported.
3646 Known power names are:
3648 total0
3650 Total power utilization averaged over Time Window 0 (uWatts).
3651 total1
3653 Total power utilization averaged over Time Window 0 (uWatts).
3654 inst
3656 Instantaneous power (uWatts).
3657 imax
3659 Max instantaneous power (uWatts).
3660 pcie
3662 PCI-E connector power (uWatts).
3663 c2x3
3665 2x3 connector power (uWatts).
3666 c2x4
3668 2x4 connector power (uWatts).
3669 vccp
3671 Core rail (uVolts).
3672 vddg
3674 Uncore rail (uVolts).
3675 vddq
3677 Memory subsystem rail (uVolts).
3678 Plugin "memory"
3680 The memory plugin provides the following configuration options:
3681 ValuesAbsolute true|false
3683 Enables or disables reporting of physical memory usage in absolute
3684 numbers, i.e. bytes. Defaults to true.
3685 ValuesPercentage false|true
3687 Enables or disables reporting of physical memory usage in
3688 percentages, e.g. percent of physical memory used. Defaults to
3689 false.
3690 This is useful for deploying collectd in a heterogeneous
3692 environment in which the sizes of physical memory vary.
3693 Plugin "modbus"
3695 The modbus plugin connects to a Modbus "slave" via Modbus/TCP or
3696 Modbus/RTU and reads register values. It supports reading single
3697 registers (unsigned 16 bit values), large integer values (unsigned
3698 32 bit and 64 bit values) and floating point values (two registers
3699 interpreted as IEEE floats in big endian notation).
3700 Synopsis:
3702 <Data "voltage-input-1">
3704 RegisterBase 0
3705 RegisterType float
3706 RegisterCmd ReadHolding
3707 Type voltage
3708 Instance "input-1"
3709 #Scale 1.0
3710 #Shift 0.0
3711 </Data>
3712 <Data "voltage-input-2">
3714 RegisterBase 2
3715 RegisterType float
3716 RegisterCmd ReadHolding
3717 Type voltage
3718 Instance "input-2"
3719 </Data>
3720 <Data "supply-temperature-1">
3722 RegisterBase 0
3723 RegisterType Int16
3724 RegisterCmd ReadHolding
3725 Type temperature
3726 Instance "temp-1"
3727 </Data>
3728 <Host "modbus.example.com">
3730 Address "192.168.0.42"
3731 Port "502"
3732 Interval 60
3733 <Slave 1>
3735 Instance "power-supply"
3736 Collect "voltage-input-1"
3737 Collect "voltage-input-2"
3738 </Slave>
3739 </Host>
3740 <Host "localhost">
3742 Device "/dev/ttyUSB0"
3743 Baudrate 38400
3744 Interval 20
3745 <Slave 1>
3747 Instance "temperature"
3748 Collect "supply-temperature-1"
3749 </Slave>
3750 </Host>
3751 <Data Name> blocks
3753 Data blocks define a mapping between register numbers and the
3754 "types" used by collectd.
3755 Within <Data /> blocks, the following options are allowed:
3757 RegisterBase Number
3759 Configures the base register to read from the device. If the
3760 option RegisterType has been set to Uint32 or Float, this and
3761 the next register will be read (the register number is
3762 increased by one).
3763 RegisterType
3765 Int16|Int32|Int64|Uint16|Uint32|UInt64|Float|Int32LE|Uint32LE|FloatLE
3766 Specifies what kind of data is returned by the device. This
3767 defaults to Uint16. If the type is Int32, Int32LE, Uint32,
3768 Uint32LE, Float or FloatLE, two 16 bit registers at
3769 RegisterBase and RegisterBase+1 will be read and the data is
3770 combined into one 32 value. For Int32, Uint32 and Float the
3771 most significant 16 bits are in the register at RegisterBase
3772 and the least significant 16 bits are in the register at
3773 RegisterBase+1. For Int32LE, Uint32LE, or Float32LE, the high
3774 and low order registers are swapped with the most significant
3775 16 bits in the RegisterBase+1 and the least significant 16 bits
3776 in RegisterBase. If the type is Int64 or UInt64, four 16 bit
3777 registers at RegisterBase, RegisterBase+1, RegisterBase+2 and
3778 RegisterBase+3 will be read and the data combined into one
3779 64 value.
3780 RegisterCmd ReadHolding|ReadInput
3782 Specifies register type to be collected from device. Works only
3783 with libmodbus 2.9.2 or higher. Defaults to ReadHolding.
3784 Type Type
3786 Specifies the "type" (data set) to use when dispatching the
3787 value to collectd. Currently, only data sets with exactly one
3788 data source are supported.
3789 Instance Instance
3791 Sets the type instance to use when dispatching the value to
3792 Instance. If unset, an empty string (no type instance) is used.
3793 Scale Value
3795 The values taken from device are multiplied by Value. The field
3796 is optional and the default is 1.0.
3797 Shift Value
3799 Value is added to values from device after they have been
3800 multiplied by Scale value. The field is optional and the
3801 default value is 0.0.
3802 <Host Name> blocks
3804 Host blocks are used to specify to which hosts to connect and what
3805 data to read from their "slaves". The string argument Name is used
3806 as hostname when dispatching the values to collectd.
3807 Within <Host /> blocks, the following options are allowed:
3809 Address Hostname
3811 For Modbus/TCP, specifies the node name (the actual network
3812 address) used to connect to the host. This may be an IP address
3813 or a hostname. Please note that the used libmodbus library only
3814 supports IPv4 at the moment.
3815 Port Service
3817 for Modbus/TCP, specifies the port used to connect to the host.
3818 The port can either be given as a number or as a service name.
3819 Please note that the Service argument must be a string, even if
3820 ports are given in their numerical form. Defaults to "502".
3821 Device Devicenode
3823 For Modbus/RTU, specifies the path to the serial device being
3824 used.
3825 Baudrate Baudrate
3827 For Modbus/RTU, specifies the baud rate of the serial device.
3828 Note, connections currently support only 8/N/1.
3829 UARTType UARTType
3831 For Modbus/RTU, specifies the type of the serial device.
3832 RS232, RS422 and RS485 are supported. Defaults to RS232.
3833 Available only on Linux systems with libmodbus>=2.9.4.
3834 Interval Interval
3836 Sets the interval (in seconds) in which the values will be
3837 collected from this host. By default the global Interval
3838 setting will be used.
3839 <Slave ID>
3841 Over each connection, multiple Modbus devices may be reached.
3842 The slave ID is used to specify which device should be
3843 addressed. For each device you want to query, one Slave block
3844 must be given.
3845 Within <Slave /> blocks, the following options are allowed:
3847 Instance Instance
3849 Specify the plugin instance to use when dispatching the
3850 values to collectd. By default "slave_ID" is used.
3851 Collect DataName
3853 Specifies which data to retrieve from the device. DataName
3854 must be the same string as the Name argument passed to a
3855 Data block. You can specify this option multiple times to
3856 collect more than one value from a slave. At least one
3857 Collect option is mandatory.
3858 Plugin "mqtt"
3860 The MQTT plugin can send metrics to MQTT (Publish blocks) and receive
3861 values from MQTT (Subscribe blocks).
3862 Synopsis:
3864 <Plugin mqtt>
3866 <Publish "name">
3867 Host "mqtt.example.com"
3868 Prefix "collectd"
3869 </Publish>
3870 <Subscribe "name">
3871 Host "mqtt.example.com"
3872 Topic "collectd/#"
3873 </Subscribe>
3874 </Plugin>
3875 The plugin's configuration is in Publish and/or Subscribe blocks,
3877 configuring the sending and receiving direction respectively. The
3878 plugin will register a write callback named "mqtt/name" where name is
3879 the string argument given to the Publish block. Both types of blocks
3880 share many but not all of the following options. If an option is valid
3881 in only one of the blocks, it will be mentioned explicitly.
3882 Options:
3884 Host Hostname
3886 Hostname of the MQTT broker to connect to.
3887 Port Service
3889 Port number or service name of the MQTT broker to connect to.
3890 User UserName
3892 Username used when authenticating to the MQTT broker.
3893 Password Password
3895 Password used when authenticating to the MQTT broker.
3896 ClientId ClientId
3898 MQTT client ID to use. Defaults to the hostname used by collectd.
3899 QoS [0-2]
3901 Sets the Quality of Service, with the values 0, 1 and 2 meaning:
3902 0 At most once
3904 1 At least once
3906 2 Exactly once
3908 In Publish blocks, this option determines the QoS flag set on
3910 outgoing messages and defaults to 0. In Subscribe blocks,
3911 determines the maximum QoS setting the client is going to accept
3912 and defaults to 2. If the QoS flag on a message is larger than the
3913 maximum accepted QoS of a subscriber, the message's QoS will be
3914 downgraded.
3915 Prefix Prefix (Publish only)
3917 This plugin will use one topic per value list which will looks like
3918 a path. Prefix is used as the first path element and defaults to
3919 collectd.
3920 An example topic name would be:
3922 collectd/cpu-0/cpu-user
3924 Retain false|true (Publish only)
3926 Controls whether the MQTT broker will retain (keep a copy of) the
3927 last message sent to each topic and deliver it to new subscribers.
3928 Defaults to false.
3929 StoreRates true|false (Publish only)
3931 Controls whether "DERIVE" and "COUNTER" metrics are converted to a
3932 rate before sending. Defaults to true.
3933 CleanSession true|false (Subscribe only)
3935 Controls whether the MQTT "cleans" the session up after the
3936 subscriber disconnects or if it maintains the subscriber's
3937 subscriptions and all messages that arrive while the subscriber is
3938 disconnected. Defaults to true.
3939 Topic TopicName (Subscribe only)
3941 Configures the topic(s) to subscribe to. You can use the single
3942 level "+" and multi level "#" wildcards. Defaults to collectd/#,
3943 i.e. all topics beneath the collectd branch.
3944 CACert file
3946 Path to the PEM-encoded CA certificate file. Setting this option
3947 enables TLS communication with the MQTT broker, and as such, Port
3948 should be the TLS-enabled port of the MQTT broker. This option
3949 enables the use of TLS.
3950 CertificateFile file
3952 Path to the PEM-encoded certificate file to use as client
3953 certificate when connecting to the MQTT broker. Only valid if
3954 CACert and CertificateKeyFile are also set.
3955 CertificateKeyFile file
3957 Path to the unencrypted PEM-encoded key file corresponding to
3958 CertificateFile. Only valid if CACert and CertificateFile are also
3959 set.
3960 TLSProtocol protocol
3962 If configured, this specifies the string protocol version (e.g.
3963 "tlsv1", "tlsv1.2") to use for the TLS connection to the broker. If
3964 not set a default version is used which depends on the version of
3965 OpenSSL the Mosquitto library was linked against. Only valid if
3966 CACert is set.
3967 CipherSuite ciphersuite
3969 A string describing the ciphers available for use. See ciphers(1)
3970 and the "openssl ciphers" utility for more information. If unset,
3971 the default ciphers will be used. Only valid if CACert is set.
3972 Plugin "mysql"
3974 The "mysql plugin" requires mysqlclient to be installed. It connects to
3975 one or more databases when started and keeps the connection up as long
3976 as possible. When the connection is interrupted for whatever reason it
3977 will try to re-connect. The plugin will complain loudly in case
3978 anything goes wrong.
3979 This plugin issues the MySQL "SHOW STATUS" / "SHOW GLOBAL STATUS"
3981 command and collects information about MySQL network traffic, executed
3982 statements, requests, the query cache and threads by evaluating the
3983 "Bytes_{received,sent}", "Com_*", "Handler_*", "Qcache_*" and
3984 "Threads_*" return values. Please refer to the MySQL reference manual,
3985 5.1.6. Server Status Variables for an explanation of these values.
3986 Optionally, master and slave statistics may be collected in a MySQL
3988 replication setup. In that case, information about the synchronization
3989 state of the nodes are collected by evaluating the "Position" return
3990 value of the "SHOW MASTER STATUS" command and the
3991 "Seconds_Behind_Master", "Read_Master_Log_Pos" and
3992 "Exec_Master_Log_Pos" return values of the "SHOW SLAVE STATUS" command.
3993 See the MySQL reference manual, 12.5.5.21 SHOW MASTER STATUS Syntax and
3994 12.5.5.31 SHOW SLAVE STATUS Syntax for details.
3995 Synopsis:
3997 <Plugin mysql>
3999 <Database foo>
4000 Host "hostname"
4001 User "username"
4002 Password "password"
4003 Port "3306"
4004 MasterStats true
4005 ConnectTimeout 10
4006 SSLKey "/path/to/key.pem"
4007 SSLCert "/path/to/cert.pem"
4008 SSLCA "/path/to/ca.pem"
4009 SSLCAPath "/path/to/cas/"
4010 SSLCipher "DHE-RSA-AES256-SHA"
4011 </Database>
4012 <Database bar>
4014 Alias "squeeze"
4015 Host "localhost"
4016 Socket "/var/run/mysql/mysqld.sock"
4017 SlaveStats true
4018 SlaveNotifications true
4019 </Database>
4020 <Database galera>
4022 Alias "galera"
4023 Host "localhost"
4024 Socket "/var/run/mysql/mysqld.sock"
4025 WsrepStats true
4026 </Database>
4027 </Plugin>
4028 A Database block defines one connection to a MySQL database. It accepts
4030 a single argument which specifies the name of the database. None of the
4031 other options are required. MySQL will use default values as documented
4032 in the "mysql_real_connect()" and "mysql_ssl_set()" sections in the
4033 MySQL reference manual.
4034 Alias Alias
4036 Alias to use as sender instead of hostname when reporting. This may
4037 be useful when having cryptic hostnames.
4038 Host Hostname
4040 Hostname of the database server. Defaults to localhost.
4041 User Username
4043 Username to use when connecting to the database. The user does not
4044 have to be granted any privileges (which is synonym to granting the
4045 "USAGE" privilege), unless you want to collectd replication
4046 statistics (see MasterStats and SlaveStats below). In this case,
4047 the user needs the "REPLICATION CLIENT" (or "SUPER") privileges.
4048 Else, any existing MySQL user will do.
4049 Password Password
4051 Password needed to log into the database.
4052 Database Database
4054 Select this database. Defaults to no database which is a perfectly
4055 reasonable option for what this plugin does.
4056 Port Port
4058 TCP-port to connect to. The port must be specified in its numeric
4059 form, but it must be passed as a string nonetheless. For example:
4060 Port "3306"
4062 If Host is set to localhost (the default), this setting has no
4064 effect. See the documentation for the "mysql_real_connect"
4065 function for details.
4066 Socket Socket
4068 Specifies the path to the UNIX domain socket of the MySQL server.
4069 This option only has any effect, if Host is set to localhost (the
4070 default). Otherwise, use the Port option above. See the
4071 documentation for the "mysql_real_connect" function for details.
4072 InnodbStats true|false
4074 If enabled, metrics about the InnoDB storage engine are collected.
4075 Disabled by default.
4076 MasterStats true|false
4078 SlaveStats true|false
4079 Enable the collection of master / slave statistics in a replication
4080 setup. In order to be able to get access to these statistics, the
4081 user needs special privileges. See the User documentation above.
4082 Defaults to false.
4083 SlaveNotifications true|false
4085 If enabled, the plugin sends a notification if the replication
4086 slave I/O and / or SQL threads are not running. Defaults to false.
4087 WsrepStats true|false
4089 Enable the collection of wsrep plugin statistics, used in Master-Master
4090 replication setups like in MySQL Galera/Percona XtraDB Cluster.
4091 User needs only privileges to execute 'SHOW GLOBAL STATUS'
4092 ConnectTimeout Seconds
4094 Sets the connect timeout for the MySQL client.
4095 SSLKey Path
4097 If provided, the X509 key in PEM format.
4098 SSLCert Path
4100 If provided, the X509 cert in PEM format.
4101 SSLCA Path
4103 If provided, the CA file in PEM format (check OpenSSL docs).
4104 SSLCAPath Path
4106 If provided, the CA directory (check OpenSSL docs).
4107 SSLCipher String
4109 If provided, the SSL cipher to use.
4110 Plugin "netapp"
4112 The netapp plugin can collect various performance and capacity
4113 information from a NetApp filer using the NetApp API.
4114 Please note that NetApp has a wide line of products and a lot of
4116 different software versions for each of these products. This plugin was
4117 developed for a NetApp FAS3040 running OnTap 7.2.3P8 and tested on
4118 FAS2050 7.3.1.1L1, FAS3140 7.2.5.1 and FAS3020 7.2.4P9. It should work
4119 for most combinations of model and software version but it is very hard
4120 to test this. If you have used this plugin with other models and/or
4121 software version, feel free to send us a mail to tell us about the
4122 results, even if it's just a short "It works".
4123 To collect these data collectd will log in to the NetApp via HTTP(S)
4125 and HTTP basic authentication.
4126 Do not use a regular user for this! Create a special collectd user with
4128 just the minimum of capabilities needed. The user only needs the
4129 "login-http-admin" capability as well as a few more depending on which
4130 data will be collected. Required capabilities are documented below.
4131 Synopsis
4133 <Plugin "netapp">
4135 <Host "netapp1.example.com">
4136 Protocol "https"
4137 Address "10.0.0.1"
4138 Port 443
4139 User "username"
4140 Password "aef4Aebe"
4141 Interval 30
4142 <WAFL>
4144 Interval 30
4145 GetNameCache true
4146 GetDirCache true
4147 GetBufferCache true
4148 GetInodeCache true
4149 </WAFL>
4150 <Disks>
4152 Interval 30
4153 GetBusy true
4154 </Disks>
4155 <VolumePerf>
4157 Interval 30
4158 GetIO "volume0"
4159 IgnoreSelectedIO false
4160 GetOps "volume0"
4161 IgnoreSelectedOps false
4162 GetLatency "volume0"
4163 IgnoreSelectedLatency false
4164 </VolumePerf>
4165 <VolumeUsage>
4167 Interval 30
4168 GetCapacity "vol0"
4169 GetCapacity "vol1"
4170 IgnoreSelectedCapacity false
4171 GetSnapshot "vol1"
4172 GetSnapshot "vol3"
4173 IgnoreSelectedSnapshot false
4174 </VolumeUsage>
4175 <Quota>
4177 Interval 60
4178 </Quota>
4179 <Snapvault>
4181 Interval 30
4182 </Snapvault>
4183 <System>
4185 Interval 30
4186 GetCPULoad true
4187 GetInterfaces true
4188 GetDiskOps true
4189 GetDiskIO true
4190 </System>
4191 <VFiler vfilerA>
4193 Interval 60
4194 SnapVault true
4196 # ...
4197 </VFiler>
4198 </Host>
4199 </Plugin>
4200 The netapp plugin accepts the following configuration options:
4202 Host Name
4204 A host block defines one NetApp filer. It will appear in collectd
4205 with the name you specify here which does not have to be its real
4206 name nor its hostname (see the Address option below).
4207 VFiler Name
4209 A VFiler block may only be used inside a host block. It accepts all
4210 the same options as the Host block (except for cascaded VFiler
4211 blocks) and will execute all NetApp API commands in the context of
4212 the specified VFiler(R). It will appear in collectd with the name
4213 you specify here which does not have to be its real name. The
4214 VFiler name may be specified using the VFilerName option. If this
4215 is not specified, it will default to the name you specify here.
4216 The VFiler block inherits all connection related settings from the
4218 surrounding Host block (which appear before the VFiler block) but
4219 they may be overwritten inside the VFiler block.
4220 This feature is useful, for example, when using a VFiler as
4222 SnapVault target (supported since OnTap 8.1). In that case, the
4223 SnapVault statistics are not available in the host filer (vfiler0)
4224 but only in the respective VFiler context.
4225 Protocol httpd|http
4227 The protocol collectd will use to query this host.
4228 Optional
4230 Type: string
4232 Default: https
4234 Valid options: http, https
4236 Address Address
4238 The hostname or IP address of the host.
4239 Optional
4241 Type: string
4243 Default: The "host" block's name.
4245 Port Port
4247 The TCP port to connect to on the host.
4248 Optional
4250 Type: integer
4252 Default: 80 for protocol "http", 443 for protocol "https"
4254 User User
4256 Password Password
4257 The username and password to use to login to the NetApp.
4258 Mandatory
4260 Type: string
4262 VFilerName Name
4264 The name of the VFiler in which context to execute API commands. If
4265 not specified, the name provided to the VFiler block will be used
4266 instead.
4267 Optional
4269 Type: string
4271 Default: name of the VFiler block
4273 Note: This option may only be used inside VFiler blocks.
4275 Interval Interval
4277 TODO
4278 The following options decide what kind of data will be collected. You
4280 can either use them as a block and fine tune various parameters inside
4281 this block, use them as a single statement to just accept all default
4282 values, or omit it to not collect any data.
4283 The following options are valid inside all blocks:
4285 Interval Seconds
4287 Collect the respective statistics every Seconds seconds. Defaults
4288 to the host specific setting.
4289 The System block
4291 This will collect various performance data about the whole system.
4293 Note: To get this data the collectd user needs the "api-perf-object-
4295 get-instances" capability.
4296 Interval Seconds
4298 Collect disk statistics every Seconds seconds.
4299 GetCPULoad true|false
4301 If you set this option to true the current CPU usage will be read.
4302 This will be the average usage between all CPUs in your NetApp
4303 without any information about individual CPUs.
4304 Note: These are the same values that the NetApp CLI command
4306 "sysstat" returns in the "CPU" field.
4307 Optional
4309 Type: boolean
4311 Default: true
4313 Result: Two value lists of type "cpu", and type instances "idle"
4315 and "system".
4316 GetInterfaces true|false
4318 If you set this option to true the current traffic of the network
4319 interfaces will be read. This will be the total traffic over all
4320 interfaces of your NetApp without any information about individual
4321 interfaces.
4322 Note: This is the same values that the NetApp CLI command "sysstat"
4324 returns in the "Net kB/s" field.
4325 Or is it?
4327 Optional
4329 Type: boolean
4331 Default: true
4333 Result: One value list of type "if_octects".
4335 GetDiskIO true|false
4337 If you set this option to true the current IO throughput will be
4338 read. This will be the total IO of your NetApp without any
4339 information about individual disks, volumes or aggregates.
4340 Note: This is the same values that the NetApp CLI command "sysstat"
4342 returns in the "Disk kB/s" field.
4343 Optional
4345 Type: boolean
4347 Default: true
4349 Result: One value list of type "disk_octets".
4351 GetDiskOps true|false
4353 If you set this option to true the current number of HTTP, NFS,
4354 CIFS, FCP, iSCSI, etc. operations will be read. This will be the
4355 total number of operations on your NetApp without any information
4356 about individual volumes or aggregates.
4357 Note: These are the same values that the NetApp CLI command
4359 "sysstat" returns in the "NFS", "CIFS", "HTTP", "FCP" and "iSCSI"
4360 fields.
4361 Optional
4363 Type: boolean
4365 Default: true
4367 Result: A variable number of value lists of type
4369 "disk_ops_complex". Each type of operation will result in one value
4370 list with the name of the operation as type instance.
4371 The WAFL block
4373 This will collect various performance data about the WAFL file system.
4375 At the moment this just means cache performance.
4376 Note: To get this data the collectd user needs the "api-perf-object-
4378 get-instances" capability.
4379 Note: The interface to get these values is classified as "Diagnostics"
4381 by NetApp. This means that it is not guaranteed to be stable even
4382 between minor releases.
4383 Interval Seconds
4385 Collect disk statistics every Seconds seconds.
4386 GetNameCache true|false
4388 Optional
4389 Type: boolean
4391 Default: true
4393 Result: One value list of type "cache_ratio" and type instance
4395 "name_cache_hit".
4396 GetDirCache true|false
4398 Optional
4399 Type: boolean
4401 Default: true
4403 Result: One value list of type "cache_ratio" and type instance
4405 "find_dir_hit".
4406 GetInodeCache true|false
4408 Optional
4409 Type: boolean
4411 Default: true
4413 Result: One value list of type "cache_ratio" and type instance
4415 "inode_cache_hit".
4416 GetBufferCache true|false
4418 Note: This is the same value that the NetApp CLI command "sysstat"
4419 returns in the "Cache hit" field.
4420 Optional
4422 Type: boolean
4424 Default: true
4426 Result: One value list of type "cache_ratio" and type instance
4428 "buf_hash_hit".
4429 The Disks block
4431 This will collect performance data about the individual disks in the
4433 NetApp.
4434 Note: To get this data the collectd user needs the "api-perf-object-
4436 get-instances" capability.
4437 Interval Seconds
4439 Collect disk statistics every Seconds seconds.
4440 GetBusy true|false
4442 If you set this option to true the busy time of all disks will be
4443 calculated and the value of the busiest disk in the system will be
4444 written.
4445 Note: This is the same values that the NetApp CLI command "sysstat"
4447 returns in the "Disk util" field. Probably.
4448 Optional
4450 Type: boolean
4452 Default: true
4454 Result: One value list of type "percent" and type instance
4456 "disk_busy".
4457 The VolumePerf block
4459 This will collect various performance data about the individual
4461 volumes.
4462 You can select which data to collect about which volume using the
4464 following options. They follow the standard ignorelist semantic.
4465 Note: To get this data the collectd user needs the api-perf-object-get-
4467 instances capability.
4468 Interval Seconds
4470 Collect volume performance data every Seconds seconds.
4471 GetIO Volume
4473 GetOps Volume
4474 GetLatency Volume
4475 Select the given volume for IO, operations or latency statistics
4476 collection. The argument is the name of the volume without the
4477 "/vol/" prefix.
4478 Since the standard ignorelist functionality is used here, you can
4480 use a string starting and ending with a slash to specify regular
4481 expression matching: To match the volumes "vol0", "vol2" and
4482 "vol7", you can use this regular expression:
4483 GetIO "/^vol[027]$/"
4485 If no regular expression is specified, an exact match is required.
4487 Both, regular and exact matching are case sensitive.
4488 If no volume was specified at all for either of the three options,
4490 that data will be collected for all available volumes.
4491 See /"IGNORELISTS" for details.
4493 IgnoreSelectedIO true|false
4495 IgnoreSelectedOps true|false
4496 IgnoreSelectedLatency true|false
4497 When set to true, the volumes selected for IO, operations or
4498 latency statistics collection will be ignored and the data will be
4499 collected for all other volumes.
4500 When set to false, data will only be collected for the specified
4502 volumes and all other volumes will be ignored.
4503 If no volumes have been specified with the above Get* options, all
4505 volumes will be collected regardless of the IgnoreSelected* option.
4506 Defaults to false
4508 The VolumeUsage block
4510 This will collect capacity data about the individual volumes.
4512 Note: To get this data the collectd user needs the api-volume-list-info
4514 capability.
4515 Interval Seconds
4517 Collect volume usage statistics every Seconds seconds.
4518 GetCapacity VolumeName
4520 The current capacity of the volume will be collected. This will
4521 result in two to four value lists, depending on the configuration
4522 of the volume. All data sources are of type "df_complex" with the
4523 name of the volume as plugin_instance.
4524 There will be type_instances "used" and "free" for the number of
4526 used and available bytes on the volume. If the volume has some
4527 space reserved for snapshots, a type_instance "snap_reserved" will
4528 be available. If the volume has SIS enabled, a type_instance
4529 "sis_saved" will be available. This is the number of bytes saved by
4530 the SIS feature.
4531 Note: The current NetApp API has a bug that results in this value
4533 being reported as a 32 bit number. This plugin tries to guess the
4534 correct number which works most of the time. If you see strange
4535 values here, bug NetApp support to fix this.
4536 Repeat this option to specify multiple volumes.
4538 IgnoreSelectedCapacity true|false
4540 Specify whether to collect only the volumes selected by the
4541 GetCapacity option or to ignore those volumes.
4542 IgnoreSelectedCapacity defaults to false. However, if no
4543 GetCapacity option is specified at all, all capacities will be
4544 selected anyway.
4545 GetSnapshot VolumeName
4547 Select volumes from which to collect snapshot information.
4548 Usually, the space used for snapshots is included in the space
4550 reported as "used". If snapshot information is collected as well,
4551 the space used for snapshots is subtracted from the used space.
4552 To make things even more interesting, it is possible to reserve
4554 space to be used for snapshots. If the space required for snapshots
4555 is less than that reserved space, there is "reserved free" and
4556 "reserved used" space in addition to "free" and "used". If the
4557 space required for snapshots exceeds the reserved space, that part
4558 allocated in the normal space is subtracted from the "used" space
4559 again.
4560 Repeat this option to specify multiple volumes.
4562 IgnoreSelectedSnapshot
4564 Specify whether to collect only the volumes selected by the
4565 GetSnapshot option or to ignore those volumes.
4566 IgnoreSelectedSnapshot defaults to false. However, if no
4567 GetSnapshot option is specified at all, all capacities will be
4568 selected anyway.
4569 The Quota block
4571 This will collect (tree) quota statistics (used disk space and number
4573 of used files). This mechanism is useful to get usage information for
4574 single qtrees. In case the quotas are not used for any other purpose,
4575 an entry similar to the following in "/etc/quotas" would be sufficient:
4576 /vol/volA/some_qtree tree - - - - -
4578 After adding the entry, issue "quota on -w volA" on the NetApp filer.
4580 Interval Seconds
4582 Collect SnapVault(R) statistics every Seconds seconds.
4583 The SnapVault block
4585 This will collect statistics about the time and traffic of SnapVault(R)
4587 transfers.
4588 Interval Seconds
4590 Collect SnapVault(R) statistics every Seconds seconds.
4591 Plugin "netlink"
4593 The "netlink" plugin uses a netlink socket to query the Linux kernel
4594 about statistics of various interface and routing aspects.
4595 Interface Interface
4597 VerboseInterface Interface
4598 Instruct the plugin to collect interface statistics. This is
4599 basically the same as the statistics provided by the "interface"
4600 plugin (see above) but potentially much more detailed.
4601 When configuring with Interface only the basic statistics will be
4603 collected, namely octets, packets, and errors. These statistics are
4604 collected by the "interface" plugin, too, so using both at the same
4605 time is no benefit.
4606 When configured with VerboseInterface all counters except the basic
4608 ones will be collected, so that no data needs to be collected twice
4609 if you use the "interface" plugin. This includes dropped packets,
4610 received multicast packets, collisions and a whole zoo of
4611 differentiated RX and TX errors. You can try the following command
4612 to get an idea of what awaits you:
4613 ip -s -s link list
4615 If Interface is All, all interfaces will be selected.
4617 QDisc Interface [QDisc]
4619 Class Interface [Class]
4620 Filter Interface [Filter]
4621 Collect the octets and packets that pass a certain qdisc, class or
4622 filter.
4623 QDiscs and classes are identified by their type and handle (or
4625 classid). Filters don't necessarily have a handle, therefore the
4626 parent's handle is used. The notation used in collectd differs
4627 from that used in tc(1) in that it doesn't skip the major or minor
4628 number if it's zero and doesn't print special ids by their name.
4629 So, for example, a qdisc may be identified by "pfifo_fast-1:0" even
4630 though the minor number of all qdiscs is zero and thus not
4631 displayed by tc(1).
4632 If QDisc, Class, or Filter is given without the second argument,
4634 i. .e. without an identifier, all qdiscs, classes, or filters that
4635 are associated with that interface will be collected.
4636 Since a filter itself doesn't necessarily have a handle, the
4638 parent's handle is used. This may lead to problems when more than
4639 one filter is attached to a qdisc or class. This isn't nice, but we
4640 don't know how this could be done any better. If you have a idea,
4641 please don't hesitate to tell us.
4642 As with the Interface option you can specify All as the interface,
4644 meaning all interfaces.
4645 Here are some examples to help you understand the above text more
4647 easily:
4648 <Plugin netlink>
4650 VerboseInterface "All"
4651 QDisc "eth0" "pfifo_fast-1:0"
4652 QDisc "ppp0"
4653 Class "ppp0" "htb-1:10"
4654 Filter "ppp0" "u32-1:0"
4655 </Plugin>
4656 See /"IGNORELISTS" for details.
4658 IgnoreSelected
4660 The behavior is the same as with all other similar plugins: If
4661 nothing is selected at all, everything is collected. If some things
4662 are selected using the options described above, only these
4663 statistics are collected. If you set IgnoreSelected to true, this
4664 behavior is inverted, i. e. the specified statistics will not be
4665 collected.
4666 Plugin "network"
4668 The Network plugin sends data to a remote instance of collectd,
4669 receives data from a remote instance, or both at the same time. Data
4670 which has been received from the network is usually not transmitted
4671 again, but this can be activated, see the Forward option below.
4672 The default IPv6 multicast group is "ff18::efc0:4a42". The default IPv4
4674 multicast group is 239.192.74.66. The default UDP port is 25826.
4675 Both, Server and Listen can be used as single option or as block. When
4677 used as block, given options are valid for this socket only. The
4678 following example will export the metrics twice: Once to an "internal"
4679 server (without encryption and signing) and one to an external server
4680 (with cryptographic signature):
4681 <Plugin "network">
4683 # Export to an internal server
4684 # (demonstrates usage without additional options)
4685 Server "collectd.internal.tld"
4686 # Export to an external server
4688 # (demonstrates usage with signature options)
4689 <Server "collectd.external.tld">
4690 SecurityLevel "sign"
4691 Username "myhostname"
4692 Password "ohl0eQue"
4693 </Server>
4694 </Plugin>
4695 <Server Host [Port]>
4697 The Server statement/block sets the server to send datagrams to.
4698 The statement may occur multiple times to send each datagram to
4699 multiple destinations.
4700 The argument Host may be a hostname, an IPv4 address or an IPv6
4702 address. The optional second argument specifies a port number or a
4703 service name. If not given, the default, 25826, is used.
4704 The following options are recognized within Server blocks:
4706 SecurityLevel Encrypt|Sign|None
4708 Set the security you require for network communication. When
4709 the security level has been set to Encrypt, data sent over the
4710 network will be encrypted using AES-256. The integrity of
4711 encrypted packets is ensured using SHA-1. When set to Sign,
4712 transmitted data is signed using the HMAC-SHA-256 message
4713 authentication code. When set to None, data is sent without any
4714 security.
4715 This feature is only available if the network plugin was linked
4717 with libgcrypt.
4718 Username Username
4720 Sets the username to transmit. This is used by the server to
4721 lookup the password. See AuthFile below. All security levels
4722 except None require this setting.
4723 This feature is only available if the network plugin was linked
4725 with libgcrypt.
4726 Password Password
4728 Sets a password (shared secret) for this socket. All security
4729 levels except None require this setting.
4730 This feature is only available if the network plugin was linked
4732 with libgcrypt.
4733 Interface Interface name
4735 Set the outgoing interface for IP packets. This applies at
4736 least to IPv6 packets and if possible to IPv4. If this option
4737 is not applicable, undefined or a non-existent interface name
4738 is specified, the default behavior is to let the kernel choose
4739 the appropriate interface. Be warned that the manual selection
4740 of an interface for unicast traffic is only necessary in rare
4741 cases.
4742 BindAddress IP Address
4744 Set the outgoing IP address for IP packets. This option can be
4745 used instead of the Interface option to explicitly define the
4746 IP address which will be used to send Packets to the remote
4747 server.
4748 ResolveInterval Seconds
4750 Sets the interval at which to re-resolve the DNS for the Host.
4751 This is useful to force a regular DNS lookup to support a high
4752 availability setup. If not specified, re-resolves are never
4753 attempted.
4754 <Listen Host [Port]>
4756 The Listen statement sets the interfaces to bind to. When multiple
4757 statements are found the daemon will bind to multiple interfaces.
4758 The argument Host may be a hostname, an IPv4 address or an IPv6
4760 address. If the argument is a multicast address the daemon will
4761 join that multicast group. The optional second argument specifies
4762 a port number or a service name. If not given, the default, 25826,
4763 is used.
4764 The following options are recognized within "<Listen>" blocks:
4766 SecurityLevel Encrypt|Sign|None
4768 Set the security you require for network communication. When
4769 the security level has been set to Encrypt, only encrypted data
4770 will be accepted. The integrity of encrypted packets is ensured
4771 using SHA-1. When set to Sign, only signed and encrypted data
4772 is accepted. When set to None, all data will be accepted. If an
4773 AuthFile option was given (see below), encrypted data is
4774 decrypted if possible.
4775 This feature is only available if the network plugin was linked
4777 with libgcrypt.
4778 AuthFile Filename
4780 Sets a file in which usernames are mapped to passwords. These
4781 passwords are used to verify signatures and to decrypt
4782 encrypted network packets. If SecurityLevel is set to None,
4783 this is optional. If given, signed data is verified and
4784 encrypted packets are decrypted. Otherwise, signed data is
4785 accepted without checking the signature and encrypted data
4786 cannot be decrypted. For the other security levels this option
4787 is mandatory.
4788 The file format is very simple: Each line consists of a
4790 username followed by a colon and any number of spaces followed
4791 by the password. To demonstrate, an example file could look
4792 like this:
4793 user0: foo
4795 user1: bar
4796 Each time a packet is received, the modification time of the
4798 file is checked using stat(2). If the file has been changed,
4799 the contents is re-read. While the file is being read, it is
4800 locked using fcntl(2).
4801 Interface Interface name
4803 Set the incoming interface for IP packets explicitly. This
4804 applies at least to IPv6 packets and if possible to IPv4. If
4805 this option is not applicable, undefined or a non-existent
4806 interface name is specified, the default behavior is, to let
4807 the kernel choose the appropriate interface. Thus incoming
4808 traffic gets only accepted, if it arrives on the given
4809 interface.
4810 TimeToLive 1-255
4812 Set the time-to-live of sent packets. This applies to all, unicast
4813 and multicast, and IPv4 and IPv6 packets. The default is to not
4814 change this value. That means that multicast packets will be sent
4815 with a TTL of 1 (one) on most operating systems.
4816 MaxPacketSize 1024-65535
4818 Set the maximum size for datagrams received over the network.
4819 Packets larger than this will be truncated. Defaults to 1452 bytes,
4820 which is the maximum payload size that can be transmitted in one
4821 Ethernet frame using IPv6 / UDP.
4822 On the server side, this limit should be set to the largest value
4824 used on any client. Likewise, the value on the client must not be
4825 larger than the value on the server, or data will be lost.
4826 Compatibility: Versions prior to version 4.8 used a fixed sized
4828 buffer of 1024 bytes. Versions 4.8, 4.9 and 4.10 used a default
4829 value of 1024 bytes to avoid problems when sending data to an older
4830 server.
4831 Forward true|false
4833 If set to true, write packets that were received via the network
4834 plugin to the sending sockets. This should only be activated when
4835 the Listen- and Server-statements differ. Otherwise packets may be
4836 send multiple times to the same multicast group. While this results
4837 in more network traffic than necessary it's not a huge problem
4838 since the plugin has a duplicate detection, so the values will not
4839 loop.
4840 ReportStats true|false
4842 The network plugin cannot only receive and send statistics, it can
4843 also create statistics about itself. Collectd data included the
4844 number of received and sent octets and packets, the length of the
4845 receive queue and the number of values handled. When set to true,
4846 the Network plugin will make these statistics available. Defaults
4847 to false.
4848 Plugin "nfs"
4850 The nfs plugin collects information about the usage of the Network File
4851 System (NFS). It counts the number of procedure calls for each
4852 procedure, grouped by version and whether the system runs as server or
4853 client.
4854 It is possibly to omit metrics for a specific NFS version by setting
4856 one or more of the following options to false (all of them default to
4857 true).
4858 ReportV2 true|false
4860 ReportV3 true|false
4861 ReportV4 true|false
4862 Plugin "nginx"
4864 This plugin collects the number of connections and requests handled by
4865 the "nginx daemon" (speak: engine X), a HTTP and mail server/proxy. It
4866 queries the page provided by the "ngx_http_stub_status_module" module,
4867 which isn't compiled by default. Please refer to
4868 <http://wiki.codemongers.com/NginxStubStatusModule> for more
4869 information on how to compile and configure nginx and this module.
4870 The following options are accepted by the "nginx plugin":
4872 URL http://host/nginx_status
4874 Sets the URL of the "ngx_http_stub_status_module" output.
4875 User Username
4877 Optional user name needed for authentication.
4878 Password Password
4880 Optional password needed for authentication.
4881 VerifyPeer true|false
4883 Enable or disable peer SSL certificate verification. See
4884 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
4885 default.
4886 VerifyHost true|false
4888 Enable or disable peer host name verification. If enabled, the
4889 plugin checks if the "Common Name" or a "Subject Alternate Name"
4890 field of the SSL certificate matches the host name provided by the
4891 URL option. If this identity check fails, the connection is
4892 aborted. Obviously, only works when connecting to a SSL enabled
4893 server. Enabled by default.
4894 CACert File
4896 File that holds one or more SSL certificates. If you want to use
4897 HTTPS you will possibly need this option. What CA certificates come
4898 bundled with "libcurl" and are checked by default depends on the
4899 distribution you use.
4900 Timeout Milliseconds
4902 The Timeout option sets the overall timeout for HTTP requests to
4903 URL, in milliseconds. By default, the configured Interval is used
4904 to set the timeout.
4905 Plugin "notify_desktop"
4907 This plugin sends a desktop notification to a notification daemon, as
4908 defined in the Desktop Notification Specification. To actually display
4909 the notifications, notification-daemon is required and collectd has to
4910 be able to access the X server (i. e., the "DISPLAY" and "XAUTHORITY"
4911 environment variables have to be set correctly) and the D-Bus message
4912 bus.
4913 The Desktop Notification Specification can be found at
4915 <http://www.galago-project.org/specs/notification/>.
4916 OkayTimeout timeout
4918 WarningTimeout timeout
4919 FailureTimeout timeout
4920 Set the timeout, in milliseconds, after which to expire the
4921 notification for "OKAY", "WARNING" and "FAILURE" severities
4922 respectively. If zero has been specified, the displayed
4923 notification will not be closed at all - the user has to do so
4924 herself. These options default to 5000. If a negative number has
4925 been specified, the default is used as well.
4926 Plugin "notify_email"
4928 The notify_email plugin uses the ESMTP library to send notifications to
4929 a configured email address.
4930 libESMTP is available from <http://www.stafford.uklinux.net/libesmtp/>.
4932 Available configuration options:
4934 From Address
4936 Email address from which the emails should appear to come from.
4937 Default: "root@localhost"
4939 Recipient Address
4941 Configures the email address(es) to which the notifications should
4942 be mailed. May be repeated to send notifications to multiple
4943 addresses.
4944 At least one Recipient must be present for the plugin to work
4946 correctly.
4947 SMTPServer Hostname
4949 Hostname of the SMTP server to connect to.
4950 Default: "localhost"
4952 SMTPPort Port
4954 TCP port to connect to.
4955 Default: 25
4957 SMTPUser Username
4959 Username for ASMTP authentication. Optional.
4960 SMTPPassword Password
4962 Password for ASMTP authentication. Optional.
4963 Subject Subject
4965 Subject-template to use when sending emails. There must be exactly
4966 two string-placeholders in the subject, given in the standard
4967 printf(3) syntax, i. e. %s. The first will be replaced with the
4968 severity, the second with the hostname.
4969 Default: "Collectd notify: %s@%s"
4971 Plugin "notify_nagios"
4973 The notify_nagios plugin writes notifications to Nagios' command file
4974 as a passive service check result.
4975 Available configuration options:
4977 CommandFile Path
4979 Sets the command file to write to. Defaults to
4980 /usr/local/nagios/var/rw/nagios.cmd.
4981 Plugin "ntpd"
4983 The "ntpd" plugin collects per-peer ntp data such as time offset and
4984 time dispersion.
4985 For talking to ntpd, it mimics what the ntpdc control program does on
4987 the wire - using mode 7 specific requests. This mode is deprecated with
4988 newer ntpd releases (4.2.7p230 and later). For the "ntpd" plugin to
4989 work correctly with them, the ntp daemon must be explicitly configured
4990 to enable mode 7 (which is disabled by default). Refer to the
4991 ntp.conf(5) manual page for details.
4992 Available configuration options for the "ntpd" plugin:
4994 Host Hostname
4996 Hostname of the host running ntpd. Defaults to localhost.
4997 Port Port
4999 UDP-Port to connect to. Defaults to 123.
5000 ReverseLookups true|false
5002 Sets whether or not to perform reverse lookups on peers. Since the
5003 name or IP-address may be used in a filename it is recommended to
5004 disable reverse lookups. The default is to do reverse lookups to
5005 preserve backwards compatibility, though.
5006 IncludeUnitID true|false
5008 When a peer is a refclock, include the unit ID in the type
5009 instance. Defaults to false for backward compatibility.
5010 If two refclock peers use the same driver and this is false, the
5012 plugin will try to write simultaneous measurements from both to the
5013 same type instance. This will result in error messages in the log
5014 and only one set of measurements making it through.
5015 Plugin "nut"
5017 UPS upsname@hostname[:port]
5018 Add a UPS to collect data from. The format is identical to the one
5019 accepted by upsc(8).
5020 ForceSSL true|false
5022 Stops connections from falling back to unsecured if an SSL
5023 connection cannot be established. Defaults to false if undeclared.
5024 VerifyPeer true|false
5026 If set to true, requires a CAPath be provided. Will use the CAPath
5027 to find certificates to use as Trusted Certificates to validate a
5028 upsd server certificate. If validation of the upsd server
5029 certificate fails, the connection will not be established. If
5030 ForceSSL is undeclared or set to false, setting VerifyPeer to true
5031 will override and set ForceSSL to true.
5032 CAPath I/path/to/certs/folder
5034 If VerifyPeer is set to true, this is required. Otherwise this is
5035 ignored. The folder pointed at must contain certificate(s) named
5036 according to their hash. Ex: XXXXXXXX.Y where X is the hash value
5037 of a cert and Y is 0. If name collisions occur because two
5038 different certs have the same hash value, Y can be incremented in
5039 order to avoid conflict. To create a symbolic link to a certificate
5040 the following command can be used from within the directory where
5041 the cert resides:
5042 "ln -s some.crt ./$(openssl x509 -hash -noout -in some.crt).0"
5044 Alternatively, the package openssl-perl provides a command
5046 "c_rehash" that will generate links like the one described above
5047 for ALL certs in a given folder. Example usage: "c_rehash
5048 /path/to/certs/folder"
5049 ConnectTimeout Milliseconds
5051 The ConnectTimeout option sets the connect timeout, in
5052 milliseconds. By default, the configured Interval is used to set
5053 the timeout.
5054 Plugin "olsrd"
5056 The olsrd plugin connects to the TCP port opened by the txtinfo plugin
5057 of the Optimized Link State Routing daemon and reads information about
5058 the current state of the meshed network.
5059 The following configuration options are understood:
5061 Host Host
5063 Connect to Host. Defaults to "localhost".
5064 Port Port
5066 Specifies the port to connect to. This must be a string, even if
5067 you give the port as a number rather than a service name. Defaults
5068 to "2006".
5069 CollectLinks No|Summary|Detail
5071 Specifies what information to collect about links, i. e. direct
5072 connections of the daemon queried. If set to No, no information is
5073 collected. If set to Summary, the number of links and the average
5074 of all link quality (LQ) and neighbor link quality (NLQ) values is
5075 calculated. If set to Detail LQ and NLQ are collected per link.
5076 Defaults to Detail.
5078 CollectRoutes No|Summary|Detail
5080 Specifies what information to collect about routes of the daemon
5081 queried. If set to No, no information is collected. If set to
5082 Summary, the number of routes and the average metric and ETX is
5083 calculated. If set to Detail metric and ETX are collected per
5084 route.
5085 Defaults to Summary.
5087 CollectTopology No|Summary|Detail
5089 Specifies what information to collect about the global topology. If
5090 set to No, no information is collected. If set to Summary, the
5091 number of links in the entire topology and the average link quality
5092 (LQ) is calculated. If set to Detail LQ and NLQ are collected for
5093 each link in the entire topology.
5094 Defaults to Summary.
5096 Plugin "onewire"
5098 EXPERIMENTAL! See notes below.
5099 The "onewire" plugin uses the owcapi library from the owfs project
5101 <http://owfs.org/> to read sensors connected via the onewire bus.
5102 It can be used in two possible modes - standard or advanced.
5104 In the standard mode only temperature sensors (sensors with the family
5106 code 10, 22 and 28 - e.g. DS1820, DS18S20, DS1920) can be read. If you
5107 have other sensors you would like to have included, please send a sort
5108 request to the mailing list. You can select sensors to be read or to be
5109 ignored depending on the option IgnoreSelected). When no list is
5110 provided the whole bus is walked and all sensors are read.
5111 Hubs (the DS2409 chips) are working, but read the note, why this plugin
5113 is experimental, below.
5114 In the advanced mode you can configure any sensor to be read (only
5116 numerical value) using full OWFS path (e.g.
5117 "/uncached/10.F10FCA000800/temperature"). In this mode you have to
5118 list all the sensors. Neither default bus walk nor IgnoreSelected are
5119 used here. Address and type (file) is extracted from the path
5120 automatically and should produce compatible structure with the
5121 "standard" mode (basically the path is expected as for example
5122 "/uncached/10.F10FCA000800/temperature" where it would extract address
5123 part "F10FCA000800" and the rest after the slash is considered the type
5124 - here "temperature"). There are two advantages to this mode - you can
5125 access virtually any sensor (not just temperature), select whether to
5126 use cached or directly read values and it is slighlty faster. The
5127 downside is more complex configuration.
5128 The two modes are distinguished automatically by the format of the
5130 address. It is not possible to mix the two modes. Once a full path is
5131 detected in any Sensor then the whole addressing (all sensors) is
5132 considered to be this way (and as standard addresses will fail parsing
5133 they will be ignored).
5134 Device Device
5136 Sets the device to read the values from. This can either be a
5137 "real" hardware device, such as a serial port or an USB port, or
5138 the address of the owserver(1) socket, usually localhost:4304.
5139 Though the documentation claims to automatically recognize the
5141 given address format, with version 2.7p4 we had to specify the type
5142 explicitly. So with that version, the following configuration
5143 worked for us:
5144 <Plugin onewire>
5146 Device "-s localhost:4304"
5147 </Plugin>
5148 This directive is required and does not have a default value.
5150 Sensor Sensor
5152 In the standard mode selects sensors to collect or to ignore
5153 (depending on IgnoreSelected, see below). Sensors are specified
5154 without the family byte at the beginning, so you have to use for
5155 example "F10FCA000800", and not include the leading 10. family byte
5156 and point. When no Sensor is configured the whole Onewire bus is
5157 walked and all supported sensors (see above) are read.
5158 In the advanced mode the Sensor specifies full OWFS path - e.g.
5160 "/uncached/10.F10FCA000800/temperature" (or when cached values are
5161 OK "/10.F10FCA000800/temperature"). IgnoreSelected is not used.
5162 As there can be multiple devices on the bus you can list multiple
5164 sensor (use multiple Sensor elements).
5165 See /"IGNORELISTS" for details.
5167 IgnoreSelected true|false
5169 If no configuration is given, the onewire plugin will collect data
5170 from all sensors found. This may not be practical, especially if
5171 sensors are added and removed regularly. Sometimes, however, it's
5172 easier/preferred to collect only specific sensors or all sensors
5173 except a few specified ones. This option enables you to do that: By
5174 setting IgnoreSelected to true the effect of Sensor is inverted:
5175 All selected interfaces are ignored and all other interfaces are
5176 collected.
5177 Used only in the standard mode - see above.
5179 Interval Seconds
5181 Sets the interval in which all sensors should be read. If not
5182 specified, the global Interval setting is used.
5183 EXPERIMENTAL! The "onewire" plugin is experimental, because it doesn't
5185 yet work with big setups. It works with one sensor being attached to
5186 one controller, but as soon as you throw in a couple more senors and
5187 maybe a hub or two, reading all values will take more than ten seconds
5188 (the default interval). We will probably add some separate thread for
5189 reading the sensors and some cache or something like that, but it's not
5190 done yet. We will try to maintain backwards compatibility in the
5191 future, but we can't promise. So in short: If it works for you: Great!
5192 But keep in mind that the config might change, though this is unlikely.
5193 Oh, and if you want to help improving this plugin, just send a short
5194 notice to the mailing list. Thanks :)
5195 Plugin "openldap"
5197 To use the "openldap" plugin you first need to configure the OpenLDAP
5198 server correctly. The backend database "monitor" needs to be loaded and
5199 working. See slapd-monitor(5) for the details.
5200 The configuration of the "openldap" plugin consists of one or more
5202 Instance blocks. Each block requires one string argument as the
5203 instance name. For example:
5204 <Plugin "openldap">
5206 <Instance "foo">
5207 URL "ldap://localhost/"
5208 </Instance>
5209 <Instance "bar">
5210 URL "ldaps://localhost/"
5211 </Instance>
5212 </Plugin>
5213 The instance name will be used as the plugin instance. To emulate the
5215 old (version 4) behavior, you can use an empty string (""). In order
5216 for the plugin to work correctly, each instance name must be unique.
5217 This is not enforced by the plugin and it is your responsibility to
5218 ensure it is.
5219 The following options are accepted within each Instance block:
5221 URL ldap://host/binddn
5223 Sets the URL to use to connect to the OpenLDAP server. This option
5224 is mandatory.
5225 BindDN BindDN
5227 Name in the form of an LDAP distinguished name intended to be used
5228 for authentication. Defaults to empty string to establish an
5229 anonymous authorization.
5230 Password Password
5232 Password for simple bind authentication. If this option is not set,
5233 unauthenticated bind operation is used.
5234 StartTLS true|false
5236 Defines whether TLS must be used when connecting to the OpenLDAP
5237 server. Disabled by default.
5238 VerifyHost true|false
5240 Enables or disables peer host name verification. If enabled, the
5241 plugin checks if the "Common Name" or a "Subject Alternate Name"
5242 field of the SSL certificate matches the host name provided by the
5243 URL option. If this identity check fails, the connection is
5244 aborted. Enabled by default.
5245 CACert File
5247 File that holds one or more SSL certificates. If you want to use
5248 TLS/SSL you may possibly need this option. What CA certificates are
5249 checked by default depends on the distribution you use and can be
5250 changed with the usual ldap client configuration mechanisms. See
5251 ldap.conf(5) for the details.
5252 Timeout Seconds
5254 Sets the timeout value for ldap operations, in seconds. By default,
5255 the configured Interval is used to set the timeout. Use -1 to
5256 disable (infinite timeout).
5257 Version Version
5259 An integer which sets the LDAP protocol version number to use when
5260 connecting to the OpenLDAP server. Defaults to 3 for using LDAPv3.
5261 Plugin "openvpn"
5263 The OpenVPN plugin reads a status file maintained by OpenVPN and
5264 gathers traffic statistics about connected clients.
5265 To set up OpenVPN to write to the status file periodically, use the
5267 --status option of OpenVPN.
5268 So, in a nutshell you need:
5270 openvpn $OTHER_OPTIONS \
5272 --status "/var/run/openvpn-status" 10
5273 Available options:
5275 StatusFile File
5277 Specifies the location of the status file.
5278 ImprovedNamingSchema true|false
5280 When enabled, the filename of the status file will be used as
5281 plugin instance and the client's "common name" will be used as type
5282 instance. This is required when reading multiple status files.
5283 Enabling this option is recommended, but to maintain backwards
5284 compatibility this option is disabled by default.
5285 CollectCompression true|false
5287 Sets whether or not statistics about the compression used by
5288 OpenVPN should be collected. This information is only available in
5289 single mode. Enabled by default.
5290 CollectIndividualUsers true|false
5292 Sets whether or not traffic information is collected for each
5293 connected client individually. If set to false, currently no
5294 traffic data is collected at all because aggregating this data in a
5295 save manner is tricky. Defaults to true.
5296 CollectUserCount true|false
5298 When enabled, the number of currently connected clients or users is
5299 collected. This is especially interesting when
5300 CollectIndividualUsers is disabled, but can be configured
5301 independently from that option. Defaults to false.
5302 Plugin "oracle"
5304 The "oracle" plugin uses the OracleX Call Interface (OCI) to connect to
5305 an OracleX Database and lets you execute SQL statements there. It is
5306 very similar to the "dbi" plugin, because it was written around the
5307 same time. See the "dbi" plugin's documentation above for details.
5308 <Plugin oracle>
5310 <Query "out_of_stock">
5311 Statement "SELECT category, COUNT(*) AS value FROM products WHERE in_stock = 0 GROUP BY category"
5312 <Result>
5313 Type "gauge"
5314 # InstancePrefix "foo"
5315 InstancesFrom "category"
5316 ValuesFrom "value"
5317 </Result>
5318 </Query>
5319 <Database "product_information">
5320 #Plugin "warehouse"
5321 ConnectID "db01"
5322 Username "oracle"
5323 Password "secret"
5324 Query "out_of_stock"
5325 </Database>
5326 </Plugin>
5327 Query blocks
5329 The Query blocks are handled identically to the Query blocks of the
5331 "dbi" plugin. Please see its documentation above for details on how to
5332 specify queries.
5333 Database blocks
5335 Database blocks define a connection to a database and which queries
5337 should be sent to that database. Each database needs a "name" as string
5338 argument in the starting tag of the block. This name will be used as
5339 "PluginInstance" in the values submitted to the daemon. Other than
5340 that, that name is not used.
5341 Plugin Plugin
5343 Use Plugin as the plugin name when submitting query results from
5344 this Database. Defaults to "oracle".
5345 ConnectID ID
5347 Defines the "database alias" or "service name" to connect to.
5348 Usually, these names are defined in the file named
5349 "$ORACLE_HOME/network/admin/tnsnames.ora".
5350 Host Host
5352 Hostname to use when dispatching values for this database. Defaults
5353 to using the global hostname of the collectd instance.
5354 Username Username
5356 Username used for authentication.
5357 Password Password
5359 Password used for authentication.
5360 Query QueryName
5362 Associates the query named QueryName with this database connection.
5363 The query needs to be defined before this statement, i. e. all
5364 query blocks you want to refer to must be placed above the database
5365 block you want to refer to them from.
5366 Plugin "ovs_events"
5368 The ovs_events plugin monitors the link status of Open vSwitch (OVS)
5369 connected interfaces, dispatches the values to collectd and sends the
5370 notification whenever the link state change occurs. This plugin uses
5371 OVS database to get a link state change notification.
5372 Synopsis:
5374 <Plugin "ovs_events">
5376 Port 6640
5377 Address "127.0.0.1"
5378 Socket "/var/run/openvswitch/db.sock"
5379 Interfaces "br0" "veth0"
5380 SendNotification true
5381 DispatchValues false
5382 </Plugin>
5383 The plugin provides the following configuration options:
5385 Address node
5387 The address of the OVS DB server JSON-RPC interface used by the
5388 plugin. To enable the interface, OVS DB daemon should be running
5389 with "--remote=ptcp:" option. See ovsdb-server(1) for more details.
5390 The option may be either network hostname, IPv4 numbers-and-dots
5391 notation or IPv6 hexadecimal string format. Defaults to
5392 "localhost".
5393 Port service
5395 TCP-port to connect to. Either a service name or a port number may
5396 be given. Defaults to 6640.
5397 Socket path
5399 The UNIX domain socket path of OVS DB server JSON-RPC interface
5400 used by the plugin. To enable the interface, the OVS DB daemon
5401 should be running with "--remote=punix:" option. See
5402 ovsdb-server(1) for more details. If this option is set, Address
5403 and Port options are ignored.
5404 Interfaces [ifname ...]
5406 List of interface names to be monitored by this plugin. If this
5407 option is not specified or is empty then all OVS connected
5408 interfaces on all bridges are monitored.
5409 Default: empty (all interfaces on all bridges are monitored)
5411 SendNotification true|false
5413 If set to true, OVS link notifications (interface status and OVS DB
5414 connection terminate) are sent to collectd. Default value is true.
5415 DispatchValues true|false
5417 Dispatch the OVS DB interface link status value with configured
5418 plugin interval. Defaults to false. Please note, if
5419 SendNotification and DispatchValues options are false, no OVS
5420 information will be provided by the plugin.
5421 Note: By default, the global interval setting is used within which to
5423 retrieve the OVS link status. To configure a plugin-specific interval,
5424 please use Interval option of the OVS LoadPlugin block settings. For
5425 milliseconds simple divide the time by 1000 for example if the desired
5426 interval is 50ms, set interval to 0.05.
5427 Plugin "ovs_stats"
5429 The ovs_stats plugin collects statistics of OVS connected interfaces.
5430 This plugin uses OVSDB management protocol (RFC7047) monitor mechanism
5431 to get statistics from OVSDB
5432 Synopsis:
5434 <Plugin "ovs_stats">
5436 Port 6640
5437 Address "127.0.0.1"
5438 Socket "/var/run/openvswitch/db.sock"
5439 Bridges "br0" "br_ext"
5440 InterfaceStats false
5441 </Plugin>
5442 The plugin provides the following configuration options:
5444 Address node
5446 The address of the OVS DB server JSON-RPC interface used by the
5447 plugin. To enable the interface, OVS DB daemon should be running
5448 with "--remote=ptcp:" option. See ovsdb-server(1) for more details.
5449 The option may be either network hostname, IPv4 numbers-and-dots
5450 notation or IPv6 hexadecimal string format. Defaults to
5451 "localhost".
5452 Port service
5454 TCP-port to connect to. Either a service name or a port number may
5455 be given. Defaults to 6640.
5456 Socket path
5458 The UNIX domain socket path of OVS DB server JSON-RPC interface
5459 used by the plugin. To enable the interface, the OVS DB daemon
5460 should be running with "--remote=punix:" option. See
5461 ovsdb-server(1) for more details. If this option is set, Address
5462 and Port options are ignored.
5463 Bridges [brname ...]
5465 List of OVS bridge names to be monitored by this plugin. If this
5466 option is omitted or is empty then all OVS bridges will be
5467 monitored.
5468 Default: empty (monitor all bridges)
5470 InterfaceStats false|true
5472 Indicates that the plugin should gather statistics for individual
5473 interfaces in addition to ports. This can be useful when
5474 monitoring an OVS setup with bond ports, where you might wish to
5475 know individual statistics for the interfaces included in the
5476 bonds. Defaults to false.
5477 Plugin "pcie_errors"
5479 The pcie_errors plugin collects PCI Express errors from Device Status
5480 in Capability structure and from Advanced Error Reporting Extended
5481 Capability where available. At every read it polls config space of PCI
5482 Express devices and dispatches notification for every error that is
5483 set. It checks for new errors at every read. The device is indicated
5484 in plugin_instance according to format "domain:bus:dev.fn". Errors are
5485 divided into categories indicated by type_instance: "correctable", and
5486 for uncorrectable errors "non_fatal" or "fatal". Fatal errors are
5487 reported as NOTIF_FAILURE and all others as NOTIF_WARNING.
5488 Synopsis:
5490 <Plugin "pcie_errors">
5492 Source "sysfs"
5493 AccessDir "/sys/bus/pci"
5494 ReportMasked false
5495 PersistentNotifications false
5496 </Plugin>
5497 Options:
5499 Source sysfs|proc
5501 Use sysfs or proc to read data from /sysfs or /proc. The default
5502 value is sysfs.
5503 AccessDir dir
5505 Directory used to access device config space. It is optional and
5506 defaults to /sys/bus/pci for sysfs and to /proc/bus/pci for proc.
5507 ReportMasked false|true
5509 If true plugin will notify about errors that are set to masked in
5510 Error Mask register. Such errors are not reported to the PCI
5511 Express Root Complex. Defaults to false.
5512 PersistentNotifications false|true
5514 If false plugin will dispatch notification only on set/clear of
5515 error. The ones already reported will be ignored. Defaults to
5516 false.
5517 Plugin "perl"
5519 This plugin embeds a Perl-interpreter into collectd and provides an
5520 interface to collectd's plugin system. See collectd-perl(5) for its
5521 documentation.
5522 Plugin "pinba"
5524 The Pinba plugin receives profiling information from Pinba, an
5525 extension for the PHP interpreter. At the end of executing a script,
5526 i.e. after a PHP-based webpage has been delivered, the extension will
5527 send a UDP packet containing timing information, peak memory usage and
5528 so on. The plugin will wait for such packets, parse them and account
5529 the provided information, which is then dispatched to the daemon once
5530 per interval.
5531 Synopsis:
5533 <Plugin pinba>
5535 Address "::0"
5536 Port "30002"
5537 # Overall statistics for the website.
5538 <View "www-total">
5539 Server "www.example.com"
5540 </View>
5541 # Statistics for www-a only
5542 <View "www-a">
5543 Host "www-a.example.com"
5544 Server "www.example.com"
5545 </View>
5546 # Statistics for www-b only
5547 <View "www-b">
5548 Host "www-b.example.com"
5549 Server "www.example.com"
5550 </View>
5551 </Plugin>
5552 The plugin provides the following configuration options:
5554 Address Node
5556 Configures the address used to open a listening socket. By default,
5557 plugin will bind to the any address "::0".
5558 Port Service
5560 Configures the port (service) to bind to. By default the default
5561 Pinba port "30002" will be used. The option accepts service names
5562 in addition to port numbers and thus requires a string argument.
5563 <View Name> block
5565 The packets sent by the Pinba extension include the hostname of the
5566 server, the server name (the name of the virtual host) and the
5567 script that was executed. Using View blocks it is possible to
5568 separate the data into multiple groups to get more meaningful
5569 statistics. Each packet is added to all matching groups, so that a
5570 packet may be accounted for more than once.
5571 Host Host
5573 Matches the hostname of the system the webserver / script is
5574 running on. This will contain the result of the gethostname(2)
5575 system call. If not configured, all hostnames will be accepted.
5576 Server Server
5578 Matches the name of the virtual host, i.e. the contents of the
5579 $_SERVER["SERVER_NAME"] variable when within PHP. If not
5580 configured, all server names will be accepted.
5581 Script Script
5583 Matches the name of the script name, i.e. the contents of the
5584 $_SERVER["SCRIPT_NAME"] variable when within PHP. If not
5585 configured, all script names will be accepted.
5586 Plugin "ping"
5588 The Ping plugin starts a new thread which sends ICMP "ping" packets to
5589 the configured hosts periodically and measures the network latency.
5590 Whenever the "read" function of the plugin is called, it submits the
5591 average latency, the standard deviation and the drop rate for each
5592 host.
5593 Available configuration options:
5595 Host IP-address
5597 Host to ping periodically. This option may be repeated several
5598 times to ping multiple hosts.
5599 Interval Seconds
5601 Sets the interval in which to send ICMP echo packets to the
5602 configured hosts. This is not the interval in which metrics are
5603 read from the plugin but the interval in which the hosts are
5604 "pinged". Therefore, the setting here should be smaller than or
5605 equal to the global Interval setting. Fractional times, such as
5606 "1.24" are allowed.
5607 Default: 1.0
5609 Timeout Seconds
5611 Time to wait for a response from the host to which an ICMP packet
5612 had been sent. If a reply was not received after Seconds seconds,
5613 the host is assumed to be down or the packet to be dropped. This
5614 setting must be smaller than the Interval setting above for the
5615 plugin to work correctly. Fractional arguments are accepted.
5616 Default: 0.9
5618 TTL 0-255
5620 Sets the Time-To-Live of generated ICMP packets.
5621 Size size
5623 Sets the size of the data payload in ICMP packet to specified size
5624 (it will be filled with regular ASCII pattern). If not set, default
5625 56 byte long string is used so that the packet size of an ICMPv4
5626 packet is exactly 64 bytes, similar to the behaviour of normal
5627 ping(1) command.
5628 SourceAddress host
5630 Sets the source address to use. host may either be a numerical
5631 network address or a network hostname.
5632 AddressFamily af
5634 Sets the address family to use. af may be "any", "ipv4" or "ipv6".
5635 This option will be ignored if you set a SourceAddress.
5636 Device name
5638 Sets the outgoing network device to be used. name has to specify an
5639 interface name (e. g. "eth0"). This might not be supported by all
5640 operating systems.
5641 MaxMissed Packets
5643 Trigger a DNS resolve after the host has not replied to Packets
5644 packets. This enables the use of dynamic DNS services (like
5645 dyndns.org) with the ping plugin.
5646 Default: -1 (disabled)
5648 Plugin "postgresql"
5650 The "postgresql" plugin queries statistics from PostgreSQL databases.
5651 It keeps a persistent connection to all configured databases and tries
5652 to reconnect if the connection has been interrupted. A database is
5653 configured by specifying a Database block as described below. The
5654 default statistics are collected from PostgreSQL's statistics collector
5655 which thus has to be enabled for this plugin to work correctly. This
5656 should usually be the case by default. See the section "The Statistics
5657 Collector" of the PostgreSQL Documentation for details.
5658 By specifying custom database queries using a Query block as described
5660 below, you may collect any data that is available from some PostgreSQL
5661 database. This way, you are able to access statistics of external
5662 daemons which are available in a PostgreSQL database or use future or
5663 special statistics provided by PostgreSQL without the need to upgrade
5664 your collectd installation.
5665 Starting with version 5.2, the "postgresql" plugin supports writing
5667 data to PostgreSQL databases as well. This has been implemented in a
5668 generic way. You need to specify an SQL statement which will then be
5669 executed by collectd in order to write the data (see below for
5670 details). The benefit of that approach is that there is no fixed
5671 database layout. Rather, the layout may be optimized for the current
5672 setup.
5673 The PostgreSQL Documentation manual can be found at
5675 <http://www.postgresql.org/docs/manuals/>.
5676 <Plugin postgresql>
5678 <Query magic>
5679 Statement "SELECT magic FROM wizard WHERE host = $1;"
5680 Param hostname
5681 <Result>
5682 Type gauge
5683 InstancePrefix "magic"
5684 ValuesFrom magic
5685 </Result>
5686 </Query>
5687 <Query rt36_tickets>
5689 Statement "SELECT COUNT(type) AS count, type \
5690 FROM (SELECT CASE \
5691 WHEN resolved = 'epoch' THEN 'open' \
5692 ELSE 'resolved' END AS type \
5693 FROM tickets) type \
5694 GROUP BY type;"
5695 <Result>
5696 Type counter
5697 InstancePrefix "rt36_tickets"
5698 InstancesFrom "type"
5699 ValuesFrom "count"
5700 </Result>
5701 </Query>
5702 <Writer sqlstore>
5704 Statement "SELECT collectd_insert($1, $2, $3, $4, $5, $6, $7, $8, $9);"
5705 StoreRates true
5706 </Writer>
5707 <Database foo>
5709 Plugin "kingdom"
5710 Host "hostname"
5711 Port "5432"
5712 User "username"
5713 Password "secret"
5714 SSLMode "prefer"
5715 KRBSrvName "kerberos_service_name"
5716 Query magic
5717 </Database>
5718 <Database bar>
5720 Interval 300
5721 Service "service_name"
5722 Query backends # predefined
5723 Query rt36_tickets
5724 </Database>
5725 <Database qux>
5727 # ...
5728 Writer sqlstore
5729 CommitInterval 10
5730 </Database>
5731 </Plugin>
5732 The Query block defines one database query which may later be used by a
5734 database definition. It accepts a single mandatory argument which
5735 specifies the name of the query. The names of all queries have to be
5736 unique (see the MinVersion and MaxVersion options below for an
5737 exception to this rule).
5738 In each Query block, there is one or more Result blocks. Multiple
5740 Result blocks may be used to extract multiple values from a single
5741 query.
5742 The following configuration options are available to define the query:
5744 Statement sql query statement
5746 Specify the sql query statement which the plugin should execute.
5747 The string may contain the tokens $1, $2, etc. which are used to
5748 reference the first, second, etc. parameter. The value of the
5749 parameters is specified by the Param configuration option - see
5750 below for details. To include a literal $ character followed by a
5751 number, surround it with single quotes (').
5752 Any SQL command which may return data (such as "SELECT" or "SHOW")
5754 is allowed. Note, however, that only a single command may be used.
5755 Semicolons are allowed as long as a single non-empty command has
5756 been specified only.
5757 The returned lines will be handled separately one after another.
5759 Param hostname|database|instance|username|interval
5761 Specify the parameters which should be passed to the SQL query. The
5762 parameters are referred to in the SQL query as $1, $2, etc. in the
5763 same order as they appear in the configuration file. The value of
5764 the parameter is determined depending on the value of the Param
5765 option as follows:
5766 hostname
5768 The configured hostname of the database connection. If a UNIX
5769 domain socket is used, the parameter expands to "localhost".
5770 database
5772 The name of the database of the current connection.
5773 instance
5775 The name of the database plugin instance. See the Instance
5776 option of the database specification below for details.
5777 username
5779 The username used to connect to the database.
5780 interval
5782 The interval with which this database is queried (as specified
5783 by the database specific or global Interval options).
5784 Please note that parameters are only supported by PostgreSQL's
5786 protocol version 3 and above which was introduced in version 7.4 of
5787 PostgreSQL.
5788 PluginInstanceFrom column
5790 Specify how to create the "PluginInstance" for reporting this query
5791 results. Only one column is supported. You may concatenate fields
5792 and string values in the query statement to get the required
5793 results.
5794 MinVersion version
5796 MaxVersion version
5797 Specify the minimum or maximum version of PostgreSQL that this
5798 query should be used with. Some statistics might only be available
5799 with certain versions of PostgreSQL. This allows you to specify
5800 multiple queries with the same name but which apply to different
5801 versions, thus allowing you to use the same configuration in a
5802 heterogeneous environment.
5803 The version has to be specified as the concatenation of the major,
5805 minor and patch-level versions, each represented as two-decimal-
5806 digit numbers. For example, version 8.2.3 will become 80203.
5807 The Result block defines how to handle the values returned from the
5809 query. It defines which column holds which value and how to dispatch
5810 that value to the daemon.
5811 Type type
5813 The type name to be used when dispatching the values. The type
5814 describes how to handle the data and where to store it. See
5815 types.db(5) for more details on types and their configuration. The
5816 number and type of values (as selected by the ValuesFrom option)
5817 has to match the type of the given name.
5818 This option is mandatory.
5820 InstancePrefix prefix
5822 InstancesFrom column0 [column1 ...]
5823 Specify how to create the "TypeInstance" for each data set (i. e.
5824 line). InstancePrefix defines a static prefix that will be
5825 prepended to all type instances. InstancesFrom defines the column
5826 names whose values will be used to create the type instance.
5827 Multiple values will be joined together using the hyphen ("-") as
5828 separation character.
5829 The plugin itself does not check whether or not all built instances
5831 are different. It is your responsibility to assure that each is
5832 unique.
5833 Both options are optional. If none is specified, the type instance
5835 will be empty.
5836 ValuesFrom column0 [column1 ...]
5838 Names the columns whose content is used as the actual data for the
5839 data sets that are dispatched to the daemon. How many such columns
5840 you need is determined by the Type setting as explained above. If
5841 you specify too many or not enough columns, the plugin will
5842 complain about that and no data will be submitted to the daemon.
5843 The actual data type, as seen by PostgreSQL, is not that important
5845 as long as it represents numbers. The plugin will automatically
5846 cast the values to the right type if it know how to do that. For
5847 that, it uses the strtoll(3) and strtod(3) functions, so anything
5848 supported by those functions is supported by the plugin as well.
5849 This option is required inside a Result block and may be specified
5851 multiple times. If multiple ValuesFrom options are specified, the
5852 columns are read in the given order.
5853 The following predefined queries are available (the definitions can be
5855 found in the postgresql_default.conf file which, by default, is
5856 available at "prefix/share/collectd/"):
5857 backends
5859 This query collects the number of backends, i. e. the number of
5860 connected clients.
5861 transactions
5863 This query collects the numbers of committed and rolled-back
5864 transactions of the user tables.
5865 queries
5867 This query collects the numbers of various table modifications
5868 (i. e. insertions, updates, deletions) of the user tables.
5869 query_plans
5871 This query collects the numbers of various table scans and returned
5872 tuples of the user tables.
5873 table_states
5875 This query collects the numbers of live and dead rows in the user
5876 tables.
5877 disk_io
5879 This query collects disk block access counts for user tables.
5880 disk_usage
5882 This query collects the on-disk size of the database in bytes.
5883 In addition, the following detailed queries are available by default.
5885 Please note that each of those queries collects information by table,
5886 thus, potentially producing a lot of data. For details see the
5887 description of the non-by_table queries above.
5888 queries_by_table
5890 query_plans_by_table
5891 table_states_by_table
5892 disk_io_by_table
5893 The Writer block defines a PostgreSQL writer backend. It accepts a
5895 single mandatory argument specifying the name of the writer. This will
5896 then be used in the Database specification in order to activate the
5897 writer instance. The names of all writers have to be unique. The
5898 following options may be specified:
5899 Statement sql statement
5901 This mandatory option specifies the SQL statement that will be
5902 executed for each submitted value. A single SQL statement is
5903 allowed only. Anything after the first semicolon will be ignored.
5904 Nine parameters will be passed to the statement and should be
5906 specified as tokens $1, $2, through $9 in the statement string. The
5907 following values are made available through those parameters:
5908 $1 The timestamp of the queried value as an RFC 3339-formatted
5910 local time.
5911 $2 The hostname of the queried value.
5913 $3 The plugin name of the queried value.
5915 $4 The plugin instance of the queried value. This value may be
5917 NULL if there is no plugin instance.
5918 $5 The type of the queried value (cf. types.db(5)).
5920 $6 The type instance of the queried value. This value may be NULL
5922 if there is no type instance.
5923 $7 An array of names for the submitted values (i. e., the name of
5925 the data sources of the submitted value-list).
5926 $8 An array of types for the submitted values (i. e., the type of
5928 the data sources of the submitted value-list; "counter",
5929 "gauge", ...). Note, that if StoreRates is enabled (which is
5930 the default, see below), all types will be "gauge".
5931 $9 An array of the submitted values. The dimensions of the value
5933 name and value arrays match.
5934 In general, it is advisable to create and call a custom function in
5936 the PostgreSQL database for this purpose. Any procedural language
5937 supported by PostgreSQL will do (see chapter "Server Programming"
5938 in the PostgreSQL manual for details).
5939 StoreRates false|true
5941 If set to true (the default), convert counter values to rates. If
5942 set to false counter values are stored as is, i. e. as an
5943 increasing integer number.
5944 The Database block defines one PostgreSQL database for which to collect
5946 statistics. It accepts a single mandatory argument which specifies the
5947 database name. None of the other options are required. PostgreSQL will
5948 use default values as documented in the section "CONNECTING TO A
5949 DATABASE" in the psql(1) manpage. However, be aware that those defaults
5950 may be influenced by the user collectd is run as and special
5951 environment variables. See the manpage for details.
5952 Interval seconds
5954 Specify the interval with which the database should be queried. The
5955 default is to use the global Interval setting.
5956 CommitInterval seconds
5958 This option may be used for database connections which have
5959 "writers" assigned (see above). If specified, it causes a writer to
5960 put several updates into a single transaction. This transaction
5961 will last for the specified amount of time. By default, each update
5962 will be executed in a separate transaction. Each transaction
5963 generates a fair amount of overhead which can, thus, be reduced by
5964 activating this option. The draw-back is, that data covering the
5965 specified amount of time will be lost, for example, if a single
5966 statement within the transaction fails or if the database server
5967 crashes.
5968 Plugin Plugin
5970 Use Plugin as the plugin name when submitting query results from
5971 this Database. Defaults to "postgresql".
5972 Instance name
5974 Specify the plugin instance name that should be used instead of the
5975 database name (which is the default, if this option has not been
5976 specified). This allows one to query multiple databases of the same
5977 name on the same host (e.g. when running multiple database server
5978 versions in parallel). The plugin instance name can also be set
5979 from the query result using the PluginInstanceFrom option in Query
5980 block.
5981 Host hostname
5983 Specify the hostname or IP of the PostgreSQL server to connect to.
5984 If the value begins with a slash, it is interpreted as the
5985 directory name in which to look for the UNIX domain socket.
5986 This option is also used to determine the hostname that is
5988 associated with a collected data set. If it has been omitted or
5989 either begins with with a slash or equals localhost it will be
5990 replaced with the global hostname definition of collectd. Any other
5991 value will be passed literally to collectd when dispatching values.
5992 Also see the global Hostname and FQDNLookup options.
5993 Port port
5995 Specify the TCP port or the local UNIX domain socket file extension
5996 of the server.
5997 User username
5999 Specify the username to be used when connecting to the server.
6000 Password password
6002 Specify the password to be used when connecting to the server.
6003 ExpireDelay delay
6005 Skip expired values in query output.
6006 SSLMode disable|allow|prefer|require
6008 Specify whether to use an SSL connection when contacting the
6009 server. The following modes are supported:
6010 disable
6012 Do not use SSL at all.
6013 allow
6015 First, try to connect without using SSL. If that fails, try
6016 using SSL.
6017 prefer (default)
6019 First, try to connect using SSL. If that fails, try without
6020 using SSL.
6021 require
6023 Use SSL only.
6024 Instance name
6026 Specify the plugin instance name that should be used instead of the
6027 database name (which is the default, if this option has not been
6028 specified). This allows one to query multiple databases of the same
6029 name on the same host (e.g. when running multiple database server
6030 versions in parallel).
6031 KRBSrvName kerberos_service_name
6033 Specify the Kerberos service name to use when authenticating with
6034 Kerberos 5 or GSSAPI. See the sections "Kerberos authentication"
6035 and "GSSAPI" of the PostgreSQL Documentation for details.
6036 Service service_name
6038 Specify the PostgreSQL service name to use for additional
6039 parameters. That service has to be defined in pg_service.conf and
6040 holds additional connection parameters. See the section "The
6041 Connection Service File" in the PostgreSQL Documentation for
6042 details.
6043 Query query
6045 Specifies a query which should be executed in the context of the
6046 database connection. This may be any of the predefined or user-
6047 defined queries. If no such option is given, it defaults to
6048 "backends", "transactions", "queries", "query_plans",
6049 "table_states", "disk_io" and "disk_usage" (unless a Writer has
6050 been specified). Else, the specified queries are used only.
6051 Writer writer
6053 Assigns the specified writer backend to the database connection.
6054 This causes all collected data to be send to the database using the
6055 settings defined in the writer configuration (see the section
6056 "FILTER CONFIGURATION" below for details on how to selectively send
6057 data to certain plugins).
6058 Each writer will register a flush callback which may be used when
6060 having long transactions enabled (see the CommitInterval option
6061 above). When issuing the FLUSH command (see collectd-unixsock(5)
6062 for details) the current transaction will be committed right away.
6063 Two different kinds of flush callbacks are available with the
6064 "postgresql" plugin:
6065 postgresql
6067 Flush all writer backends.
6068 postgresql-database
6070 Flush all writers of the specified database only.
6071 Plugin "powerdns"
6073 The "powerdns" plugin queries statistics from an authoritative PowerDNS
6074 nameserver and/or a PowerDNS recursor. Since both offer a wide variety
6075 of values, many of which are probably meaningless to most users, but
6076 may be useful for some. So you may chose which values to collect, but
6077 if you don't, some reasonable defaults will be collected.
6078 <Plugin "powerdns">
6080 <Server "server_name">
6081 Collect "latency"
6082 Collect "udp-answers" "udp-queries"
6083 Socket "/var/run/pdns.controlsocket"
6084 </Server>
6085 <Recursor "recursor_name">
6086 Collect "questions"
6087 Collect "cache-hits" "cache-misses"
6088 Socket "/var/run/pdns_recursor.controlsocket"
6089 </Recursor>
6090 LocalSocket "/opt/collectd/var/run/collectd-powerdns"
6091 </Plugin>
6092 Server and Recursor block
6094 The Server block defines one authoritative server to query, the
6095 Recursor does the same for an recursing server. The possible
6096 options in both blocks are the same, though. The argument defines a
6097 name for the server / recursor and is required.
6098 Collect Field
6100 Using the Collect statement you can select which values to
6101 collect. Here, you specify the name of the values as used by
6102 the PowerDNS servers, e. g. "dlg-only-drops", "answers10-100".
6103 The method of getting the values differs for Server and
6105 Recursor blocks: When querying the server a "SHOW *" command is
6106 issued in any case, because that's the only way of getting
6107 multiple values out of the server at once. collectd then picks
6108 out the values you have selected. When querying the recursor, a
6109 command is generated to query exactly these values. So if you
6110 specify invalid fields when querying the recursor, a syntax
6111 error may be returned by the daemon and collectd may not
6112 collect any values at all.
6113 If no Collect statement is given, the following Server values
6115 will be collected:
6116 latency
6118 packetcache-hit
6119 packetcache-miss
6120 packetcache-size
6121 query-cache-hit
6122 query-cache-miss
6123 recursing-answers
6124 recursing-questions
6125 tcp-answers
6126 tcp-queries
6127 udp-answers
6128 udp-queries
6129 The following Recursor values will be collected by default:
6131 noerror-answers
6133 nxdomain-answers
6134 servfail-answers
6135 sys-msec
6136 user-msec
6137 qa-latency
6138 cache-entries
6139 cache-hits
6140 cache-misses
6141 questions
6142 Please note that up to that point collectd doesn't know what
6144 values are available on the server and values that are added do
6145 not need a change of the mechanism so far. However, the values
6146 must be mapped to collectd's naming scheme, which is done using
6147 a lookup table that lists all known values. If values are added
6148 in the future and collectd does not know about them, you will
6149 get an error much like this:
6150 powerdns plugin: submit: Not found in lookup table: foobar = 42
6152 In this case please file a bug report with the collectd team.
6154 Socket Path
6156 Configures the path to the UNIX domain socket to be used when
6157 connecting to the daemon. By default
6158 "${localstatedir}/run/pdns.controlsocket" will be used for an
6159 authoritative server and
6160 "${localstatedir}/run/pdns_recursor.controlsocket" will be used
6161 for the recursor.
6162 LocalSocket Path
6164 Querying the recursor is done using UDP. When using UDP over UNIX
6165 domain sockets, the client socket needs a name in the file system,
6166 too. You can set this local name to Path using the LocalSocket
6167 option. The default is "prefix/var/run/collectd-powerdns".
6168 Plugin "processes"
6170 Collects information about processes of local system.
6171 By default, with no process matches configured, only general statistics
6173 is collected: the number of processes in each state and fork rate.
6174 Process matches can be configured by Process and ProcessMatch options.
6176 These may also be a block in which further options may be specified.
6177 The statistics collected for matched processes are:
6179 - size of the resident segment size (RSS)
6180 - user- and system-time used
6181 - number of processes
6182 - number of threads
6183 - number of open files (under Linux)
6184 - number of memory mapped files (under Linux)
6185 - io data (where available)
6186 - context switches (under Linux)
6187 - minor and major pagefaults
6188 - Delay Accounting information (Linux only, requires libmnl)
6189 Synopsis:
6191 <Plugin processes>
6193 CollectFileDescriptor true
6194 CollectContextSwitch true
6195 CollectDelayAccounting false
6196 Process "name"
6197 ProcessMatch "name" "regex"
6198 <Process "collectd">
6199 CollectFileDescriptor false
6200 CollectContextSwitch false
6201 CollectDelayAccounting true
6202 </Process>
6203 <ProcessMatch "name" "regex">
6204 CollectFileDescriptor false
6205 CollectContextSwitch true
6206 </ProcessMatch>
6207 </Plugin>
6208 Process Name
6210 Select more detailed statistics of processes matching this name.
6211 Some platforms have a limit on the length of process names. Name
6213 must stay below this limit.
6214 ProcessMatch name regex
6216 Select more detailed statistics of processes matching the specified
6217 regex (see regex(7) for details). The statistics of all matching
6218 processes are summed up and dispatched to the daemon using the
6219 specified name as an identifier. This allows one to "group" several
6220 processes together. name must not contain slashes.
6221 CollectContextSwitch Boolean
6223 Collect the number of context switches for matched processes.
6224 Disabled by default.
6225 CollectDelayAccounting Boolean
6227 If enabled, collect Linux Delay Accounding information for matching
6228 processes. Delay Accounting provides the time processes wait for
6229 the CPU to become available, for I/O operations to finish, for
6230 pages to be swapped in and for freed pages to be reclaimed. The
6231 metrics are reported as "seconds per second" using the "delay_rate"
6232 type, e.g. "delay_rate-delay-cpu". Disabled by default.
6233 This option is only available on Linux, requires the "libmnl"
6235 library and requires the "CAP_NET_ADMIN" capability at runtime.
6236 CollectFileDescriptor Boolean
6238 Collect number of file descriptors of matched processes. Disabled
6239 by default.
6240 CollectMemoryMaps Boolean
6242 Collect the number of memory mapped files of the process. The
6243 limit for this number is configured via /proc/sys/vm/max_map_count
6244 in the Linux kernel.
6245 The CollectContextSwitch, CollectDelayAccounting, CollectFileDescriptor
6247 and CollectMemoryMaps options may be used inside Process and
6248 ProcessMatch blocks. When used there, these options affect reporting
6249 the corresponding processes only. Outside of Process and ProcessMatch
6250 blocks these options set the default value for subsequent matches.
6251 Plugin "protocols"
6253 Collects a lot of information about various network protocols, such as
6254 IP, TCP, UDP, etc.
6255 Available configuration options:
6257 Value Selector
6259 Selects whether or not to select a specific value. The string being
6260 matched is of the form "Protocol:ValueName", where Protocol will be
6261 used as the plugin instance and ValueName will be used as type
6262 instance. An example of the string being used would be
6263 "Tcp:RetransSegs".
6264 You can use regular expressions to match a large number of values
6266 with just one configuration option. To select all "extended" TCP
6267 values, you could use the following statement:
6268 Value "/^TcpExt:/"
6270 Whether only matched values are selected or all matched values are
6272 ignored depends on the IgnoreSelected. By default, only matched
6273 values are selected. If no value is configured at all, all values
6274 will be selected.
6275 See /"IGNORELISTS" for details.
6277 IgnoreSelected true|false
6279 If set to true, inverts the selection made by Value, i. e. all
6280 matching values will be ignored.
6281 Plugin "python"
6283 This plugin embeds a Python-interpreter into collectd and provides an
6284 interface to collectd's plugin system. See collectd-python(5) for its
6285 documentation.
6286 Plugin "routeros"
6288 The "routeros" plugin connects to a device running RouterOS, the Linux-
6289 based operating system for routers by MikroTik. The plugin uses
6290 librouteros to connect and reads information about the interfaces and
6291 wireless connections of the device. The configuration supports querying
6292 multiple routers:
6293 <Plugin "routeros">
6295 <Router>
6296 Host "router0.example.com"
6297 User "collectd"
6298 Password "secr3t"
6299 CollectInterface true
6300 CollectCPULoad true
6301 CollectMemory true
6302 </Router>
6303 <Router>
6304 Host "router1.example.com"
6305 User "collectd"
6306 Password "5ecret"
6307 CollectInterface true
6308 CollectRegistrationTable true
6309 CollectDF true
6310 CollectDisk true
6311 CollectHealth true
6312 </Router>
6313 </Plugin>
6314 As you can see above, the configuration of the routeros plugin consists
6316 of one or more <Router> blocks. Within each block, the following
6317 options are understood:
6318 Host Host
6320 Hostname or IP-address of the router to connect to.
6321 Port Port
6323 Port name or port number used when connecting. If left unspecified,
6324 the default will be chosen by librouteros, currently "8728". This
6325 option expects a string argument, even when a numeric port number
6326 is given.
6327 User User
6329 Use the user name User to authenticate. Defaults to "admin".
6330 Password Password
6332 Set the password used to authenticate.
6333 CollectInterface true|false
6335 When set to true, interface statistics will be collected for all
6336 interfaces present on the device. Defaults to false.
6337 CollectRegistrationTable true|false
6339 When set to true, information about wireless LAN connections will
6340 be collected. Defaults to false.
6341 CollectCPULoad true|false
6343 When set to true, information about the CPU usage will be
6344 collected. The number is a dimensionless value where zero indicates
6345 no CPU usage at all. Defaults to false.
6346 CollectMemory true|false
6348 When enabled, the amount of used and free memory will be collected.
6349 How used memory is calculated is unknown, for example whether or
6350 not caches are counted as used space. Defaults to false.
6351 CollectDF true|false
6353 When enabled, the amount of used and free disk space will be
6354 collected. Defaults to false.
6355 CollectDisk true|false
6357 When enabled, the number of sectors written and bad blocks will be
6358 collected. Defaults to false.
6359 CollectHealth true|false
6361 When enabled, the health statistics will be collected. This
6362 includes the voltage and temperature on supported hardware.
6363 Defaults to false.
6364 Plugin "redis"
6366 The Redis plugin connects to one or more Redis servers, gathers
6367 information about each server's state and executes user-defined
6368 queries. For each server there is a Node block which configures the
6369 connection parameters and set of user-defined queries for this node.
6370 <Plugin redis>
6372 <Node "example">
6373 Host "localhost"
6374 Port "6379"
6375 #Socket "/var/run/redis/redis.sock"
6376 Timeout 2000
6377 ReportCommandStats false
6378 ReportCpuUsage true
6379 <Query "LLEN myqueue">
6380 #Database 0
6381 Type "queue_length"
6382 Instance "myqueue"
6383 </Query>
6384 </Node>
6385 </Plugin>
6386 Node Nodename
6388 The Node block identifies a new Redis node, that is a new Redis
6389 instance running in an specified host and port. The name for node
6390 is a canonical identifier which is used as plugin instance. It is
6391 limited to 128 characters in length.
6392 When no Node is configured explicitly, plugin connects to
6394 "localhost:6379".
6395 Host Hostname
6397 The Host option is the hostname or IP-address where the Redis
6398 instance is running on.
6399 Port Port
6401 The Port option is the TCP port on which the Redis instance accepts
6402 connections. Either a service name of a port number may be given.
6403 Please note that numerical port numbers must be given as a string,
6404 too.
6405 Socket Path
6407 Connect to Redis using the UNIX domain socket at Path. If this
6408 setting is given, the Hostname and Port settings are ignored.
6409 Password Password
6411 Use Password to authenticate when connecting to Redis.
6412 Timeout Milliseconds
6414 The Timeout option set the socket timeout for node response. Since
6415 the Redis read function is blocking, you should keep this value as
6416 low as possible. It is expected what Timeout values should be
6417 lower than Interval defined globally.
6418 Defaults to 2000 (2 seconds).
6420 ReportCommandStats false|true
6422 Enables or disables reporting of statistics based on the command
6423 type, including rate of command calls and average CPU time consumed
6424 by command processing. Defaults to false.
6425 ReportCpuUsage true|false
6427 Enables or disables reporting of CPU consumption statistics.
6428 Defaults to true.
6429 Query Querystring
6431 The Query block identifies a query to execute against the redis
6432 server. There may be an arbitrary number of queries to execute.
6433 Each query should return single string or integer.
6434 Type Collectd type
6436 Within a query definition, a valid collectd type to use as when
6437 submitting the result of the query. When not supplied, will default
6438 to gauge.
6439 Currently only types with one datasource are supported. See
6441 types.db(5) for more details on types and their configuration.
6442 Instance Type instance
6444 Within a query definition, an optional type instance to use when
6445 submitting the result of the query. When not supplied will default
6446 to the escaped command, up to 128 chars.
6447 Database Index
6449 This index selects the Redis logical database to use for query.
6450 Defaults to 0.
6451 Plugin "rrdcached"
6453 The "rrdcached" plugin uses the RRDtool accelerator daemon,
6454 rrdcached(1), to store values to RRD files in an efficient manner. The
6455 combination of the "rrdcached" plugin and the "rrdcached" daemon is
6456 very similar to the way the "rrdtool" plugin works (see below). The
6457 added abstraction layer provides a number of benefits, though: Because
6458 the cache is not within "collectd" anymore, it does not need to be
6459 flushed when "collectd" is to be restarted. This results in much
6460 shorter (if any) gaps in graphs, especially under heavy load. Also, the
6461 "rrdtool" command line utility is aware of the daemon so that it can
6462 flush values to disk automatically when needed. This allows one to
6463 integrate automated flushing of values into graphing solutions much
6464 more easily.
6465 There are disadvantages, though: The daemon may reside on a different
6467 host, so it may not be possible for "collectd" to create the
6468 appropriate RRD files anymore. And even if "rrdcached" runs on the same
6469 host, it may run in a different base directory, so relative paths may
6470 do weird stuff if you're not careful.
6471 So the recommended configuration is to let "collectd" and "rrdcached"
6473 run on the same host, communicating via a UNIX domain socket. The
6474 DataDir setting should be set to an absolute path, so that a changed
6475 base directory does not result in RRD files being created / expected in
6476 the wrong place.
6477 DaemonAddress Address
6479 Address of the daemon as understood by the "rrdc_connect" function
6480 of the RRD library. See rrdcached(1) for details. Example:
6481 <Plugin "rrdcached">
6483 DaemonAddress "unix:/var/run/rrdcached.sock"
6484 </Plugin>
6485 DataDir Directory
6487 Set the base directory in which the RRD files reside. If this is a
6488 relative path, it is relative to the working base directory of the
6489 "rrdcached" daemon! Use of an absolute path is recommended.
6490 CreateFiles true|false
6492 Enables or disables the creation of RRD files. If the daemon is not
6493 running locally, or DataDir is set to a relative path, this will
6494 not work as expected. Default is true.
6495 CreateFilesAsync false|true
6497 When enabled, new RRD files are enabled asynchronously, using a
6498 separate thread that runs in the background. This prevents writes
6499 to block, which is a problem especially when many hundreds of files
6500 need to be created at once. However, since the purpose of creating
6501 the files asynchronously is not to block until the file is
6502 available, values before the file is available will be discarded.
6503 When disabled (the default) files are created synchronously,
6504 blocking for a short while, while the file is being written.
6505 StepSize Seconds
6507 Force the stepsize of newly created RRD-files. Ideally (and per
6508 default) this setting is unset and the stepsize is set to the
6509 interval in which the data is collected. Do not use this option
6510 unless you absolutely have to for some reason. Setting this option
6511 may cause problems with the "snmp plugin", the "exec plugin" or
6512 when the daemon is set up to receive data from other hosts.
6513 HeartBeat Seconds
6515 Force the heartbeat of newly created RRD-files. This setting should
6516 be unset in which case the heartbeat is set to twice the StepSize
6517 which should equal the interval in which data is collected. Do not
6518 set this option unless you have a very good reason to do so.
6519 RRARows NumRows
6521 The "rrdtool plugin" calculates the number of PDPs per CDP based on
6522 the StepSize, this setting and a timespan. This plugin creates RRD-
6523 files with three times five RRAs, i. e. five RRAs with the CFs MIN,
6524 AVERAGE, and MAX. The five RRAs are optimized for graphs covering
6525 one hour, one day, one week, one month, and one year.
6526 So for each timespan, it calculates how many PDPs need to be
6528 consolidated into one CDP by calculating:
6529 number of PDPs = timespan / (stepsize * rrarows)
6530 Bottom line is, set this no smaller than the width of you graphs in
6532 pixels. The default is 1200.
6533 RRATimespan Seconds
6535 Adds an RRA-timespan, given in seconds. Use this option multiple
6536 times to have more then one RRA. If this option is never used, the
6537 built-in default of (3600, 86400, 604800, 2678400, 31622400) is
6538 used.
6539 For more information on how RRA-sizes are calculated see RRARows
6541 above.
6542 XFF Factor
6544 Set the "XFiles Factor". The default is 0.1. If unsure, don't set
6545 this option. Factor must be in the range "[0.0-1.0)", i.e. between
6546 zero (inclusive) and one (exclusive).
6547 CollectStatistics false|true
6549 When set to true, various statistics about the rrdcached daemon
6550 will be collected, with "rrdcached" as the plugin name. Defaults to
6551 false.
6552 Statistics are read via rrdcacheds socket using the STATS command.
6554 See rrdcached(1) for details.
6555 Plugin "rrdtool"
6557 You can use the settings StepSize, HeartBeat, RRARows, and XFF to fine-
6558 tune your RRD-files. Please read rrdcreate(1) if you encounter problems
6559 using these settings. If you don't want to dive into the depths of
6560 RRDtool, you can safely ignore these settings.
6561 DataDir Directory
6563 Set the directory to store RRD files under. By default RRD files
6564 are generated beneath the daemon's working directory, i.e. the
6565 BaseDir.
6566 CreateFilesAsync false|true
6568 When enabled, new RRD files are enabled asynchronously, using a
6569 separate thread that runs in the background. This prevents writes
6570 to block, which is a problem especially when many hundreds of files
6571 need to be created at once. However, since the purpose of creating
6572 the files asynchronously is not to block until the file is
6573 available, values before the file is available will be discarded.
6574 When disabled (the default) files are created synchronously,
6575 blocking for a short while, while the file is being written.
6576 StepSize Seconds
6578 Force the stepsize of newly created RRD-files. Ideally (and per
6579 default) this setting is unset and the stepsize is set to the
6580 interval in which the data is collected. Do not use this option
6581 unless you absolutely have to for some reason. Setting this option
6582 may cause problems with the "snmp plugin", the "exec plugin" or
6583 when the daemon is set up to receive data from other hosts.
6584 HeartBeat Seconds
6586 Force the heartbeat of newly created RRD-files. This setting should
6587 be unset in which case the heartbeat is set to twice the StepSize
6588 which should equal the interval in which data is collected. Do not
6589 set this option unless you have a very good reason to do so.
6590 RRARows NumRows
6592 The "rrdtool plugin" calculates the number of PDPs per CDP based on
6593 the StepSize, this setting and a timespan. This plugin creates RRD-
6594 files with three times five RRAs, i.e. five RRAs with the CFs MIN,
6595 AVERAGE, and MAX. The five RRAs are optimized for graphs covering
6596 one hour, one day, one week, one month, and one year.
6597 So for each timespan, it calculates how many PDPs need to be
6599 consolidated into one CDP by calculating:
6600 number of PDPs = timespan / (stepsize * rrarows)
6601 Bottom line is, set this no smaller than the width of you graphs in
6603 pixels. The default is 1200.
6604 RRATimespan Seconds
6606 Adds an RRA-timespan, given in seconds. Use this option multiple
6607 times to have more then one RRA. If this option is never used, the
6608 built-in default of (3600, 86400, 604800, 2678400, 31622400) is
6609 used.
6610 For more information on how RRA-sizes are calculated see RRARows
6612 above.
6613 XFF Factor
6615 Set the "XFiles Factor". The default is 0.1. If unsure, don't set
6616 this option. Factor must be in the range "[0.0-1.0)", i.e. between
6617 zero (inclusive) and one (exclusive).
6618 CacheFlush Seconds
6620 When the "rrdtool" plugin uses a cache (by setting CacheTimeout,
6621 see below) it writes all values for a certain RRD-file if the
6622 oldest value is older than (or equal to) the number of seconds
6623 specified by CacheTimeout. That check happens on new values
6624 arriwal. If some RRD-file is not updated anymore for some reason
6625 (the computer was shut down, the network is broken, etc.) some
6626 values may still be in the cache. If CacheFlush is set, then every
6627 Seconds seconds the entire cache is searched for entries older than
6628 CacheTimeout + RandomTimeout seconds. The entries found are written
6629 to disk. Since scanning the entire cache is kind of expensive and
6630 does nothing under normal circumstances, this value should not be
6631 too small. 900 seconds might be a good value, though setting this
6632 to 7200 seconds doesn't normally do much harm either.
6633 Defaults to 10x CacheTimeout. CacheFlush must be larger than or
6635 equal to CacheTimeout, otherwise the above default is used.
6636 CacheTimeout Seconds
6638 If this option is set to a value greater than zero, the "rrdtool
6639 plugin" will save values in a cache, as described above. Writing
6640 multiple values at once reduces IO-operations and thus lessens the
6641 load produced by updating the files. The trade off is that the
6642 graphs kind of "drag behind" and that more memory is used.
6643 WritesPerSecond Updates
6645 When collecting many statistics with collectd and the "rrdtool"
6646 plugin, you will run serious performance problems. The CacheFlush
6647 setting and the internal update queue assert that collectd
6648 continues to work just fine even under heavy load, but the system
6649 may become very unresponsive and slow. This is a problem especially
6650 if you create graphs from the RRD files on the same machine, for
6651 example using the "graph.cgi" script included in the
6652 "contrib/collection3/" directory.
6653 This setting is designed for very large setups. Setting this option
6655 to a value between 25 and 80 updates per second, depending on your
6656 hardware, will leave the server responsive enough to draw graphs
6657 even while all the cached values are written to disk. Flushed
6658 values, i. e. values that are forced to disk by the FLUSH command,
6659 are not effected by this limit. They are still written as fast as
6660 possible, so that web frontends have up to date data when
6661 generating graphs.
6662 For example: If you have 100,000 RRD files and set WritesPerSecond
6664 to 30 updates per second, writing all values to disk will take
6665 approximately 56 minutes. Together with the flushing ability that's
6666 integrated into "collection3" you'll end up with a responsive and
6667 fast system, up to date graphs and basically a "backup" of your
6668 values every hour.
6669 RandomTimeout Seconds
6671 When set, the actual timeout for each value is chosen randomly
6672 between CacheTimeout-RandomTimeout and CacheTimeout+RandomTimeout.
6673 The intention is to avoid high load situations that appear when
6674 many values timeout at the same time. This is especially a problem
6675 shortly after the daemon starts, because all values were added to
6676 the internal cache at roughly the same time.
6677 Plugin "sensors"
6679 The Sensors plugin uses lm_sensors to retrieve sensor-values. This
6680 means that all the needed modules have to be loaded and lm_sensors has
6681 to be configured (most likely by editing /etc/sensors.conf. Read
6682 sensors.conf(5) for details.
6683 The lm_sensors homepage can be found at
6685 <http://secure.netroedge.com/~lm78/>.
6686 SensorConfigFile File
6688 Read the lm_sensors configuration from File. When unset
6689 (recommended), the library's default will be used.
6690 Sensor chip-bus-address/type-feature
6692 Selects the name of the sensor which you want to collect or ignore,
6693 depending on the IgnoreSelected below. For example, the option
6694 "Sensor it8712-isa-0290/voltage-in1" will cause collectd to gather
6695 data for the voltage sensor in1 of the it8712 on the isa bus at the
6696 address 0290.
6697 See /"IGNORELISTS" for details.
6699 IgnoreSelected true|false
6701 If no configuration if given, the sensors-plugin will collect data
6702 from all sensors. This may not be practical, especially for
6703 uninteresting sensors. Thus, you can use the Sensor-option to pick
6704 the sensors you're interested in. Sometimes, however, it's
6705 easier/preferred to collect all sensors except a few ones. This
6706 option enables you to do that: By setting IgnoreSelected to true
6707 the effect of Sensor is inverted: All selected sensors are ignored
6708 and all other sensors are collected.
6709 UseLabels true|false
6711 Configures how sensor readings are reported. When set to true,
6712 sensor readings are reported using their descriptive label (e.g.
6713 "VCore"). When set to false (the default) the sensor name is used
6714 ("in0").
6715 Plugin "sigrok"
6717 The sigrok plugin uses libsigrok to retrieve measurements from any
6718 device supported by the sigrok <http://sigrok.org/> project.
6719 Synopsis
6721 <Plugin sigrok>
6723 LogLevel 3
6724 <Device "AC Voltage">
6725 Driver "fluke-dmm"
6726 MinimumInterval 10
6727 Conn "/dev/ttyUSB2"
6728 </Device>
6729 <Device "Sound Level">
6730 Driver "cem-dt-885x"
6731 Conn "/dev/ttyUSB1"
6732 </Device>
6733 </Plugin>
6734 LogLevel 0-5
6736 The sigrok logging level to pass on to the collectd log, as a
6737 number between 0 and 5 (inclusive). These levels correspond to
6738 "None", "Errors", "Warnings", "Informational", "Debug "and "Spew",
6739 respectively. The default is 2 ("Warnings"). The sigrok log
6740 messages, regardless of their level, are always submitted to
6741 collectd at its INFO log level.
6742 <Device Name>
6744 A sigrok-supported device, uniquely identified by this section's
6745 options. The Name is passed to collectd as the plugin instance.
6746 Driver DriverName
6748 The sigrok driver to use for this device.
6749 Conn ConnectionSpec
6751 If the device cannot be auto-discovered, or more than one might be
6752 discovered by the driver, ConnectionSpec specifies the connection
6753 string to the device. It can be of the form of a device path
6754 (e.g. "/dev/ttyUSB2"), or, in case of a non-serial USB-connected
6755 device, the USB VendorID.ProductID separated by a period
6756 (e.g. 0403.6001). A USB device can also be specified as Bus.Address
6757 (e.g. 1.41).
6758 SerialComm SerialSpec
6760 For serial devices with non-standard port settings, this option can
6761 be used to specify them in a form understood by sigrok,
6762 e.g. "9600/8n1". This should not be necessary; drivers know how to
6763 communicate with devices they support.
6764 MinimumInterval Seconds
6766 Specifies the minimum time between measurement dispatches to
6767 collectd, in seconds. Since some sigrok supported devices can
6768 acquire measurements many times per second, it may be necessary to
6769 throttle these. For example, the RRD plugin cannot process writes
6770 more than once per second.
6771 The default MinimumInterval is 0, meaning measurements received
6773 from the device are always dispatched to collectd. When throttled,
6774 unused measurements are discarded.
6775 Plugin "smart"
6777 The "smart" plugin collects SMART information from physical disks.
6778 Values collectd include temperature, power cycle count, poweron time
6779 and bad sectors. Also, all SMART attributes are collected along with
6780 the normalized current value, the worst value, the threshold and a
6781 human readable value.
6782 Using the following two options you can ignore some disks or configure
6784 the collection only of specific disks.
6785 Disk Name
6787 Select the disk Name. Whether it is collected or ignored depends on
6788 the IgnoreSelected setting, see below. As with other plugins that
6789 use the daemon's ignorelist functionality, a string that starts and
6790 ends with a slash is interpreted as a regular expression. Examples:
6791 Disk "sdd"
6793 Disk "/hda[34]/"
6794 See /"IGNORELISTS" for details.
6796 IgnoreSelected true|false
6798 Sets whether selected disks, i. e. the ones matches by any of the
6799 Disk statements, are ignored or if all other disks are ignored. The
6800 behavior (hopefully) is intuitive: If no Disk option is configured,
6801 all disks are collected. If at least one Disk option is given and
6802 no IgnoreSelected or set to false, only matching disks will be
6803 collected. If IgnoreSelected is set to true, all disks are
6804 collected except the ones matched.
6805 IgnoreSleepMode true|false
6807 Normally, the "smart" plugin will ignore disks that are reported to
6808 be asleep. This option disables the sleep mode check and allows
6809 the plugin to collect data from these disks anyway. This is useful
6810 in cases where libatasmart mistakenly reports disks as asleep
6811 because it has not been updated to incorporate support for newer
6812 idle states in the ATA spec.
6813 UseSerial true|false
6815 A disk's kernel name (e.g., sda) can change from one boot to the
6816 next. If this option is enabled, the "smart" plugin will use the
6817 disk's serial number (e.g., HGST_HUH728080ALE600_2EJ8VH8X) instead
6818 of the kernel name as the key for storing data. This ensures that
6819 the data for a given disk will be kept together even if the kernel
6820 name changes.
6821 Plugin "snmp"
6823 Since the configuration of the "snmp plugin" is a little more
6824 complicated than other plugins, its documentation has been moved to an
6825 own manpage, collectd-snmp(5). Please see there for details.
6826 Plugin "snmp_agent"
6828 The snmp_agent plugin is an AgentX subagent that receives and handles
6829 queries from SNMP master agent and returns the data collected by read
6830 plugins. The snmp_agent plugin handles requests only for OIDs
6831 specified in configuration file. To handle SNMP queries the plugin gets
6832 data from collectd and translates requested values from collectd's
6833 internal format to SNMP format. This plugin is a generic plugin and
6834 cannot work without configuration. For more details on AgentX subagent
6835 see <http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/>
6836 Synopsis:
6838 <Plugin snmp_agent>
6840 <Data "memAvailReal">
6841 Plugin "memory"
6842 #PluginInstance "some"
6843 Type "memory"
6844 TypeInstance "free"
6845 OIDs "1.3.6.1.4.1.2021.4.6.0"
6846 </Data>
6847 <Table "ifTable">
6848 IndexOID "IF-MIB::ifIndex"
6849 SizeOID "IF-MIB::ifNumber"
6850 <Data "ifDescr">
6851 <IndexKey>
6852 Source "PluginInstance"
6853 </IndexKey>
6854 Plugin "interface"
6855 OIDs "IF-MIB::ifDescr"
6856 </Data>
6857 <Data "ifOctets">
6858 Plugin "interface"
6859 Type "if_octets"
6860 TypeInstance ""
6861 OIDs "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
6862 </Data>
6863 </Table>
6864 <Table "CPUAffinityTable">
6865 <Data "DomainName">
6866 <IndexKey>
6867 Source "PluginInstance"
6868 </IndexKey>
6869 Plugin "virt"
6870 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhAffinityDomainName"
6871 </Data>
6872 <Data "VCPU">
6873 Plugin "virt"
6874 <IndexKey>
6875 Source "TypeInstance"
6876 Regex "^vcpu_([0-9]{1,3})-cpu_[0-9]{1,3}$"
6877 Group 1
6878 </IndexKey>
6879 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhVCPUIndex"
6880 </Data>
6881 <Data "CPU">
6882 Plugin "virt"
6883 <IndexKey>
6884 Source "TypeInstance"
6885 Regex "^vcpu_[0-9]{1,3}-cpu_([0-9]{1,3})$"
6886 Group 1
6887 </IndexKey>
6888 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhCPUIndex"
6889 </Data>
6890 <Data "CPUAffinity">
6891 Plugin "virt"
6892 Type "cpu_affinity"
6893 OIDs "LIBVIRT-HYPERVISOR-MIB::lvhCPUAffinity"
6894 </Data>
6895 </Table>
6896 </Plugin>
6897 There are two types of blocks that can be contained in the "<Plugin
6899 snmp_agent>" block: Data and Table:
6900 Data block
6902 The Data block defines a list OIDs that are to be handled. This block
6904 can define scalar or table OIDs. If Data block is defined inside of
6905 Table block it reperesents table OIDs. The following options can be
6906 set:
6907 IndexKey block
6909 IndexKey block contains all data needed for proper index build of
6910 snmp table. In case more than one table Data block has IndexKey
6911 block present then multiple key index is built. If Data block
6912 defines scalar data type IndexKey has no effect and can be omitted.
6913 Source String
6915 Source can be set to one of the following values:
6916 "Hostname", "Plugin", "PluginInstance", "Type",
6917 "TypeInstance". This value indicates which field of
6918 corresponding collectd metric is taken as a SNMP table
6919 index.
6920 Regex String
6922 Regex option can also be used to parse strings or numbers
6923 out of specific field. For example: type-instance field
6924 which is "vcpu1-cpu2" can be parsed into two numeric fields
6925 CPU = 2 and VCPU = 1 and can be later used as a table
6926 index.
6927 Group Number
6929 Group number can be specified in case groups are used in
6930 regex.
6931 Plugin String
6933 Read plugin name whose collected data will be mapped to specified
6934 OIDs.
6935 PluginInstance String
6937 Read plugin instance whose collected data will be mapped to
6938 specified OIDs. The field is optional and by default there is no
6939 plugin instance check. Allowed only if Data block defines scalar
6940 data type.
6941 Type String
6943 Collectd's type that is to be used for specified OID, e. g.
6944 "if_octets" for example. The types are read from the TypesDB (see
6945 collectd.conf(5)).
6946 TypeInstance String
6948 Collectd's type-instance that is to be used for specified OID.
6949 OIDs OID [OID ...]
6951 Configures the OIDs to be handled by snmp_agent plugin. Values for
6952 these OIDs are taken from collectd data type specified by Plugin,
6953 PluginInstance, Type, TypeInstance fields of this Data block.
6954 Number of the OIDs configured should correspond to number of values
6955 in specified Type. For example two OIDs "IF-MIB::ifInOctets"
6956 "IF-MIB::ifOutOctets" can be mapped to "rx" and "tx" values of
6957 "if_octets" type.
6958 Scale Value
6960 The values taken from collectd are multiplied by Value. The field
6961 is optional and the default is 1.0.
6962 Shift Value
6964 Value is added to values from collectd after they have been
6965 multiplied by Scale value. The field is optional and the default
6966 value is 0.0.
6967 The Table block
6969 The Table block defines a collection of Data blocks that belong to one
6971 snmp table. In addition to multiple Data blocks the following options
6972 can be set:
6973 IndexOID OID
6975 OID that is handled by the plugin and is mapped to numerical index
6976 value that is generated by the plugin for each table record.
6977 SizeOID OID
6979 OID that is handled by the plugin. Returned value is the number of
6980 records in the table. The field is optional.
6981 Plugin "statsd"
6983 The statsd plugin listens to a UDP socket, reads "events" in the statsd
6984 protocol and dispatches rates or other aggregates of these numbers
6985 periodically.
6986 The plugin implements the Counter, Timer, Gauge and Set types which are
6988 dispatched as the collectd types "derive", "latency", "gauge" and
6989 "objects" respectively.
6990 The following configuration options are valid:
6992 Host Host
6994 Bind to the hostname / address Host. By default, the plugin will
6995 bind to the "any" address, i.e. accept packets sent to any of the
6996 hosts addresses.
6997 Port Port
6999 UDP port to listen to. This can be either a service name or a port
7000 number. Defaults to 8125.
7001 DeleteCounters false|true
7003 DeleteTimers false|true
7004 DeleteGauges false|true
7005 DeleteSets false|true
7006 These options control what happens if metrics are not updated in an
7007 interval. If set to False, the default, metrics are dispatched
7008 unchanged, i.e. the rate of counters and size of sets will be zero,
7009 timers report "NaN" and gauges are unchanged. If set to True, the
7010 such metrics are not dispatched and removed from the internal
7011 cache.
7012 CounterSum false|true
7014 When enabled, creates a "count" metric which reports the change
7015 since the last read. This option primarily exists for compatibility
7016 with the statsd implementation by Etsy.
7017 TimerPercentile Percent
7019 Calculate and dispatch the configured percentile, i.e. compute the
7020 latency, so that Percent of all reported timers are smaller than or
7021 equal to the computed latency. This is useful for cutting off the
7022 long tail latency, as it's often done in Service Level Agreements
7023 (SLAs).
7024 Different percentiles can be calculated by setting this option
7026 several times. If none are specified, no percentiles are
7027 calculated / dispatched.
7028 TimerLower false|true
7030 TimerUpper false|true
7031 TimerSum false|true
7032 TimerCount false|true
7033 Calculate and dispatch various values out of Timer metrics received
7034 during an interval. If set to False, the default, these values
7035 aren't calculated / dispatched.
7036 Please note what reported timer values less than 0.001 are ignored
7038 in all Timer* reports.
7039 Plugin "swap"
7041 The Swap plugin collects information about used and available swap
7042 space. On Linux and Solaris, the following options are available:
7043 ReportByDevice false|true
7045 Configures how to report physical swap devices. If set to false
7046 (the default), the summary over all swap devices is reported only,
7047 i.e. the globally used and available space over all devices. If
7048 true is configured, the used and available space of each device
7049 will be reported separately.
7050 This option is only available if the Swap plugin can read
7052 "/proc/swaps" (under Linux) or use the swapctl(2) mechanism (under
7053 Solaris).
7054 ReportBytes false|true
7056 When enabled, the swap I/O is reported in bytes. When disabled, the
7057 default, swap I/O is reported in pages. This option is available
7058 under Linux only.
7059 ValuesAbsolute true|false
7061 Enables or disables reporting of absolute swap metrics, i.e. number
7062 of bytes available and used. Defaults to true.
7063 ValuesPercentage false|true
7065 Enables or disables reporting of relative swap metrics, i.e.
7066 percent available and free. Defaults to false.
7067 This is useful for deploying collectd in a heterogeneous
7069 environment, where swap sizes differ and you want to specify
7070 generic thresholds or similar.
7071 ReportIO true|false
7073 Enables or disables reporting swap IO. Defaults to true.
7074 This is useful for the cases when swap IO is not neccessary, is not
7076 available, or is not reliable.
7077 Plugin "syslog"
7079 LogLevel debug|info|notice|warning|err
7080 Sets the log-level. If, for example, set to notice, then all events
7081 with severity notice, warning, or err will be submitted to the
7082 syslog-daemon.
7083 Please note that debug is only available if collectd has been
7085 compiled with debugging support.
7086 NotifyLevel OKAY|WARNING|FAILURE
7088 Controls which notifications should be sent to syslog. The default
7089 behaviour is not to send any. Less severe notifications always
7090 imply logging more severe notifications: Setting this to OKAY means
7091 all notifications will be sent to syslog, setting this to WARNING
7092 will send WARNING and FAILURE notifications but will dismiss OKAY
7093 notifications. Setting this option to FAILURE will only send
7094 failures to syslog.
7095 Plugin "table"
7097 The "table plugin" provides generic means to parse tabular data and
7098 dispatch user specified values. Values are selected based on column
7099 numbers. For example, this plugin may be used to get values from the
7100 Linux proc(5) filesystem or CSV (comma separated values) files.
7101 <Plugin table>
7103 <Table "/proc/slabinfo">
7104 #Plugin "slab"
7105 Instance "slabinfo"
7106 Separator " "
7107 <Result>
7108 Type gauge
7109 InstancePrefix "active_objs"
7110 InstancesFrom 0
7111 ValuesFrom 1
7112 </Result>
7113 <Result>
7114 Type gauge
7115 InstancePrefix "objperslab"
7116 InstancesFrom 0
7117 ValuesFrom 4
7118 </Result>
7119 </Table>
7120 </Plugin>
7121 The configuration consists of one or more Table blocks, each of which
7123 configures one file to parse. Within each Table block, there are one or
7124 more Result blocks, which configure which data to select and how to
7125 interpret it.
7126 The following options are available inside a Table block:
7128 Plugin Plugin
7130 If specified, Plugin is used as the plugin name when submitting
7131 values. Defaults to table.
7132 Instance instance
7134 If specified, instance is used as the plugin instance. If omitted,
7135 the filename of the table is used instead, with all special
7136 characters replaced with an underscore ("_").
7137 Separator string
7139 Any character of string is interpreted as a delimiter between the
7140 different columns of the table. A sequence of two or more
7141 contiguous delimiters in the table is considered to be a single
7142 delimiter, i. e. there cannot be any empty columns. The plugin uses
7143 the strtok_r(3) function to parse the lines of a table - see its
7144 documentation for more details. This option is mandatory.
7145 A horizontal tab, newline and carriage return may be specified by
7147 "\\t", "\\n" and "\\r" respectively. Please note that the double
7148 backslashes are required because of collectd's config parsing.
7149 The following options are available inside a Result block:
7151 Type type
7153 Sets the type used to dispatch the values to the daemon. Detailed
7154 information about types and their configuration can be found in
7155 types.db(5). This option is mandatory.
7156 InstancePrefix prefix
7158 If specified, prepend prefix to the type instance. If omitted, only
7159 the InstancesFrom option is considered for the type instance.
7160 InstancesFrom column0 [column1 ...]
7162 If specified, the content of the given columns (identified by the
7163 column number starting at zero) will be used to create the type
7164 instance for each row. Multiple values (and the instance prefix)
7165 will be joined together with dashes (-) as separation character. If
7166 omitted, only the InstancePrefix option is considered for the type
7167 instance.
7168 The plugin itself does not check whether or not all built instances
7170 are different. ItXs your responsibility to assure that each is
7171 unique. This is especially true, if you do not specify
7172 InstancesFrom: You have to make sure that the table only contains
7173 one row.
7174 If neither InstancePrefix nor InstancesFrom is given, the type
7176 instance will be empty.
7177 ValuesFrom column0 [column1 ...]
7179 Specifies the columns (identified by the column numbers starting at
7180 zero) whose content is used as the actual data for the data sets
7181 that are dispatched to the daemon. How many such columns you need
7182 is determined by the Type setting above. If you specify too many or
7183 not enough columns, the plugin will complain about that and no data
7184 will be submitted to the daemon. The plugin uses strtoll(3) and
7185 strtod(3) to parse counter and gauge values respectively, so
7186 anything supported by those functions is supported by the plugin as
7187 well. This option is mandatory.
7188 Plugin "tail"
7190 The "tail plugin" follows logfiles, just like tail(1) does, parses each
7191 line and dispatches found values. What is matched can be configured by
7192 the user using (extended) regular expressions, as described in
7193 regex(7).
7194 <Plugin "tail">
7196 <File "/var/log/exim4/mainlog">
7197 Plugin "mail"
7198 Instance "exim"
7199 Interval 60
7200 <Match>
7201 Regex "S=([1-9][0-9]*)"
7202 DSType "CounterAdd"
7203 Type "ipt_bytes"
7204 Instance "total"
7205 </Match>
7206 <Match>
7207 Regex "\\<R=local_user\\>"
7208 ExcludeRegex "\\<R=local_user\\>.*mail_spool defer"
7209 DSType "CounterInc"
7210 Type "counter"
7211 Instance "local_user"
7212 </Match>
7213 <Match>
7214 Regex "l=([0-9]*\\.[0-9]*)"
7215 <DSType "Distribution">
7216 Percentile 99
7217 Bucket 0 100
7218 #BucketType "bucket"
7219 </DSType>
7220 Type "latency"
7221 Instance "foo"
7222 </Match>
7223 </File>
7224 </Plugin>
7225 The config consists of one or more File blocks, each of which
7227 configures one logfile to parse. Within each File block, there are one
7228 or more Match blocks, which configure a regular expression to search
7229 for.
7230 The Plugin and Instance options in the File block may be used to set
7232 the plugin name and instance respectively. So in the above example the
7233 plugin name "mail-exim" would be used.
7234 These options are applied for all Match blocks that follow it, until
7236 the next Plugin or Instance option. This way you can extract several
7237 plugin instances from one logfile, handy when parsing syslog and the
7238 like.
7239 The Interval option allows you to define the length of time between
7241 reads. If this is not set, the default Interval will be used.
7242 Each Match block has the following options to describe how the match
7244 should be performed:
7245 Regex regex
7247 Sets the regular expression to use for matching against a line. The
7248 first subexpression has to match something that can be turned into
7249 a number by strtoll(3) or strtod(3), depending on the value of
7250 "CounterAdd", see below. Because extended regular expressions are
7251 used, you do not need to use backslashes for subexpressions! If in
7252 doubt, please consult regex(7). Due to collectd's config parsing
7253 you need to escape backslashes, though. So if you want to match
7254 literal parentheses you need to do the following:
7255 Regex "SPAM \\(Score: (-?[0-9]+\\.[0-9]+)\\)"
7257 ExcludeRegex regex
7259 Sets an optional regular expression to use for excluding lines from
7260 the match. An example which excludes all connections from
7261 localhost from the match:
7262 ExcludeRegex "127\\.0\\.0\\.1"
7264 DSType Type
7266 Sets how the values are cumulated. Type is one of:
7267 GaugeAverage
7269 Calculate the average of all values matched during the
7270 interval.
7271 GaugeMin
7273 Report the smallest value matched during the interval.
7274 GaugeMax
7276 Report the greatest value matched during the interval.
7277 GaugeLast
7279 Report the last value matched during the interval.
7280 GaugePersist
7282 Report the last matching value. The metric is not reset to
7283 "NaN" at the end of an interval. It is continuously reported
7284 until another value is matched. This is intended for cases in
7285 which only state changes are reported, for example a
7286 thermometer that only reports the temperature when it changes.
7287 CounterSet
7289 DeriveSet
7290 AbsoluteSet
7291 The matched number is a counter. Simply sets the internal
7292 counter to this value. Variants exist for "COUNTER", "DERIVE",
7293 and "ABSOLUTE" data sources.
7294 GaugeAdd
7296 CounterAdd
7297 DeriveAdd
7298 Add the matched value to the internal counter. In case of
7299 DeriveAdd, the matched number may be negative, which will
7300 effectively subtract from the internal counter.
7301 GaugeInc
7303 CounterInc
7304 DeriveInc
7305 Increase the internal counter by one. These DSType are the only
7306 ones that do not use the matched subexpression, but simply
7307 count the number of matched lines. Thus, you may use a regular
7308 expression without submatch in this case.
7309 GaugeInc is reset to zero after every read, unlike other Gauge*
7311 metrics which are reset to "NaN".
7312 Distribution
7314 Type to do calculations based on the distribution of values,
7315 primarily calculating percentiles. This is primarily geared
7316 towards latency, but can be used for other metrics as well. The
7317 range of values tracked with this setting must be in the range
7318 (0X2^34) and can be fractional. Please note that neither zero
7319 nor 2^34 are inclusive bounds, i.e. zero cannot be handled by a
7320 distribution.
7321 This option must be used together with the Percentile and/or
7323 Bucket options.
7324 Synopsis:
7326 <DSType "Distribution">
7328 Percentile 99
7329 Bucket 0 100
7330 BucketType "bucket"
7331 </DSType>
7332 Percentile Percent
7334 Calculate and dispatch the configured percentile, i.e.
7335 compute the value, so that Percent of all matched values
7336 are smaller than or equal to the computed latency.
7337 Metrics are reported with the type Type (the value of the
7339 above option) and the type instance
7340 "[<Instance>-]<Percent>".
7341 This option may be repeated to calculate more than one
7343 percentile.
7344 Bucket lower_bound upper_bound
7346 Export the number of values (a "DERIVE") falling within the
7347 given range. Both, lower_bound and upper_bound may be a
7348 fractional number, such as 0.5. Each Bucket option
7349 specifies an interval "(lower_bound, upper_bound]", i.e.
7350 the range excludes the lower bound and includes the upper
7351 bound. lower_bound and upper_bound may be zero, meaning no
7352 lower/upper bound.
7353 To export the entire (0Xinf) range without overlap, use the
7355 upper bound of the previous range as the lower bound of the
7356 following range. In other words, use the following schema:
7357 Bucket 0 1
7359 Bucket 1 2
7360 Bucket 2 5
7361 Bucket 5 10
7362 Bucket 10 20
7363 Bucket 20 50
7364 Bucket 50 0
7365 Metrics are reported with the type set by BucketType option
7367 ("bucket" by default) and the type instance
7368 "<Type>[-<Instance>]-<lower_bound>_<upper_bound>".
7369 This option may be repeated to calculate more than one
7371 rate.
7372 BucketType Type
7374 Sets the type used to dispatch Bucket metrics. Optional,
7375 by default "bucket" will be used.
7376 The Gauge* and Distribution types interpret the submatch as a
7378 floating point number, using strtod(3). The Counter* and
7379 AbsoluteSet types interpret the submatch as an unsigned integer
7380 using strtoull(3). The Derive* types interpret the submatch as a
7381 signed integer using strtoll(3). CounterInc, DeriveInc and GaugeInc
7382 do not use the submatch at all and it may be omitted in this case.
7383 The Gauge* types, unless noted otherwise, are reset to "NaN" after
7385 being reported. In other words, GaugeAverage reports the average of
7386 all values matched since the last metric was reported (or "NaN" if
7387 there was no match).
7388 Type Type
7390 Sets the type used to dispatch this value. Detailed information
7391 about types and their configuration can be found in types.db(5).
7392 Instance TypeInstance
7394 This optional setting sets the type instance to use.
7395 Plugin "tail_csv"
7397 The tail_csv plugin reads files in the CSV format, e.g. the statistics
7398 file written by Snort.
7399 Synopsis:
7401 <Plugin "tail_csv">
7403 <Metric "snort-dropped">
7404 Type "percent"
7405 Instance "dropped"
7406 ValueFrom 1
7407 </Metric>
7408 <File "/var/log/snort/snort.stats">
7409 Plugin "snortstats"
7410 Instance "eth0"
7411 Interval 600
7412 Collect "snort-dropped"
7413 #TimeFrom 0
7414 </File>
7415 </Plugin>
7416 The configuration consists of one or more Metric blocks that define an
7418 index into the line of the CSV file and how this value is mapped to
7419 collectd's internal representation. These are followed by one or more
7420 Instance blocks which configure which file to read, in which interval
7421 and which metrics to extract.
7422 <Metric Name>
7424 The Metric block configures a new metric to be extracted from the
7425 statistics file and how it is mapped on collectd's data model. The
7426 string Name is only used inside the Instance blocks to refer to
7427 this block, so you can use one Metric block for multiple CSV files.
7428 Type Type
7430 Configures which Type to use when dispatching this metric.
7431 Types are defined in the types.db(5) file, see the appropriate
7432 manual page for more information on specifying types. Only
7433 types with a single data source are supported by the tail_csv
7434 plugin. The information whether the value is an absolute value
7435 (i.e. a "GAUGE") or a rate (i.e. a "DERIVE") is taken from the
7436 Type's definition.
7437 Instance TypeInstance
7439 If set, TypeInstance is used to populate the type instance
7440 field of the created value lists. Otherwise, no type instance
7441 is used.
7442 ValueFrom Index
7444 Configure to read the value from the field with the zero-based
7445 index Index. If the value is parsed as signed integer,
7446 unsigned integer or double depends on the Type setting, see
7447 above.
7448 <File Path>
7450 Each File block represents one CSV file to read. There must be at
7451 least one File block but there can be multiple if you have multiple
7452 CSV files.
7453 Plugin Plugin
7455 Use Plugin as the plugin name when submitting values. Defaults
7456 to "tail_csv".
7457 Instance PluginInstance
7459 Sets the plugin instance used when dispatching the values.
7460 Collect Metric
7462 Specifies which Metric to collect. This option must be
7463 specified at least once, and you can use this option multiple
7464 times to specify more than one metric to be extracted from this
7465 statistic file.
7466 Interval Seconds
7468 Configures the interval in which to read values from this
7469 instance / file. Defaults to the plugin's default interval.
7470 TimeFrom Index
7472 Rather than using the local time when dispatching a value, read
7473 the timestamp from the field with the zero-based index Index.
7474 The value is interpreted as seconds since epoch. The value is
7475 parsed as a double and may be factional.
7476 Plugin "teamspeak2"
7478 The "teamspeak2 plugin" connects to the query port of a teamspeak2
7479 server and polls interesting global and virtual server data. The plugin
7480 can query only one physical server but unlimited virtual servers. You
7481 can use the following options to configure it:
7482 Host hostname/ip
7484 The hostname or ip which identifies the physical server. Default:
7485 127.0.0.1
7486 Port port
7488 The query port of the physical server. This needs to be a string.
7489 Default: "51234"
7490 Server port
7492 This option has to be added once for every virtual server the
7493 plugin should query. If you want to query the virtual server on
7494 port 8767 this is what the option would look like:
7495 Server "8767"
7497 This option, although numeric, needs to be a string, i. e. you must
7499 use quotes around it! If no such statement is given only global
7500 information will be collected.
7501 Plugin "ted"
7503 The TED plugin connects to a device of "The Energy Detective", a device
7504 to measure power consumption. These devices are usually connected to a
7505 serial (RS232) or USB port. The plugin opens a configured device and
7506 tries to read the current energy readings. For more information on TED,
7507 visit <http://www.theenergydetective.com/>.
7508 Available configuration options:
7510 Device Path
7512 Path to the device on which TED is connected. collectd will need
7513 read and write permissions on that file.
7514 Default: /dev/ttyUSB0
7516 Retries Num
7518 Apparently reading from TED is not that reliable. You can therefore
7519 configure a number of retries here. You only configure the retries
7520 here, to if you specify zero, one reading will be performed (but no
7521 retries if that fails); if you specify three, a maximum of four
7522 readings are performed. Negative values are illegal.
7523 Default: 0
7525 Plugin "tcpconns"
7527 The "tcpconns plugin" counts the number of currently established TCP
7528 connections based on the local port and/or the remote port. Since there
7529 may be a lot of connections the default if to count all connections
7530 with a local port, for which a listening socket is opened. You can use
7531 the following options to fine-tune the ports you are interested in:
7532 ListeningPorts true|false
7534 If this option is set to true, statistics for all local ports for
7535 which a listening socket exists are collected. The default depends
7536 on LocalPort and RemotePort (see below): If no port at all is
7537 specifically selected, the default is to collect listening ports.
7538 If specific ports (no matter if local or remote ports) are
7539 selected, this option defaults to false, i. e. only the selected
7540 ports will be collected unless this option is set to true
7541 specifically.
7542 LocalPort Port
7544 Count the connections to a specific local port. This can be used to
7545 see how many connections are handled by a specific daemon, e. g.
7546 the mailserver. You have to specify the port in numeric form, so
7547 for the mailserver example you'd need to set 25.
7548 RemotePort Port
7550 Count the connections to a specific remote port. This is useful to
7551 see how much a remote service is used. This is most useful if you
7552 want to know how many connections a local service has opened to
7553 remote services, e. g. how many connections a mail server or news
7554 server has to other mail or news servers, or how many connections a
7555 web proxy holds to web servers. You have to give the port in
7556 numeric form.
7557 AllPortsSummary true|false
7559 If this option is set to true a summary of statistics from all
7560 connections are collected. This option defaults to false.
7561 Plugin "thermal"
7563 ForceUseProcfs true|false
7564 By default, the Thermal plugin tries to read the statistics from
7565 the Linux "sysfs" interface. If that is not available, the plugin
7566 falls back to the "procfs" interface. By setting this option to
7567 true, you can force the plugin to use the latter. This option
7568 defaults to false.
7569 Device Device
7571 Selects the name of the thermal device that you want to collect or
7572 ignore, depending on the value of the IgnoreSelected option. This
7573 option may be used multiple times to specify a list of devices.
7574 See /"IGNORELISTS" for details.
7576 IgnoreSelected true|false
7578 Invert the selection: If set to true, all devices except the ones
7579 that match the device names specified by the Device option are
7580 collected. By default only selected devices are collected if a
7581 selection is made. If no selection is configured at all, all
7582 devices are selected.
7583 Plugin "threshold"
7585 The Threshold plugin checks values collected or received by collectd
7586 against a configurable threshold and issues notifications if values are
7587 out of bounds.
7588 Documentation for this plugin is available in the collectd-threshold(5)
7590 manual page.
7591 Plugin "tokyotyrant"
7593 The TokyoTyrant plugin connects to a TokyoTyrant server and collects a
7594 couple metrics: number of records, and database size on disk.
7595 Host Hostname/IP
7597 The hostname or IP which identifies the server. Default: 127.0.0.1
7598 Port Service/Port
7600 The query port of the server. This needs to be a string, even if
7601 the port is given in its numeric form. Default: 1978
7602 Plugin "turbostat"
7604 The Turbostat plugin reads CPU frequency and C-state residency on
7605 modern Intel processors by using Model Specific Registers.
7606 CoreCstates Bitmask(Integer)
7608 Bit mask of the list of core C-states supported by the processor.
7609 This option should only be used if the automated detection fails.
7610 Default value extracted from the CPU model and family.
7611 Currently supported C-states (by this plugin): 3, 6, 7
7613 Example:
7615 All states (3, 6 and 7):
7617 (1<<3) + (1<<6) + (1<<7) = 392
7618 PackageCstates Bitmask(Integer)
7620 Bit mask of the list of packages C-states supported by the
7621 processor. This option should only be used if the automated
7622 detection fails. Default value extracted from the CPU model and
7623 family.
7624 Currently supported C-states (by this plugin): 2, 3, 6, 7, 8, 9, 10
7626 Example:
7628 States 2, 3, 6 and 7:
7630 (1<<2) + (1<<3) + (1<<6) + (1<<7) = 396
7631 SystemManagementInterrupt true|false
7633 Boolean enabling the collection of the I/O System-Management
7634 Interrupt counter. This option should only be used if the
7635 automated detection fails or if you want to disable this feature.
7636 DigitalTemperatureSensor true|false
7638 Boolean enabling the collection of the temperature of each core.
7639 This option should only be used if the automated detection fails or
7640 if you want to disable this feature.
7641 TCCActivationTemp Temperature
7643 Thermal Control Circuit Activation Temperature of the installed
7644 CPU. This temperature is used when collecting the temperature of
7645 cores or packages. This option should only be used if the automated
7646 detection fails. Default value extracted from
7647 MSR_IA32_TEMPERATURE_TARGET.
7648 RunningAveragePowerLimit Bitmask(Integer)
7650 Bit mask of the list of elements to be thermally monitored. This
7651 option should only be used if the automated detection fails or if
7652 you want to disable some collections. The different bits of this
7653 bit mask accepted by this plugin are:
7654 0 ('1'): Package
7656 1 ('2'): DRAM
7657 2 ('4'): Cores
7658 3 ('8'): Embedded graphic device
7659 LogicalCoreNames true|false
7660 Boolean enabling the use of logical core numbering for per core
7661 statistics. When enabled, "cpu<n>" is used as plugin instance,
7662 where n is a dynamic number assigned by the kernel. Otherwise,
7663 "core<n>" is used if there is only one package and "pkg<n>-core<m>"
7664 if there is more than one, where n is the n-th core of package m.
7665 RestoreAffinityPolicy AllCPUs|Restore
7667 Reading data from CPU has side-effect: collectd process's CPU
7668 affinity mask changes. After reading data is completed, affinity
7669 mask needs to be restored. This option allows to set restore
7670 policy.
7671 AllCPUs (the default): Restore the affinity by setting affinity to
7673 any/all CPUs.
7674 Restore: Save affinity using sched_getaffinity() before reading
7676 data and restore it after.
7677 On some systems, sched_getaffinity() will fail due to inconsistency
7679 of the CPU set size between userspace and kernel. In these cases
7680 plugin will detect the unsuccessful call and fail with an error,
7681 preventing data collection. Most of configurations does not need
7682 to save affinity as Collectd process is allowed to run on any/all
7683 available CPUs.
7684 If you need to save and restore affinity and get errors like
7686 'Unable to save the CPU affinity', setting 'possible_cpus' kernel
7687 boot option may also help.
7688 See following links for details:
7690 <https://github.com/collectd/collectd/issues/1593>
7692 <https://sourceware.org/bugzilla/show_bug.cgi?id=15630>
7693 <https://bugzilla.kernel.org/show_bug.cgi?id=151821>
7694 Plugin "unixsock"
7696 SocketFile Path
7697 Sets the socket-file which is to be created.
7698 SocketGroup Group
7700 If running as root change the group of the UNIX-socket after it has
7701 been created. Defaults to collectd.
7702 SocketPerms Permissions
7704 Change the file permissions of the UNIX-socket after it has been
7705 created. The permissions must be given as a numeric, octal value as
7706 you would pass to chmod(1). Defaults to 0770.
7707 DeleteSocket false|true
7709 If set to true, delete the socket file before calling bind(2), if a
7710 file with the given name already exists. If collectd crashes a
7711 socket file may be left over, preventing the daemon from opening a
7712 new socket when restarted. Since this is potentially dangerous,
7713 this defaults to false.
7714 Plugin "uuid"
7716 This plugin, if loaded, causes the Hostname to be taken from the
7717 machine's UUID. The UUID is a universally unique designation for the
7718 machine, usually taken from the machine's BIOS. This is most useful if
7719 the machine is running in a virtual environment such as Xen, in which
7720 case the UUID is preserved across shutdowns and migration.
7721 The following methods are used to find the machine's UUID, in order:
7723 · Check /etc/uuid (or UUIDFile).
7725 · Check for UUID from HAL
7727 (<http://www.freedesktop.org/wiki/Software/hal>) if present.
7728 · Check for UUID from "dmidecode" / SMBIOS.
7730 · Check for UUID from Xen hypervisor.
7732 If no UUID can be found then the hostname is not modified.
7734 UUIDFile Path
7736 Take the UUID from the given file (default /etc/uuid).
7737 Plugin "varnish"
7739 The varnish plugin collects information about Varnish, an HTTP
7740 accelerator. It collects a subset of the values displayed by
7741 varnishstat(1), and organizes them in categories which can be enabled
7742 or disabled. Currently only metrics shown in varnishstat(1)'s MAIN
7743 section are collected. The exact meaning of each metric can be found in
7744 varnish-counters(7).
7745 Synopsis:
7747 <Plugin "varnish">
7749 <Instance "example">
7750 CollectBackend true
7751 CollectBan false
7752 CollectCache true
7753 CollectConnections true
7754 CollectDirectorDNS false
7755 CollectESI false
7756 CollectFetch false
7757 CollectHCB false
7758 CollectObjects false
7759 CollectPurge false
7760 CollectSession false
7761 CollectSHM true
7762 CollectSMA false
7763 CollectSMS false
7764 CollectSM false
7765 CollectStruct false
7766 CollectTotals false
7767 CollectUptime false
7768 CollectVCL false
7769 CollectVSM false
7770 CollectWorkers false
7771 CollectLock false
7772 CollectMempool false
7773 CollectManagement false
7774 CollectSMF false
7775 CollectVBE false
7776 CollectMSE false
7777 </Instance>
7778 </Plugin>
7779 The configuration consists of one or more <Instance Name> blocks. Name
7781 is the parameter passed to "varnishd -n". If left empty, it will
7782 collectd statistics from the default "varnishd" instance (this should
7783 work fine in most cases).
7784 Inside each <Instance> blocks, the following options are recognized:
7786 CollectBackend true|false
7788 Back-end connection statistics, such as successful, reused, and
7789 closed connections. True by default.
7790 CollectBan true|false
7792 Statistics about ban operations, such as number of bans added,
7793 retired, and number of objects tested against ban operations. Only
7794 available with Varnish 3.x and above. False by default.
7795 CollectCache true|false
7797 Cache hits and misses. True by default.
7798 CollectConnections true|false
7800 Number of client connections received, accepted and dropped. True
7801 by default.
7802 CollectDirectorDNS true|false
7804 DNS director lookup cache statistics. Only available with Varnish
7805 3.x. False by default.
7806 CollectESI true|false
7808 Edge Side Includes (ESI) parse statistics. False by default.
7809 CollectFetch true|false
7811 Statistics about fetches (HTTP requests sent to the backend). False
7812 by default.
7813 CollectHCB true|false
7815 Inserts and look-ups in the crit bit tree based hash. Look-ups are
7816 divided into locked and unlocked look-ups. False by default.
7817 CollectObjects true|false
7819 Statistics on cached objects: number of objects expired, nuked
7820 (prematurely expired), saved, moved, etc. False by default.
7821 CollectPurge true|false
7823 Statistics about purge operations, such as number of purges added,
7824 retired, and number of objects tested against purge operations.
7825 Only available with Varnish 2.x. False by default.
7826 CollectSession true|false
7828 Client session statistics. Number of past and current sessions,
7829 session herd and linger counters, etc. False by default. Note that
7830 if using Varnish 4.x, some metrics found in the Connections and
7831 Threads sections with previous versions of Varnish have been moved
7832 here.
7833 CollectSHM true|false
7835 Statistics about the shared memory log, a memory region to store
7836 log messages which is flushed to disk when full. True by default.
7837 CollectSMA true|false
7839 malloc or umem (umem_alloc(3MALLOC) based) storage statistics. The
7840 umem storage component is Solaris specific. Note: SMA, SMF and MSE
7841 share counters, enable only the one used by the Varnish instance.
7842 Only available with Varnish 2.x. False by default.
7843 CollectSMS true|false
7845 synth (synthetic content) storage statistics. This storage
7846 component is used internally only. False by default.
7847 CollectSM true|false
7849 file (memory mapped file) storage statistics. Only available with
7850 Varnish 2.x., in varnish 4.x. use CollectSMF. False by default.
7851 CollectStruct true|false
7853 Current varnish internal state statistics. Number of current
7854 sessions, objects in cache store, open connections to backends
7855 (with Varnish 2.x), etc. False by default.
7856 CollectTotals true|false
7858 Collects overview counters, such as the number of sessions created,
7859 the number of requests and bytes transferred. False by default.
7860 CollectUptime true|false
7862 Varnish uptime. Only available with Varnish 3.x and above. False by
7863 default.
7864 CollectVCL true|false
7866 Number of total (available + discarded) VCL (config files). False
7867 by default.
7868 CollectVSM true|false
7870 Collect statistics about Varnish's shared memory usage (used by the
7871 logging and statistics subsystems). Only available with Varnish
7872 4.x. False by default.
7873 CollectWorkers true|false
7875 Collect statistics about worker threads. False by default.
7876 CollectVBE true|false
7878 Backend counters. Only available with Varnish 4.x. False by
7879 default.
7880 CollectSMF true|false
7882 file (memory mapped file) storage statistics. Only available with
7883 Varnish 4.x. Note: SMA, SMF and MSE share counters, enable only
7884 the one used by the Varnish instance. Used to be called SM in
7885 Varnish 2.x. False by default.
7886 CollectManagement true|false
7888 Management process counters. Only available with Varnish 4.x. False
7889 by default.
7890 CollectLock true|false
7892 Lock counters. Only available with Varnish 4.x. False by default.
7893 CollectMempool true|false
7895 Memory pool counters. Only available with Varnish 4.x. False by
7896 default.
7897 CollectMSE true|false
7899 Varnish Massive Storage Engine 2.0 (MSE2) is an improved storage
7900 backend for Varnish, replacing the traditional malloc and file
7901 storages. Only available with Varnish-Plus 4.x. Note: SMA, SMF and
7902 MSE share counters, enable only the one used by the Varnish
7903 instance. False by default.
7904 Plugin "virt"
7906 This plugin allows CPU, disk, network load and other metrics to be
7907 collected for virtualized guests on the machine. The statistics are
7908 collected through libvirt API (<http://libvirt.org/>). Majority of
7909 metrics can be gathered without installing any additional software on
7910 guests, especially collectd, which runs only on the host system.
7911 Only Connection is required.
7913 Consider the following example config:
7915 <Plugin "virt">
7917 Connection "qemu:///system"
7918 HostnameFormat "hostname"
7919 InterfaceFormat "address"
7920 PluginInstanceFormat "name"
7921 </Plugin>
7922 It will generate the following values:
7924 node42.example.com/virt-instance-0006f26c/disk_octets-vda
7926 node42.example.com/virt-instance-0006f26c/disk_ops-vda
7927 node42.example.com/virt-instance-0006f26c/if_dropped-ca:fe:ca:fe:ca:fe
7928 node42.example.com/virt-instance-0006f26c/if_errors-ca:fe:ca:fe:ca:fe
7929 node42.example.com/virt-instance-0006f26c/if_octets-ca:fe:ca:fe:ca:fe
7930 node42.example.com/virt-instance-0006f26c/if_packets-ca:fe:ca:fe:ca:fe
7931 node42.example.com/virt-instance-0006f26c/memory-actual_balloon
7932 node42.example.com/virt-instance-0006f26c/memory-available
7933 node42.example.com/virt-instance-0006f26c/memory-last_update
7934 node42.example.com/virt-instance-0006f26c/memory-major_fault
7935 node42.example.com/virt-instance-0006f26c/memory-minor_fault
7936 node42.example.com/virt-instance-0006f26c/memory-rss
7937 node42.example.com/virt-instance-0006f26c/memory-swap_in
7938 node42.example.com/virt-instance-0006f26c/memory-swap_out
7939 node42.example.com/virt-instance-0006f26c/memory-total
7940 node42.example.com/virt-instance-0006f26c/memory-unused
7941 node42.example.com/virt-instance-0006f26c/memory-usable
7942 node42.example.com/virt-instance-0006f26c/virt_cpu_total
7943 node42.example.com/virt-instance-0006f26c/virt_vcpu-0
7944 You can get information on the metric's units from the online libvirt
7946 documentation. For instance, virt_cpu_total is in nanoseconds.
7947 Connection uri
7949 Connect to the hypervisor given by uri. For example if using Xen
7950 use:
7951 Connection "xen:///"
7953 Details which URIs allowed are given at
7955 <http://libvirt.org/uri.html>.
7956 RefreshInterval seconds
7958 Refresh the list of domains and devices every seconds. The default
7959 is 60 seconds. Setting this to be the same or smaller than the
7960 Interval will cause the list of domains and devices to be refreshed
7961 on every iteration.
7962 Refreshing the devices in particular is quite a costly operation,
7964 so if your virtualization setup is static you might consider
7965 increasing this. If this option is set to 0, refreshing is disabled
7966 completely.
7967 Domain name
7969 BlockDevice name:dev
7970 InterfaceDevice name:dev
7971 IgnoreSelected true|false
7972 Select which domains and devices are collected.
7973 If IgnoreSelected is not given or false then only the listed
7975 domains and disk/network devices are collected.
7976 If IgnoreSelected is true then the test is reversed and the listed
7978 domains and disk/network devices are ignored, while the rest are
7979 collected.
7980 The domain name and device names may use a regular expression, if
7982 the name is surrounded by /.../ and collectd was compiled with
7983 support for regexps.
7984 The default is to collect statistics for all domains and all their
7986 devices.
7987 Note: BlockDevice and InterfaceDevice options are related to
7989 corresponding *Format options. Specifically, BlockDevice filtering
7990 depends on BlockDeviceFormat setting - if user wants to filter
7991 block devices by 'target' name then BlockDeviceFormat option has to
7992 be set to 'target' and BlockDevice option must be set to a valid
7993 block device target name("/:hdb/"). Mixing formats and filter
7994 values from different worlds (i.e., using 'target' name as
7995 BlockDevice value with BlockDeviceFormat set to 'source') may lead
7996 to unexpected results (all devices filtered out or all visible,
7997 depending on the value of IgnoreSelected option). Similarly,
7998 option InterfaceDevice is related to InterfaceFormat setting (i.e.,
7999 when user wants to use MAC address as a filter then InterfaceFormat
8000 has to be set to 'address' - using wrong type here may filter out
8001 all of the interfaces).
8002 Example 1:
8004 Ignore all hdb devices on any domain, but other block devices (eg.
8006 hda) will be collected:
8007 BlockDevice "/:hdb/"
8009 IgnoreSelected "true"
8010 BlockDeviceFormat "target"
8011 Example 2:
8013 Collect metrics only for block device on 'baremetal0' domain when
8015 its 'source' matches given path:
8016 BlockDevice "baremetal0:/var/lib/libvirt/images/baremetal0.qcow2"
8018 BlockDeviceFormat source
8019 As you can see it is possible to filter devices/interfaces using
8021 various formats - for block devices 'target' or 'source' name can
8022 be used. Interfaces can be filtered using 'name', 'address' or
8023 'number'.
8024 Example 3:
8026 Collect metrics only for domains 'baremetal0' and 'baremetal1' and
8028 ignore any other domain:
8029 Domain "baremetal0"
8031 Domain "baremetal1"
8032 It is possible to filter multiple block devices/domains/interfaces
8034 by adding multiple filtering entries in separate lines.
8035 BlockDeviceFormat target|source
8037 If BlockDeviceFormat is set to target, the default, then the device
8038 name seen by the guest will be used for reporting metrics. This
8039 corresponds to the "<target>" node in the XML definition of the
8040 domain.
8041 If BlockDeviceFormat is set to source, then metrics will be
8043 reported using the path of the source, e.g. an image file. This
8044 corresponds to the "<source>" node in the XML definition of the
8045 domain.
8046 Example:
8048 If the domain XML have the following device defined:
8050 <disk type='block' device='disk'>
8052 <driver name='qemu' type='raw' cache='none' io='native' discard='unmap'/>
8053 <source dev='/var/lib/libvirt/images/image1.qcow2'/>
8054 <target dev='sda' bus='scsi'/>
8055 <boot order='2'/>
8056 <address type='drive' controller='0' bus='0' target='0' unit='0'/>
8057 </disk>
8058 Setting "BlockDeviceFormat target" will cause the type instance to
8060 be set to "sda". Setting "BlockDeviceFormat source" will cause the
8061 type instance to be set to "var_lib_libvirt_images_image1.qcow2".
8062 Note: this option determines also what field will be used for
8064 filtering over block devices (filter value in BlockDevice will be
8065 applied to target or source). More info about filtering block
8066 devices can be found in the description of BlockDevice.
8067 BlockDeviceFormatBasename false|true
8069 The BlockDeviceFormatBasename controls whether the full path or the
8070 basename(1) of the source is being used as the type instance when
8071 BlockDeviceFormat is set to source. Defaults to false.
8072 Example:
8074 Assume the device path (source tag) is
8076 "/var/lib/libvirt/images/image1.qcow2". Setting
8077 "BlockDeviceFormatBasename false" will cause the type instance to
8078 be set to "var_lib_libvirt_images_image1.qcow2". Setting
8079 "BlockDeviceFormatBasename true" will cause the type instance to be
8080 set to "image1.qcow2".
8081 HostnameFormat name|uuid|hostname|metadata...
8083 When the virt plugin logs data, it sets the hostname of the
8084 collected data according to this setting. The default is to use the
8085 guest name as provided by the hypervisor, which is equal to setting
8086 name.
8087 uuid means use the guest's UUID. This is useful if you want to
8089 track the same guest across migrations.
8090 hostname means to use the global Hostname setting, which is
8092 probably not useful on its own because all guests will appear to
8093 have the same name. This is useful in conjunction with
8094 PluginInstanceFormat though.
8095 metadata means use information from guest's metadata. Use
8097 HostnameMetadataNS and HostnameMetadataXPath to localize this
8098 information.
8099 You can also specify combinations of these fields. For example name
8101 uuid means to concatenate the guest name and UUID (with a literal
8102 colon character between, thus "foo:1234-1234-1234-1234").
8103 At the moment of writing (collectd-5.5), hostname string is limited
8105 to 62 characters. In case when combination of fields exceeds 62
8106 characters, hostname will be truncated without a warning.
8107 InterfaceFormat name|address|number
8109 When the virt plugin logs interface data, it sets the name of the
8110 collected data according to this setting. The default is to use the
8111 path as provided by the hypervisor (the "dev" property of the
8112 target node), which is equal to setting name.
8113 address means use the interface's mac address. This is useful since
8115 the interface path might change between reboots of a guest or
8116 across migrations.
8117 number means use the interface's number in guest.
8119 Note: this option determines also what field will be used for
8121 filtering over interface device (filter value in InterfaceDevice
8122 will be applied to name, address or number). More info about
8123 filtering interfaces can be found in the description of
8124 InterfaceDevice.
8125 PluginInstanceFormat name|uuid|metadata|none
8127 When the virt plugin logs data, it sets the plugin_instance of the
8128 collected data according to this setting. The default is to not set
8129 the plugin_instance.
8130 name means use the guest's name as provided by the hypervisor.
8132 uuid means use the guest's UUID. metadata means use information
8133 from guest's metadata.
8134 You can also specify combinations of the name and uuid fields. For
8136 example name uuid means to concatenate the guest name and UUID
8137 (with a literal colon character between, thus
8138 "foo:1234-1234-1234-1234").
8139 HostnameMetadataNS string
8141 When metadata is used in HostnameFormat or PluginInstanceFormat,
8142 this selects in which metadata namespace we will pick the hostname.
8143 The default is http://openstack.org/xmlns/libvirt/nova/1.0.
8144 HostnameMetadataXPath string
8146 When metadata is used in HostnameFormat or PluginInstanceFormat,
8147 this describes where the hostname is located in the libvirt
8148 metadata. The default is /instance/name/text().
8149 ReportBlockDevices true|false
8151 Enabled by default. Allows to disable stats reporting of block
8152 devices for whole plugin.
8153 ReportNetworkInterfaces true|false
8155 Enabled by default. Allows to disable stats reporting of network
8156 interfaces for whole plugin.
8157 ExtraStats string
8159 Report additional extra statistics. The default is no extra
8160 statistics, preserving the previous behaviour of the plugin. If
8161 unsure, leave the default. If enabled, allows the plugin to
8162 reported more detailed statistics about the behaviour of Virtual
8163 Machines. The argument is a space-separated list of selectors.
8164 Currently supported selectors are:
8166 cpu_util: report CPU utilization per domain in percentage.
8168 disk: report extra statistics like number of flush operations and
8169 total service time for read, write and flush operations. Requires
8170 libvirt API version 0.9.5 or later.
8171 disk_err: report disk errors if any occured. Requires libvirt API
8172 version 0.9.10 or later.
8173 domain_state: report domain state and reason as 'domain_state'
8174 metric.
8175 fs_info: report file system information as a notification. Requires
8176 libvirt API version 1.2.11 or later. Can be collected only if Guest
8177 Agent is installed and configured inside VM. Make sure that
8178 installed Guest Agent version supports retrieving file system
8179 information.
8180 job_stats_background: report statistics about progress of a
8181 background job on a domain. Only one type of job statistics can be
8182 collected at the same time. Requires libvirt API version 1.2.9 or
8183 later.
8184 job_stats_completed: report statistics about a recently completed
8185 job on a domain. Only one type of job statistics can be collected
8186 at the same time. Requires libvirt API version 1.2.9 or later.
8187 memory: report statistics about memory usage details, provided by
8188 libvirt virDomainMemoryStats() function.
8189 pcpu: report the physical user/system cpu time consumed by the
8190 hypervisor, per-vm. Requires libvirt API version 0.9.11 or later.
8191 perf: report performance monitoring events. To collect performance
8192 metrics they must be enabled for domain and supported by the
8193 platform. Requires libvirt API version 1.3.3 or later. Note: perf
8194 metrics can't be collected if intel_rdt plugin is enabled.
8195 vcpu: report domain virtual CPUs utilisation.
8196 vcpupin: report pinning of domain VCPUs to host physical CPUs.
8197 disk_physical: report 'disk_physical' statistic for disk device.
8198 Note: This statistic is only reported for disk devices with
8199 'source' property available.
8200 disk_allocation: report 'disk_allocation' statistic for disk
8201 device. Note: This statistic is only reported for disk devices with
8202 'source' property available.
8203 disk_capacity: report 'disk_capacity' statistic for disk device.
8204 Note: This statistic is only reported for disk devices with
8205 'source' property available.
8206 PersistentNotification true|false
8207 Override default configuration to only send notifications when
8208 there is a change in the lifecycle state of a domain. When set to
8209 true notifications will be sent for every read cycle. Default is
8210 false. Does not affect the stats being dispatched.
8211 Instances integer
8213 How many read instances you want to use for this plugin. The
8214 default is one, and the sensible setting is a multiple of the
8215 ReadThreads value.
8216 This option is only useful when domains are specially tagged. If
8218 you are not sure, just use the default setting.
8219 The reader instance will only query the domains with attached
8221 matching tag. Tags should have the form of 'virt-X' where X is the
8222 reader instance number, starting from 0.
8223 The special-purpose reader instance #0, guaranteed to be always
8225 present, will query all the domains with missing or unrecognized
8226 tag, so no domain will ever be left out.
8227 Domain tagging is done with a custom attribute in the libvirt
8229 domain metadata section. Value is selected by an XPath
8230 /domain/metadata/ovirtmap/tag/text() expression in the
8231 http://ovirt.org/ovirtmap/tag/1.0 namespace. (XPath and namespace
8232 values are not configurable yet).
8233 Tagging could be used by management applications to evenly spread
8235 the load among the reader threads, or to pin on the same threads
8236 all the libvirt domains which use the same shared storage, to
8237 minimize the disruption in presence of storage outages.
8238 Plugin "vmem"
8240 The "vmem" plugin collects information about the usage of virtual
8241 memory. Since the statistics provided by the Linux kernel are very
8242 detailed, they are collected very detailed. However, to get all the
8243 details, you have to switch them on manually. Most people just want an
8244 overview over, such as the number of pages read from swap space.
8245 Verbose true|false
8247 Enables verbose collection of information. This will start
8248 collecting page "actions", e. g. page allocations, (de)activations,
8249 steals and so on. Part of these statistics are collected on a "per
8250 zone" basis.
8251 Plugin "vserver"
8253 This plugin doesn't have any options. VServer support is only available
8254 for Linux. It cannot yet be found in a vanilla kernel, though. To make
8255 use of this plugin you need a kernel that has VServer support built in,
8256 i. e. you need to apply the patches and compile your own kernel, which
8257 will then provide the /proc/virtual filesystem that is required by this
8258 plugin.
8259 The VServer homepage can be found at <http://linux-vserver.org/>.
8261 Note: The traffic collected by this plugin accounts for the amount of
8263 traffic passing a socket which might be a lot less than the actual on-
8264 wire traffic (e. g. due to headers and retransmission). If you want to
8265 collect on-wire traffic you could, for example, use the logging
8266 facilities of iptables to feed data for the guest IPs into the iptables
8267 plugin.
8268 Plugin "write_graphite"
8270 The "write_graphite" plugin writes data to Graphite, an open-source
8271 metrics storage and graphing project. The plugin connects to Carbon,
8272 the data layer of Graphite, via TCP or UDP and sends data via the "line
8273 based" protocol (per default using port 2003). The data will be sent in
8274 blocks of at most 1428 bytes to minimize the number of network packets.
8275 Synopsis:
8277 <Plugin write_graphite>
8279 <Node "example">
8280 Host "localhost"
8281 Port "2003"
8282 Protocol "tcp"
8283 LogSendErrors true
8284 Prefix "collectd"
8285 UseTags false
8286 ReverseHost false
8287 </Node>
8288 </Plugin>
8289 The configuration consists of one or more <Node Name> blocks. Inside
8291 the Node blocks, the following options are recognized:
8292 Host Address
8294 Hostname or address to connect to. Defaults to "localhost".
8295 Port Service
8297 Service name or port number to connect to. Defaults to 2003.
8298 Protocol String
8300 Protocol to use when connecting to Graphite. Defaults to "tcp".
8301 ReconnectInterval Seconds
8303 When set to non-zero, forces the connection to the Graphite backend
8304 to be closed and re-opend periodically. This behavior is desirable
8305 in environments where the connection to the Graphite backend is
8306 done through load balancers, for example. When set to zero, the
8307 default, the connetion is kept open for as long as possible.
8308 LogSendErrors false|true
8310 If set to true (the default), logs errors when sending data to
8311 Graphite. If set to false, it will not log the errors. This is
8312 especially useful when using Protocol UDP since many times we want
8313 to use the "fire-and-forget" approach and logging errors fills
8314 syslog with unneeded messages.
8315 Prefix String
8317 When UseTags is false, Prefix value is added in front of the host
8318 name. When UseTags is true, Prefix value is added in front of
8319 series name.
8320 Dots and whitespace are not escaped in this string (see
8322 EscapeCharacter below).
8323 Postfix String
8325 When UseTags is false, Postfix value appended to the host name.
8326 When UseTags is true, Postgix value appended to the end of series
8327 name (before the first ; that separates the name from the tags).
8328 Dots and whitespace are not escaped in this string (see
8330 EscapeCharacter below).
8331 EscapeCharacter Char
8333 Carbon uses the dot (".") as escape character and doesn't allow
8334 whitespace in the identifier. The EscapeCharacter option determines
8335 which character dots, whitespace and control characters are
8336 replaced with. Defaults to underscore ("_").
8337 StoreRates false|true
8339 If set to true (the default), convert counter values to rates. If
8340 set to false counter values are stored as is, i. e. as an
8341 increasing integer number.
8342 SeparateInstances false|true
8344 If set to true, the plugin instance and type instance will be in
8345 their own path component, for example "host.cpu.0.cpu.idle". If set
8346 to false (the default), the plugin and plugin instance (and
8347 likewise the type and type instance) are put into one component,
8348 for example "host.cpu-0.cpu-idle".
8349 Option value is not used when UseTags is true.
8351 AlwaysAppendDS false|true
8353 If set to true, append the name of the Data Source (DS) to the
8354 "metric" identifier. If set to false (the default), this is only
8355 done when there is more than one DS.
8356 PreserveSeparator false|true
8358 If set to false (the default) the "." (dot) character is replaced
8359 with EscapeCharacter. Otherwise, if set to true, the "." (dot)
8360 character is preserved, i.e. passed through.
8361 Option value is not used when UseTags is true.
8363 DropDuplicateFields false|true
8365 If set to true, detect and remove duplicate components in Graphite
8366 metric names. For example, the metric name
8367 "host.load.load.shortterm" will be shortened to
8368 "host.load.shortterm".
8369 UseTags false|true
8371 If set to true, Graphite metric names will be generated as tagged
8372 series. This allows for much more flexibility than the traditional
8373 hierarchical layout.
8374 Example:
8376 "test.single;host=example.com;plugin=test;plugin_instance=foo;type=single;type_instance=bar"
8377 You can use Postfix option to add more tags by specifying it like
8379 ";tag1=value1;tag2=value2". Note what tagging support was added
8380 since Graphite version 1.1.x.
8381 If set to true, the SeparateInstances and PreserveSeparator
8383 settings are not used.
8384 Default value: false.
8386 ReverseHost false|true
8388 If set to true, the (dot separated) parts of the host field of the
8389 value list will be rewritten in reverse order. The rewrite happens
8390 before special characters are replaced with the EscapeCharacter.
8391 This option might be convenient if the metrics are presented with
8393 Graphite in a DNS like tree structure (probably without replacing
8394 dots in hostnames).
8395 Example:
8397 Hostname "node3.cluster1.example.com"
8398 LoadPlugin "cpu"
8399 LoadPlugin "write_graphite"
8400 <Plugin "write_graphite">
8401 <Node "graphite.example.com">
8402 EscapeCharacter "."
8403 ReverseHost true
8404 </Node>
8405 </Plugin>
8406 result on the wire: com.example.cluster1.node3.cpu-0.cpu-idle 99.900993 1543010932
8408 Default value: false.
8410 Plugin "write_log"
8412 The "write_log" plugin writes metrics as INFO log messages.
8413 This plugin supports two output formats: Graphite and JSON.
8415 Synopsis:
8417 <Plugin write_log>
8419 Format Graphite
8420 </Plugin>
8421 Format Format
8423 The output format to use. Can be one of "Graphite" or "JSON".
8424 Plugin "write_tsdb"
8426 The "write_tsdb" plugin writes data to OpenTSDB, a scalable open-source
8427 time series database. The plugin connects to a TSD, a masterless, no
8428 shared state daemon that ingests metrics and stores them in HBase. The
8429 plugin uses TCP over the "line based" protocol with a default port
8430 4242. The data will be sent in blocks of at most 1428 bytes to minimize
8431 the number of network packets.
8432 Synopsis:
8434 <Plugin write_tsdb>
8436 ResolveInterval 60
8437 ResolveJitter 60
8438 <Node "example">
8439 Host "tsd-1.my.domain"
8440 Port "4242"
8441 HostTags "status=production"
8442 </Node>
8443 </Plugin>
8444 The configuration consists of one or more <Node Name> blocks and global
8446 directives.
8447 Global directives are:
8449 ResolveInterval seconds
8451 ResolveJitter seconds
8452 When collectd connects to a TSDB node, it will request the hostname
8453 from DNS. This can become a problem if the TSDB node is unavailable
8454 or badly configured because collectd will request DNS in order to
8455 reconnect for every metric, which can flood your DNS. So you can
8456 cache the last value for ResolveInterval seconds. Defaults to the
8457 Interval of the write_tsdb plugin, e.g. 10 seconds.
8458 You can also define a jitter, a random interval to wait in addition
8460 to ResolveInterval. This prevents all your collectd servers to
8461 resolve the hostname at the same time when the connection fails.
8462 Defaults to the Interval of the write_tsdb plugin, e.g. 10 seconds.
8463 Note: If the DNS resolution has already been successful when the
8465 socket closes, the plugin will try to reconnect immediately with
8466 the cached information. DNS is queried only when the socket is
8467 closed for a longer than ResolveInterval + ResolveJitter seconds.
8468 Inside the Node blocks, the following options are recognized:
8470 Host Address
8472 Hostname or address to connect to. Defaults to "localhost".
8473 Port Service
8475 Service name or port number to connect to. Defaults to 4242.
8476 HostTags String
8478 When set, HostTags is added to the end of the metric. It is
8479 intended to be used for name=value pairs that the TSD will tag the
8480 metric with. Dots and whitespace are not escaped in this string.
8481 StoreRates false|true
8483 If set to true, convert counter values to rates. If set to false
8484 (the default) counter values are stored as is, as an increasing
8485 integer number.
8486 AlwaysAppendDS false|true
8488 If set the true, append the name of the Data Source (DS) to the
8489 "metric" identifier. If set to false (the default), this is only
8490 done when there is more than one DS.
8491 Plugin "write_mongodb"
8493 The write_mongodb plugin will send values to MongoDB, a schema-less
8494 NoSQL database.
8495 Synopsis:
8497 <Plugin "write_mongodb">
8499 <Node "default">
8500 Host "localhost"
8501 Port "27017"
8502 Timeout 1000
8503 StoreRates true
8504 </Node>
8505 </Plugin>
8506 The plugin can send values to multiple instances of MongoDB by
8508 specifying one Node block for each instance. Within the Node blocks,
8509 the following options are available:
8510 Host Address
8512 Hostname or address to connect to. Defaults to "localhost".
8513 Port Service
8515 Service name or port number to connect to. Defaults to 27017.
8516 Timeout Milliseconds
8518 Set the timeout for each operation on MongoDB to Timeout
8519 milliseconds. Setting this option to zero means no timeout, which
8520 is the default.
8521 StoreRates false|true
8523 If set to true (the default), convert counter values to rates. If
8524 set to false counter values are stored as is, i.e. as an increasing
8525 integer number.
8526 Database Database
8528 User User
8529 Password Password
8530 Sets the information used when authenticating to a MongoDB
8531 database. The fields are optional (in which case no authentication
8532 is attempted), but if you want to use authentication all three
8533 fields must be set.
8534 Plugin "write_prometheus"
8536 The write_prometheus plugin implements a tiny webserver that can be
8537 scraped using Prometheus.
8538 Options:
8540 Host Host
8542 Bind to the hostname / address Host. By default, the plugin will
8543 bind to the "any" address, i.e. accept packets sent to any of the
8544 hosts addresses.
8545 This option is supported only for libmicrohttpd newer than 0.9.0.
8547 Port Port
8549 Port the embedded webserver should listen on. Defaults to 9103.
8550 StalenessDelta Seconds
8552 Time in seconds after which Prometheus considers a metric "stale"
8553 if it hasn't seen any update for it. This value must match the
8554 setting in Prometheus. It defaults to 300 seconds (5 minutes),
8555 same as Prometheus.
8556 Background:
8558 Prometheus has a global setting, "StalenessDelta", which controls
8560 after which time a metric without updates is considered "stale".
8561 This setting effectively puts an upper limit on the interval in
8562 which metrics are reported.
8563 When the write_prometheus plugin encounters a metric with an
8565 interval exceeding this limit, it will inform you, the user, and
8566 provide the metric to Prometheus without a timestamp. That causes
8567 Prometheus to consider the metric "fresh" each time it is scraped,
8568 with the time of the scrape being considered the time of the
8569 update. The result is that there appear more datapoints in
8570 Prometheus than were actually created, but at least the metric
8571 doesn't disappear periodically.
8572 Plugin "write_http"
8574 This output plugin submits values to an HTTP server using POST requests
8575 and encoding metrics with JSON or using the "PUTVAL" command described
8576 in collectd-unixsock(5).
8577 Synopsis:
8579 <Plugin "write_http">
8581 <Node "example">
8582 URL "http://example.com/post-collectd"
8583 User "collectd"
8584 Password "weCh3ik0"
8585 Format JSON
8586 </Node>
8587 </Plugin>
8588 The plugin can send values to multiple HTTP servers by specifying one
8590 <Node Name> block for each server. Within each Node block, the
8591 following options are available:
8592 URL URL
8594 URL to which the values are submitted to. Mandatory.
8595 User Username
8597 Optional user name needed for authentication.
8598 Password Password
8600 Optional password needed for authentication.
8601 VerifyPeer true|false
8603 Enable or disable peer SSL certificate verification. See
8604 <http://curl.haxx.se/docs/sslcerts.html> for details. Enabled by
8605 default.
8606 VerifyHost true|false
8608 Enable or disable peer host name verification. If enabled, the
8609 plugin checks if the "Common Name" or a "Subject Alternate Name"
8610 field of the SSL certificate matches the host name provided by the
8611 URL option. If this identity check fails, the connection is
8612 aborted. Obviously, only works when connecting to a SSL enabled
8613 server. Enabled by default.
8614 CACert File
8616 File that holds one or more SSL certificates. If you want to use
8617 HTTPS you will possibly need this option. What CA certificates come
8618 bundled with "libcurl" and are checked by default depends on the
8619 distribution you use.
8620 CAPath Directory
8622 Directory holding one or more CA certificate files. You can use
8623 this if for some reason all the needed CA certificates aren't in
8624 the same file and can't be pointed to using the CACert option.
8625 Requires "libcurl" to be built against OpenSSL.
8626 ClientKey File
8628 File that holds the private key in PEM format to be used for
8629 certificate-based authentication.
8630 ClientCert File
8632 File that holds the SSL certificate to be used for certificate-
8633 based authentication.
8634 ClientKeyPass Password
8636 Password required to load the private key in ClientKey.
8637 Header Header
8639 A HTTP header to add to the request. Multiple headers are added if
8640 this option is specified more than once. Example:
8641 Header "X-Custom-Header: custom_value"
8643 SSLVersion SSLv2|SSLv3|TLSv1|TLSv1_0|TLSv1_1|TLSv1_2
8645 Define which SSL protocol version must be used. By default
8646 "libcurl" will attempt to figure out the remote SSL protocol
8647 version. See curl_easy_setopt(3) for more details.
8648 Format Command|JSON|KAIROSDB
8650 Format of the output to generate. If set to Command, will create
8651 output that is understood by the Exec and UnixSock plugins. When
8652 set to JSON, will create output in the JavaScript Object Notation
8653 (JSON). When set to KAIROSDB , will create output in the KairosDB
8654 format.
8655 Defaults to Command.
8657 Attribute String String
8659 Only available for the KAIROSDB output format.
8660 Consider the two given strings to be the key and value of an
8662 additional tag for each metric being sent out.
8663 You can add multiple Attribute.
8665 TTL Int
8667 Only available for the KAIROSDB output format.
8668 Sets the Cassandra ttl for the data points.
8670 Please refer to
8672 <http://kairosdb.github.io/docs/build/html/restapi/AddDataPoints.html?highlight=ttl>
8673 Prefix String
8675 Only available for the KAIROSDB output format.
8676 Sets the metrics prefix string. Defaults to collectd.
8678 Metrics true|false
8680 Controls whether metrics are POSTed to this location. Defaults to
8681 true.
8682 Notifications false|true
8684 Controls whether notifications are POSTed to this location.
8685 Defaults to false.
8686 StoreRates true|false
8688 If set to true, convert counter values to rates. If set to false
8689 (the default) counter values are stored as is, i.e. as an
8690 increasing integer number.
8691 BufferSize Bytes
8693 Sets the send buffer size to Bytes. By increasing this buffer, less
8694 HTTP requests will be generated, but more metrics will be batched /
8695 metrics are cached for longer before being sent, introducing
8696 additional delay until they are available on the server side. Bytes
8697 must be at least 1024 and cannot exceed the size of an "int", i.e.
8698 2 GByte. Defaults to 4096.
8699 LowSpeedLimit Bytes per Second
8701 Sets the minimal transfer rate in Bytes per Second below which the
8702 connection with the HTTP server will be considered too slow and
8703 aborted. All the data submitted over this connection will probably
8704 be lost. Defaults to 0, which means no minimum transfer rate is
8705 enforced.
8706 Timeout Timeout
8708 Sets the maximum time in milliseconds given for HTTP POST
8709 operations to complete. When this limit is reached, the POST
8710 operation will be aborted, and all the data in the current send
8711 buffer will probably be lost. Defaults to 0, which means the
8712 connection never times out.
8713 LogHttpError false|true
8715 Enables printing of HTTP error code to log. Turned off by default.
8716 The "write_http" plugin regularly submits the collected values to
8718 the HTTP server. How frequently this happens depends on how much
8719 data you are collecting and the size of BufferSize. The optimal
8720 value to set Timeout to is slightly below this interval, which you
8721 can estimate by monitoring the network traffic between collectd and
8722 the HTTP server.
8723 Plugin "write_kafka"
8725 The write_kafka plugin will send values to a Kafka topic, a distributed
8726 queue. Synopsis:
8727 <Plugin "write_kafka">
8729 Property "metadata.broker.list" "broker1:9092,broker2:9092"
8730 <Topic "collectd">
8731 Format JSON
8732 </Topic>
8733 </Plugin>
8734 The following options are understood by the write_kafka plugin:
8736 <Topic Name>
8738 The plugin's configuration consists of one or more Topic blocks.
8739 Each block is given a unique Name and specifies one kafka producer.
8740 Inside the Topic block, the following per-topic options are
8741 understood:
8742 Property String String
8744 Configure the named property for the current topic. Properties
8745 are forwarded to the kafka producer library librdkafka.
8746 Key String
8748 Use the specified string as a partitioning key for the topic.
8749 Kafka breaks topic into partitions and guarantees that for a
8750 given topology, the same consumer will be used for a specific
8751 key. The special (case insensitive) string Random can be used
8752 to specify that an arbitrary partition should be used.
8753 Format Command|JSON|Graphite
8755 Selects the format in which messages are sent to the broker. If
8756 set to Command (the default), values are sent as "PUTVAL"
8757 commands which are identical to the syntax used by the Exec and
8758 UnixSock plugins.
8759 If set to JSON, the values are encoded in the JavaScript Object
8761 Notation, an easy and straight forward exchange format.
8762 If set to Graphite, values are encoded in the Graphite format,
8764 which is "<metric> <value> <timestamp>\n".
8765 StoreRates true|false
8767 Determines whether or not "COUNTER", "DERIVE" and "ABSOLUTE"
8768 data sources are converted to a rate (i.e. a "GAUGE" value). If
8769 set to false (the default), no conversion is performed.
8770 Otherwise the conversion is performed using the internal value
8771 cache.
8772 Please note that currently this option is only used if the
8774 Format option has been set to JSON.
8775 GraphitePrefix (Format=Graphite only)
8777 A prefix can be added in the metric name when outputting in the
8778 Graphite format.
8779 When GraphiteUseTags is false, prefix is added before the Host
8781 name. Metric name will be
8782 "<prefix><host><postfix><plugin><type><name>"
8783 When GraphiteUseTags is true, prefix is added in front of
8785 series name.
8786 GraphitePostfix (Format=Graphite only)
8788 A postfix can be added in the metric name when outputting in
8789 the Graphite format.
8790 When GraphiteUseTags is false, postfix is added after the Host
8792 name. Metric name will be
8793 "<prefix><host><postfix><plugin><type><name>"
8794 When GraphiteUseTags is true, prefix value appended to the end
8796 of series name (before the first ; that separates the name from
8797 the tags).
8798 GraphiteEscapeChar (Format=Graphite only)
8800 Specify a character to replace dots (.) in the host part of the
8801 metric name. In Graphite metric name, dots are used as
8802 separators between different metric parts (host, plugin, type).
8803 Default is "_" (Underscore).
8804 GraphiteSeparateInstances false|true
8806 If set to true, the plugin instance and type instance will be
8807 in their own path component, for example "host.cpu.0.cpu.idle".
8808 If set to false (the default), the plugin and plugin instance
8809 (and likewise the type and type instance) are put into one
8810 component, for example "host.cpu-0.cpu-idle".
8811 Option value is not used when GraphiteUseTags is true.
8813 GraphiteAlwaysAppendDS true|false
8815 If set to true, append the name of the Data Source (DS) to the
8816 "metric" identifier. If set to false (the default), this is
8817 only done when there is more than one DS.
8818 GraphitePreserveSeparator false|true
8820 If set to false (the default) the "." (dot) character is
8821 replaced with GraphiteEscapeChar. Otherwise, if set to true,
8822 the "." (dot) character is preserved, i.e. passed through.
8823 Option value is not used when GraphiteUseTags is true.
8825 GraphiteUseTags false|true
8827 If set to true Graphite metric names will be generated as
8828 tagged series.
8829 Default value: false.
8831 StoreRates true|false
8833 If set to true (the default), convert counter values to rates.
8834 If set to false counter values are stored as is, i.e. as an
8835 increasing integer number.
8836 This will be reflected in the "ds_type" tag: If StoreRates is
8838 enabled, converted values will have "rate" appended to the data
8839 source type, e.g. "ds_type:derive:rate".
8840 Property String String
8842 Configure the kafka producer through properties, you almost always
8843 will want to set metadata.broker.list to your Kafka broker list.
8844 Plugin "write_redis"
8846 The write_redis plugin submits values to Redis, a data structure
8847 server.
8848 Synopsis:
8850 <Plugin "write_redis">
8852 <Node "example">
8853 Host "localhost"
8854 Port "6379"
8855 Timeout 1000
8856 Prefix "collectd/"
8857 Database 1
8858 MaxSetSize -1
8859 MaxSetDuration -1
8860 StoreRates true
8861 </Node>
8862 </Plugin>
8863 Values are submitted to Sorted Sets, using the metric name as the key,
8865 and the timestamp as the score. Retrieving a date range can then be
8866 done using the "ZRANGEBYSCORE" Redis command. Additionally, all the
8867 identifiers of these Sorted Sets are kept in a Set called
8868 "collectd/values" (or "${prefix}/values" if the Prefix option was
8869 specified) and can be retrieved using the "SMEMBERS" Redis command. You
8870 can specify the database to use with the Database parameter (default is
8871 0). See <http://redis.io/commands#sorted_set> and
8872 <http://redis.io/commands#set> for details.
8873 The information shown in the synopsis above is the default
8875 configuration which is used by the plugin if no configuration is
8876 present.
8877 The plugin can send values to multiple instances of Redis by specifying
8879 one Node block for each instance. Within the Node blocks, the following
8880 options are available:
8881 Node Nodename
8883 The Node block identifies a new Redis node, that is a new Redis
8884 instance running on a specified host and port. The node name is a
8885 canonical identifier which is used as plugin instance. It is
8886 limited to 51 characters in length.
8887 Host Hostname
8889 The Host option is the hostname or IP-address where the Redis
8890 instance is running on.
8891 Port Port
8893 The Port option is the TCP port on which the Redis instance accepts
8894 connections. Either a service name of a port number may be given.
8895 Please note that numerical port numbers must be given as a string,
8896 too.
8897 Timeout Milliseconds
8899 The Timeout option sets the socket connection timeout, in
8900 milliseconds.
8901 Prefix Prefix
8903 Prefix used when constructing the name of the Sorted Sets and the
8904 Set containing all metrics. Defaults to "collectd/", so metrics
8905 will have names like "collectd/cpu-0/cpu-user". When setting this
8906 to something different, it is recommended but not required to
8907 include a trailing slash in Prefix.
8908 Database Index
8910 This index selects the redis database to use for writing
8911 operations. Defaults to 0.
8912 MaxSetSize Items
8914 The MaxSetSize option limits the number of items that the Sorted
8915 Sets can hold. Negative values for Items sets no limit, which is
8916 the default behavior.
8917 MaxSetDuration Seconds
8919 The MaxSetDuration option limits the duration of items that the
8920 Sorted Sets can hold. Negative values for Items sets no duration,
8921 which is the default behavior.
8922 StoreRates true|false
8924 If set to true (the default), convert counter values to rates. If
8925 set to false counter values are stored as is, i.e. as an increasing
8926 integer number.
8927 Plugin "write_riemann"
8929 The write_riemann plugin will send values to Riemann, a powerful stream
8930 aggregation and monitoring system. The plugin sends Protobuf encoded
8931 data to Riemann using UDP packets.
8932 Synopsis:
8934 <Plugin "write_riemann">
8936 <Node "example">
8937 Host "localhost"
8938 Port "5555"
8939 Protocol UDP
8940 StoreRates true
8941 AlwaysAppendDS false
8942 TTLFactor 2.0
8943 </Node>
8944 Tag "foobar"
8945 Attribute "foo" "bar"
8946 </Plugin>
8947 The following options are understood by the write_riemann plugin:
8949 <Node Name>
8951 The plugin's configuration consists of one or more Node blocks.
8952 Each block is given a unique Name and specifies one connection to
8953 an instance of Riemann. Indise the Node block, the following per-
8954 connection options are understood:
8955 Host Address
8957 Hostname or address to connect to. Defaults to "localhost".
8958 Port Service
8960 Service name or port number to connect to. Defaults to 5555.
8961 Protocol UDP|TCP|TLS
8963 Specify the protocol to use when communicating with Riemann.
8964 Defaults to TCP.
8965 TLSCertFile Path
8967 When using the TLS protocol, path to a PEM certificate to
8968 present to remote host.
8969 TLSCAFile Path
8971 When using the TLS protocol, path to a PEM CA certificate to
8972 use to validate the remote hosts's identity.
8973 TLSKeyFile Path
8975 When using the TLS protocol, path to a PEM private key
8976 associated with the certificate defined by TLSCertFile.
8977 Batch true|false
8979 If set to true and Protocol is set to TCP, events will be
8980 batched in memory and flushed at regular intervals or when
8981 BatchMaxSize is exceeded.
8982 Notifications are not batched and sent as soon as possible.
8984 When enabled, it can occur that events get processed by the
8986 Riemann server close to or after their expiration time. Tune
8987 the TTLFactor and BatchMaxSize settings according to the amount
8988 of values collected, if this is an issue.
8989 Defaults to true
8991 BatchMaxSize size
8993 Maximum payload size for a riemann packet. Defaults to 8192
8994 BatchFlushTimeout seconds
8996 Maximum amount of seconds to wait in between to batch flushes.
8997 No timeout by default.
8998 StoreRates true|false
9000 If set to true (the default), convert counter values to rates.
9001 If set to false counter values are stored as is, i.e. as an
9002 increasing integer number.
9003 This will be reflected in the "ds_type" tag: If StoreRates is
9005 enabled, converted values will have "rate" appended to the data
9006 source type, e.g. "ds_type:derive:rate".
9007 AlwaysAppendDS false|true
9009 If set to true, append the name of the Data Source (DS) to the
9010 "service", i.e. the field that, together with the "host" field,
9011 uniquely identifies a metric in Riemann. If set to false (the
9012 default), this is only done when there is more than one DS.
9013 TTLFactor Factor
9015 Riemann events have a Time to Live (TTL) which specifies how
9016 long each event is considered active. collectd populates this
9017 field based on the metrics interval setting. This setting
9018 controls the factor with which the interval is multiplied to
9019 set the TTL. The default value is 2.0. Unless you know exactly
9020 what you're doing, you should only increase this setting from
9021 its default value.
9022 Notifications false|true
9024 If set to true, create riemann events for notifications. This
9025 is true by default. When processing thresholds from
9026 write_riemann, it might prove useful to avoid getting
9027 notification events.
9028 CheckThresholds false|true
9030 If set to true, attach state to events based on thresholds
9031 defined in the Threshold plugin. Defaults to false.
9032 EventServicePrefix String
9034 Add the given string as a prefix to the event service name. If
9035 EventServicePrefix not set or set to an empty string (""), no
9036 prefix will be used.
9037 Tag String
9039 Add the given string as an additional tag to the metric being sent
9040 to Riemann.
9041 Attribute String String
9043 Consider the two given strings to be the key and value of an
9044 additional attribute for each metric being sent out to Riemann.
9045 Plugin "write_sensu"
9047 The write_sensu plugin will send values to Sensu, a powerful stream
9048 aggregation and monitoring system. The plugin sends JSON encoded data
9049 to a local Sensu client using a TCP socket.
9050 At the moment, the write_sensu plugin does not send over a
9052 collectd_host parameter so it is not possible to use one collectd
9053 instance as a gateway for others. Each collectd host must pair with one
9054 Sensu client.
9055 Synopsis:
9057 <Plugin "write_sensu">
9059 <Node "example">
9060 Host "localhost"
9061 Port "3030"
9062 StoreRates true
9063 AlwaysAppendDS false
9064 MetricHandler "influx"
9065 MetricHandler "default"
9066 NotificationHandler "flapjack"
9067 NotificationHandler "howling_monkey"
9068 Notifications true
9069 </Node>
9070 Tag "foobar"
9071 Attribute "foo" "bar"
9072 </Plugin>
9073 The following options are understood by the write_sensu plugin:
9075 <Node Name>
9077 The plugin's configuration consists of one or more Node blocks.
9078 Each block is given a unique Name and specifies one connection to
9079 an instance of Sensu. Inside the Node block, the following per-
9080 connection options are understood:
9081 Host Address
9083 Hostname or address to connect to. Defaults to "localhost".
9084 Port Service
9086 Service name or port number to connect to. Defaults to 3030.
9087 StoreRates true|false
9089 If set to true (the default), convert counter values to rates.
9090 If set to false counter values are stored as is, i.e. as an
9091 increasing integer number.
9092 This will be reflected in the "collectd_data_source_type" tag:
9094 If StoreRates is enabled, converted values will have "rate"
9095 appended to the data source type, e.g.
9096 "collectd_data_source_type:derive:rate".
9097 AlwaysAppendDS false|true
9099 If set the true, append the name of the Data Source (DS) to the
9100 "service", i.e. the field that, together with the "host" field,
9101 uniquely identifies a metric in Sensu. If set to false (the
9102 default), this is only done when there is more than one DS.
9103 Notifications false|true
9105 If set to true, create Sensu events for notifications. This is
9106 false by default. At least one of Notifications or Metrics
9107 should be enabled.
9108 Metrics false|true
9110 If set to true, create Sensu events for metrics. This is false
9111 by default. At least one of Notifications or Metrics should be
9112 enabled.
9113 Separator String
9115 Sets the separator for Sensu metrics name or checks. Defaults
9116 to "/".
9117 MetricHandler String
9119 Add a handler that will be set when metrics are sent to Sensu.
9120 You can add several of them, one per line. Defaults to no
9121 handler.
9122 NotificationHandler String
9124 Add a handler that will be set when notifications are sent to
9125 Sensu. You can add several of them, one per line. Defaults to
9126 no handler.
9127 EventServicePrefix String
9129 Add the given string as a prefix to the event service name. If
9130 EventServicePrefix not set or set to an empty string (""), no
9131 prefix will be used.
9132 Tag String
9134 Add the given string as an additional tag to the metric being sent
9135 to Sensu.
9136 Attribute String String
9138 Consider the two given strings to be the key and value of an
9139 additional attribute for each metric being sent out to Sensu.
9140 Plugin "write_stackdriver"
9142 The "write_stackdriver" plugin writes metrics to the Google Stackdriver
9143 Monitoring service.
9144 This plugin supports two authentication methods: When configured,
9146 credentials are read from the JSON credentials file specified with
9147 CredentialFile. Alternatively, when running on Google Compute Engine
9148 (GCE), an OAuth token is retrieved from the metadata server and used to
9149 authenticate to GCM.
9150 Synopsis:
9152 <Plugin write_stackdriver>
9154 CredentialFile "/path/to/service_account.json"
9155 <Resource "global">
9156 Label "project_id" "monitored_project"
9157 </Resource>
9158 </Plugin>
9159 CredentialFile file
9161 Path to a JSON credentials file holding the credentials for a GCP
9162 service account.
9163 If CredentialFile is not specified, the plugin uses Application
9165 Default Credentials. That means which credentials are used depends
9166 on the environment:
9167 · The environment variable "GOOGLE_APPLICATION_CREDENTIALS" is
9169 checked. If this variable is specified it should point to a
9170 JSON file that defines the credentials.
9171 · The path
9173 "${HOME}/.config/gcloud/application_default_credentials.json"
9174 is checked. This where credentials used by the gcloud command
9175 line utility are stored. You can use "gcloud auth
9176 application-default login" to create these credentials.
9177 Please note that these credentials are often of your personal
9179 account, not a service account, and are therefore unfit to be
9180 used in a production environment.
9181 · When running on GCE, the built-in service account associated
9183 with the virtual machine instance is used. See also the Email
9184 option below.
9185 Project Project
9187 The Project ID or the Project Number of the Stackdriver Account.
9188 The Project ID is a string identifying the GCP project, which you
9189 can chose freely when creating a new project. The Project Number is
9190 a 12-digit decimal number. You can look up both on the Developer
9191 Console.
9192 This setting is optional. If not set, the project ID is read from
9194 the credentials file or determined from the GCE's metadata service.
9195 Email Email (GCE only)
9197 Choses the GCE Service Account used for authentication.
9198 Each GCE instance has a "default" Service Account but may also be
9200 associated with additional Service Accounts. This is often used to
9201 restrict the permissions of services running on the GCE instance to
9202 the required minimum. The write_stackdriver plugin requires the
9203 "https://www.googleapis.com/auth/monitoring" scope. When multiple
9204 Service Accounts are available, this option selects which one is
9205 used by write_stackdriver plugin.
9206 Resource ResourceType
9208 Configures the Monitored Resource to use when storing metrics.
9209 More information on Monitored Resources and Monitored Resource
9210 Types are available at
9211 <https://cloud.google.com/monitoring/api/resources>.
9212 This block takes one string argument, the ResourceType. Inside the
9214 block are one or more Label options which configure the resource
9215 labels.
9216 This block is optional. The default value depends on the runtime
9218 environment: on GCE, the "gce_instance" resource type is used,
9219 otherwise the "global" resource type ist used:
9220 · On GCE, defaults to the equivalent of this config:
9222 <Resource "gce_instance">
9224 Label "project_id" "<project_id>"
9225 Label "instance_id" "<instance_id>"
9226 Label "zone" "<zone>"
9227 </Resource>
9228 The values for project_id, instance_id and zone are read from
9230 the GCE metadata service.
9231 · Elsewhere, i.e. not on GCE, defaults to the equivalent of this
9233 config:
9234 <Resource "global">
9236 Label "project_id" "<Project>"
9237 </Resource>
9238 Where Project refers to the value of the Project option or the
9240 project ID inferred from the CredentialFile.
9241 Url Url
9243 URL of the Stackdriver Monitoring API. Defaults to
9244 "https://monitoring.googleapis.com/v3".
9245 Plugin "write_syslog"
9247 The "write_syslog" plugin writes data in syslog format log messages.
9248 It implements the basic syslog protocol, RFC 5424, extends it with
9249 content-based filtering, rich filtering capabilities, flexible
9250 configuration options and adds features such as using TCP for
9251 transport. The plugin can connect to a Syslog daemon, like syslog-ng
9252 and rsyslog, that will ingest metrics, transform and ship them to the
9253 specified output. The plugin uses TCP over the "line based" protocol
9254 with a default port 44514. The data will be sent in blocks of at most
9255 1428 bytes to minimize the number of network packets.
9256 Synopsis:
9258 <Plugin write_syslog>
9260 ResolveInterval 60
9261 ResolveJitter 60
9262 <Node "example">
9263 Host "syslog-1.my.domain"
9264 Port "44514"
9265 Prefix "collectd"
9266 MessageFormat "human"
9267 HostTags ""
9268 </Node>
9269 </Plugin>
9270 The configuration consists of one or more <Node Name> blocks and global
9272 directives.
9273 Global directives are:
9275 ResolveInterval seconds
9277 ResolveJitter seconds
9278 When collectd connects to a syslog node, it will request the
9279 hostname from DNS. This can become a problem if the syslog node is
9280 unavailable or badly configured because collectd will request DNS
9281 in order to reconnect for every metric, which can flood your DNS.
9282 So you can cache the last value for ResolveInterval seconds.
9283 Defaults to the Interval of the write_syslog plugin, e.g.
9284 10 seconds.
9285 You can also define a jitter, a random interval to wait in addition
9287 to ResolveInterval. This prevents all your collectd servers to
9288 resolve the hostname at the same time when the connection fails.
9289 Defaults to the Interval of the write_syslog plugin, e.g.
9290 10 seconds.
9291 Note: If the DNS resolution has already been successful when the
9293 socket closes, the plugin will try to reconnect immediately with
9294 the cached information. DNS is queried only when the socket is
9295 closed for a longer than ResolveInterval + ResolveJitter seconds.
9296 Inside the Node blocks, the following options are recognized:
9298 Host Address
9300 Hostname or address to connect to. Defaults to "localhost".
9301 Port Service
9303 Service name or port number to connect to. Defaults to 44514.
9304 HostTags String
9306 When set, HostTags is added to the end of the metric. It is
9307 intended to be used for adding additional metadata to tag the
9308 metric with. Dots and whitespace are not escaped in this string.
9309 Examples:
9311 When MessageFormat is set to "human".
9313 ["prefix1" "example1"="example1_v"]["prefix2" "example2"="example2_v"]"
9315 When MessageFormat is set to "JSON", text should be in JSON format.
9317 Escaping the quotation marks is required.
9318 HostTags "\"prefix1\": {\"example1\":\"example1_v\",\"example2\":\"example2_v\"}"
9320 MessageFormat String
9322 MessageFormat selects the format in which messages are sent to the
9323 syslog deamon, human or JSON. Defaults to human.
9324 Syslog message format:
9326 <priority>VERSION ISOTIMESTAMP HOSTNAME APPLICATION PID MESSAGEID
9328 STRUCTURED-DATA MSG
9329 The difference between the message formats are in the STRUCTURED-
9331 DATA and MSG parts.
9332 Human format:
9334 <166>1 ISOTIMESTAMP HOSTNAME collectd PID MESSAGEID
9336 ["collectd" "value": "v1" "plugin"="plugin_v" "plugin_instance"="plugin_instance_v"
9337 "type_instance"="type_instance_v" "type"="type_v" "ds_name"="ds_name_v" "interval"="interval_v" ]
9338 "host_tag_example"="host_tag_example_v" plugin_v.type_v.ds_name_v="v1"
9339 JSON format:
9341 <166>1 ISOTIMESTAMP HOSTNAME collectd PID MESSAGEID STRUCTURED-DATA
9343 {
9344 "collectd": {
9345 "time": time_as_epoch, "interval": interval_v, "plugin": "plugin_v",
9346 "plugin_instance": "plugin_instance_v", "type":"type_v",
9347 "type_instance": "type_instance_v", "plugin_v": {"type_v": v1}
9348 } , "host":"host_v", "host_tag_example": "host_tag_example_v"
9349 }
9350 StoreRates false|true
9352 If set to true, convert counter values to rates. If set to false
9353 (the default) counter values are stored as is, as an increasing
9354 integer number.
9355 AlwaysAppendDS false|true
9357 If set to true, append the name of the Data Source (DS) to the
9358 "metric" identifier. If set to false (the default), this is only
9359 done when there is more than one DS.
9360 Prefix String
9362 When set, Prefix is added to all metrics names as a prefix. It is
9363 intended in case you want to be able to define the source of the
9364 specific metric. Dots and whitespace are not escaped in this
9365 string.
9366 Plugin "xencpu"
9368 This plugin collects metrics of hardware CPU load for machine running
9369 Xen hypervisor. Load is calculated from 'idle time' value, provided by
9370 Xen. Result is reported using the "percent" type, for each CPU (core).
9371 This plugin doesn't have any options (yet).
9373 Plugin "zookeeper"
9375 The zookeeper plugin will collect statistics from a Zookeeper server
9376 using the mntr command. It requires Zookeeper 3.4.0+ and access to the
9377 client port.
9378 Synopsis:
9380 <Plugin "zookeeper">
9382 Host "127.0.0.1"
9383 Port "2181"
9384 </Plugin>
9385 Host Address
9387 Hostname or address to connect to. Defaults to "localhost".
9388 Port Service
9390 Service name or port number to connect to. Defaults to 2181.
9391
9393 Starting with version 4.3.0 collectd has support for monitoring. By
9394 that we mean that the values are not only stored or sent somewhere, but
9395 that they are judged and, if a problem is recognized, acted upon. The
9396 only action collectd takes itself is to generate and dispatch a
9397 "notification". Plugins can register to receive notifications and
9398 perform appropriate further actions.
9399 Since systems and what you expect them to do differ a lot, you can
9401 configure thresholds for your values freely. This gives you a lot of
9402 flexibility but also a lot of responsibility.
9403 Every time a value is out of range a notification is dispatched. This
9405 means that the idle percentage of your CPU needs to be less then the
9406 configured threshold only once for a notification to be generated.
9407 There's no such thing as a moving average or similar - at least not
9408 now.
9409 Also, all values that match a threshold are considered to be relevant
9411 or "interesting". As a consequence collectd will issue a notification
9412 if they are not received for Timeout iterations. The Timeout
9413 configuration option is explained in section "GLOBAL OPTIONS". If, for
9414 example, Timeout is set to "2" (the default) and some hosts sends it's
9415 CPU statistics to the server every 60 seconds, a notification will be
9416 dispatched after about 120 seconds. It may take a little longer because
9417 the timeout is checked only once each Interval on the server.
9418 When a value comes within range again or is received after it was
9420 missing, an "OKAY-notification" is dispatched.
9421 Here is a configuration example to get you started. Read below for more
9423 information.
9424 <Plugin threshold>
9426 <Type "foo">
9427 WarningMin 0.00
9428 WarningMax 1000.00
9429 FailureMin 0.00
9430 FailureMax 1200.00
9431 Invert false
9432 Instance "bar"
9433 </Type>
9434 <Plugin "interface">
9436 Instance "eth0"
9437 <Type "if_octets">
9438 FailureMax 10000000
9439 DataSource "rx"
9440 </Type>
9441 </Plugin>
9442 <Host "hostname">
9444 <Type "cpu">
9445 Instance "idle"
9446 FailureMin 10
9447 </Type>
9448 <Plugin "memory">
9450 <Type "memory">
9451 Instance "cached"
9452 WarningMin 100000000
9453 </Type>
9454 </Plugin>
9455 </Host>
9456 </Plugin>
9457 There are basically two types of configuration statements: The "Host",
9459 "Plugin", and "Type" blocks select the value for which a threshold
9460 should be configured. The "Plugin" and "Type" blocks may be specified
9461 further using the "Instance" option. You can combine the block by
9462 nesting the blocks, though they must be nested in the above order,
9463 i. e. "Host" may contain either "Plugin" and "Type" blocks, "Plugin"
9464 may only contain "Type" blocks and "Type" may not contain other blocks.
9465 If multiple blocks apply to the same value the most specific block is
9466 used.
9467 The other statements specify the threshold to configure. They must be
9469 included in a "Type" block. Currently the following statements are
9470 recognized:
9471 FailureMax Value
9473 WarningMax Value
9474 Sets the upper bound of acceptable values. If unset defaults to
9475 positive infinity. If a value is greater than FailureMax a FAILURE
9476 notification will be created. If the value is greater than
9477 WarningMax but less than (or equal to) FailureMax a WARNING
9478 notification will be created.
9479 FailureMin Value
9481 WarningMin Value
9482 Sets the lower bound of acceptable values. If unset defaults to
9483 negative infinity. If a value is less than FailureMin a FAILURE
9484 notification will be created. If the value is less than WarningMin
9485 but greater than (or equal to) FailureMin a WARNING notification
9486 will be created.
9487 DataSource DSName
9489 Some data sets have more than one "data source". Interesting
9490 examples are the "if_octets" data set, which has received ("rx")
9491 and sent ("tx") bytes and the "disk_ops" data set, which holds
9492 "read" and "write" operations. The system load data set, "load",
9493 even has three data sources: "shortterm", "midterm", and
9494 "longterm".
9495 Normally, all data sources are checked against a configured
9497 threshold. If this is undesirable, or if you want to specify
9498 different limits for each data source, you can use the DataSource
9499 option to have a threshold apply only to one data source.
9500 Invert true|false
9502 If set to true the range of acceptable values is inverted, i. e.
9503 values between FailureMin and FailureMax (WarningMin and
9504 WarningMax) are not okay. Defaults to false.
9505 Persist true|false
9507 Sets how often notifications are generated. If set to true one
9508 notification will be generated for each value that is out of the
9509 acceptable range. If set to false (the default) then a notification
9510 is only generated if a value is out of range but the previous value
9511 was okay.
9512 This applies to missing values, too: If set to true a notification
9514 about a missing value is generated once every Interval seconds. If
9515 set to false only one such notification is generated until the
9516 value appears again.
9517 Percentage true|false
9519 If set to true, the minimum and maximum values given are
9520 interpreted as percentage value, relative to the other data
9521 sources. This is helpful for example for the "df" type, where you
9522 may want to issue a warning when less than 5 % of the total space
9523 is available. Defaults to false.
9524 Hits Number
9526 Delay creating the notification until the threshold has been passed
9527 Number times. When a notification has been generated, or when a
9528 subsequent value is inside the threshold, the counter is reset. If,
9529 for example, a value is collected once every 10 seconds and Hits is
9530 set to 3, a notification will be dispatched at most once every
9531 30 seconds.
9532 This is useful when short bursts are not a problem. If, for
9534 example, 100% CPU usage for up to a minute is normal (and data is
9535 collected every 10 seconds), you could set Hits to 6 to account for
9536 this.
9537 Hysteresis Number
9539 When set to non-zero, a hysteresis value is applied when checking
9540 minimum and maximum bounds. This is useful for values that increase
9541 slowly and fluctuate a bit while doing so. When these values come
9542 close to the threshold, they may "flap", i.e. switch between
9543 failure / warning case and okay case repeatedly.
9544 If, for example, the threshold is configures as
9546 WarningMax 100.0
9548 Hysteresis 1.0
9549 then a Warning notification is created when the value exceeds 101
9551 and the corresponding Okay notification is only created once the
9552 value falls below 99, thus avoiding the "flapping".
9553
9555 Starting with collectd 4.6 there is a powerful filtering infrastructure
9556 implemented in the daemon. The concept has mostly been copied from
9557 ip_tables, the packet filter infrastructure for Linux. We'll use a
9558 similar terminology, so that users that are familiar with iptables feel
9559 right at home.
9560 Terminology
9562 The following are the terms used in the remainder of the filter
9563 configuration documentation. For an ASCII-art schema of the mechanism,
9564 see "General structure" below.
9565 Match
9567 A match is a criteria to select specific values. Examples are, of
9568 course, the name of the value or it's current value.
9569 Matches are implemented in plugins which you have to load prior to
9571 using the match. The name of such plugins starts with the "match_"
9572 prefix.
9573 Target
9575 A target is some action that is to be performed with data. Such
9576 actions could, for example, be to change part of the value's
9577 identifier or to ignore the value completely.
9578 Some of these targets are built into the daemon, see "Built-in
9580 targets" below. Other targets are implemented in plugins which you
9581 have to load prior to using the target. The name of such plugins
9582 starts with the "target_" prefix.
9583 Rule
9585 The combination of any number of matches and at least one target is
9586 called a rule. The target actions will be performed for all values
9587 for which all matches apply. If the rule does not have any matches
9588 associated with it, the target action will be performed for all
9589 values.
9590 Chain
9592 A chain is a list of rules and possibly default targets. The rules
9593 are tried in order and if one matches, the associated target will
9594 be called. If a value is handled by a rule, it depends on the
9595 target whether or not any subsequent rules are considered or if
9596 traversal of the chain is aborted, see "Flow control" below. After
9597 all rules have been checked, the default targets will be executed.
9598 General structure
9600 The following shows the resulting structure:
9601 +---------+
9603 ! Chain !
9604 +---------+
9605 !
9606 V
9607 +---------+ +---------+ +---------+ +---------+
9608 ! Rule !->! Match !->! Match !->! Target !
9609 +---------+ +---------+ +---------+ +---------+
9610 !
9611 V
9612 +---------+ +---------+ +---------+
9613 ! Rule !->! Target !->! Target !
9614 +---------+ +---------+ +---------+
9615 !
9616 V
9617 :
9618 :
9619 !
9620 V
9621 +---------+ +---------+ +---------+
9622 ! Rule !->! Match !->! Target !
9623 +---------+ +---------+ +---------+
9624 !
9625 V
9626 +---------+
9627 ! Default !
9628 ! Target !
9629 +---------+
9630 Flow control
9632 There are four ways to control which way a value takes through the
9633 filter mechanism:
9634 jump
9636 The built-in jump target can be used to "call" another chain, i. e.
9637 process the value with another chain. When the called chain
9638 finishes, usually the next target or rule after the jump is
9639 executed.
9640 stop
9642 The stop condition, signaled for example by the built-in target
9643 stop, causes all processing of the value to be stopped immediately.
9644 return
9646 Causes processing in the current chain to be aborted, but
9647 processing of the value generally will continue. This means that if
9648 the chain was called via Jump, the next target or rule after the
9649 jump will be executed. If the chain was not called by another
9650 chain, control will be returned to the daemon and it may pass the
9651 value to another chain.
9652 continue
9654 Most targets will signal the continue condition, meaning that
9655 processing should continue normally. There is no special built-in
9656 target for this condition.
9657 Synopsis
9659 The configuration reflects this structure directly:
9660 PostCacheChain "PostCache"
9662 <Chain "PostCache">
9663 <Rule "ignore_mysql_show">
9664 <Match "regex">
9665 Plugin "^mysql$"
9666 Type "^mysql_command$"
9667 TypeInstance "^show_"
9668 </Match>
9669 <Target "stop">
9670 </Target>
9671 </Rule>
9672 <Target "write">
9673 Plugin "rrdtool"
9674 </Target>
9675 </Chain>
9676 The above configuration example will ignore all values where the plugin
9678 field is "mysql", the type is "mysql_command" and the type instance
9679 begins with "show_". All other values will be sent to the "rrdtool"
9680 write plugin via the default target of the chain. Since this chain is
9681 run after the value has been added to the cache, the MySQL "show_*"
9682 command statistics will be available via the "unixsock" plugin.
9683 List of configuration options
9685 PreCacheChain ChainName
9686 PostCacheChain ChainName
9687 Configure the name of the "pre-cache chain" and the "post-cache
9688 chain". The argument is the name of a chain that should be executed
9689 before and/or after the values have been added to the cache.
9690 To understand the implications, it's important you know what is
9692 going on inside collectd. The following diagram shows how values
9693 are passed from the read-plugins to the write-plugins:
9694 +---------------+
9696 ! Read-Plugin !
9697 +-------+-------+
9698 !
9699 + - - - - V - - - - +
9700 : +---------------+ :
9701 : ! Pre-Cache ! :
9702 : ! Chain ! :
9703 : +-------+-------+ :
9704 : ! :
9705 : V :
9706 : +-------+-------+ : +---------------+
9707 : ! Cache !--->! Value Cache !
9708 : ! insert ! : +---+---+-------+
9709 : +-------+-------+ : ! !
9710 : ! ,------------' !
9711 : V V : V
9712 : +-------+---+---+ : +-------+-------+
9713 : ! Post-Cache +--->! Write-Plugins !
9714 : ! Chain ! : +---------------+
9715 : +---------------+ :
9716 : :
9717 : dispatch values :
9718 + - - - - - - - - - +
9719 After the values are passed from the "read" plugins to the dispatch
9721 functions, the pre-cache chain is run first. The values are added
9722 to the internal cache afterwards. The post-cache chain is run after
9723 the values have been added to the cache. So why is it such a huge
9724 deal if chains are run before or after the values have been added
9725 to this cache?
9726 Targets that change the identifier of a value list should be
9728 executed before the values are added to the cache, so that the name
9729 in the cache matches the name that is used in the "write" plugins.
9730 The "unixsock" plugin, too, uses this cache to receive a list of
9731 all available values. If you change the identifier after the value
9732 list has been added to the cache, this may easily lead to
9733 confusion, but it's not forbidden of course.
9734 The cache is also used to convert counter values to rates. These
9736 rates are, for example, used by the "value" match (see below). If
9737 you use the rate stored in the cache before the new value is added,
9738 you will use the old, previous rate. Write plugins may use this
9739 rate, too, see the "csv" plugin, for example. The "unixsock"
9740 plugin uses these rates too, to implement the "GETVAL" command.
9741 Last but not last, the stop target makes a difference: If the pre-
9743 cache chain returns the stop condition, the value will not be added
9744 to the cache and the post-cache chain will not be run.
9745 Chain Name
9747 Adds a new chain with a certain name. This name can be used to
9748 refer to a specific chain, for example to jump to it.
9749 Within the Chain block, there can be Rule blocks and Target blocks.
9751 Rule [Name]
9753 Adds a new rule to the current chain. The name of the rule is
9754 optional and currently has no meaning for the daemon.
9755 Within the Rule block, there may be any number of Match blocks and
9757 there must be at least one Target block.
9758 Match Name
9760 Adds a match to a Rule block. The name specifies what kind of match
9761 should be performed. Available matches depend on the plugins that
9762 have been loaded.
9763 The arguments inside the Match block are passed to the plugin
9765 implementing the match, so which arguments are valid here depends
9766 on the plugin being used. If you do not need any to pass any
9767 arguments to a match, you can use the shorter syntax:
9768 Match "foobar"
9770 Which is equivalent to:
9772 <Match "foobar">
9774 </Match>
9775 Target Name
9777 Add a target to a rule or a default target to a chain. The name
9778 specifies what kind of target is to be added. Which targets are
9779 available depends on the plugins being loaded.
9780 The arguments inside the Target block are passed to the plugin
9782 implementing the target, so which arguments are valid here depends
9783 on the plugin being used. If you do not need any to pass any
9784 arguments to a target, you can use the shorter syntax:
9785 Target "stop"
9787 This is the same as writing:
9789 <Target "stop">
9791 </Target>
9792 Built-in targets
9794 The following targets are built into the core daemon and therefore need
9795 no plugins to be loaded:
9796 return
9798 Signals the "return" condition, see the "Flow control" section
9799 above. This causes the current chain to stop processing the value
9800 and returns control to the calling chain. The calling chain will
9801 continue processing targets and rules just after the jump target
9802 (see below). This is very similar to the RETURN target of iptables,
9803 see iptables(8).
9804 This target does not have any options.
9806 Example:
9808 Target "return"
9810 stop
9812 Signals the "stop" condition, see the "Flow control" section above.
9813 This causes processing of the value to be aborted immediately. This
9814 is similar to the DROP target of iptables, see iptables(8).
9815 This target does not have any options.
9817 Example:
9819 Target "stop"
9821 write
9823 Sends the value to "write" plugins.
9824 Available options:
9826 Plugin Name
9828 Name of the write plugin to which the data should be sent. This
9829 option may be given multiple times to send the data to more
9830 than one write plugin. If the plugin supports multiple
9831 instances, the plugin's instance(s) must also be specified.
9832 If no plugin is explicitly specified, the values will be sent to
9834 all available write plugins.
9835 Single-instance plugin example:
9837 <Target "write">
9839 Plugin "rrdtool"
9840 </Target>
9841 Multi-instance plugin example:
9843 <Plugin "write_graphite">
9845 <Node "foo">
9846 ...
9847 </Node>
9848 <Node "bar">
9849 ...
9850 </Node>
9851 </Plugin>
9852 ...
9853 <Target "write">
9854 Plugin "write_graphite/foo"
9855 </Target>
9856 jump
9858 Starts processing the rules of another chain, see "Flow control"
9859 above. If the end of that chain is reached, or a stop condition is
9860 encountered, processing will continue right after the jump target,
9861 i. e. with the next target or the next rule. This is similar to the
9862 -j command line option of iptables, see iptables(8).
9863 Available options:
9865 Chain Name
9867 Jumps to the chain Name. This argument is required and may
9868 appear only once.
9869 Example:
9871 <Target "jump">
9873 Chain "foobar"
9874 </Target>
9875 Available matches
9877 regex
9878 Matches a value using regular expressions.
9879 Available options:
9881 Host Regex
9883 Plugin Regex
9884 PluginInstance Regex
9885 Type Regex
9886 TypeInstance Regex
9887 MetaData String Regex
9888 Match values where the given regular expressions match the
9889 various fields of the identifier of a value. If multiple
9890 regular expressions are given, all regexen must match for a
9891 value to match.
9892 Invert false|true
9894 When set to true, the result of the match is inverted, i.e. all
9895 value lists where all regular expressions apply are not
9896 matched, all other value lists are matched. Defaults to false.
9897 Example:
9899 <Match "regex">
9901 Host "customer[0-9]+"
9902 Plugin "^foobar$"
9903 </Match>
9904 timediff
9906 Matches values that have a time which differs from the time on the
9907 server.
9908 This match is mainly intended for servers that receive values over
9910 the "network" plugin and write them to disk using the "rrdtool"
9911 plugin. RRDtool is very sensitive to the timestamp used when
9912 updating the RRD files. In particular, the time must be ever
9913 increasing. If a misbehaving client sends one packet with a
9914 timestamp far in the future, all further packets with a correct
9915 time will be ignored because of that one packet. What's worse, such
9916 corrupted RRD files are hard to fix.
9917 This match lets one match all values outside a specified time range
9919 (relative to the server's time), so you can use the stop target
9920 (see below) to ignore the value, for example.
9921 Available options:
9923 Future Seconds
9925 Matches all values that are ahead of the server's time by
9926 Seconds or more seconds. Set to zero for no limit. Either
9927 Future or Past must be non-zero.
9928 Past Seconds
9930 Matches all values that are behind of the server's time by
9931 Seconds or more seconds. Set to zero for no limit. Either
9932 Future or Past must be non-zero.
9933 Example:
9935 <Match "timediff">
9937 Future 300
9938 Past 3600
9939 </Match>
9940 This example matches all values that are five minutes or more ahead
9942 of the server or one hour (or more) lagging behind.
9943 value
9945 Matches the actual value of data sources against given minimum /
9946 maximum values. If a data-set consists of more than one data-
9947 source, all data-sources must match the specified ranges for a
9948 positive match.
9949 Available options:
9951 Min Value
9953 Sets the smallest value which still results in a match. If
9954 unset, behaves like negative infinity.
9955 Max Value
9957 Sets the largest value which still results in a match. If
9958 unset, behaves like positive infinity.
9959 Invert true|false
9961 Inverts the selection. If the Min and Max settings result in a
9962 match, no-match is returned and vice versa. Please note that
9963 the Invert setting only effects how Min and Max are applied to
9964 a specific value. Especially the DataSource and Satisfy
9965 settings (see below) are not inverted.
9966 DataSource DSName [DSName ...]
9968 Select one or more of the data sources. If no data source is
9969 configured, all data sources will be checked. If the type
9970 handled by the match does not have a data source of the
9971 specified name(s), this will always result in no match
9972 (independent of the Invert setting).
9973 Satisfy Any|All
9975 Specifies how checking with several data sources is performed.
9976 If set to Any, the match succeeds if one of the data sources is
9977 in the configured range. If set to All the match only succeeds
9978 if all data sources are within the configured range. Default is
9979 All.
9980 Usually All is used for positive matches, Any is used for
9982 negative matches. This means that with All you usually check
9983 that all values are in a "good" range, while with Any you check
9984 if any value is within a "bad" range (or outside the "good"
9985 range).
9986 Either Min or Max, but not both, may be unset.
9988 Example:
9990 # Match all values smaller than or equal to 100. Matches only if all data
9992 # sources are below 100.
9993 <Match "value">
9994 Max 100
9995 Satisfy "All"
9996 </Match>
9997 # Match if the value of any data source is outside the range of 0 - 100.
9999 <Match "value">
10000 Min 0
10001 Max 100
10002 Invert true
10003 Satisfy "Any"
10004 </Match>
10005 empty_counter
10007 Matches all values with one or more data sources of type COUNTER
10008 and where all counter values are zero. These counters usually never
10009 increased since they started existing (and are therefore
10010 uninteresting), or got reset recently or overflowed and you had
10011 really, really bad luck.
10012 Please keep in mind that ignoring such counters can result in
10014 confusing behavior: Counters which hardly ever increase will be
10015 zero for long periods of time. If the counter is reset for some
10016 reason (machine or service restarted, usually), the graph will be
10017 empty (NAN) for a long time. People may not understand why.
10018 hashed
10020 Calculates a hash value of the host name and matches values
10021 according to that hash value. This makes it possible to divide all
10022 hosts into groups and match only values that are in a specific
10023 group. The intended use is in load balancing, where you want to
10024 handle only part of all data and leave the rest for other servers.
10025 The hashing function used tries to distribute the hosts evenly.
10027 First, it calculates a 32 bit hash value using the characters of
10028 the hostname:
10029 hash_value = 0;
10031 for (i = 0; host[i] != 0; i++)
10032 hash_value = (hash_value * 251) + host[i];
10033 The constant 251 is a prime number which is supposed to make this
10035 hash value more random. The code then checks the group for this
10036 host according to the Total and Match arguments:
10037 if ((hash_value % Total) == Match)
10039 matches;
10040 else
10041 does not match;
10042 Please note that when you set Total to two (i. e. you have only two
10044 groups), then the least significant bit of the hash value will be
10045 the XOR of all least significant bits in the host name. One
10046 consequence is that when you have two hosts, "server0.example.com"
10047 and "server1.example.com", where the host name differs in one digit
10048 only and the digits differ by one, those hosts will never end up in
10049 the same group.
10050 Available options:
10052 Match Match Total
10054 Divide the data into Total groups and match all hosts in group
10055 Match as described above. The groups are numbered from zero,
10056 i. e. Match must be smaller than Total. Total must be at least
10057 one, although only values greater than one really do make any
10058 sense.
10059 You can repeat this option to match multiple groups, for
10061 example:
10062 Match 3 7
10064 Match 5 7
10065 The above config will divide the data into seven groups and
10067 match groups three and five. One use would be to keep every
10068 value on two hosts so that if one fails the missing data can
10069 later be reconstructed from the second host.
10070 Example:
10072 # Operate on the pre-cache chain, so that ignored values are not even in the
10074 # global cache.
10075 <Chain "PreCache">
10076 <Rule>
10077 <Match "hashed">
10078 # Divide all received hosts in seven groups and accept all hosts in
10079 # group three.
10080 Match 3 7
10081 </Match>
10082 # If matched: Return and continue.
10083 Target "return"
10084 </Rule>
10085 # If not matched: Return and stop.
10086 Target "stop"
10087 </Chain>
10088 Available targets
10090 notification
10091 Creates and dispatches a notification.
10092 Available options:
10094 Message String
10096 This required option sets the message of the notification. The
10097 following placeholders will be replaced by an appropriate
10098 value:
10099 %{host}
10101 %{plugin}
10102 %{plugin_instance}
10103 %{type}
10104 %{type_instance}
10105 These placeholders are replaced by the identifier field of
10106 the same name.
10107 %{ds:name}
10109 These placeholders are replaced by a (hopefully) human
10110 readable representation of the current rate of this data
10111 source. If you changed the instance name (using the set or
10112 replace targets, see below), it may not be possible to
10113 convert counter values to rates.
10114 Please note that these placeholders are case sensitive!
10116 Severity "FAILURE"|"WARNING"|"OKAY"
10118 Sets the severity of the message. If omitted, the severity
10119 "WARNING" is used.
10120 Example:
10122 <Target "notification">
10124 Message "Oops, the %{type_instance} temperature is currently %{ds:value}!"
10125 Severity "WARNING"
10126 </Target>
10127 replace
10129 Replaces parts of the identifier using regular expressions.
10130 Available options:
10132 Host Regex Replacement
10134 Plugin Regex Replacement
10135 PluginInstance Regex Replacement
10136 TypeInstance Regex Replacement
10137 MetaData String Regex Replacement
10138 DeleteMetaData String Regex
10139 Match the appropriate field with the given regular expression
10140 Regex. If the regular expression matches, that part that
10141 matches is replaced with Replacement. If multiple places of the
10142 input buffer match a given regular expression, only the first
10143 occurrence will be replaced.
10144 You can specify each option multiple times to use multiple
10146 regular expressions one after another.
10147 Example:
10149 <Target "replace">
10151 # Replace "example.net" with "example.com"
10152 Host "\\<example.net\\>" "example.com"
10153 # Strip "www." from hostnames
10155 Host "\\<www\\." ""
10156 </Target>
10157 set Sets part of the identifier of a value to a given string.
10159 Available options:
10161 Host String
10163 Plugin String
10164 PluginInstance String
10165 TypeInstance String
10166 MetaData String String
10167 Set the appropriate field to the given string. The strings for
10168 plugin instance, type instance, and meta data may be empty, the
10169 strings for host and plugin may not be empty. It's currently
10170 not possible to set the type of a value this way.
10171 The following placeholders will be replaced by an appropriate
10173 value:
10174 %{host}
10176 %{plugin}
10177 %{plugin_instance}
10178 %{type}
10179 %{type_instance}
10180 These placeholders are replaced by the identifier field of
10181 the same name.
10182 %{meta:name}
10184 These placeholders are replaced by the meta data value with
10185 the given name.
10186 Please note that these placeholders are case sensitive!
10188 DeleteMetaData String
10190 Delete the named meta data field.
10191 Example:
10193 <Target "set">
10195 PluginInstance "coretemp"
10196 TypeInstance "core3"
10197 </Target>
10198 Backwards compatibility
10200 If you use collectd with an old configuration, i. e. one without a
10201 Chain block, it will behave as it used to. This is equivalent to the
10202 following configuration:
10203 <Chain "PostCache">
10205 Target "write"
10206 </Chain>
10207 If you specify a PostCacheChain, the write target will not be added
10209 anywhere and you will have to make sure that it is called where
10210 appropriate. We suggest to add the above snippet as default target to
10211 your "PostCache" chain.
10212 Examples
10214 Ignore all values, where the hostname does not contain a dot, i. e.
10215 can't be an FQDN.
10216 <Chain "PreCache">
10218 <Rule "no_fqdn">
10219 <Match "regex">
10220 Host "^[^\.]*$"
10221 </Match>
10222 Target "stop"
10223 </Rule>
10224 Target "write"
10225 </Chain>
10226
10228 Ignorelists are a generic framework to either ignore some metrics or
10229 report specific metrics only. Plugins usually provide one or more
10230 options to specify the items (mounts points, devices, ...) and the
10231 boolean option "IgnoreSelected".
10232 Select String
10234 Selects the item String. This option often has a plugin specific
10235 name, e.g. Sensor in the "sensors" plugin. It is also plugin
10236 specific what this string is compared to. For example, the "df"
10237 plugin's MountPoint compares it to a mount point and the "sensors"
10238 plugin's Sensor compares it to a sensor name.
10239 By default, this option is doing a case-sensitive full-string
10241 match. The following config will match "foo", but not "Foo":
10242 Select "foo"
10244 If String starts and ends with "/" (a slash), the string is
10246 compiled as a regular expression. For example, so match all item
10247 starting with "foo", use could use the following syntax:
10248 Select "/^foo/"
10250 The regular expression is not anchored, i.e. the following config
10252 will match "foobar", "barfoo" and "AfooZ":
10253 Select "/foo/"
10255 The Select option may be repeated to select multiple items.
10257 IgnoreSelected true|false
10259 If set to true, matching metrics are ignored and all other metrics
10260 are collected. If set to false, matching metrics are collected and
10261 all other metrics are ignored.
10262
10264 collectd(1), collectd-exec(5), collectd-perl(5), collectd-unixsock(5),
10265 types.db(5), hddtemp(8), iptables(8), kstat(3KSTAT), mbmon(1), psql(1),
10266 regex(7), rrdtool(1), sensors(1)
10267
10269 Florian Forster <octo@collectd.org>
102705.9.2 2019-09-16 COLLECTD.CONF(5)