From 0c1d10389d86c1e6c5cb33552baf58840529406b Mon Sep 17 00:00:00 2001 From: Maryam Tahhan Date: Fri, 2 Dec 2016 19:04:29 +0000 Subject: userguide: update with plugin build info Update the userguide with build instructions for individual plugins. Change-Id: I8c5a16a8749ff4a45692b6d09a0c7a4b27b31e0c Signed-off-by: Maryam Tahhan --- docs/userguide/collectd.userguide.rst | 249 +++++++++++++++++++++++++++++++++- 1 file changed, 247 insertions(+), 2 deletions(-) (limited to 'docs') 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 + + Coremask "0xf" + ProcessType "secondary" + FilePrefix "rte" + EnabledPortMask 0xffff + + +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 + + ReportPerNodeHP true + ReportRootHP true + ValuesPages true + ValuesBytes false + ValuesPercentage false + + +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 + + + Interval 1 + + + Cores "" + + +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 + + # Exec "user:group" "/path/to/exec" + NotificationExec "user" "/barometer/src/collectd/collectd_sample_configs/write_notification.sh" + + +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 + + LogLevel info + File "/var/log/collectd.log" + Timestamp true + PrintSeverity false + + Monitoring Interfaces and Openstack Support ------------------------------------------- .. Figure:: monitoring_interfaces.png -- cgit 1.2.3-korg