Merge "collectd VES agent: collectd VES agent code"

2 files changed, 197 insertions, 0 deletions

diff --git a/docs/userguide/collectd.ves.userguide.rst b/docs/userguide/collectd.ves.userguide.rst
new file mode 100644
index 00000000..a83b6469
--- /dev/null
+++ b/docs/userguide/collectd.ves.userguide.rst
@@ -0,0 +1,196 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Intel Corporation and others.
+
+collectd VES plugin
+===================
+The Barometer repository contains a python based write plugin for VES.
+
+The plugin currently supports pushing platform relevant metrics through the
+additional measurements field for VES.
+
+**Please note**: Hardcoded configuration values will be modified so that they
+are configurable through the configuration file.
+
+Installation Instructions:
+--------------------------
+1. Clone this repo
+2. Install collectd
+
+.. code:: bash
+
+   $ sudo apt-get install collectd
+
+3. Modify the collectd configuration script: `/etc/collectd/collectd.conf`
+
+.. code:: bash
+
+    <LoadPlugin python>
+      Globals true
+    </LoadPlugin>
+
+    <Plugin python>
+      ModulePath "/path/to/your/python/modules"
+      LogTraces true
+      Interactive false
+      Import "ves_plugin"
+    <Module ves_plugin>
+    # VES plugin configuration (see next section below)
+    </Module>
+    </Plugin>
+
+where "/path/to/your/python/modules" is the path to where you cloned this repo
+
+VES python plugin configuration description:
+--------------------------------------------
+
+**Note** Details of the Vendor Event Listener REST service
+
+REST resources are defined with respect to a ServerRoot:
+
+.. code:: bash
+
+    ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
+
+REST resources are of the form:
+
+.. code:: bash
+
+    {ServerRoot}/eventListener/v{apiVersion}`
+    {ServerRoot}/eventListener/v{apiVersion}/{topicName}`
+    {ServerRoot}/eventListener/v{apiVersion}/eventBatch`
+
+
+**Domain** *"host"*
+* VES domain name. It can be IP address or hostname of VES collector
+(default: `127.0.0.1`)
+
+**Port** *port*
+* VES port (default: `30000`)
+
+**Path** *"path"*
+* Used as the "optionalRoutingPath" element in the REST path (default: `empty`)
+
+**Topic** *"path"*
+* Used as the "topicName" element in the REST  path (default: `empty`)
+
+**UseHttps** *true|false*
+* Allow plugin to use HTTPS instead of HTTP (default: `false`)
+
+**Username** *"username"*
+* VES collector user name (default: `empty`)
+
+**Password** *"passwd"*
+* VES collector password (default: `empty`)
+
+**FunctionalRole** *"role"*
+* Used as the 'functionalRole' field of 'commonEventHeader' event (default:
+`Collectd VES Agent`)
+
+**GuestRunning** *true|false*
+* This option is used if the collectd is running on a guest machine, e.g this
+option should be set to `true` in this case. Defaults to `false`.
+
+Other collectd.conf configurations
+----------------------------------
+Please ensure that FQDNLookup is set to false
+
+.. code:: bash
+
+    FQDNLookup   false
+
+
+Please ensure that the virt plugin is enabled and configured as follows. This configuration
+is is required only on a host side ('GuestRunning' = false).
+
+.. code:: bash
+
+    LoadPlugin virt
+
+    <Plugin virt>
+            Connection "qemu:///system"
+            RefreshInterval 60
+            HostnameFormat uuid
+    </Plugin>
+
+Please ensure that the cpu plugin is enabled and configured as follows
+
+.. code:: bash
+
+    LoadPlugin cpu
+
+    <Plugin cpu>
+        ReportByCpu false
+        ValuesPercentage true
+    </Plugin>
+
+Please ensure that the aggregation plugin is enabled and configured as follows
+
+.. code:: bash
+
+    LoadPlugin aggregation
+
+    <Plugin aggregation>
+        <Aggregation>
+                Plugin "cpu"
+                Type "percent"
+                GroupBy "Host"
+                GroupBy "TypeInstance"
+                SetPlugin "cpu-aggregation"
+                CalculateAverage true
+        </Aggregation>
+    </Plugin>
+
+If plugin is running on a guest side, it is important to enable uuid plugin
+too. In this case the hostname in event message will be represented as UUID
+instead of system host name.
+
+LoadPlugin uuid
+
+If custom UUID needs to be provided, the following configuration is required in collectd.conf
+file:
+
+.. code:: bash
+
+    <Plugin uuid>
+        UUIDFile "/etc/uuid"
+    </Plugin>
+
+Where "/etc/uuid" is a file containing custom UUID.
+
+Please also ensure that the following plugins are enabled:
+
+.. code:: bash
+
+    LoadPlugin disk
+    LoadPlugin interface
+    LoadPlugin memory
+
+VES plugin notification example
+-------------------------------
+
+A good example of collectD notification is monitoring of CPU load on a host or guest using
+'threshold' plugin. The following configuration will setup VES plugin to send 'Fault'
+event every time a CPU idle value is out of range (e.g.: WARNING: CPU-IDLE < 50%, CRITICAL:
+CPU-IDLE < 30%) and send 'Fault' NORMAL event if CPU idle value is back to normal.
+
+.. code:: bash
+
+    LoadPlugin threshold
+
+    <Plugin "threshold">
+         <Plugin "cpu-aggregation">
+            <Type "percent">
+              WarningMin    50.0
+              WarningMax   100.0
+              FailureMin    30.0
+              FailureMax   100.0
+              Instance "idle"
+              Hits 1
+            </Type>
+        </Plugin>
+    </Plugin>
+
+More detailed information on how to configure collectD thresholds(memory, cpu
+etc.) can be found here at
+https://collectd.org/documentation/manpages/collectd-threshold.5.shtml
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
index bf62a43d..aaeadf91 100644
--- a/docs/userguide/index.rst
+++ b/docs/userguide/index.rst
@@ -16,3 +16,4 @@ Barometer user guide
      :maxdepth: 3
 
      collectd.userguide.rst
+     collectd.ves.userguide.rst