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 ves_plugin.py,
  44 which is located in this repo.
  45
  46 VES python plugin configuration description:
  47 --------------------------------------------
  48
  49 **Note** Details of the Vendor Event Listener REST service
  50
  51 REST resources are defined with respect to a ServerRoot:
  52
  53 .. code:: bash
  54
  55     ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
  56
  57 REST resources are of the form:
  58
  59 .. code:: bash
  60
  61     {ServerRoot}/eventListener/v{apiVersion}`
  62     {ServerRoot}/eventListener/v{apiVersion}/{topicName}`
  63     {ServerRoot}/eventListener/v{apiVersion}/eventBatch`
  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 **SendEventInterval** *interval*
  92   This configuration option controls how often (sec) collectd data is sent to
  93   Vendor Event Listener (default: `20`)
  94
  95 **ApiVersion** *version*
  96   Used as the "apiVersion" element in the REST path (default: `5.1`)
  97
  98 Other collectd.conf configurations
  99 ----------------------------------
 100 Please ensure that FQDNLookup is set to false
 101
 102 .. code:: bash
 103
 104     FQDNLookup   false
 105
 106 Please ensure that the virt plugin is enabled and configured as follows.
 107
 108 .. code:: bash
 109
 110     LoadPlugin virt
 111
 112     <Plugin virt>
 113             Connection "qemu:///system"
 114             RefreshInterval 60
 115             HostnameFormat uuid
 116             PluginInstanceFormat name
 117             ExtraStats "cpu_util perf"
 118     </Plugin>
 119
 120
 121 .. note:: For more detailed information on the `virt` plugin configuration,
 122   requirements etc., please see the userguide of the collectd virt plugin.
 123
 124 Please ensure that the cpu plugin is enabled and configured as follows
 125
 126 .. code:: bash
 127
 128     LoadPlugin cpu
 129
 130     <Plugin cpu>
 131         ReportByCpu false
 132         ValuesPercentage true
 133     </Plugin>
 134
 135 To report the host name as a UUID the uuid plugin can be used.
 136
 137 .. code:: bash
 138
 139     LoadPlugin uuid
 140
 141 If a custom UUID needs to be provided, the following configuration is required in collectd.conf
 142 file:
 143
 144 .. code:: bash
 145
 146     <Plugin uuid>
 147         UUIDFile "/etc/uuid"
 148     </Plugin>
 149
 150 Where "/etc/uuid" is a file containing custom UUID.
 151
 152 Please also ensure that the following plugins are enabled:
 153
 154 .. code:: bash
 155
 156     LoadPlugin disk
 157     LoadPlugin interface
 158     LoadPlugin memory
 159
 160 VES plugin notification example
 161 -------------------------------
 162
 163 A good example of collectD notification is monitoring of the total CPU usage on a VM
 164 using the 'threshold' plugin. The following configuration will setup VES plugin to send 'Fault'
 165 event every time a total VM CPU value is out of range (e.g.: WARNING: VM CPU TOTAL > 50%,
 166 CRITICAL: VM CPU TOTAL > 96%) and send 'Fault' NORMAL event if the CPU value is back
 167 to normal. In the example below, there is one VM with two CPUs configured which is running
 168 on the host with a total of 48 cores. Thus, the threshold value 2.08 (100/48) means that
 169 one CPU of the VM is fully loaded (e.g.: 50% of total CPU usage of the VM) and 4.0 means
 170 96% of total CPU usage of the VM. Those values can also be obtained by virt-top
 171 command line tool.
 172
 173 .. code:: bash
 174
 175     LoadPlugin threshold
 176
 177     <Plugin "threshold">
 178         <Plugin "virt">
 179             <Type "percent">
 180                 WarningMax    2.08
 181                 FailureMax    4.0
 182                 Instance      "virt_cpu_total"
 183             </Type>
 184         </Plugin>
 185     </Plugin>
 186
 187 More detailed information on how to configure collectD thresholds can be found at
 188 https://collectd.org/documentation/manpages/collectd-threshold.5.shtml