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