docs/requirements/02-collectd.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation and others.
   4
   5 collectd
   6 ~~~~~~~~
   7 collectd is a daemon which collects system performance statistics periodically
   8 and provides a variety of mechanisms to publish the collected metrics. It
   9 supports more than 90 different input and output plugins. Input plugins retrieve
  10 metrics and publish them to the collectd deamon, while output plugins publish
  11 the data they receive to an end point. collectd also has infrastructure to
  12 support thresholding and notification.
  13
  14 collectd statistics and Notifications
  15 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  16 Within collectd notifications and performance data are dispatched in the same
  17 way. There are producer plugins (plugins that create notifications/metrics),
  18 and consumer plugins (plugins that receive notifications/metrics and do
  19 something with them).
  20
  21 Statistics in collectd consist of a value list. A value list includes:
  22
  23 * Values, can be one of:
  24
  25   * Derive: used for values where a change in the value since it's last been
  26     read is of interest. Can be used to calculate and store a rate.
  27
  28   * Counter: similar to derive values, but take the possibility of a counter
  29     wrap around into consideration.
  30
  31   * Gauge: used for values that are stored as is.
  32
  33   * Absolute: used for counters that are reset after reading.
  34
  35 * Value length: the number of values in the data set.
  36
  37 * Time: timestamp at which the value was collected.
  38
  39 * Interval: interval at which to expect a new value.
  40
  41 * Host: used to identify the host.
  42
  43 * Plugin: used to identify the plugin.
  44
  45 * Plugin instance (optional): used to group a set of values together. For e.g.
  46   values belonging to a DPDK interface.
  47
  48 * Type: unit used to measure a value. In other words used to refer to a data
  49   set.
  50
  51 * Type instance (optional): used to distinguish between values that have an
  52   identical type.
  53
  54 * meta data: an opaque data structure that enables the passing of additional
  55   information about a value list. "Meta data in the global cache can be used to
  56   store arbitrary information about an identifier" [7].
  57
  58 Host, plugin, plugin instance, type and type instance uniquely identify a
  59 collectd value.
  60
  61 Values lists are often accompanied by data sets that describe the values in more
  62 detail. Data sets consist of:
  63
  64 * A type: a name which uniquely identifies a data set.
  65
  66 * One or more data sources (entries in a data set) which include:
  67
  68   * The name of the data source. If there is only a single data source this is
  69     set to "value".
  70
  71   * The type of the data source, one of: counter, gauge, absolute or derive.
  72
  73   * A min and a max value.
  74
  75 Types in collectd are defined in types.db. Examples of types in types.db:
  76
  77 .. code-block:: console
  78
  79     bitrate    value:GAUGE:0:4294967295
  80     counter    value:COUNTER:U:U
  81     if_octets  rx:COUNTER:0:4294967295, tx:COUNTER:0:4294967295
  82
  83 In the example above if_octets has two data sources: tx and rx.
  84
  85 Notifications in collectd are generic messages containing:
  86
  87 * An associated severity, which can be one of OKAY, WARNING, and FAILURE.
  88
  89 * A time.
  90
  91 * A Message
  92
  93 * A host.
  94
  95 * A plugin.
  96
  97 * A plugin instance (optional).
  98
  99 * A type.
 100
 101 * A types instance (optional).
 102
 103 * Meta-data.