src: build all dependencies and plugins

Build all dependencies and plugins. Provide sample plugin configurations and
update user guide.

Change-Id: I5170c84529e514e12bb1bd4dc34ecdd93eb764d7
Signed-off-by: Maryam Tahhan <maryam.tahhan@intel.com>

9 files changed, 202 insertions, 167 deletions

diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst
index d5b161f6..d97583c2 100644
--- a/docs/configguide/index.rst
+++ b/docs/configguide/index.rst
@@ -2,10 +2,6 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright (c) 2016 Open Platform for NFV Project, Inc. and its contributors
 
-==================================
-Barometer Guides and Installation
-==================================
-
 .. toctree::
     :numbered:
     :maxdepth: 3
diff --git a/docs/index.rst b/docs/index.rst
index 00e13366..a6d3b939 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,9 +2,9 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Intel Corporation and others.
 
-**********
+=========
 Barometer
-**********
+=========
 
 :Project: Barometer, https://wiki.opnfv.org/display/fastpath/Barometer+Home
 :Authors: Maryam Tahhan <maryam.tahhan@intel.com>
@@ -24,7 +24,7 @@ Table of Contents:
      :maxdepth: 4
      :numbered:
 
-     requirements/index.rst
-     configguide/index.rst
-     userguide/index.rst
-     release/index.rst
+     ./requirements/index.rst
+     ./configguide/index.rst
+     ./userguide/index.rst
+     ./release/index.rst
diff --git a/docs/requirements/02-collectd.rst b/docs/requirements/02-collectd.rst
new file mode 100755
index 00000000..2303fadc
--- /dev/null
+++ b/docs/requirements/02-collectd.rst
@@ -0,0 +1,103 @@
+.. 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
+~~~~~~~~
+collectd is a daemon which collects system performance statistics periodically
+and provides a variety of mechanisms to publish the collected metrics. It
+supports more than 90 different input and output plugins. Input plugins retrieve
+metrics and publish them to the collectd deamon, while output plugins publish
+the data they receive to an end point. collectd also has infrastructure to
+support thresholding and notification.
+
+collectd statistics and Notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Within collectd notifications and performance data are dispatched in the same
+way. There are producer plugins (plugins that create notifications/metrics),
+and consumer plugins (plugins that receive notifications/metrics and do
+something with them).
+
+Statistics in collectd consist of a value list. A value list includes:
+
+* Values, can be one of:
+
+  * Derive: used for values where a change in the value since it's last been
+    read is of interest. Can be used to calculate and store a rate.
+
+  * Counter: similar to derive values, but take the possibility of a counter
+    wrap around into consideration.
+
+  * Gauge: used for values that are stored as is.
+
+  * Absolute: used for counters that are reset after reading.
+
+* Value length: the number of values in the data set.
+
+* Time: timestamp at which the value was collected.
+
+* Interval: interval at which to expect a new value.
+
+* Host: used to identify the host.
+
+* Plugin: used to identify the plugin.
+
+* Plugin instance (optional): used to group a set of values together. For e.g.
+  values belonging to a DPDK interface.
+
+* Type: unit used to measure a value. In other words used to refer to a data
+  set.
+
+* Type instance (optional): used to distinguish between values that have an
+  identical type.
+
+* meta data: an opaque data structure that enables the passing of additional
+  information about a value list. "Meta data in the global cache can be used to
+  store arbitrary information about an identifier" [7].
+
+Host, plugin, plugin instance, type and type instance uniquely identify a
+collectd value.
+
+Values lists are often accompanied by data sets that describe the values in more
+detail. Data sets consist of:
+
+* A type: a name which uniquely identifies a data set.
+
+* One or more data sources (entries in a data set) which include:
+
+  * The name of the data source. If there is only a single data source this is
+    set to "value".
+
+  * The type of the data source, one of: counter, gauge, absolute or derive.
+
+  * A min and a max value.
+
+Types in collectd are defined in types.db. Examples of types in types.db:
+
+.. code-block:: console
+
+    bitrate    value:GAUGE:0:4294967295
+    counter    value:COUNTER:U:U
+    if_octets  rx:COUNTER:0:4294967295, tx:COUNTER:0:4294967295
+
+In the example above if_octets has two data sources: tx and rx.
+
+Notifications in collectd are generic messages containing:
+
+* An associated severity, which can be one of OKAY, WARNING, and FAILURE.
+
+* A time.
+
+* A Message
+
+* A host.
+
+* A plugin.
+
+* A plugin instance (optional).
+
+* A type.
+
+* A types instance (optional).
+
+* Meta-data.
diff --git a/docs/userguide/keepalive.userguide.rst b/docs/requirements/03-dpdk.rst
index 4b6e990d..ad7c8c78 100644
--- a/docs/userguide/keepalive.userguide.rst
+++ b/docs/requirements/03-dpdk.rst
@@ -2,8 +2,50 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Intel Corporation and others.
 
+DPDK Enhancements
+==================
+This section will discuss the Barometer features that were integrated with DPDK.
+
+Measuring Telco Traffic and Performance KPIs
+--------------------------------------------
+This section will discuss the Barometer features that enable Measuring Telco Traffic
+and Performance KPIs.
+
+.. Figure:: stats_and_timestamps.png
+
+   Measuring Telco Traffic and Performance KPIs
+
+* The very first thing Barometer enabled was a call-back API in DPDK and an
+  associated application that used the API to demonstrate how to timestamp
+  packets and measure packet latency in DPDK (the sample app is called
+  rxtx_callbacks). This was upstreamed to DPDK 2.0 and is represented by
+  the interfaces 1 and 2 in Figure 1.2.
+
+* The second thing Barometer implemented in DPDK is the extended NIC statistics API,
+  which exposes NIC stats including error stats to the DPDK user by reading the
+  registers on the NIC. This is represented by interface 3 in Figure 1.2.
+
+  * For DPDK 2.1 this API was only implemented for the ixgbe (10Gb) NIC driver,
+    in association with a sample application that runs as a DPDK secondary
+    process and retrieves the extended NIC stats.
+
+  * For DPDK 2.2 the API was implemented for igb, i40e and all the Virtual
+    Functions (VFs) for all drivers.
+
+  * For DPDK 16.07 the API migrated from using string value pairs to using id
+    value pairs, improving the overall performance of the API.
+
+Monitoring DPDK interfaces
+--------------------------
+With the features Barometer enabled in DPDK to enable measuring Telco traffic and
+performance KPIs, we can now retrieve NIC statistics including error stats and
+relay them to a DPDK user. The next step is to enable monitoring of the DPDK
+interfaces based on the stats that we are retrieving from the NICs, by relaying
+the information to a higher level Fault Management entity. To enable this Barometer
+has been enabling a number of plugins for collectd.
+
 DPDK Keep Alive description
-===========================
+---------------------------
 SFQM aims to enable fault detection within DPDK, the very first feature to
 meet this goal is the DPDK Keep Alive Sample app that is part of DPDK 2.2.
 
@@ -29,7 +71,7 @@ detection and notification.
   heartbeat mechanism.
 
 DPDK Keep Alive Sample App Internals
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This section provides some explanation of the The Keep-Alive/'Liveliness'
 conceptual scheme as well as the DPDK Keep Alive App. The initialization and
 run-time paths are very similar to those of the L2 forwarding application (see
@@ -51,7 +93,7 @@ The Keep-Alive/'Liveliness' conceptual scheme is:
 to monitor the Keep Alive Monitor Agent Core.
 
 DPDK Keep Alive Sample App Code Internals
------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The following section provides some explanation of the code aspects that are
 specific to the Keep Alive sample application.
 
diff --git a/docs/userguide/dpdk_ka.png b/docs/requirements/dpdk_ka.png
index 4a45e10c..4a45e10c 100644
--- a/docs/userguide/dpdk_ka.png
+++ b/docs/requirements/dpdk_ka.png
diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst
index a9be153d..b36f4513 100644
--- a/docs/requirements/index.rst
+++ b/docs/requirements/index.rst
@@ -7,3 +7,5 @@
      :numbered:
 
      01-intro.rst
+     02-collectd.rst
+     03-dpdk.rst
diff --git a/docs/userguide/stats_and_timestamps.png b/docs/requirements/stats_and_timestamps.png
index 84aef726..84aef726 100644
--- a/docs/userguide/stats_and_timestamps.png
+++ b/docs/requirements/stats_and_timestamps.png
diff --git a/docs/userguide/collectd.userguide.rst b/docs/userguide/collectd.userguide.rst
index 5151befc..8bf666e2 100644
--- a/docs/userguide/collectd.userguide.rst
+++ b/docs/userguide/collectd.userguide.rst
@@ -2,153 +2,8 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Intel Corporation and others.
 
-collectd plugins description
-============================
-The SFQM collectd plugins enable the ability to monitor DPDK interfaces by
-exposing stats and the relevant events to higher level telemetry and fault
-management applications. The following sections will discuss the SFQM features
-in detail.
-
-Measuring Telco Traffic and Performance KPIs
---------------------------------------------
-This section will discuss the SFQM features that enable Measuring Telco Traffic
-and Performance KPIs.
-
-.. Figure:: stats_and_timestamps.png
-
-   Measuring Telco Traffic and Performance KPIs
-
-* The very first thing SFQM enabled was a call-back API in DPDK and an
-  associated application that used the API to demonstrate how to timestamp
-  packets and measure packet latency in DPDK (the sample app is called
-  rxtx_callbacks). This was upstreamed to DPDK 2.0 and is represented by
-  the interfaces 1 and 2 in Figure 1.2.
-
-* The second thing SFQM implemented in DPDK is the extended NIC statistics API,
-  which exposes NIC stats including error stats to the DPDK user by reading the
-  registers on the NIC. This is represented by interface 3 in Figure 1.2.
-
-  * For DPDK 2.1 this API was only implemented for the ixgbe (10Gb) NIC driver,
-    in association with a sample application that runs as a DPDK secondary
-    process and retrieves the extended NIC stats.
-
-  * For DPDK 2.2 the API was implemented for igb, i40e and all the Virtual
-    Functions (VFs) for all drivers.
-
-  * For DPDK 16.07 the API migrated from using string value pairs to using id
-    value pairs, improving the overall performance of the API.
-
-Monitoring DPDK interfaces
---------------------------
-With the features SFQM enabled in DPDK to enable measuring Telco traffic and
-performance KPIs, we can now retrieve NIC statistics including error stats and
-relay them to a DPDK user. The next step is to enable monitoring of the DPDK
-interfaces based on the stats that we are retrieving from the NICs, by relaying
-the information to a higher level Fault Management entity. To enable this SFQM
-has been enabling a number of plugins for collectd.
-
-collectd
-~~~~~~~~
-collectd is a daemon which collects system performance statistics periodically
-and provides a variety of mechanisms to publish the collected metrics. It
-supports more than 90 different input and output plugins. Input plugins retrieve
-metrics and publish them to the collectd deamon, while output plugins publish
-the data they receive to an end point. collectd also has infrastructure to
-support thresholding and notification.
-
-collectd statistics and Notifications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Within collectd notifications and performance data are dispatched in the same
-way. There are producer plugins (plugins that create notifications/metrics),
-and consumer plugins (plugins that receive notifications/metrics and do
-something with them).
-
-Statistics in collectd consist of a value list. A value list includes:
-
-* Values, can be one of:
-
-  * Derive: used for values where a change in the value since it's last been
-    read is of interest. Can be used to calculate and store a rate.
-
-  * Counter: similar to derive values, but take the possibility of a counter
-    wrap around into consideration.
-
-  * Gauge: used for values that are stored as is.
-
-  * Absolute: used for counters that are reset after reading.
-
-* Value length: the number of values in the data set.
-
-* Time: timestamp at which the value was collected.
-
-* Interval: interval at which to expect a new value.
-
-* Host: used to identify the host.
-
-* Plugin: used to identify the plugin.
-
-* Plugin instance (optional): used to group a set of values together. For e.g.
-  values belonging to a DPDK interface.
-
-* Type: unit used to measure a value. In other words used to refer to a data
-  set.
-
-* Type instance (optional): used to distinguish between values that have an
-  identical type.
-
-* meta data: an opaque data structure that enables the passing of additional
-  information about a value list. "Meta data in the global cache can be used to
-  store arbitrary information about an identifier" [7].
-
-Host, plugin, plugin instance, type and type instance uniquely identify a
-collectd value.
-
-Values lists are often accompanied by data sets that describe the values in more
-detail. Data sets consist of:
-
-* A type: a name which uniquely identifies a data set.
-
-* One or more data sources (entries in a data set) which include:
-
-  * The name of the data source. If there is only a single data source this is
-    set to "value".
-
-  * The type of the data source, one of: counter, gauge, absolute or derive.
-
-  * A min and a max value.
-
-Types in collectd are defined in types.db. Examples of types in types.db:
-
-.. code-block:: console
-
-    bitrate    value:GAUGE:0:4294967295
-    counter    value:COUNTER:U:U
-    if_octets  rx:COUNTER:0:4294967295, tx:COUNTER:0:4294967295
-
-In the example above if_octets has two data sources: tx and rx.
-
-Notifications in collectd are generic messages containing:
-
-* An associated severity, which can be one of OKAY, WARNING, and FAILURE.
-
-* A time.
-
-* A Message
-
-* A host.
-
-* A plugin.
-
-* A plugin instance (optional).
-
-* A type.
-
-* A types instance (optional).
-
-* Meta-data.
-
 collectd plugins
-----------------
+=================
 Barometer has enabled the following collectd plugins:
 
 * dpdkstat plugin: A read plugin that retrieve stats from the DPDK extended
@@ -165,12 +20,14 @@ Barometer has enabled the following collectd plugins:
 * RDT plugin: A read plugin that provides the last level cache utilitzation and
   memory bandwidth utilization
 
+* Open vSwitch events Plugin: A read plugin that retrieves events from OVS.
+
 All the plugins above are available on the collectd master, except for the
 ceilometer plugin as it's a python based plugin and only C plugins are accepted
 by the collectd community. The ceilometer plugin lives in the OpenStack
 repositories.
 
-Other plugins in progress:
+Other plugins under development or existing as a pull request into collectd master:
 
 * dpdkevents:  A read plugin that retrieves DPDK link status and DPDK
   forwarding cores liveliness status (DPDK Keep Alive).
@@ -178,8 +35,6 @@ Other plugins in progress:
 * Open vSwitch stats Plugin: A read plugin that retrieve flow and interface
   stats from OVS.
 
-* Open vSwitch events Plugin: A read plugin that retrieves events from OVS.
-
 * mcelog plugin: A read plugin that uses mcelog client protocol to check for
   memory Machine Check Exceptions and sends the stats for reported exceptions.
 
@@ -190,6 +45,44 @@ Other plugins in progress:
 * Legacy/IPMI: A read plugin that will report platform thermals, voltages,
   fanspeed....
 
+Building collectd with the Barometer plugins and installing the dependencies
+=============================================================================
+The plugins that have been merged to master can all be built and configured through
+the barometer repository.
+
+**Note**: sudo permissions are required to install collectd.
+
+**Note**: These are instructions for Ubuntu 16.04.
+
+To build and install these dependencies, clone the barometer repo:
+
+.. code:: c
+
+    $ git clone https://gerrit.opnfv.org/gerrit/barometer
+
+Install the build dependencies
+
+.. code:: bash
+
+    $ ./src/install_build_deps.sh
+
+To install collectd as a service and install all it's dependencies:
+
+.. code:: bash
+
+    $ cd barometer/src && sudo make && sudo make install
+
+This will install collectd as a service and the base install directory
+is /opt/collectd.
+
+Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d'
+
+Please note if you are using any Open vSwitch plugins you need to run:
+
+.. code:: bash
+
+    $ sudo ovs-vsctl set-manager ptcp:6640
+
 Monitoring Interfaces and Openstack Support
 -------------------------------------------
 .. Figure:: monitoring_interfaces.png
@@ -201,7 +94,7 @@ node, sending and receiving traffic. collectd is also running on this compute
 node retrieving the stats periodically from DPDK through the dpdkstat plugin
 and publishing the retrieved stats to Ceilometer through the ceilometer plugin.
 
-To see this demo in action please checkout: `SFQM OPNFV Summit demo`_
+To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
 
 References
 ----------
@@ -213,5 +106,5 @@ References
 [6] https://collectd.org/wiki/index.php/Data_source
 [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
 
-.. _SFQM OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
+.. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
 .. _ceilometer plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/mitaka
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
index ae459d0a..5f019181 100644
--- a/docs/userguide/index.rst
+++ b/docs/userguide/index.rst
@@ -1,6 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
-   .. http://creativecommons.org/licenses/by/4.0
-      .. (c) <optionally add copywriters name>
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) Intel Corporation and OPNFV
 
 ====================
 Barometer user guide
@@ -16,4 +16,3 @@ Barometer user guide
      :maxdepth: 3
 
      collectd.userguide.rst
-     keepalive.userguide.rst