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.
5 ==============================
6 collectd VES plugin User Guide
7 ==============================
8 The Barometer repository contains a python based write plugin for VES.
10 The plugin currently supports pushing platform relevant metrics through the
11 additional measurements field for VES.
13 **Please note**: Hardcoded configuration values will be modified so that they
14 are configurable through the configuration file.
16 Installation Instructions:
17 --------------------------
23 $ sudo apt-get install collectd
25 3. Modify the collectd configuration script: `/etc/collectd/collectd.conf`
34 ModulePath "/path/to/your/python/modules"
39 # VES plugin configuration (see next section below)
43 where "/path/to/your/python/modules" is the path to where you cloned this repo
45 VES python plugin configuration description:
46 --------------------------------------------
48 **Note** Details of the Vendor Event Listener REST service
50 REST resources are defined with respect to a ServerRoot:
54 ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
56 REST resources are of the form:
60 {ServerRoot}/eventListener/v{apiVersion}`
61 {ServerRoot}/eventListener/v{apiVersion}/{topicName}`
62 {ServerRoot}/eventListener/v{apiVersion}/eventBatch`
66 * VES domain name. It can be IP address or hostname of VES collector
67 (default: `127.0.0.1`)
70 * VES port (default: `30000`)
73 * Used as the "optionalRoutingPath" element in the REST path (default: `empty`)
76 * Used as the "topicName" element in the REST path (default: `empty`)
78 **UseHttps** *true|false*
79 * Allow plugin to use HTTPS instead of HTTP (default: `false`)
81 **Username** *"username"*
82 * VES collector user name (default: `empty`)
84 **Password** *"passwd"*
85 * VES collector password (default: `empty`)
87 **FunctionalRole** *"role"*
88 * Used as the 'functionalRole' field of 'commonEventHeader' event (default:
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`.
95 Other collectd.conf configurations
96 ----------------------------------
97 Please ensure that FQDNLookup is set to false
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).
112 Connection "qemu:///system"
117 Please ensure that the cpu plugin is enabled and configured as follows
125 ValuesPercentage true
128 Please ensure that the aggregation plugin is enabled and configured as follows
132 LoadPlugin aggregation
139 GroupBy "TypeInstance"
140 SetPlugin "cpu-aggregation"
141 CalculateAverage true
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.
151 If custom UUID needs to be provided, the following configuration is required in collectd.conf
160 Where "/etc/uuid" is a file containing custom UUID.
162 Please also ensure that the following plugins are enabled:
170 VES plugin notification example
171 -------------------------------
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.
183 <Plugin "cpu-aggregation">
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