userguide: update with plugin build info

Update the userguide with build instructions for individual plugins.

Change-Id: I8c5a16a8749ff4a45692b6d09a0c7a4b27b31e0c
Signed-off-by: Maryam Tahhan <maryam.tahhan@intel.com>

1 files changed, 247 insertions, 2 deletions

diff --git a/docs/userguide/collectd.userguide.rst b/docs/userguide/collectd.userguide.rst
index 8bf666e2..cbe87a09 100644
--- a/docs/userguide/collectd.userguide.rst
+++ b/docs/userguide/collectd.userguide.rst
@@ -47,8 +47,11 @@ Other plugins under development or existing as a pull request into collectd mast
 
 Building collectd with the Barometer plugins and installing the dependencies
 =============================================================================
-The plugins that have been merged to master can all be built and configured through
-the barometer repository.
+
+All plugins
+-----------
+The plugins that have been merged to the baromter master branch can all be
+built and configured through the barometer repository.
 
 **Note**: sudo permissions are required to install collectd.
 
@@ -83,6 +86,248 @@ Please note if you are using any Open vSwitch plugins you need to run:
 
     $ 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.git
+    $ make
+    $ make install PREFIX=/usr
+
+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
+
+Installing collectd 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