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 **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 **SendEventInterval** *interval*
  95   This configuration option controls how often (sec) collectd data is sent to
  96   Vendor Event Listener (default: `20`)
  97
  98 **ApiVersion** *version*
  99   Used as the "apiVersion" element in the REST path (default: `1`)
 100
 101 Other collectd.conf configurations
 102 ----------------------------------
 103 Please ensure that FQDNLookup is set to false
 104
 105 .. code:: bash
 106
 107     FQDNLookup   false
 108
 109 Please ensure that the virt plugin is enabled and configured as follows. This configuration
 110 is is required only on a host side ('GuestRunning' = false).
 111
 112 .. code:: bash
 113
 114     LoadPlugin virt
 115
 116     <Plugin virt>
 117             Connection "qemu:///system"
 118             RefreshInterval 60
 119             HostnameFormat uuid
 120     </Plugin>
 121
 122 Please ensure that the cpu plugin is enabled and configured as follows
 123
 124 .. code:: bash
 125
 126     LoadPlugin cpu
 127
 128     <Plugin cpu>
 129         ReportByCpu false
 130         ValuesPercentage true
 131     </Plugin>
 132
 133 **Note**: The `ReportByCpu` option should be set to `true` (default) if VES pugin
 134 is running on guest machine ('GuestRunning' = true).
 135
 136 Please ensure that the aggregation plugin is enabled and configured as follows
 137 (required if 'GuestRunning' = true)
 138
 139 .. code:: bash
 140
 141     LoadPlugin aggregation
 142
 143     <Plugin aggregation>
 144         <Aggregation>
 145                 Plugin "cpu"
 146                 Type "percent"
 147                 GroupBy "Host"
 148                 GroupBy "TypeInstance"
 149                 SetPlugin "cpu-aggregation"
 150                 CalculateAverage true
 151         </Aggregation>
 152     </Plugin>
 153
 154 If plugin is running on a guest side, it is important to enable uuid plugin
 155 too. In this case the hostname in event message will be represented as UUID
 156 instead of system host name.
 157
 158 .. code:: bash
 159
 160   LoadPlugin uuid
 161
 162 If custom UUID needs to be provided, the following configuration is required in collectd.conf
 163 file:
 164
 165 .. code:: bash
 166
 167     <Plugin uuid>
 168         UUIDFile "/etc/uuid"
 169     </Plugin>
 170
 171 Where "/etc/uuid" is a file containing custom UUID.
 172
 173 Please also ensure that the following plugins are enabled:
 174
 175 .. code:: bash
 176
 177     LoadPlugin disk
 178     LoadPlugin interface
 179     LoadPlugin memory
 180
 181 VES plugin notification example
 182 -------------------------------
 183
 184 A good example of collectD notification is monitoring of CPU load on a host or guest using
 185 'threshold' plugin. The following configuration will setup VES plugin to send 'Fault'
 186 event every time a CPU idle value is out of range (e.g.: WARNING: CPU-IDLE < 50%, CRITICAL:
 187 CPU-IDLE < 30%) and send 'Fault' NORMAL event if CPU idle value is back to normal.
 188
 189 .. code:: bash
 190
 191     LoadPlugin threshold
 192
 193     <Plugin "threshold">
 194          <Plugin "cpu-aggregation">
 195             <Type "percent">
 196               WarningMin    50.0
 197               WarningMax   100.0
 198               FailureMin    30.0
 199               FailureMax   100.0
 200               Instance "idle"
 201               Hits 1
 202             </Type>
 203         </Plugin>
 204     </Plugin>
 205
 206 More detailed information on how to configure collectD thresholds(memory, cpu
 207 etc.) can be found here at
 208 https://collectd.org/documentation/manpages/collectd-threshold.5.shtml