docs/userguide/collectd.ves.userguide.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 VES plugin
   6 ===================
   7 The Barometer repository contains a python based write plugin for VES.
   8
   9 The plugin currently supports pushing platform relevant metrics through the
  10 additional measurements field for VES.
  11
  12 **Please note**: Hardcoded configuration values will be modified so that they
  13 are configurable through the configuration file.
  14
  15 Installation Instructions:
  16 --------------------------
  17 1. Clone this repo
  18 2. Install collectd
  19
  20 .. code:: bash
  21
  22    $ sudo apt-get install collectd
  23
  24 3. Modify the collectd configuration script: `/etc/collectd/collectd.conf`
  25
  26 .. code:: bash
  27
  28     <LoadPlugin python>
  29       Globals true
  30     </LoadPlugin>
  31
  32     <Plugin python>
  33       ModulePath "/path/to/your/python/modules"
  34       LogTraces true
  35       Interactive false
  36       Import "ves_plugin"
  37     <Module ves_plugin>
  38     # VES plugin configuration (see next section below)
  39     </Module>
  40     </Plugin>
  41
  42 where "/path/to/your/python/modules" is the path to where you cloned this repo
  43
  44 VES python plugin configuration description:
  45 --------------------------------------------
  46
  47 **Note** Details of the Vendor Event Listener REST service
  48
  49 REST resources are defined with respect to a ServerRoot:
  50
  51 .. code:: bash
  52
  53     ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
  54
  55 REST resources are of the form:
  56
  57 .. code:: bash
  58
  59     {ServerRoot}/eventListener/v{apiVersion}`
  60     {ServerRoot}/eventListener/v{apiVersion}/{topicName}`
  61     {ServerRoot}/eventListener/v{apiVersion}/eventBatch`
  62
  63
  64 **Domain** *"host"*
  65 * VES domain name. It can be IP address or hostname of VES collector
  66 (default: `127.0.0.1`)
  67
  68 **Port** *port*
  69 * VES port (default: `30000`)
  70
  71 **Path** *"path"*
  72 * Used as the "optionalRoutingPath" element in the REST path (default: `empty`)
  73
  74 **Topic** *"path"*
  75 * Used as the "topicName" element in the REST  path (default: `empty`)
  76
  77 **UseHttps** *true|false*
  78 * Allow plugin to use HTTPS instead of HTTP (default: `false`)
  79
  80 **Username** *"username"*
  81 * VES collector user name (default: `empty`)
  82
  83 **Password** *"passwd"*
  84 * VES collector password (default: `empty`)
  85
  86 **FunctionalRole** *"role"*
  87 * Used as the 'functionalRole' field of 'commonEventHeader' event (default:
  88 `Collectd VES Agent`)
  89
  90 **GuestRunning** *true|false*
  91 * This option is used if the collectd is running on a guest machine, e.g this
  92 option should be set to `true` in this case. Defaults to `false`.
  93
  94 Other collectd.conf configurations
  95 ----------------------------------
  96 Please ensure that FQDNLookup is set to false
  97
  98 .. code:: bash
  99
 100     FQDNLookup   false
 101
 102
 103 Please ensure that the virt plugin is enabled and configured as follows. This configuration
 104 is is required only on a host side ('GuestRunning' = false).
 105
 106 .. code:: bash
 107
 108     LoadPlugin virt
 109
 110     <Plugin virt>
 111             Connection "qemu:///system"
 112             RefreshInterval 60
 113             HostnameFormat uuid
 114     </Plugin>
 115
 116 Please ensure that the cpu plugin is enabled and configured as follows
 117
 118 .. code:: bash
 119
 120     LoadPlugin cpu
 121
 122     <Plugin cpu>
 123         ReportByCpu false
 124         ValuesPercentage true
 125     </Plugin>
 126
 127 Please ensure that the aggregation plugin is enabled and configured as follows
 128
 129 .. code:: bash
 130
 131     LoadPlugin aggregation
 132
 133     <Plugin aggregation>
 134         <Aggregation>
 135                 Plugin "cpu"
 136                 Type "percent"
 137                 GroupBy "Host"
 138                 GroupBy "TypeInstance"
 139                 SetPlugin "cpu-aggregation"
 140                 CalculateAverage true
 141         </Aggregation>
 142     </Plugin>
 143
 144 If plugin is running on a guest side, it is important to enable uuid plugin
 145 too. In this case the hostname in event message will be represented as UUID
 146 instead of system host name.
 147
 148 LoadPlugin uuid
 149
 150 If custom UUID needs to be provided, the following configuration is required in collectd.conf
 151 file:
 152
 153 .. code:: bash
 154
 155     <Plugin uuid>
 156         UUIDFile "/etc/uuid"
 157     </Plugin>
 158
 159 Where "/etc/uuid" is a file containing custom UUID.
 160
 161 Please also ensure that the following plugins are enabled:
 162
 163 .. code:: bash
 164
 165     LoadPlugin disk
 166     LoadPlugin interface
 167     LoadPlugin memory
 168
 169 VES plugin notification example
 170 -------------------------------
 171
 172 A good example of collectD notification is monitoring of CPU load on a host or guest using
 173 'threshold' plugin. The following configuration will setup VES plugin to send 'Fault'
 174 event every time a CPU idle value is out of range (e.g.: WARNING: CPU-IDLE < 50%, CRITICAL:
 175 CPU-IDLE < 30%) and send 'Fault' NORMAL event if CPU idle value is back to normal.
 176
 177 .. code:: bash
 178
 179     LoadPlugin threshold
 180
 181     <Plugin "threshold">
 182          <Plugin "cpu-aggregation">
 183             <Type "percent">
 184               WarningMin    50.0
 185               WarningMax   100.0
 186               FailureMin    30.0
 187               FailureMax   100.0
 188               Instance "idle"
 189               Hits 1
 190             </Type>
 191         </Plugin>
 192     </Plugin>
 193
 194 More detailed information on how to configure collectD thresholds(memory, cpu
 195 etc.) can be found here at
 196 https://collectd.org/documentation/manpages/collectd-threshold.5.shtml