aboutsummaryrefslogtreecommitdiffstats
path: root/docs/release/userguide
diff options
context:
space:
mode:
Diffstat (limited to 'docs/release/userguide')
-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
4 files changed, 1075 insertions, 0 deletions
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