summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorMaryam Tahhan <maryam.tahhan@intel.com>2016-12-15 16:22:33 +0000
committerGerrit Code Review <gerrit@opnfv.org>2016-12-15 16:22:33 +0000
commitdb7cec29b6a71c0eb0a5a3bcb1e20c4fac73d804 (patch)
tree20dd491e57e5b2c7cec5f8775fdea2791abe2ca0 /docs
parent9864e17ff636d7fffe39e0a4b68a370ab7cb9f58 (diff)
parentb638ad979489977fc47ad464c4b803a55f68d801 (diff)
Merge "docs: userguide ovs and mcelog instructions"
Diffstat (limited to 'docs')
-rw-r--r--docs/userguide/collectd.userguide.rst228
1 files changed, 223 insertions, 5 deletions
diff --git a/docs/userguide/collectd.userguide.rst b/docs/userguide/collectd.userguide.rst
index 2dcb3593..ea09bb1a 100644
--- a/docs/userguide/collectd.userguide.rst
+++ b/docs/userguide/collectd.userguide.rst
@@ -20,8 +20,6 @@ Barometer has enabled the following collectd plugins:
* RDT plugin: A read plugin that provides the last level cache utilitzation and
memory bandwidth utilization
-* Open vSwitch events Plugin: A read plugin that retrieves events from OVS.
-
All the plugins above are available on the collectd master, except for the
ceilometer plugin as it's a python based plugin and only C plugins are accepted
by the collectd community. The ceilometer plugin lives in the OpenStack
@@ -32,6 +30,8 @@ Other plugins under development or existing as a pull request into collectd mast
* dpdkevents: A read plugin that retrieves DPDK link status and DPDK
forwarding cores liveliness status (DPDK Keep Alive).
+* Open vSwitch events Plugin: A read plugin that retrieves events from OVS.
+
* Open vSwitch stats Plugin: A read plugin that retrieve flow and interface
stats from OVS.
@@ -48,9 +48,9 @@ Other plugins under development or existing as a pull request into collectd mast
Building collectd with the Barometer plugins and installing the dependencies
=============================================================================
-All plugins
------------
-The plugins that have been merged to the baromter master branch can all be
+All Upstreamed plugins
+-----------------------
+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.
@@ -246,6 +246,224 @@ include:
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+Mcelog Plugin:
+--------------
+Repo: https://github.com/maryamtahhan/collectd
+
+Branch: feat_ras
+
+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
+ $ ./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
+---------------------
+Repo: https://github.com/maryamtahhan/collectd
+
+Branch: feat_ovs_link, 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 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_ovs_link 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 plugins 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>
+
+For more information on the plugin parameters, please see:
+https://github.com/maryamtahhan/collectd/blob/feat_ovs_link/src/collectd.conf.pod
+and
+https://github.com/maryamtahhan/collectd/blob/feat_ovs_stats/src/collectd.conf.pod
+
Installing collectd as a service
--------------------------------
Collectd service scripts are available in the collectd/contrib directory.