Merge "Docs: Updating Barometer Configuration Guide for E Release"

2 files changed, 92 insertions, 92 deletions

diff --git a/docs/release/configguide/featureconfig.rst b/docs/release/configguide/featureconfig.rst
index f7f7ec5e..52546178 100644
--- a/docs/release/configguide/featureconfig.rst
+++ b/docs/release/configguide/featureconfig.rst
@@ -1,14 +1,12 @@
 .. 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.
+=============================
+Barometer Configuration Guide
+=============================
+This document provides guidelines on how to install and configure Barometer with Apex.
+The deployment script installs and enables a series of collectd plugins on the compute node(s),
+which collect and dispatch specific metrics and events from the platform.
 
 .. contents::
    :depth: 3
@@ -16,45 +14,28 @@ and send them to ceilometer.
 
 Pre-configuration activities
 ----------------------------
-The Barometer Fuel plugin can be found in /opt/opnfv on the fuel master.
-To enable this plugin:
+Deploying the Barometer components in Apex is done through the deploy-opnfv command by selecting
+a scenario-file which contains the ``barometer: true`` option.  These files are located on the
+Jump Host in the ``/etc/opnfv-apex/ folder``.  Two scenarios are pre-defined to include Barometer,
+and they are: ``os-nosdn-bar-ha.yaml`` and ``os-nosdn-bar-noha.yaml``.
 
 .. 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.
+    $ cd /etc/opnfv-apex
+    $ opnfv-deploy -d os-nosdn-bar-ha.yaml -n network_settings.yaml -i inventory.yaml –- debug
 
 Hardware configuration
 ----------------------
-There's no specific Hardware configuration required for this the barometer fuel plugin.
+There's no specific Hardware configuration required.  However, the ``intel_rdt`` plugin works
+only on platforms with Intel CPUs.
 
 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.
+All Barometer plugins are automatically deployed on all compute nodes.  There is no option to
+selectively install only a subset of plugins.  Any custom disabling or configuration must be done
+directly on the compute node(s) after the deployment is completed.
 
+Upgrading the plugins
+---------------------
+The Barometer components are built-in in the Apex ISO image, and respectively the Apex RPMs.  There
+is no simple way to update only the Barometer plugins in an existing deployment.
diff --git a/docs/release/configguide/postinstall.rst b/docs/release/configguide/postinstall.rst
index 5ebdc031..45a79ffb 100644
--- a/docs/release/configguide/postinstall.rst
+++ b/docs/release/configguide/postinstall.rst
@@ -1,81 +1,100 @@
 .. 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.
+This document describes briefly the methods of validating the Barometer installation.
 
 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.
+The Barometer test-suite in Functest is called ``barometercollectd`` and is part of the ``Features``
+tier.  Running these tests is done automatically by the OPNFV deployment pipeline on the supported
+scenarios.  The testing consists of basic verifications that each plugin is functional per their
+default configurations.  Inside the Functest container, the detailed results can be found in the
+``/home/opnfv/functest/results/barometercollectd.log``.
 
 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.
+---------------------------------------
+The functionality for each plugin (such as enabling/disabling and configuring its capabilities)
+is controlled as described in the User Guide through their individual ``.conf`` file located in
+the ``/etc/collectd/collectd.conf.d/`` folder on the compute node(s).  In order for any changes to
+take effect, the collectd service must be stopped and then started again.
 
 Platform components validation
----------------------------------
-1. SSH to a compute node and ensure that the collectd service is running.
+------------------------------
+The following steps describe how to perform a simple "manual" testing of the Barometer components:
+
+1. Connect to any compute node and ensure that the collectd service is running.  The log file
+   ``collectd.log`` should contain no errors and should indicate that each plugin was successfully
+   loaded.  For example, from the Jump Host:
+
+   .. code:: bash
+
+       $ opnfv-util overcloud compute0
+       $ ls /etc/collectd/collectd.conf.d/
+       $ systemctl status collectd
+       $ vi /opt/stack/collectd.log
 
-2. On the compute node, you need to inject a corrected memory error:
+   The following plugings should be found loaded:
+   aodh, gnocchi, hugepages, intel_rdt, mcelog, ovs_events, ovs_stats, snmp, virt
 
-.. code:: bash
+2. On the compute node, induce an event monitored by the plugins; e.g. a corrected memory error:
 
-    $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
-    $ cd mce-inject
-    $ make
-    $ modprobe mce-inject
+   .. code:: bash
 
-Modify the test/corrected script to include the following:
+      $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
+      $ cd mce-inject
+      $ make
+      $ modprobe mce-inject
 
-.. code:: bash
+   Modify the test/corrected script to include the following:
 
-    CPU 0 BANK 0
-    STATUS 0xcc00008000010090
-    ADDR 0x0010FFFFFFF
+   .. code:: bash
 
-Inject the error:
+      CPU 0 BANK 0
+      STATUS 0xcc00008000010090
+      ADDR 0x0010FFFFFFF
 
-.. code:: bash
+   Inject the error:
 
-    $ ./mce-inject < test/corrected
+   .. code:: bash
 
-3. SSH to openstack controller node and query the ceilometer DB:
+      $ ./mce-inject < test/corrected
 
-.. code:: bash
+3. Connect to the controller and query the monitoring services.  Make sure the overcloudrc.v3
+   file has been copied to the controller (from the undercloud VM or from the Jump Host) in order
+   to be able to authenticate for OpenStack services.
 
-    $ 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
+   .. code:: bash
 
-As you run each command above, you should see output similar to the examples below:
+      $ opnfv-util overcloud controller0
+      $ su
+      $ source overcloudrc.v3
+      $ gnocchi metric list
+      $ aodh alarm list
 
-.. 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 |
+   The output for the gnocchi and aodh queries should be similar to the excerpts below:
 
- | 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 |
- +-------------------------------------+-------------------------+-------+--------+------+---------------------+
+   .. code:: bash
 
- | 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 |
+      +--------------------------------------+---------------------+------------------------------------------------------------------------------------------------------------+-----------+-------------+
+      | id                                   | archive_policy/name | name                                                                                                       | unit      | resource_id |
+      +--------------------------------------+---------------------+------------------------------------------------------------------------------------------------------------+-----------+-------------+
+        [...]
+      | 0550d7c1-384f-4129-83bc-03321b6ba157 | high                | overcloud-novacompute-0.jf.intel.com-hugepages-mm-2048Kb@vmpage_number.free                                | Pages     | None        |
+      | 0cf9f871-0473-4059-9497-1fea96e5d83a | high                | overcloud-novacompute-0.jf.intel.com-hugepages-node0-2048Kb@vmpage_number.free                             | Pages     | None        |
+      | 0d56472e-99d2-4a64-8652-81b990cd177a | high                | overcloud-novacompute-0.jf.intel.com-hugepages-node1-1048576Kb@vmpage_number.used                          | Pages     | None        |
+      | 0ed71a49-6913-4e57-a475-d30ca2e8c3d2 | high                | overcloud-novacompute-0.jf.intel.com-hugepages-mm-1048576Kb@vmpage_number.used                             | Pages     | None        |
+      | 11c7be53-b2c1-4c0e-bad7-3152d82c6503 | high                | overcloud-novacompute-0.jf.intel.com-mcelog-                                                               | None      | None        |
+      |                                      |                     | SOCKET_0_CHANNEL_any_DIMM_any@errors.uncorrected_memory_errors_in_24h                                      |           |             |
+      | 120752d4-385e-4153-aed8-458598a2a0e0 | high                | overcloud-novacompute-0.jf.intel.com-cpu-24@cpu.interrupt                                                  | jiffies   | None        |
+      | 1213161e-472e-4e1b-9e56-5c6ad1647c69 | high                | overcloud-novacompute-0.jf.intel.com-cpu-6@cpu.softirq                                                     | jiffies   | None        |
+        [...]
 
+      +--------------------------------------+-------+------------------------------------------------------------------+-------+----------+---------+
+      | alarm_id                             | type  | name                                                             | state | severity | enabled |
+      +--------------------------------------+-------+------------------------------------------------------------------+-------+----------+---------+
+      | fbd06539-45dd-42c5-a991-5c5dbf679730 | event | gauge.memory_erros(overcloud-novacompute-0.jf.intel.com-mcelog)  | ok    | moderate | True    |
+      | d73251a5-1c4e-4f16-bd3d-377dd1e8cdbe | event | gauge.mcelog_status(overcloud-novacompute-0.jf.intel.com-mcelog) | ok    | moderate | True    |
+        [...]