X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Frelease%2Fuserguide%2Ffeature.userguide.rst;h=ed4729ed3c3991905dffd249f325d6e361acc667;hb=HEAD;hp=50d59cf5e699d2720720505129c0324f70d6f965;hpb=6402cb3470bf9e6e790b9afa4b5b61a79717d259;p=barometer.git diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 50d59cf5..2750bd8d 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -1,10 +1,12 @@ +.. _feature-userguide: + .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. (c) +.. (c) Anuket and others -=================================== -OPNFV Barometer User Guide -=================================== +=========================== +Anuket Barometer User Guide +=========================== Barometer collectd plugins description --------------------------------------- @@ -20,26 +22,15 @@ to support thresholding and notification. Barometer has enabled the following collectd plugins: -* *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). - * *dpdk_telemetry plugin*: A read plugin to collect dpdk interface stats and - application or global stats from dpdk telemetry library. Both 'dpdkstat' and - 'dpdk_telemetry' plugins provides dpdk NIC Stats, but only 'dpdk_telemetry' - provides the DPDK Application stats. So in other words, 'dpdk_telemetry' is - an advanced version of dpdkstat. This plugin don't deal with dpdk events. - So not in related with 'dpdkevents' plugin. The mimimum dpdk version required - to use this plugin is 19.08. + application or global stats from dpdk telemetry library. The ``dpdk_telemetry`` + plugin provides both DPDK NIC Stats and DPDK application stats. + This plugin doesn't deal with dpdk events. + The mimimum dpdk version required to use this plugin is 19.08. .. note:: - dpdpkstat and dpdk_telemetry should not be used together. Use dpdk_telemetry - if your version of dpdk supports it (i.e. DPDK >= 19.08) and use dpdkstat otherwise. - dpdkstat, dpdkevents and dpdk_telemetry plugins should only be used if your dpdk - application doesn't already have more relevant metrics available(e.g.ovs_stats). - + The ``dpdk_telemetry`` plugin should only be used if your dpdk application + doesn't already have more relevant metrics available (e.g.ovs_stats). * `gnocchi plugin`_: A write plugin that pushes the retrieved stats to Gnocchi. It's capable of pushing any stats read through collectd to @@ -107,15 +98,12 @@ Read Plugins/application: Intel RDT plugin, virt plugin, Open vSwitch stats plug Open vSwitch PMD stats application. Collectd capabilities and usage ------------------------------------- +------------------------------- .. Describe the specific capabilities and usage for feature. .. Provide enough information that a user will be able to operate the feature on a deployed scenario. -.. 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. +The collectd plugins in Anuket are configured with reasonable defaults, but can +be overridden. Building all Barometer upstreamed plugins from scratch ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -152,12 +140,12 @@ Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d' 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. + 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: -.. code:: bash + .. code:: bash $ sudo ovs-vsctl set-manager ptcp:6640 @@ -176,15 +164,15 @@ collectd, check out the `collectd-openstack-plugins GSG`_. Below is the per plugin installation and configuration guide, if you only want to install some/particular plugins. -DPDK plugins -^^^^^^^^^^^^^ +DPDK telemetry plugin +^^^^^^^^^^^^^^^^^^^^^ Repo: https://github.com/collectd/collectd Branch: main -Dependencies: DPDK (http://dpdk.org/) +Dependencies: `DPDK `_ (runtime), libjansson (compile-time) -.. note:: DPDK statistics plugin requires DPDK version 16.04 or later. +.. note:: DPDK telemetry plugin requires DPDK version 19.08 or later. To build and install DPDK to /usr please see: https://github.com/collectd/collectd/blob/main/docs/BUILD.dpdkstat.md @@ -200,83 +188,35 @@ Building and installing collectd: $ make $ sudo make install -.. note:: If DPDK was installed in a non standard location you will need to - specify 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). - -Example of specifying custom paths to DPDK headers and libraries: - -.. code:: bash - - $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries" - 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 - - Coremask "0xf" - ProcessType "secondary" - FilePrefix "rte" - EnabledPortMask 0xffff - PortName "interface1" - PortName "interface2" - - -To configure the dpdkevents plugin you need to modify the configuration file to +To configure the dpdk_telemetry plugin you need to modify the configuration file to include: .. code:: bash - - Interval 1 - - - - - Coremask "0x1" - MemoryChannels "4" - FilePrefix "rte" - - - SendEventsOnUpdate false - EnabledPortMask 0xffff - SendNotification true - - - SendEventsOnUpdate false - LCoreMask "0xf" - KeepAliveShmName "/dpdk_keepalive_shm_name" - SendNotification true - + LoadPlugin dpdk_telemetry + + #ClientSocketPath "/var/run/.client" + #DpdkSocketPath "/var/run/dpdk/rte/telemetry" -.. note:: Currently, the DPDK library doesn’t support API to de-initialize - the DPDK resources allocated on the initialization. It means, the collectd - plugin will not be able to release the allocated DPDK resources - (locks/memory/pci bindings etc.) correctly on collectd shutdown or reinitialize - the DPDK library if primary DPDK process is restarted. The only way to release - those resources is to terminate the process itself. For this reason, the plugin - forks off a separate collectd process. This child process becomes a secondary - DPDK process which can be run on specific CPU cores configured by user through - collectd configuration file (“Coremask” EAL configuration option, the - hexadecimal bitmask of the cores to run on). +The plugin uses default values (as shown) for the socket paths, if you use different values, +uncomment and update ``ClientSocketPath`` and ``DpdkSocketPath`` as required. For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/main/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 - ports is increased, internal buffers are resized. That requires 3 read cycles - and no port statistics are submitted during that time. +.. note:: + + To gather metrics from a DPDK application, telemetry needs to be enabled. + This can be done by setting the ``CONFIG_RTE_LIBRTE_TELEMETRY=y`` config flag. + The application then needs to be run with the ``--telemetry`` EAL option, e.g. + :: + $dpdk/app/testpmd --telemetry -l 2,3,4 -n 4 + +For more information on the ``dpdk_telemetry`` plugin, see the `anuket wiki `_. 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 @@ -299,29 +239,8 @@ To fully enable ASLR: and only when all implications of this change have been understood. For more information on multi-process support, please see: -http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html - -**DPDK stats plugin limitations:** - -1. The DPDK primary process application should use the same version of DPDK - that collectd DPDK plugin is using; - -2. L2 statistics are only supported; - -3. The plugin has been tested on Intel NIC’s only. +https://doc.dpdk.org/guides/prog_guide/multi_proc_support.html -**DPDK stats known issues:** - -* DPDK port visibility - - 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, additional work is - required to be done to support DPDK ports and statistics. - -**DPDK telemetry plugin** - -Please refer https://wiki.opnfv.org/display/fastpath/DPDK+Telemetry+Plugin Hugepages Plugin ^^^^^^^^^^^^^^^^^ @@ -355,16 +274,9 @@ 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: -.. code:: bash - - LoadPlugin hugepages - - ReportPerNodeHP true - ReportRootHP true - ValuesPages true - ValuesBytes false - ValuesPercentage false - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/hugepages.conf + :start-at: LoadPlugin + :language: bash For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod @@ -424,37 +336,18 @@ 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 - - - Interval 1 - - - ReportHardwareCacheEvents true - ReportKernelPMUEvents true - ReportSoftwareEvents true - Cores "" - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/intel_pmu.conf + :start-at: LoadPlugin + :language: bash -If you want to monitor Intel CPU specific CPU events, make sure to enable the -additional two options shown below: - -.. code:: bash - - - ReportHardwareCacheEvents true - ReportKernelPMUEvents true - ReportSoftwareEvents true - EventList "$HOME/.cache/pmu-events/GenuineIntel-6-2D-core.json" - HardwareEvents "L2_RQSTS.CODE_RD_HIT,L2_RQSTS.CODE_RD_MISS" "L2_RQSTS.ALL_CODE_RD" - Cores "" - +If you want to monitor Intel CPU specific CPU events, make sure to uncomment the +``EventList`` and ``HardwareEvents`` options above. .. note:: If you set XDG_CACHE_HOME to anything other than the variable above - you will need to modify the path for the EventList configuration. -Use "Cores" option to monitor metrics only for configured cores. If an empty string is provided +Use ``Cores`` option to monitor metrics only for configured cores. If an empty string is provided as value for this field default cores configuration is applied - that is all available cores are monitored separately. To limit monitoring to cores 0-7 set the option as shown below: @@ -482,14 +375,14 @@ Branch: main Dependencies: - * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git - * msr kernel module +* PQoS/Intel RDT library https://github.com/intel/intel-cmt-cat +* msr kernel module Building and installing PQoS/Intel RDT library: .. code:: bash - $ git clone https://github.com/01org/intel-cmt-cat.git + $ git clone https://github.com/intel/intel-cmt-cat $ cd intel-cmt-cat $ make $ make install PREFIX=/usr @@ -516,14 +409,9 @@ 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: -.. code:: bash - - - Interval 1 - - - Cores "" - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/rdt.conf + :start-at: LoadPlugin + :language: bash For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod @@ -534,7 +422,7 @@ Repo: https://github.com/collectd/collectd Branch: feat_ipmi_events, feat_ipmi_analog -Dependencies: OpenIPMI library (http://openipmi.sourceforge.net/) +Dependencies: `OpenIPMI library `_ The IPMI plugin is already implemented in the latest collectd and sensors like temperature, voltage, fanspeed, current are already supported there. @@ -638,7 +526,7 @@ collectd IPMI documentation can be used: IPMI documentation: - https://www.kernel.org/doc/Documentation/IPMI.txt -- http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html +- https://www.intel.com/content/www/us/en/products/docs/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html Mcelog Plugin ^^^^^^^^^^^^^^ @@ -646,7 +534,7 @@ Repo: https://github.com/collectd/collectd Branch: main -Dependencies: mcelog +Dependencies: `mcelog `_ Start by installing mcelog. @@ -729,18 +617,9 @@ 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: -.. code:: bash - - - Interval 1 - - - - McelogClientSocket "/var/run/mcelog-client" - PersistentNotification false - - #McelogLogfile "/var/log/mcelog" - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/mcelog.conf + :start-at: LoadPlugin + :language: bash For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod @@ -839,15 +718,15 @@ To inject corrected memory errors: * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog. Open vSwitch Plugins -^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^ OvS Plugins Repo: https://github.com/collectd/collectd OvS Plugins Branch: main 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) +`IF-MIB `_ -Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl) +Dependencies: Open vSwitch, `Yet Another JSON Library `_ On Centos, install the dependencies and Open vSwitch: @@ -856,7 +735,7 @@ On Centos, install the dependencies and Open vSwitch: $ sudo yum install yajl-devel Steps to install Open vSwtich can be found at -http://docs.openvswitch.org/en/latest/intro/install/fedora/ +https://docs.openvswitch.org/en/latest/intro/install/fedora/ Start the Open vSwitch service: @@ -884,47 +763,33 @@ Clone and install the collectd ovs plugin: 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: +To configure the OVS events plugin you need to modify the configuration file +(uncommenting and updating values as appropriate) to include: -.. code:: bash - - - Interval 1 - - - Port "6640" - Address "127.0.0.1" - Socket "/var/run/openvswitch/db.sock" - Interfaces "br0" "veth0" - SendNotification true - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/ovs_events.conf + :start-at: LoadPlugin + :language: bash To configure the OVS stats plugin you need to modify the configuration file -to include: - -.. code:: bash +(uncommenting and updating values as appropriate) to include: - - Interval 1 - - - Port "6640" - Address "127.0.0.1" - Socket "/var/run/openvswitch/db.sock" - Bridges "br0" - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/ovs_stats.conf + :start-at: LoadPlugin + :language: bash For more information on the plugin parameters, please see: https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod OVS PMD stats -^^^^^^^^^^^^^^ -Repo: https://gerrit.opnfv.org/gerrit/barometer +^^^^^^^^^^^^^ +Repo: https://gerrit.opnfv.org/gerrit/gitweb?p=barometer.git Prequistes: -1. Open vSwitch dependencies are installed. -2. Open vSwitch service is running. -3. Ovsdb-server manager is configured. + +#. Open vSwitch dependencies are installed. +#. Open vSwitch service is running. +#. Ovsdb-server manager is configured. + You can refer `Open vSwitch Plugins`_ section above for each one of them. OVS PMD stats application is run through the exec plugin. @@ -943,12 +808,11 @@ to include: .. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service. -ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument: +``ovs_pmd_stat.sh`` calls the script for OVS PMD stats application with its argument: -.. code:: bash - - sudo python /usr/local/src/ovs_pmd_stats.py" "--socket-pid-file" - "/var/run/openvswitch/ovs-vswitchd.pid" +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/ovs_pmd_stats.sh + :start-at: python + :language: bash SNMP Agent Plugin ^^^^^^^^^^^^^^^^^ @@ -1100,12 +964,12 @@ http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/ .. _virt-plugin: virt plugin -^^^^^^^^^^^^ +^^^^^^^^^^^ Repo: https://github.com/collectd/collectd Branch: main -Dependencies: libvirt (https://libvirt.org/), libxml2 +Dependencies: `libvirt `_, libxml2 On Centos, install the dependencies: @@ -1133,7 +997,7 @@ metrics depends on running libvirt daemon version. .. note:: Please keep in mind that RDT metrics (part of *Performance monitoring events*) have to be supported by hardware. For more details on hardware support, please see: - https://github.com/01org/intel-cmt-cat + https://github.com/intel/intel-cmt-cat Additionally perf metrics **cannot** be collected if *Intel RDT* plugin is enabled. @@ -1242,8 +1106,6 @@ https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod Installing collectd as a service ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**NOTE**: In an OPNFV installation, collectd is installed and configured as a -service. Collectd service scripts are available in the collectd/contrib directory. To install collectd as a service: @@ -1274,33 +1136,27 @@ Reload $ 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: +for debug). Modify ``/opt/collectd/etc/collectd.conf`` to include the +``NotificationExec`` config option, taking care to add the right directory path +to the ``write_notification.sh`` script: -.. code:: bash - - LoadPlugin exec - - # Exec "user:group" "/path/to/exec" - NotificationExec "user" "/barometer/src/collectd/collectd_sample_configs/write_notification.sh" - +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/exec.conf + :start-at: LoadPlugin + :emphasize-lines: 6 + :language: bash -write_notification.sh (just writes the notification passed from exec through -STDIN to a file (/tmp/notifications)): - -.. code:: bash +``write_notification.sh`` writes the notification passed from exec through +STDIN to a file (``/tmp/notifications``): - #!/bin/bash - rm -f /tmp/notifications - while read x y - do - echo $x$y >> /tmp/notifications - done +.. literalinclude:: ../../../src/collectd/collectd_sample_configs/write_notification.sh + :start-at: rm -f + :language: bash -output to /tmp/notifications should look like: +output to ``/tmp/notifications`` should look like: .. code:: bash @@ -1347,7 +1203,7 @@ For more information on configuring and installing OpenStack plugins for collectd, check out the `collectd-openstack-plugins GSG`_. Security -^^^^^^^^^ +^^^^^^^^ * AAA – on top of collectd there secure agents like SNMP V3, Openstack agents etc. with their own AAA methods. @@ -1358,7 +1214,7 @@ Security * Ensuring that only one instance of the program is executed by collectd at any time * Forcing the plugin to check that custom programs are never executed with superuser - privileges. + privileges. * Protection of Data in flight: @@ -1377,7 +1233,7 @@ Security * `CVE-2010-4336`_ fixed https://mailman.verplant.org/pipermail/collectd/2010-November/004277.html in Version 4.10.2. - * http://www.cvedetails.com/product/20310/Collectd-Collectd.html?vendor_id=11242 + * https://www.cvedetails.com/product/20310/Collectd-Collectd.html?vendor_id=11242 * It's recommended to only use collectd plugins from signed packages. @@ -1392,10 +1248,10 @@ References .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/ -.. _gnocchi plugin: https://github.com/openstack/collectd-openstack-plugins/tree/stable/ocata/ -.. _aodh plugin: https://github.com/openstack/collectd-openstack-plugins/tree/stable/ocata/ -.. _collectd-openstack-plugins GSG: https://github.com/openstack/collectd-openstack-plugins/blob/master/doc/source/GSG.rst -.. _grafana guide: https://wiki.opnfv.org/display/fastpath/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd +.. _gnocchi plugin: https://opendev.org/x/collectd-openstack-plugins/src/branch/stable/ocata/ +.. _aodh plugin: https://opendev.org/x/collectd-openstack-plugins/src/branch/stable/ocata/ +.. _collectd-openstack-plugins GSG: https://opendev.org/x/collectd-openstack-plugins/src/branch/master/doc/source/GSG.rst +.. _grafana guide: https://wiki.anuket.io/display/HOME/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd .. _CVE-2017-7401: https://www.cvedetails.com/cve/CVE-2017-7401/ .. _CVE-2016-6254: https://www.cvedetails.com/cve/CVE-2016-6254/ .. _CVE-2010-4336: https://www.cvedetails.com/cve/CVE-2010-4336/