summaryrefslogtreecommitdiffstats
path: root/docs/release
diff options
context:
space:
mode:
authorMaryam Tahhan <maryam.tahhan@intel.com>2017-02-16 14:28:05 +0000
committerMaryam Tahhan <maryam.tahhan@intel.com>2017-02-17 09:35:25 +0000
commit2bb8c4857689cabe69d3d2d3d54dffa78d8f4a9f (patch)
tree75c0b7fdeb5167588fe42d02702fb7d5b354725a /docs/release
parent47ccd41d789085a2186fc1fb86364d93a20783ef (diff)
docs: moving to new doc structure
Change-Id: I91188deec2bd4e8aa405a9e023acde42b3fb31f7 Signed-off-by: Maryam Tahhan <maryam.tahhan@intel.com>
Diffstat (limited to 'docs/release')
-rw-r--r--docs/release/01-release.rst40
-rw-r--r--docs/release/configguide/featureconfig.rst60
-rw-r--r--docs/release/configguide/index.rst15
-rw-r--r--docs/release/configguide/postinstall.rst81
-rw-r--r--docs/release/release-notes/Features_to_date1.png (renamed from docs/release/Features_to_date1.png)bin80139 -> 80139 bytes
-rw-r--r--docs/release/release-notes/Features_to_date2.png (renamed from docs/release/Features_to_date2.png)bin111037 -> 111037 bytes
-rw-r--r--docs/release/release-notes/index.rst (renamed from docs/release/index.rst)13
-rw-r--r--docs/release/release-notes/release-notes.rst245
-rw-r--r--docs/release/scenarios/index.rst16
-rw-r--r--docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst118
-rw-r--r--docs/release/userguide/collectd.ves.userguide.rst197
-rw-r--r--docs/release/userguide/feature.userguide.rst855
-rw-r--r--docs/release/userguide/index.rst23
-rw-r--r--docs/release/userguide/monitoring_interfaces.pngbin0 -> 94097 bytes
14 files changed, 1617 insertions, 46 deletions
diff --git a/docs/release/01-release.rst b/docs/release/01-release.rst
deleted file mode 100644
index dcf6e180..00000000
--- a/docs/release/01-release.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-.. 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.
-
-Features to Date
-================
-This section provides a summary of the features implemented to date and their
-relevant upstream projects.
-
-.. Figure:: Features_to_date1.png
-
- Barometer features to date
-
-.. Figure:: Features_to_date2.png
-
- Barometer features to date cont.
-
-Please note the timeline denotes DPDK releases.
-
-Release B
-=========
-The features implemented for OPNFV release B (as part of SFQM) in DPDK include:
-
-* Callback API to enable TX/RX timestamping to measure latency through DPDK.
-* Extended NIC statistics API for 1GB, 10GB and 40GB NICs to expose detailed
- statistics for DPDK interfaces in addition to the overall aggregate statistics.
-* DPDK Keep Alive.
-
-Release C
-=========
-The features implemented for OPNFV release C (as part of SFQM) include:
-
-* DPDK extended NIC stats API improvement; migrate from key value pairs to
- using id value pairs.
-* DPDK Keep Alive improvement, so that core status is exposed through a posix
- shared memory object.
-* collectd dpdkstat plugin that can retrieve DPDK interface statistics.
-* collectd ceilometer plugin that can publish any statistics collected by
- collectd to ceilometer.
-* Fuel plugin support for the collectd ceilometer plugin for OPNFV.
diff --git a/docs/release/configguide/featureconfig.rst b/docs/release/configguide/featureconfig.rst
new file mode 100644
index 00000000..f7f7ec5e
--- /dev/null
+++ b/docs/release/configguide/featureconfig.rst
@@ -0,0 +1,60 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+========================
+Barometer Configuration
+========================
+This document provides guidelines on how to install and configure the Barometer
+plugin when using Fuel as a deployment tool. The plugin name is: Collectd
+Ceilometer Plugin. This plugin installs collectd on a compute node and enables
+a number of collectd plugins to collect metrics and events from the platform
+and send them to ceilometer.
+
+.. contents::
+ :depth: 3
+ :local:
+
+Pre-configuration activities
+----------------------------
+The Barometer Fuel plugin can be found in /opt/opnfv on the fuel master.
+To enable this plugin:
+
+.. code:: bash
+
+ $ cd /opt/opnfv
+ $ fuel plugins --install fuel-plugin-collectd-ceilometer-1.0-1.0.0-1.noarch.rpm
+
+On the Fuel UI, create a new environment.
+* In Settings > OpenStack Services
+* Enable "Install Ceilometer and Aodh"
+* In Settings > Other
+* Enable "Deploy Collectd Ceilometer Plugin"
+* Enable the barometer plugins you'd like to deploy using the checkboxes
+* Continue with environment configuration and deployment as normal.
+
+Hardware configuration
+----------------------
+There's no specific Hardware configuration required for this the barometer fuel plugin.
+
+Feature configuration
+---------------------
+Describe the procedures to configure your feature on the platform in order
+that it is ready to use according to the feature instructions in the platform
+user guide. Where applicable you should add content in the postinstall.rst
+to validate the feature is configured for use.
+(checking components are installed correctly etc...)
+
+Upgrading the plugin
+--------------------
+
+From time to time new versions of the plugin may become available.
+
+The plugin cannot be upgraded if an active environment is using the plugin.
+
+In order to upgrade the plugin:
+
+* Copy the updated plugin file to the fuel-master.
+* On the Fuel UI, reset the environment.
+* On the Fuel CLI "fuel plugins --update <fuel-plugin-file>"
+* On the Fuel UI, re-deploy the environment.
+
diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst
new file mode 100644
index 00000000..7f0e14a9
--- /dev/null
+++ b/docs/release/configguide/index.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (c) 2017 Open Platform for NFV Project, Inc. and its contributors
+
+======================================
+OPNFV Barometer configuration Guide
+======================================
+
+.. toctree::
+ :numbered:
+ :maxdepth: 3
+
+ featureconfig
+ postinstall
+
diff --git a/docs/release/configguide/postinstall.rst b/docs/release/configguide/postinstall.rst
new file mode 100644
index 00000000..5ebdc031
--- /dev/null
+++ b/docs/release/configguide/postinstall.rst
@@ -0,0 +1,81 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Barometer post installation procedures
+======================================
+Add a brief introduction to the methods of validating the installation
+according to this specific installer or feature.
+
+Automated post installation activities
+--------------------------------------
+Describe specific post installation activities performed by the OPNFV
+deployment pipeline including testing activities and reports. Refer to
+the relevant testing guides, results, and release notes.
+
+note: this section should be singular and derived from the test projects
+once we have one test suite to run for all deploy tools. This is not the
+case yet so each deploy tool will need to provide (hopefully very simillar)
+documentation of this.
+
+Barometer post configuration procedures
+--------------------------------------
+The fuel plugin installs collectd and its plugins on compute nodes.
+separate config files for each of the collectd plugins. These
+configuration files can be found on the compute node @
+`/etc/collectd/collectd.conf.d/` directory. Each collectd plugin will
+have its own configuration file with a default configuration for each
+plugin. You can override any of the plugin configurations, by modifying
+the configuration file and restarting the collectd service on the compute node.
+
+Platform components validation
+---------------------------------
+1. SSH to a compute node and ensure that the collectd service is running.
+
+2. On the compute node, you need to inject a corrected memory error:
+
+.. code:: bash
+
+ $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
+ $ cd mce-inject
+ $ make
+ $ modprobe mce-inject
+
+Modify the test/corrected script to include the following:
+
+.. code:: bash
+
+ CPU 0 BANK 0
+ STATUS 0xcc00008000010090
+ ADDR 0x0010FFFFFFF
+
+Inject the error:
+
+.. code:: bash
+
+ $ ./mce-inject < test/corrected
+
+3. SSH to openstack controller node and query the ceilometer DB:
+
+.. code:: bash
+
+ $ source openrc
+ $ ceilometer sample-list -m interface.if_packets
+ $ ceilometer sample-list -m hugepages.vmpage_number
+ $ ceilometer sample-list -m ovs_events.gauge
+ $ ceilometer sample-list -m mcelog.errors
+
+As you run each command above, you should see output similar to the examples below:
+
+.. code:: bash
+ | node-6.domain.tld-br-prv-link_status | ovs_events.gauge | gauge | 1.0 | None | 2017-01-20T18:18:40 |
+ | node-6.domain.tld-int-br-prv-link_status | ovs_events.gauge | gauge | 1.0 | None | 2017-01-20T18:18:39 |
+ | node-6.domain.tld-br-int-link_status | ovs_events.gauge | gauge | 0.0 | None | 2017-01-20T18:18:39 |
+
+ | node-6.domain.tld-mm-2048Kb-free | hugepages.vmpage_number | gauge | 0.0 | None | 2017-01-20T18:17:12 |
+ | node-6.domain.tld-mm-2048Kb-used | hugepages.vmpage_number | gauge | 0.0 | None | 2017-01-20T18:17:12 |
+ +-------------------------------------+-------------------------+-------+--------+------+---------------------+
+
+ | bf05daca-df41-11e6-b097-5254006ed58e | node-6.domain.tld-SOCKET_0_CHANNEL_0_DIMM_any-uncorrected_memory_errors_in_24h | mcelog.errors | gauge | 0.0 | None | 2017-01-20T18:53:34 |
+ | bf05dacb-df41-11e6-b097-5254006ed58e | node-6.domain.tld-SOCKET_0_CHANNEL_any_DIMM_any-uncorrected_memory_errors_in_24h | mcelog.errors | gauge | 0.0 | None | 2017-01-20T18:53:34 |
+ | bdcb930d-df41-11e6-b097-5254006ed58e | node-6.domain.tld-SOCKET_0_CHANNEL_any_DIMM_any-uncorrected_memory_errors | mcelog.errors | gauge | 0.0 | None | 2017-01-20T18:53:33 |
+
diff --git a/docs/release/Features_to_date1.png b/docs/release/release-notes/Features_to_date1.png
index 2469fe3a..2469fe3a 100644
--- a/docs/release/Features_to_date1.png
+++ b/docs/release/release-notes/Features_to_date1.png
Binary files differ
diff --git a/docs/release/Features_to_date2.png b/docs/release/release-notes/Features_to_date2.png
index edd2c074..edd2c074 100644
--- a/docs/release/Features_to_date2.png
+++ b/docs/release/release-notes/Features_to_date2.png
Binary files differ
diff --git a/docs/release/index.rst b/docs/release/release-notes/index.rst
index 30b2524c..44713cd3 100644
--- a/docs/release/index.rst
+++ b/docs/release/release-notes/index.rst
@@ -2,11 +2,12 @@
.. http://creativecommons.org/licenses/by/4.0
.. (c) OPNFV, Intel Corporation and others.
-************************
-Barometer Release Notes
-************************
+==================================================
+OPNFV Barometer Release Notes
+==================================================
+
.. toctree::
- :maxdepth: 3
- :numbered:
+ :maxdepth: 1
+
+ release-notes
- 01-release.rst
diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst
new file mode 100644
index 00000000..3837b1e7
--- /dev/null
+++ b/docs/release/release-notes/release-notes.rst
@@ -0,0 +1,245 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+======================================================================
+OPNFV Barometer Release Notes
+======================================================================
+
+This document provides the release notes for Danube Release of Barometer.
+
+.. contents::
+ :depth: 3
+ :local:
+
+
+Version history
+------------------
+
++--------------------+--------------------+--------------------+--------------------+
+| **Date** | **Ver.** | **Author** | **Comment** |
+| | | | |
++--------------------+--------------------+--------------------+--------------------+
+| 2017-02-16 | 0.1.0 | Maryam Tahhan | First draft |
+| | | | |
++--------------------+--------------------+--------------------+--------------------+
+
+Important notes
+-----------------
+None to date.
+
+Summary
+------------
+The Barometer@OPNFV project adds a platform telemetry agent to compute nodes
+that is capabable of retrieving platform statistics and events, and relay them
+to Openstack ceilometer. The telemetry agent currently supported by Barometer
+is collectd. Some additional collectd plugin were developed to add functionality
+to retrieve statistics or events for:
+
+- Hugepages
+- mcelog memory machine check exceptions
+- Open vSwitch events
+- Ceilometer
+
+Release Data
+---------------
+
++--------------------------------------+--------------------------------------+
+| **Project** | Danube/barometer/barometer@opnfv |
+| | |
++--------------------------------------+--------------------------------------+
+| **Repo/commit-ID** | barometer/ |
+| | |
++--------------------------------------+--------------------------------------+
+| **Release designation** | Danube 1.0 |
+| | |
++--------------------------------------+--------------------------------------+
+| **Release date** | |
+| | |
++--------------------------------------+--------------------------------------+
+| **Purpose of the delivery** | Official OPNFV release |
+| | |
++--------------------------------------+--------------------------------------+
+
+Version change
+^^^^^^^^^^^^^^^^
+
+Module version changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- There have been no version changes.
+
+Document version changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- The Barometer@OPNFV installation guide version has changed from version 0.1 to to 0.2
+
+Reason for version
+^^^^^^^^^^^^^^^^^^^^
+Feature additions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**JIRA BACK-LOG:**
+
++--------------------------------------+--------------------------------------+
+| **JIRA REFERENCE** | **SLOGAN** |
+| | |
++--------------------------------------+--------------------------------------+
+| BAROMETER-38 | RAS Collectd Plugin |
+| | |
++--------------------------------------+--------------------------------------+
+| BAROMETER-41 | OVS Collectd Plugin |
+| | |
++--------------------------------------+--------------------------------------+
+| BAROMETER-43 | Fuel Plugin for D Release |
+| | |
++--------------------------------------+--------------------------------------+
+| BAROMETER-48 | Hugepages Plugin for Collectd |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+
+Bug corrections
+~~~~~~~~~~~~~~~~~~~~~
+
+**JIRA TICKETS:**
+
++--------------------------------------+--------------------------------------+
+| **JIRA REFERENCE** | **SLOGAN** |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+
+Deliverables
+----------------
+
+Software deliverables
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Features to Date
+~~~~~~~~~~~~~~~~
+
+This section provides a summary of the features implemented to date and their
+relevant upstream projects.
+
+.. Figure:: Features_to_date1.png
+
+ Barometer features to date
+
+.. Figure:: Features_to_date2.png
+
+ Barometer features to date cont.
+
+Please note the timeline denotes DPDK releases.
+
+Release B
+~~~~~~~~~~
+The features implemented for OPNFV release B (as part of SFQM) in DPDK include:
+
+* Callback API to enable TX/RX timestamping to measure latency through DPDK.
+* Extended NIC statistics API for 1GB, 10GB and 40GB NICs to expose detailed
+ statistics for DPDK interfaces in addition to the overall aggregate statistics.
+* DPDK Keep Alive.
+
+Release C
+~~~~~~~~~~
+The features implemented for OPNFV release C (as part of SFQM) include:
+
+* DPDK extended NIC stats API improvement; migrate from key value pairs to
+ using id value pairs.
+* DPDK Keep Alive improvement, so that core status is exposed through a posix
+ shared memory object.
+* collectd dpdkstat plugin that can retrieve DPDK interface statistics.
+* collectd ceilometer plugin that can publish any statistics collected by
+ collectd to ceilometer.
+* Fuel plugin support for the collectd ceilometer plugin for OPNFV.
+
+Documentation deliverables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Configuration guide
+- User guide
+- Release notes
+- Scenario documentation.
+
+Known Limitations, Issues and Workarounds
+--------------------------------------------
+
+System Limitations
+^^^^^^^^^^^^^^^^^^^^
+
+Barometer has the same limiations as the fuel project in general as regards
+
+- **Max number of blades*
+
+- **Min number of blades**
+
+- **Storage**
+
+- **Max number of networks**
+
+- **L3Agent**
+
+The only additional limitiation is the following:
+
+**Telemetry:** Ceilometer service needs to be configured for compute nodes.
+
+Known issues
+^^^^^^^^^^^^^^^
+
+No known issues to date.
+
+**JIRA TICKETS:**
+
++--------------------------------------+--------------------------------------+
+| **JIRA REFERENCE** | **SLOGAN** |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+
+Workarounds
+^^^^^^^^^^^^^^^^^
+
+- None to date.
+
+Test Result
+---------------
+
+Barometer@OPNFV Danube RC1 has undergone QA test runs with the following results:
+
++--------------------------------------+--------------------------------------+
+| **TEST-SUITE** | **Results:** |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
+| | |
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+| | |
+| | |
+| | |
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+
+References
+------------
+
+For more information on the OPNFV Danube release, please see:
+
+http://opnfv.org/danube
+
diff --git a/docs/release/scenarios/index.rst b/docs/release/scenarios/index.rst
new file mode 100644
index 00000000..12ca9933
--- /dev/null
+++ b/docs/release/scenarios/index.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) 2017 Intel Corporation and Others
+
+=============================
+OPNFV Barometer Scenarios
+=============================
+.. This document will be used to provide a description of the scenario for an end user.
+.. You should explain the purpose of the scenario, the types of capabilities provided and
+.. the unique components that make up the scenario including how they are used.
+
+.. toctree::
+ :maxdepth: 1
+
+ ./os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description
+
diff --git a/docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst b/docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst
new file mode 100644
index 00000000..f98a05ab
--- /dev/null
+++ b/docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst
@@ -0,0 +1,118 @@
+.. 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>
+
+===================================
+OPNFV os-nosdn-kvm_ovs_dpdk_bar-ha
+===================================
+
+This document provides scenario level details for Danube of Barometer.
+
+.. contents::
+ :depth: 3
+ :local:
+
+Introduction
+---------------
+.. In this section explain the purpose of the scenario and the types of
+.. capabilities provided
+This scenario combines the features from the following three projects in a
+single instantiation of OPNFV:
+
+- KVM4NFV
+- OVS4NFV
+- Barometer
+
+A distinguishing factor for this scenario vs other scenarios that integrate
+Open vSwitch and KVM is that collectd (a telemetry agent) is installed on
+compute nodes so that their statistics and events can be relayed to ceilometer.
+These are the first steps in paving the way for Platform (NFVI) Monitoring in
+OPNFV.
+
+For Fuel this scenario installs the latest DPDK-enabled Open vSwitch component,
+KVM4NFV latest software packages for Linux Kernel and QEMU patches for
+achieving low latency, and the collectd telemetry agent.
+
+Scenario components and composition
+-------------------------------------
+.. In this section describe the unique components that make up the scenario,
+.. what each component provides and why it has been included in order
+.. to communicate to the user the capabilities available in this scenario.
+
+This scenario deploys the High Availability OPNFV Cloud based on the
+configurations provided in ha_nfv-kvm_ovs_bar_heat_ceilometer_scenario.yaml.
+This yaml file contains following configurations and is passed as an
+argument to deploy.py script
+
+* scenario.yaml:This configuration file defines translation between a
+ short deployment scenario name(os-nosdn-kvm_ovs_dpdk_bar-ha) and an actual
+ deployment scenario configuration file
+ (ha_nfv-kvm_nfv-ovs-dpdk_bar_heat_ceilometer_scenario.yaml)
+
+* deployment-scenario-metadata:Contains the configuration metadata like
+ title,version,created,comment.
+
+* stack-extensions:Stack extentions are opnfv added value features in form
+ of a fuel-plugin.Plugins listed in stack extensions are enabled and
+ configured.
+
+* dea-override-config: Used to configure the HA mode,network segmentation
+ types and role to node assignments. These configurations overrides
+ corresponding keys in the dea_base.yaml and dea_pod_override.yaml.
+ These keys are used to deploy multiple nodes(3 controllers,2 computes)
+ as mention below.
+
+* **Node 1**: This node has MongoDB and Controller roles. The controller
+ node runs the Identity service, Image Service, management portions of
+ Compute and Networking, Networking plug-in and the dashboard. The
+ Telemetry service which was designed to support billing systems for
+ OpenStack cloud resources uses a NoSQL database to store information.
+ The database typically runs on the controller node.
+
+* **Node 2**: This node has Controller and Ceph-osd roles. Ceph is a
+ massively scalable, open source, distributed storage system. It is
+ comprised of an object store, block store and a POSIX-compliant distributed
+ file system. Enabling Ceph, configures Nova to store ephemeral volumes in
+ RBD, configures Glance to use the Ceph RBD backend to store images,
+ configures Cinder to store volumes in Ceph RBD images and configures the
+ default number of object replicas in Ceph.
+
+* **Node 3**: This node has Controller role in order to achieve high
+ availability.
+
+* **Node 4**: This node has Compute role. The compute node runs the
+ hypervisor portion of Compute that operates tenant virtual machines
+ instances. By default, Compute uses KVM as the hypervisor. Collectd
+ will be installed on this node.
+
+* **Node 5**: This node has compute role.
+
+* dha-override-config:Provides information about the VM definition and
+ Network config for virtual deployment. These configurations overrides
+ the pod dha definition and points to the controller,compute and
+ fuel definition files.
+
+* os-nosdn-kvm_ovs_dpdk_bar-ha scenario is successful when all the 5 Nodes are
+ accessible, up and running.
+
+Scenario usage overview
+----------------------------
+.. Provide a brief overview on how to use the scenario and the features available to the
+.. user. This should be an "introduction" to the userguide document, and explicitly link to it,
+.. where the specifics of the features are covered including examples and API's
+
+After installation use of the scenario traffic on the private network will
+automatically be processed by the upgraded DPDK datapath.
+
+Limitations, Issues and Workarounds
+---------------------------------------
+.. Explain scenario limitations here, this should be at a design level rather than discussing
+.. faults or bugs. If the system design only provide some expected functionality then provide
+.. some insight at this point.
+
+References
+-----------------
+
+For more information on the OPNFV Danube release, please visit
+http://www.opnfv.org/danube
+
diff --git a/docs/release/userguide/collectd.ves.userguide.rst b/docs/release/userguide/collectd.ves.userguide.rst
new file mode 100644
index 00000000..3cf26004
--- /dev/null
+++ b/docs/release/userguide/collectd.ves.userguide.rst
@@ -0,0 +1,197 @@
+.. 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 User Guide
+==============================
+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/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
new file mode 100644
index 00000000..2be44d33
--- /dev/null
+++ b/docs/release/userguide/feature.userguide.rst
@@ -0,0 +1,855 @@
+.. 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>
+
+===================================
+OPNFV Barometer User Guide
+===================================
+
+.. contents::
+ :depth: 3
+ :local:
+
+Barometer collectd plugins description
+---------------------------------------
+.. Describe the specific features and how it is realised in the scenario in a brief manner
+.. to ensure the user understand the context for the user guide instructions to follow.
+
+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.
+
+Barometer has enabled the following collectd plugins:
+
+* *dpdkstat plugin*: A read plugin that retrieve stats from the DPDK extended
+ NIC stats API.
+
+* `ceilometer plugin`_: A write plugin that pushes the retrieved stats to
+ Ceilometer. It's capable of pushing any stats read through collectd to
+ Ceilometer, not just the DPDK stats.
+
+* *hugepages plugin*: A read plugin that retrieves the number of available
+ and free hugepages on a platform as well as what is available in terms of
+ hugepages per socket.
+
+* *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.
+
+* *mcelog plugin*: A read plugin that uses mcelog client protocol to check for
+ memory Machine Check Exceptions and sends the stats for reported exceptions
+
+All the plugins above are available on the collectd master, except for the
+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 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).
+
+* *Open vSwitch stats Plugin*: A read plugin that retrieve flow and interface
+ stats from OVS.
+
+* *SNMP Agent*: A write plugin that will act as a AgentX subagent that receives
+ and handles queries from SNMP master agent and returns the data collected
+ by read plugins. The SNMP Agent plugin handles requests only for OIDs
+ specified in configuration file. To handle SNMP queries the plugin gets data
+ from collectd and translates requested values from collectd's internal format
+ to SNMP format. Supports SNMP: get, getnext and walk requests.
+
+* *Legacy/IPMI*: A read plugin that reports platform thermals, voltages,
+ fanspeed, current, flow, power etc. Also, the plugin monitors Intelligent
+ Platform Management Interface (IPMI) System Event Log (SEL) and sends the
+
+**Plugins included in the Danube release:**
+
+* Hugepages
+* Open vSwitch Events
+* Ceilometer
+* Mcelog
+
+collectd capabilities and usage
+------------------------------------
+.. Describe the specific capabilities and usage for <XYZ> feature.
+.. Provide enough information that a user will be able to operate the feature on a deployed scenario.
+
+**NOTE** Plugins included in the OPNFV D release will be built-in to the fuel
+plugin and available in the /opt/opnfv directory on the fuel master. You don't
+need to clone the barometer/collectd repos to use these, but you can configure
+them as shown in the examples below. Please note, the collectd plugins in OPNFV
+are configured with reasonable defaults, but can be overriden.
+
+Building all Barometer upstreamed plugins from scratch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The plugins that have been merged to the collectd master branch 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'
+
+**Note**: Exec plugin requires non-root user to execute scripts. By default,
+`collectd_exec` user is used. Barometer scripts do *not* create this user. It
+needs to be manually added or exec plugin configuration has to be changed to use
+other, existing user before starting collectd service.
+
+Please note if you are using any Open vSwitch plugins you need to run:
+
+
+.. code:: bash
+
+ $ sudo ovs-vsctl set-manager ptcp:6640
+
+DPDK statistics plugin
+^^^^^^^^^^^^^^^^^^^^^^
+Repo: https://github.com/collectd/collectd
+
+Branch: master
+
+Dependencies: DPDK (http://dpdk.org/)
+
+To build and install DPDK to /usr please see:
+https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md
+
+Building and installing collectd:
+
+.. code:: bash
+
+ $ git clone https://github.com/collectd/collectd.git
+ $ cd collectd
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug
+ $ make
+ $ sudo make install
+
+
+This will install collectd to /opt/collectd
+The collectd configuration file can be found at /opt/collectd/etc
+To configure the hugepages plugin you need to modify the configuration file to
+include:
+
+.. code:: bash
+
+ LoadPlugin dpdkstat
+ <Plugin dpdkstat>
+ Coremask "0xf"
+ ProcessType "secondary"
+ FilePrefix "rte"
+ EnabledPortMask 0xffff
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+
+Please note if you are configuring collectd with the **static DPDK library**
+you must compile the DPDK library with the -fPIC flag:
+
+.. code:: bash
+
+ $ make EXTRA_CFLAGS=-fPIC
+
+You must also modify the configuration step when building collectd:
+
+.. code:: bash
+
+ $ ./configure CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive"
+
+Please also note that if you are not building and installing DPDK system-wide
+you will need to specify the specific paths to the header files and libraries
+using LIBDPDK_CPPFLAGS and LIBDPDK_LDFLAGS. You will also need to add the DPDK
+library symbols to the shared library path using ldconfig. Note that this
+update to the shared library path is not persistant (i.e. it will not survive a
+reboot). Pending a merge of https://github.com/collectd/collectd/pull/2073.
+
+.. code:: bash
+
+ $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries"
+
+Hugepages Plugin
+^^^^^^^^^^^^^^^^^
+Repo: https://github.com/collectd/collectd
+
+Branch: master
+
+Dependencies: None, but assumes hugepages are configured.
+
+To configure some hugepages:
+
+.. code:: bash
+
+ sudo mkdir -p /mnt/huge
+ sudo mount -t hugetlbfs nodev /mnt/huge
+ sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
+
+Building and installing collectd:
+
+.. code:: bash
+
+ $ git clone https://github.com/collectd/collectd.git
+ $ cd collectd
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-hugepages --enable-debug
+ $ make
+ $ sudo make install
+
+This will install collectd to /opt/collectd
+The collectd configuration file can be found at /opt/collectd/etc
+To configure the hugepages plugin you need to modify the configuration file to
+include:
+
+.. code:: bash
+
+ LoadPlugin hugepages
+ <Plugin hugepages>
+ ReportPerNodeHP true
+ ReportRootHP true
+ ValuesPages true
+ ValuesBytes false
+ ValuesPercentage false
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+
+Intel RDT Plugin
+^^^^^^^^^^^^^^^^
+Repo: https://github.com/collectd/collectd
+
+Branch: master
+
+Dependencies:
+
+ * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git
+ * msr kernel module
+
+Building and installing PQoS/Intel RDT library:
+
+.. code:: bash
+
+ $ git clone https://github.com/01org/intel-cmt-cat.git
+ $ cd intel-cmt-cat
+ $ make
+ $ make install PREFIX=/usr
+
+You will need to insert the msr kernel module:
+
+.. code:: bash
+
+ $ modprobe msr
+
+Building and installing collectd:
+
+.. code:: bash
+
+ $ git clone https://github.com/collectd/collectd.git
+ $ cd collectd
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --with-libpqos=/usr/ --enable-debug
+ $ make
+ $ sudo make install
+
+This will install collectd to /opt/collectd
+The collectd configuration file can be found at /opt/collectd/etc
+To configure the RDT plugin you need to modify the configuration file to
+include:
+
+.. code:: bash
+
+ <LoadPlugin intel_rdt>
+ Interval 1
+ </LoadPlugin>
+ <Plugin "intel_rdt">
+ Cores ""
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+
+IPMI Plugin
+^^^^^^^^^^^^
+Repo: https://github.com/maryamtahhan/collectd
+
+Branch: feat_ipmi_events, feat_ipmi_analog
+
+Dependencies: OpenIPMI library
+
+The IPMI plugin is already implemented in the latest collectd and sensors
+like temperature, voltage, fanspeed, current are already supported there.
+The list of supported IPMI sensors has been extended and sensors like flow,
+power are supported now. Also, a System Event Log (SEL) notification feature
+has been introduced.
+
+* The feat_ipmi_events branch includes new SEL feature support in collectd
+ IPMI plugin. If this feature is enabled, the collectd IPMI plugin will
+ dispatch notifications about new events in System Event Log.
+
+* The feat_ipmi_analog branch includes the support of extended IPMI sensors in
+ collectd IPMI plugin.
+
+On Ubuntu, install the dependencies:
+
+.. code:: bash
+
+ $ sudo apt-get install libopenipmi-dev
+
+Enable IPMI support in the kernel:
+
+.. code:: bash
+
+ $ sudo modprobe ipmi_devintf
+ $ sudo modprobe ipmi_si
+
+**Note**: If HW supports IPMI, the ``/dev/ipmi0`` character device will be
+created.
+
+Clone and install the collectd IPMI plugin:
+
+.. code:: bash
+
+ $ git clone https://github.com/maryamtahhan/collectd
+ $ cd collectd
+ $ git checkout $BRANCH
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug
+ $ make
+ $ sudo make install
+
+Where $BRANCH is feat_ipmi_events or feat_ipmi_analog.
+
+This will install collectd to default folder ``/opt/collectd``. The collectd
+configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To
+configure the IPMI plugin you need to modify the file to include:
+
+.. code:: bash
+
+ LoadPlugin ipmi
+ <Plugin ipmi>
+ SELEnabled true # only feat_ipmi_events branch supports this
+ </Plugin>
+
+**Note**: By default, IPMI plugin will read all available analog sensor values,
+dispatch the values to collectd and send SEL notifications.
+
+For more information on the IPMI plugin parameters and SEL feature configuration,
+please see:
+https://github.com/maryamtahhan/collectd/blob/feat_ipmi_events/src/collectd.conf.pod
+
+Extended analog sensors support doesn't require additional configuration. The usual
+collectd IPMI documentation can be used:
+
+- https://collectd.org/wiki/index.php/Plugin:IPMI
+- https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_ipmi
+
+IPMI documentation:
+
+- https://www.kernel.org/doc/Documentation/IPMI.txt
+- http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
+
+Mcelog Plugin
+^^^^^^^^^^^^^^
+Repo: https://github.com/collectd/collectd
+
+Branch: master
+
+Dependencies: mcelog
+
+Start by installing mcelog. Note: The kernel has to have CONFIG_X86_MCE
+enabled. For 32bit kernels you need at least a 2.6,30 kernel.
+
+On ubuntu:
+
+.. code:: bash
+
+ $ apt-get update && apt-get install mcelog
+
+Or build from source
+
+.. code:: bash
+
+ $ git clone git://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git
+ $ cd mcelog
+ $ make
+ ... become root ...
+ $ make install
+ $ cp mcelog.service /etc/systemd/system/
+ $ systemctl enable mcelog.service
+ $ systemctl start mcelog.service
+
+
+Verify you got a /dev/mcelog. You can verify the daemon is running completely
+by running:
+
+.. code:: bash
+
+ $ mcelog --client
+
+This should query the information in the running daemon. If it prints nothing
+that is fine (no errors logged yet). More info @
+http://www.mcelog.org/installation.html
+
+Modify the mcelog configuration file "/etc/mcelog/mcelog.conf" to include or
+enable:
+
+.. code:: bash
+
+ socket-path = /var/run/mcelog-client
+
+Clone and install the collectd mcelog plugin:
+
+.. code:: bash
+
+ $ git clone https://github.com/maryamtahhan/collectd
+ $ cd collectd
+ $ git checkout feat_ras
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug
+ $ make
+ $ sudo make install
+
+This will install collectd to /opt/collectd
+The collectd configuration file can be found at /opt/collectd/etc
+To configure the mcelog plugin you need to modify the configuration file to
+include:
+
+.. code:: bash
+
+ <LoadPlugin mcelog>
+ Interval 1
+ </LoadPlugin>
+ <Plugin "mcelog">
+ McelogClientSocket "/var/run/mcelog-client"
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/maryamtahhan/collectd/blob/feat_ras/src/collectd.conf.pod
+
+Simulating a Machine Check Exception can be done in one of 3 ways:
+
+* Running $make test in the mcelog cloned directory - mcelog test suite
+* using mce-inject
+* using mce-test
+
+**mcelog test suite:**
+
+It is always a good idea to test an error handling mechanism before it is
+really needed. mcelog includes a test suite. The test suite relies on
+mce-inject which needs to be installed and in $PATH.
+
+You also need the mce-inject kernel module configured (with
+CONFIG_X86_MCE_INJECT=y), compiled, installed and loaded:
+
+.. code:: bash
+
+ $ modprobe mce-inject
+
+Then you can run the mcelog test suite with
+
+.. code:: bash
+
+ $ make test
+
+This will inject different classes of errors and check that the mcelog triggers
+runs. There will be some kernel messages about page offlining attempts. The
+test will also lose a few pages of memory in your system (not significant)
+**Note this test will kill any running mcelog, which needs to be restarted
+manually afterwards**.
+**mce-inject:**
+
+A utility to inject corrected, uncorrected and fatal machine check exceptions
+
+.. code:: bash
+
+ $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
+ $ cd mce-inject
+ $ make
+ $ modprobe mce-inject
+
+Modify the test/corrected script to include the following:
+
+.. code:: bash
+
+ CPU 0 BANK 0
+ STATUS 0xcc00008000010090
+ ADDR 0x0010FFFFFFF
+
+Inject the error:
+.. code:: bash
+
+ $ ./mce-inject < test/corrected
+
+**Note: the uncorrected and fatal scripts under test will cause a platform reset.
+Only the fatal script generates the memory errors**. In order to quickly
+emulate uncorrected memory errors and avoid host reboot following test errors
+from mce-test suite can be injected:
+
+.. code:: bash
+
+ $ mce-inject mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub
+
+**mce-test:**
+
+In addition an more in-depth test of the Linux kernel machine check facilities
+can be done with the mce-test test suite. mce-test supports testing uncorrected
+error handling, real error injection, handling of different soft offlining
+cases, and other tests.
+
+**Corrected memory error injection:**
+
+To inject corrected memory errors:
+
+* Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core
+* Insert einj module: modprobe einj param_extension=1
+* Inject an error by specifying details (last command should be repeated at least two times):
+
+.. code:: bash
+
+ $ APEI_IF=/sys/kernel/debug/apei/einj
+ $ echo 0x8 > $APEI_IF/error_type
+ $ echo 0x01f5591000 > $APEI_IF/param1
+ $ echo 0xfffffffffffff000 > $APEI_IF/param2
+ $ echo 1 > $APEI_IF/notrigger
+ $ echo 1 > $APEI_IF/error_inject
+
+* Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
+
+Open vSwitch Plugins
+^^^^^^^^^^^^^^^^^^^^^
+OvS Events Repo: https://github.com/collectd/collectd
+
+OvS Stats Repo: https://github.com/maryamtahhan/collectd
+
+OvS Events Branch: master
+
+OvS Stats Branch:feat_ovs_stats
+
+Dependencies: Open vSwitch, libyajl
+
+On Ubuntu, install the dependencies:
+
+.. code:: bash
+
+ $ sudo apt-get install libyajl-dev openvswitch-switch
+
+Start the Open vSwitch service:
+
+.. code:: bash
+
+ $ sudo service openvswitch-switch start
+
+configure the ovsdb-server manager:
+
+.. code:: bash
+
+ $ sudo ovs-vsctl set-manager ptcp:6640
+
+Clone and install the collectd ovs plugin:
+
+.. code:: bash
+
+ $ git clone $REPO
+ $ cd collectd
+ $ git checkout $BRANCH
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug
+ $ make
+ $ sudo make install
+
+where $REPO is one of the repos listed at the top of this section.
+
+Where $BRANCH is master or feat_ovs_stats.
+
+This will install collectd to /opt/collectd. The collectd configuration file
+can be found at /opt/collectd/etc. To configure the OVS events plugin you
+need to modify the configuration file to include:
+
+.. code:: bash
+
+ <LoadPlugin ovs_events>
+ Interval 1
+ </LoadPlugin>
+ <Plugin "ovs_events">
+ Port 6640
+ Socket "/var/run/openvswitch/db.sock"
+ Interfaces "br0" "veth0"
+ SendNotification false
+ </Plugin>
+
+To configure the OVS stats plugin you need to modify the configuration file
+to include:
+
+.. code:: bash
+
+ <LoadPlugin ovs_stats>
+ Interval 1
+ </LoadPlugin>
+ <Plugin ovs_stats>
+ Port "6640"
+ Address "127.0.0.1"
+ Socket "/var/run/openvswitch/db.sock"
+ Bridges "br0" "br_ext"
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+and
+https://github.com/maryamtahhan/collectd/blob/feat_ovs_stats/src/collectd.conf.pod
+
+SNMP Agent Plugin
+^^^^^^^^^^^^^^^^^
+Repo: https://github.com/maryamtahhan/collectd/
+
+Branch: feat_snmp
+
+Dependencies: NET-SNMP library
+
+Start by installing net-snmp and dependencies.
+
+On ubuntu:
+
+.. code:: bash
+
+ $ apt-get install snmp snmp-mibs-downloader snmpd libsnmp-dev
+ $ systemctl start snmpd.service
+
+Or build from source
+
+Become root to install net-snmp dependencies
+
+.. code:: bash
+
+ $ apt-get install libperl-dev
+
+Clone and build net-snmp
+
+.. code:: bash
+
+ $ git clone https://github.com/haad/net-snmp.git
+ $ cd net-snmp
+ $ ./configure --with-persistent-directory="/var/net-snmp" --with-systemd --enable-shared --prefix=/usr
+ $ make
+
+Become root
+
+.. code:: bash
+
+ $ make install
+
+Copy default configuration to persistent folder
+
+.. code:: bash
+
+ $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf
+
+Set library path and default MIB configuration
+
+.. code:: bash
+
+ $ cd ~/
+ $ echo export LD_LIBRARY_PATH=/usr/lib >> .bashrc
+ $ net-snmp-config --default-mibdirs
+ $ net-snmp-config --snmpconfpath
+
+Configure snmpd as a service
+
+.. code:: bash
+
+ $ cd net-snmp
+ $ cp ./dist/snmpd.service /etc/systemd/system/
+ $ systemctl enable snmpd.service
+ $ systemctl start snmpd.service
+
+Add the following line to snmpd.conf configuration file
+"/usr/share/snmp/snmpd.conf" to make all OID tree visible for SNMP clients:
+
+.. code:: bash
+
+ view systemonly included .1
+
+To verify that SNMP is working you can get IF-MIB table using SNMP client
+to view the list of Linux interfaces:
+
+.. code:: bash
+
+ $ snmpwalk -v 2c -c public localhost IF-MIB::interfaces
+
+Clone and install the collectd snmp_agent plugin:
+
+.. code:: bash
+
+ $ git clone https://github.com/maryamtahhan/collectd
+ $ cd collectd
+ $ git checkout feat_snmp
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug --enable-snmp --with-libnetsnmp
+ $ make
+ $ sudo make install
+
+This will install collectd to /opt/collectd
+The collectd configuration file can be found at /opt/collectd/etc
+**SNMP Agent plugin is a generic plugin and cannot work without configuration**.
+To configure the snmp_agent plugin you need to modify the configuration file to
+include OIDs mapped to collectd types. The following example maps scalar
+memAvailReal OID to value represented as free memory type of memory plugin:
+
+.. code:: bash
+
+ LoadPlugin snmp_agent
+ <Plugin "snmp_agent">
+ <Data "memAvailReal">
+ Plugin "memory"
+ Type "memory"
+ TypeInstance "free"
+ OIDs "1.3.6.1.4.1.2021.4.6.0"
+ </Data>
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/maryamtahhan/collectd/blob/feat_snmp/src/collectd.conf.pod
+
+For more details on AgentX subagent, please see:
+http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/
+
+Installing collectd as a service
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**NOTE**: In an OPNFV installation, collectd is installed and configured as a
+service.
+
+Collectd service scripts are available in the collectd/contrib directory.
+To install collectd as a service:
+
+.. code:: bash
+
+ $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
+ $ cd /etc/systemd/system/
+ $ sudo mv systemd.collectd.service collectd.service
+ $ sudo chmod +x collectd.service
+
+Modify collectd.service
+
+.. code:: bash
+
+ [Service]
+ ExecStart=/opt/collectd/sbin/collectd
+ EnvironmentFile=-/opt/collectd/etc/
+ EnvironmentFile=-/opt/collectd/etc/
+ CapabilityBoundingSet=CAP_SETUID CAP_SETGID
+
+Reload
+
+.. code:: bash
+
+ $ sudo systemctl daemon-reload
+ $ sudo systemctl start collectd.service
+ $ sudo systemctl status collectd.service should show success
+
+Additional useful plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* **Exec Plugin** : Can be used to show you when notifications are being
+ generated by calling a bash script that dumps notifications to file. (handy
+ for debug). Modify /opt/collectd/etc/collectd.conf:
+
+.. code:: bash
+
+ LoadPlugin exec
+ <Plugin exec>
+ # Exec "user:group" "/path/to/exec"
+ NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
+ </Plugin>
+
+write_notification.sh (just writes the notification passed from exec through
+STDIN to a file (/tmp/notifications)):
+
+.. code:: bash
+
+ #!/bin/bash
+ rm -f /tmp/notifications
+ while read x y
+ do
+ echo $x$y >> /tmp/notifications
+ done
+
+output to /tmp/notifications should look like:
+
+.. code:: bash
+
+ Severity:WARNING
+ Time:1479991318.806
+ Host:localhost
+ Plugin:ovs_events
+ PluginInstance:br-ex
+ Type:gauge
+ TypeInstance:link_status
+ uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
+
+ linkstate of "br-ex" interface has been changed to "DOWN"
+
+* **logfile plugin**: Can be used to log collectd activity. Modify
+ /opt/collectd/etc/collectd.conf to include:
+
+.. code:: bash
+
+ LoadPlugin logfile
+ <Plugin logfile>
+ LogLevel info
+ File "/var/log/collectd.log"
+ Timestamp true
+ PrintSeverity false
+ </Plugin>
+
+
+Monitoring Interfaces and Openstack Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. Figure:: monitoring_interfaces.png
+
+ Monitoring Interfaces and Openstack Support
+
+The figure above shows the DPDK L2 forwarding application running on a compute
+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: `Barometer OPNFV Summit demo`_
+
+References
+^^^^^^^^^^^
+.. [1] https://collectd.org/wiki/index.php/Naming_schema
+.. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
+.. [3] https://collectd.org/wiki/index.php/Value_list_t
+.. [4] https://collectd.org/wiki/index.php/Data_set
+.. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
+.. [6] https://collectd.org/wiki/index.php/Data_source
+.. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
+
+.. _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/release/userguide/index.rst b/docs/release/userguide/index.rst
new file mode 100644
index 00000000..287b16be
--- /dev/null
+++ b/docs/release/userguide/index.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) Intel and OPNFV
+
+===========================
+OPNFV Barometer User Guide
+===========================
+
+.. The feature user guide should provide an OPNFV user with enough information to
+.. use the features provided by the feature project in the supported scenarios.
+.. This guide should walk a user through the usage of the features once a scenario
+.. has been deployed and is active according to the installation guide provided
+.. by the installer project.
+
+.. toctree::
+ :maxdepth: 1
+
+ feature.userguide
+ collectd.ves.userguide.rst
+.. The feature.userguide.rst file should contain the text for this document
+.. additional documents can be added to this directory and added in the right order
+.. to this file as a list below.
+
diff --git a/docs/release/userguide/monitoring_interfaces.png b/docs/release/userguide/monitoring_interfaces.png
new file mode 100644
index 00000000..e57c4aa1
--- /dev/null
+++ b/docs/release/userguide/monitoring_interfaces.png
Binary files differ