diff options
Diffstat (limited to 'docs/release/userguide/feature.userguide.rst')
| -rw-r--r-- | docs/release/userguide/feature.userguide.rst | 318 |
1 files changed, 197 insertions, 121 deletions
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 29298536..099d8e27 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -15,7 +15,7 @@ Barometer collectd plugins description .. Describe the specific features and how it is realised in the scenario in a brief manner .. to ensure the user understand the context for the user guide instructions to follow. -collectd is a daemon which collects system performance statistics periodically +Collectd is a daemon which collects system performance statistics periodically and provides a variety of mechanisms to publish the collected metrics. It supports more than 90 different input and output plugins. Input plugins retrieve metrics and publish them to the collectd deamon, while output plugins @@ -24,8 +24,8 @@ to support thresholding and notification. Barometer has enabled the following collectd plugins: -* *dpdkstat plugin*: A read plugin that retrieve stats from the DPDK extended - NIC stats API. +* *dpdkstat plugin*: A read plugin that retrieves 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). @@ -47,10 +47,13 @@ Barometer has enabled the following collectd plugins: 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 + memory Machine Check Exceptions and sends the stats for reported exceptions. + +* *PMU plugin*: A read plugin that provides performance counters data on + Intel CPUs using Linux perf interface. * *RDT plugin*: A read plugin that provides the last level cache utilization and - memory bandwidth utilization + memory bandwidth utilization. * *virt*: A read plugin that uses virtualization API *libvirt* to gather statistics about virtualized guests on a system directly from the hypervisor, @@ -84,22 +87,20 @@ Third party application in Barometer repository: * *Open vSwitch PMD stats*: An aplication that retrieves PMD stats from OVS. It is run through exec plugin. -**Plugins included in the Danube release:** +**Plugins and application included in the Euphrates release:** + +Write Plugins: aodh plugin, SNMP agent plugin, gnocchi plugin. -* Hugepages -* Open vSwitch Events -* Ceilometer -* Mcelog +Read Plugins/application: Intel RDT plugin, virt plugin, Open vSwitch stats plugin, +Open vSwitch PMD stats application. -collectd capabilities and usage +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. +.. note:: Plugins included in the OPNFV E release will be built-in for Apex integration + and can be configured as shown in the examples below. The collectd plugins in OPNFV are configured with reasonable defaults, but can be overridden. @@ -111,7 +112,7 @@ built and configured through the barometer repository. .. note:: * sudo permissions are required to install collectd. - * These are instructions for Ubuntu 16.04 + * These instructions are for Centos 7. To build all the upstream plugins, clone the barometer repo: @@ -135,13 +136,11 @@ Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d' sample config file from '/opt/collectd/etc/collectd.conf.d' .. note:: If you plan on using the Exec plugin (for OVS_PMD_STATS or for executing scripts - on notification generation), the plugin requires a non-root - user to execute scripts. By default, `collectd_exec` user is used in the exec.conf - provided in the sample configurations directory under src/collectd in the Barometer - repo. The scripts *DO NOT* create this user. You need to create this user before you - run build_base_machine.sh. Or modify configuration in the sample configurations - directory under src/collectd to use another existing non root user before running - run build_base_machine.sh. + on notification generation), the plugin requires a non-root user to execute scripts. + By default, `collectd_exec` user is used in the exec.conf provided in the sample + configurations directory under src/collectd in the Barometer repo. These scripts *DO NOT* create this user. + You need to create this user or modify the configuration in the sample configurations directory + under src/collectd to use another existing non root user before running build_base_machine.sh. .. note:: If you are using any Open vSwitch plugins you need to run: @@ -173,7 +172,7 @@ Branch: master Dependencies: DPDK (http://dpdk.org/) -.. note:: DPDK statistics plugin requires DPDK version 16.04 or later +.. note:: DPDK statistics plugin requires DPDK version 16.04 or later. To build and install DPDK to /usr please see: https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md @@ -201,25 +200,21 @@ Example of specifying custom paths to DPDK headers and libraries: $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries" -This will install collectd to /opt/collectd -The collectd configuration file can be found at /opt/collectd/etc - +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To configure the dpdkstats plugin you need to modify the configuration file to include: .. code:: bash LoadPlugin dpdkstat - <Plugin "dpdkstat"> - <EAL> - Coremask "0x2" - MemoryChannels "4" - ProcessType "secondary" - FilePrefix "rte" - </EAL> - EnabledPortMask 0xffff - PortName "interface1" - PortName "interface2" + <Plugin dpdkstat> + Coremask "0xf" + ProcessType "secondary" + FilePrefix "rte" + EnabledPortMask 0xffff + PortName "interface1" + PortName "interface2" </Plugin> @@ -228,28 +223,27 @@ include: .. code:: bash - LoadPlugin dpdkevents + <LoadPlugin dpdkevents> + Interval 1 + </LoadPlugin> + <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> + <EAL> + Coremask "0x1" + MemoryChannels "4" + FilePrefix "rte" + </EAL> + <Event "link_status"> + SendEventsOnUpdate false + EnabledPortMask 0xffff + SendNotification true + </Event> + <Event "keep_alive"> + SendEventsOnUpdate false + LCoreMask "0xf" + KeepAliveShmName "/dpdk_keepalive_shm_name" + SendNotification true + </Event> </Plugin> .. note:: Currently, the DPDK library doesn’t support API to de-initialize @@ -267,10 +261,10 @@ For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod .. note:: dpdkstat plugin initialization time depends on read interval. It - requires 5 read cycles to set up internal buffers and states. During that time - no statistics are submitted. Also if plugin is running and the number of DPDK + requires 5 read cycles to set up internal buffers and states, during that time + no statistics are submitted. Also, if plugin is running and the number of DPDK ports is increased, internal buffers are resized. That requires 3 read cycles - and no port statistics are submitted in that time. + and no port statistics are submitted during that time. The Address-Space Layout Randomization (ASLR) security feature in Linux should be disabled, in order for the same hugepage memory mappings to be present in all @@ -310,7 +304,7 @@ http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html When network port controlled by Linux is bound to DPDK driver, the port will not be available in the OS. It affects the SNMP write plugin as those - ports will not be present in standard IF-MIB. Thus addition work is + ports will not be present in standard IF-MIB. Thus, additional work is required to be done to support DPDK ports and statistics. Hugepages Plugin @@ -325,9 +319,9 @@ 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 + $ 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: @@ -340,8 +334,8 @@ Building and installing collectd: $ make $ sudo make install -This will install collectd to /opt/collectd -The collectd configuration file can be found at /opt/collectd/etc +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To configure the hugepages plugin you need to modify the configuration file to include: @@ -359,6 +353,72 @@ include: For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod +Intel PMU Plugin +^^^^^^^^^^^^^^^^ +Repo: https://github.com/collectd/collectd + +Branch: master + +Dependencies: + + * PMU tools (jevents library) https://github.com/andikleen/pmu-tools + +To be suitable for use in collectd plugin shared library *libjevents* should be +compiled as position-independent code. To do this add the following line to +*pmu-tools/jevents/Makefile*: + +.. code:: bash + + CFLAGS += -fPIC + +Building and installing *jevents* library: + +.. code:: bash + + $ git clone https://github.com/andikleen/pmu-tools.git + $ cd pmu-tools/jevents/ + $ make + $ sudo make install + +Building and installing collectd: + +.. code:: bash + + $ git clone https://github.com/collectd/collectd.git + $ cd collectd + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --with-libjevents=/usr/local --enable-debug + $ make + $ sudo make install + +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. +To configure the PMU plugin you need to modify the configuration file to +include: + +.. code:: bash + + <LoadPlugin intel_pmu> + Interval 1 + </LoadPlugin> + <Plugin "intel_pmu"> + ReportHardwareCacheEvents true + ReportKernelPMUEvents true + ReportSoftwareEvents true + </Plugin> + +For more information on the plugin parameters, please see: +https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod + +.. note:: + + The plugin opens file descriptors whose quantity depends on number of + monitored CPUs and number of monitored counters. Depending on configuration, + it might be required to increase the limit on the number of open file + descriptors allowed. This can be done using 'ulimit -n' command. If collectd + is executed as a service 'LimitNOFILE=' directive should be defined in + [Service] section of *collectd.service* file. + Intel RDT Plugin ^^^^^^^^^^^^^^^^ Repo: https://github.com/collectd/collectd @@ -396,8 +456,8 @@ Building and installing collectd: $ make $ sudo make install -This will install collectd to /opt/collectd -The collectd configuration file can be found at /opt/collectd/etc +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To configure the RDT plugin you need to modify the configuration file to include: @@ -436,11 +496,11 @@ has been introduced. **Install dependencies** -On Ubuntu, the OpenIPMI library can be installed via apt package manager: +On Centos, install OpenIPMI library: .. code:: bash - $ sudo apt-get install libopenipmi-dev + $ sudo yum install OpenIPMI ipmitool Anyway, it's recommended to use the latest version of the OpenIPMI library as it includes fixes of known issues which aren't included in standard OpenIPMI @@ -452,7 +512,7 @@ Remove old version of OpenIPMI library: .. code:: bash - $ sudo apt-get remove libopenipmi-dev + $ sudo yum remove OpenIPMI ipmitool Download OpenIPMI library sources: @@ -515,8 +575,8 @@ Clone and install the collectd IPMI plugin: Where $BRANCH is feat_ipmi_events or feat_ipmi_analog. This will install collectd to default folder ``/opt/collectd``. The collectd -configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To -configure the IPMI plugin you need to modify the file to include: +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. +To configure the IPMI plugin you need to modify the file to include: .. code:: bash @@ -556,19 +616,19 @@ 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. + need atleast a 2.6,30 kernel. -On ubuntu: +On Centos: .. code:: bash - $ apt-get update && apt-get install mcelog + $ sudo yum install mcelog Or build from source .. code:: bash - $ git clone git://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git + $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git $ cd mcelog $ make ... become root ... @@ -595,6 +655,27 @@ enable: .. code:: bash socket-path = /var/run/mcelog-client + [dimm] + dimm-tracking-enabled = yes + dmi-prepopulate = yes + uc-error-threshold = 1 / 24h + ce-error-threshold = 10 / 24h + + [socket] + socket-tracking-enabled = yes + mem-uc-error-threshold = 100 / 24h + mem-ce-error-threshold = 100 / 24h + mem-ce-error-log = yes + + [page] + memory-ce-threshold = 10 / 24h + memory-ce-log = yes + memory-ce-action = soft + + [trigger] + children-max = 2 + directory = /etc/mcelog + Clone and install the collectd mcelog plugin: @@ -602,14 +683,13 @@ Clone and install the collectd mcelog plugin: $ 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 +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To configure the mcelog plugin you need to modify the configuration file to include: @@ -618,7 +698,7 @@ include: <LoadPlugin mcelog> Interval 1 </LoadPlugin> - <Plugin "mcelog"> + <Plugin mcelog> McelogClientSocket "/var/run/mcelog-client" </Plugin> @@ -652,7 +732,7 @@ Then you can run the mcelog test suite with 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) +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. @@ -685,7 +765,7 @@ Inject the error: 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: + from mce-test suite can be injected: .. code:: bash @@ -693,7 +773,7 @@ Inject the error: **mce-test:** -In addition an more in-depth test of the Linux kernel machine check facilities +In addition a 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. @@ -728,11 +808,14 @@ 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: +On Centos, install the dependencies and Open vSwitch: .. code:: bash - $ sudo apt-get install libyajl-dev openvswitch-switch + $ sudo yum install yajl-devel + +Steps to install Open vSwtich can be found at +http://docs.openvswitch.org/en/latest/intro/install/fedora/ Start the Open vSwitch service: @@ -740,7 +823,7 @@ Start the Open vSwitch service: $ sudo service openvswitch-switch start -configure the ovsdb-server manager: +Configure the ovsdb-server manager: .. code:: bash @@ -758,21 +841,21 @@ Clone and install the collectd ovs plugin: $ 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 OVS events plugin you -need to modify the configuration file to include: +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. +To configure the OVS events plugin you need to modify the configuration file to include: .. code:: bash <LoadPlugin ovs_events> Interval 1 </LoadPlugin> - <Plugin "ovs_events"> - Port 6640 + <Plugin ovs_events> + Port "6640" + Address "127.0.0.1" Socket "/var/run/openvswitch/db.sock" Interfaces "br0" "veth0" - SendNotification false - DispatchValues true + SendNotification true </Plugin> To configure the OVS stats plugin you need to modify the configuration file @@ -787,7 +870,7 @@ to include: Port "6640" Address "127.0.0.1" Socket "/var/run/openvswitch/db.sock" - Bridges "br0" "br_ext" + Bridges "br0" </Plugin> For more information on the plugin parameters, please see: @@ -815,7 +898,6 @@ to include: </LoadPlugin <Plugin exec> Exec "user:group" "<path to ovs_pmd_stat.sh>" - #NotificationExec "nobody" "/usr/lib/collectd/notify.sh" </Plugin> .. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service. @@ -831,28 +913,22 @@ SNMP Agent Plugin ^^^^^^^^^^^^^^^^^ Repo: https://github.com/maryamtahhan/collectd/ -Branch: feat_snmp +Branch: master Dependencies: NET-SNMP library Start by installing net-snmp and dependencies. -On ubuntu: +On Centos 7: .. code:: bash - $ apt-get install snmp snmp-mibs-downloader snmpd libsnmp-dev + $ sudo yum install net-snmp net-snmp-libs net-snmp-utils net-snmp-devel $ systemctl start snmpd.service Or build from source -Become root to install net-snmp dependencies - -.. code:: bash - - $ apt-get install libperl-dev - -Clone and build net-snmp +Clone and build net-snmp: .. code:: bash @@ -867,13 +943,13 @@ Become root $ make install -Copy default configuration to persistent folder +Copy default configuration to persistent folder: .. code:: bash $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf -Set library path and default MIB configuration +Set library path and default MIB configuration: .. code:: bash @@ -882,7 +958,7 @@ Set library path and default MIB configuration $ net-snmp-config --default-mibdirs $ net-snmp-config --snmpconfpath -Configure snmpd as a service +Configure snmpd as a service: .. code:: bash @@ -917,8 +993,9 @@ Clone and install the collectd snmp_agent plugin: $ make $ sudo make install -This will install collectd to /opt/collectd -The collectd configuration file can be found at /opt/collectd/etc +This will install collectd to default folder ``/opt/collectd``. The collectd +configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. + **SNMP Agent plugin is a generic plugin and cannot work without configuration**. To configure the snmp_agent plugin you need to modify the configuration file to include OIDs mapped to collectd types. The following example maps scalar @@ -954,15 +1031,15 @@ virt plugin ^^^^^^^^^^^^ Repo: https://github.com/maryamtahhan/collectd -Branch: feat_libvirt_upstream +Branch: master Dependencies: libvirt (https://libvirt.org/), libxml2 -On Ubuntu, install the dependencies: +On Centos, install the dependencies: .. code:: bash - $ sudo apt-get install libxml2-dev + $ sudo yum install libxml2-dev libpciaccess-devel yajl-devel device-mapper-devel Install libvirt: @@ -1056,24 +1133,23 @@ Clone and install the collectd virt plugin: $ git clone $REPO $ cd collectd - $ git checkout $BRANCH $ ./build.sh $ ./configure --enable-syslog --enable-logfile --enable-debug $ make $ sudo make install -Where ``$REPO`` and ``$BRANCH`` are equal to information provided above. +Where ``$REPO`` is equal to information provided above. This will install collectd to ``/opt/collectd``. The collectd configuration file -``collectd.conf`` can be found at ``/opt/collectd/etc``. To load the virt plugin -user needs to modify the configuration file to include: +``collectd.conf`` can be found at ``/opt/collectd/etc``. +To load the virt plugin user needs to modify the configuration file to include: .. code:: bash LoadPlugin virt Additionally, user can specify plugin configuration parameters in this file, -such as connection URI, domain name and much more. By default extended virt plugin +such as connection URL, domain name and much more. By default extended virt plugin statistics are disabled. They can be enabled with ``ExtraStats`` option. .. code:: bash @@ -1182,7 +1258,7 @@ Monitoring Interfaces and Openstack Support Monitoring Interfaces and Openstack Support The figure above shows the DPDK L2 forwarding application running on a compute -node, sending and receiving traffic. collectd is also running on this compute +node, sending and receiving traffic. Collectd is also running on this compute node retrieving the stats periodically from DPDK through the dpdkstat plugin and publishing the retrieved stats to OpenStack through the collectd-ceilometer-plugin. |