summaryrefslogtreecommitdiffstats
path: root/docs/userguide
diff options
context:
space:
mode:
authorMaryam Tahhan <maryam.tahhan@intel.com>2016-12-02 19:04:29 +0000
committerMaryam Tahhan <maryam.tahhan@intel.com>2016-12-05 14:10:52 +0000
commit0c1d10389d86c1e6c5cb33552baf58840529406b (patch)
tree6ba77d0f8fcf10994930eff80120b0abc54c4069 /docs/userguide
parent843ea84d9da3a4a20a7ad388d94ae8c861380254 (diff)
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>
Diffstat (limited to 'docs/userguide')
-rw-r--r--docs/userguide/collectd.userguide.rst249
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