summaryrefslogtreecommitdiffstats
path: root/docs/release/userguide
diff options
context:
space:
mode:
Diffstat (limited to 'docs/release/userguide')
-rw-r--r--docs/release/userguide/feature.userguide.rst158
1 files changed, 114 insertions, 44 deletions
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
index 2be44d33..4e9b0d01 100644
--- a/docs/release/userguide/feature.userguide.rst
+++ b/docs/release/userguide/feature.userguide.rst
@@ -27,6 +27,9 @@ Barometer has enabled the following collectd plugins:
* *dpdkstat plugin*: A read plugin that retrieve stats from the DPDK extended
NIC stats API.
+* *dpdkevents plugin*: A read plugin that retrieves DPDK link status and DPDK
+ forwarding cores liveliness status (DPDK Keep Alive).
+
* `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.
@@ -35,26 +38,23 @@ Barometer has enabled the following collectd plugins:
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.
+* *Open vSwitch stats Plugin*: A read plugin that retrieve flow and interface
+ stats 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
+* *RDT plugin*: A read plugin that provides the last level cache utilitzation and
+ memory bandwidth utilization
+
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
+ceilometer plugin as it's a python based plugin and only C plugins are accepted
by the collectd community. The ceilometer plugin lives in the OpenStack
repositories.
-Other plugins 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.
+Other plugins existing as a pull request into collectd master:
* *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
@@ -67,6 +67,7 @@ Other plugins under development or existing as a pull request into collectd mast
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
@@ -79,20 +80,22 @@ 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.
+.. 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.
+
+ 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.**
+.. note::
+ * sudo permissions are required to install collectd.
+ * These are instructions for Ubuntu 16.04
To build and install these dependencies, clone the barometer repo:
@@ -113,29 +116,37 @@ To install collectd as a service and install all it's dependencies:
$ cd barometer/src && sudo make && sudo make install
This will install collectd as a service and the base install directory
-is /opt/collectd.
+will be /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.
+.. note::
+ - If you plan on using the Exec plugin, the 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:
+ - If you don't want to use one of the Barometer plugins, simply remove the
+ sample config file from '/opt/collectd/etc/collectd.conf.d'
+ - If you are using any Open vSwitch plugins you need to run:
.. code:: bash
$ sudo ovs-vsctl set-manager ptcp:6640
+
+Below is the per plugin installation and configuration guide, if you only want
+to install some/particular plugins.
+
DPDK statistics plugin
^^^^^^^^^^^^^^^^^^^^^^
Repo: https://github.com/collectd/collectd
Branch: master
-Dependencies: DPDK (http://dpdk.org/)
+Dependencies: DPDK (http://dpdk.org/) Min_Version: 16.04
To build and install DPDK to /usr please see:
https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md
@@ -154,41 +165,96 @@ Building and installing collectd:
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
+To configure the dpdkstats 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 "dpdkstat">
+ <EAL>
+ Coremask "0x2"
+ MemoryChannels "4"
+ ProcessType "secondary"
+ FilePrefix "rte"
+ </EAL>
+ EnabledPortMask 0xffff
+ PortName "interface1"
+ PortName "interface2"
</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:
+.. note:: 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).
+
+DPDK events 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
- $ make EXTRA_CFLAGS=-fPIC
+ $ git clone https://github.com/maryamtahhan/collectd.git
+ $ cd collectd
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug
+ $ make
+ $ sudo make install
-You must also modify the configuration step when building collectd:
+This will install collectd to /opt/collectd
+The collectd configuration file can be found at /opt/collectd/etc
+To configure the dpdkevents plugin you need to modify the configuration file to
+include:
.. code:: bash
- $ ./configure CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive"
+ LoadPlugin dpdkevents
+ <Plugin "dpdkevents">
+ Interval 1
+ <EAL>
+ Coremask "0x1"
+ MemoryChannels "4"
+ ProcessType "secondary"
+ FilePrefix "rte"
+ </EAL>
+ <Event "link_status">
+ SendEventsOnUpdate true
+ EnabledPortMask 0xffff
+ PortName "interface1"
+ PortName "interface2"
+ SendNotification false
+ </Event>
+ <Event "keep_alive">
+ SendEventsOnUpdate true
+ LCoreMask "0xf"
+ KeepAliveShmName "/dpdk_keepalive_shm_name"
+ SendNotification false
+ </Event>
+ </Plugin>
+
+For more information on the plugin parameters, please see:
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
-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.
+.. note:: 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).
.. code:: bash
@@ -551,7 +617,10 @@ OvS Events Branch: master
OvS Stats Branch:feat_ovs_stats
-Dependencies: Open vSwitch, libyajl
+OvS Events MIBs: The SNMP OVS interface link status is provided by standard
+IF-MIB (http://www.net-snmp.org/docs/mibs/IF-MIB.txt)
+
+Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl)
On Ubuntu, install the dependencies:
@@ -601,6 +670,7 @@ need to modify the configuration file to include:
Socket "/var/run/openvswitch/db.sock"
Interfaces "br0" "veth0"
SendNotification false
+ DispatchValues true
</Plugin>
To configure the OVS stats plugin you need to modify the configuration file