docs/release/userguide/feature.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) <optionally add copywriters name>
   4
   5 ===================================
   6 OPNFV Barometer User Guide
   7 ===================================
   8
   9 .. contents::
  10    :depth: 3
  11    :local:
  12
  13 Barometer collectd plugins description
  14 ---------------------------------------
  15 .. Describe the specific features and how it is realised in the scenario in a brief manner
  16 .. to ensure the user understand the context for the user guide instructions to follow.
  17
  18 collectd is a daemon which collects system performance statistics periodically
  19 and provides a variety of mechanisms to publish the collected metrics. It
  20 supports more than 90 different input and output plugins. Input plugins
  21 retrieve metrics and publish them to the collectd deamon, while output plugins
  22 publish the data they receive to an end point. collectd also has infrastructure
  23 to support thresholding and notification.
  24
  25 Barometer has enabled the following collectd plugins:
  26
  27 * *dpdkstat plugin*: A read plugin that retrieve stats from the DPDK extended
  28    NIC stats API.
  29
  30 * *dpdkevents plugin*:  A read plugin that retrieves DPDK link status and DPDK
  31   forwarding cores liveliness status (DPDK Keep Alive).
  32
  33 * `gnocchi plugin`_: A write plugin that pushes the retrieved stats to
  34   Gnocchi. It's capable of pushing any stats read through collectd to
  35   Gnocchi, not just the DPDK stats.
  36
  37 * `aodh plugin`_: A notification plugin that pushes events to Aodh, and
  38   creates/updates alarms appropriately.
  39
  40 * *hugepages plugin*:  A read plugin that retrieves the number of available
  41   and free hugepages on a platform as well as what is available in terms of
  42   hugepages per socket.
  43
  44 * *Open vSwitch events Plugin*: A read plugin that retrieves events from OVS.
  45
  46 * *Open vSwitch stats Plugin*: A read plugin that retrieves flow and interface
  47   stats from OVS.
  48
  49 * *mcelog plugin*: A read plugin that uses mcelog client protocol to check for
  50   memory Machine Check Exceptions and sends the stats for reported exceptions
  51
  52 * *RDT plugin*: A read plugin that provides the last level cache utilization and
  53   memory bandwidth utilization
  54
  55 * *virt*: A read plugin that uses virtualization API *libvirt* to gather
  56   statistics about virtualized guests on a system directly from the hypervisor,
  57   without a need to install collectd instance on the guest.
  58
  59 * *SNMP Agent*: A write plugin that will act as a AgentX subagent that receives
  60   and handles queries from SNMP master agent and returns the data collected
  61   by read plugins. The SNMP Agent plugin handles requests only for OIDs
  62   specified in configuration file. To handle SNMP queries the plugin gets data
  63   from collectd and translates requested values from collectd's internal format
  64   to SNMP format. Supports SNMP: get, getnext and walk requests.
  65
  66 All the plugins above are available on the collectd master, except for the
  67 Gnocchi and Aodh plugins as they are Python-based plugins and only C plugins
  68 are accepted by the collectd community. The Gnocchi and Aodh plugins live in
  69 the OpenStack repositories.
  70
  71 Other plugins existing as a pull request into collectd master:
  72
  73 * *Legacy/IPMI*: A read plugin that reports platform thermals, voltages,
  74   fanspeed, current, flow, power etc. Also, the plugin monitors Intelligent
  75   Platform Management Interface (IPMI) System Event Log (SEL) and sends the
  76   appropriate notifications based on monitored SEL events.
  77
  78 * *PCIe AER*: A read plugin that monitors PCIe standard and advanced errors and
  79   sends notifications about those errors.
  80
  81
  82 Third party application in Barometer repository:
  83
  84 * *Open vSwitch PMD stats*: An aplication that retrieves PMD stats from OVS. It is run
  85   through exec plugin.
  86
  87 **Plugins included in the Danube release:**
  88
  89 * Hugepages
  90 * Open vSwitch Events
  91 * Ceilometer
  92 * Mcelog
  93
  94 collectd capabilities and usage
  95 ------------------------------------
  96 .. Describe the specific capabilities and usage for <XYZ> feature.
  97 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
  98
  99 .. note:: Plugins included in the OPNFV D release will be built-in to the fuel
 100  plugin and available in the /opt/opnfv directory on the fuel master. You don't
 101  need to clone the barometer/collectd repos to use these, but you can configure
 102  them as shown in the examples below.
 103
 104  The collectd plugins in OPNFV are configured with reasonable defaults, but can
 105  be overridden.
 106
 107 Building all Barometer upstreamed plugins from scratch
 108 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 109 The plugins that have been merged to the collectd master branch can all be
 110 built and configured through the barometer repository.
 111
 112 .. note::
 113  * sudo permissions are required to install collectd.
 114  * These are instructions for Ubuntu 16.04
 115
 116 To build all the upstream plugins, clone the barometer repo:
 117
 118 .. code:: c
 119
 120     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 121
 122 To install collectd as a service and install all it's dependencies:
 123
 124 .. code:: bash
 125
 126     $ cd barometer/systems && ./build_base_machine.sh
 127
 128 This will install collectd as a service and the base install directory
 129 will be /opt/collectd.
 130
 131 Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d'
 132
 133 .. note::
 134   If you don't want to use one of the Barometer plugins, simply remove the
 135   sample config file from '/opt/collectd/etc/collectd.conf.d'
 136 .. note::
 137   If you plan on using the Exec plugin (for OVS_PMD_STATS or for executing scripts
 138   on notification generation), the plugin requires a non-root
 139   user to execute scripts. By default, `collectd_exec` user is used in the exec.conf
 140   provided in the sample configurations directory under src/collectd in the Barometer
 141   repo. The scripts *DO NOT* create this user. You need to create this user before you
 142   run build_base_machine.sh. Or modify configuration in the sample configurations
 143   directory under src/collectd to use another existing non root user before running
 144   run build_base_machine.sh.
 145
 146 .. note::
 147   If you are using any Open vSwitch plugins you need to run:
 148
 149 .. code:: bash
 150
 151     $ sudo ovs-vsctl set-manager ptcp:6640
 152
 153 After this, you should be able to start collectd as a service
 154
 155 .. code:: bash
 156
 157     $ sudo systemctl status collectd
 158
 159 If you want to use granfana to display the metrics you collect, please see:
 160 `grafana guide`_
 161
 162 For more information on configuring and installing OpenStack plugins for
 163 collectd, check out the `collectd-ceilometer-plugin GSG`_.
 164
 165 Below is the per plugin installation and configuration guide, if you only want
 166 to install some/particular plugins.
 167
 168 DPDK plugins
 169 ^^^^^^^^^^^^^
 170 Repo: https://github.com/collectd/collectd
 171
 172 Branch: master
 173
 174 Dependencies: DPDK (http://dpdk.org/)
 175
 176 .. note:: DPDK statistics plugin requires DPDK version 16.04 or later
 177
 178 To build and install DPDK to /usr please see:
 179 https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md
 180
 181 Building and installing collectd:
 182
 183 .. code:: bash
 184
 185     $ git clone https://github.com/collectd/collectd.git
 186     $ cd collectd
 187     $ ./build.sh
 188     $ ./configure --enable-syslog --enable-logfile --enable-debug
 189     $ make
 190     $ sudo make install
 191
 192 .. note:: If DPDK was installed in a non standard location you will need to
 193     specify paths to the header files and libraries using *LIBDPDK_CPPFLAGS* and
 194     *LIBDPDK_LDFLAGS*. You will also need to add the DPDK library symbols to the
 195     shared library path using *ldconfig*. Note that this update to the shared
 196     library path is not persistant (i.e. it will not survive a reboot).
 197
 198 Example of specifying custom paths to DPDK headers and libraries:
 199
 200 .. code:: bash
 201
 202     $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries"
 203
 204 This will install collectd to /opt/collectd
 205 The collectd configuration file can be found at /opt/collectd/etc
 206
 207 To configure the dpdkstats plugin you need to modify the configuration file to
 208 include:
 209
 210 .. code:: bash
 211
 212     LoadPlugin dpdkstat
 213     <Plugin "dpdkstat">
 214         <EAL>
 215             Coremask "0x2"
 216             MemoryChannels "4"
 217             ProcessType "secondary"
 218             FilePrefix "rte"
 219         </EAL>
 220         EnabledPortMask 0xffff
 221         PortName "interface1"
 222         PortName "interface2"
 223     </Plugin>
 224
 225
 226 To configure the dpdkevents plugin you need to modify the configuration file to
 227 include:
 228
 229 .. code:: bash
 230
 231     LoadPlugin dpdkevents
 232     <Plugin "dpdkevents">
 233         Interval 1
 234         <EAL>
 235             Coremask "0x1"
 236             MemoryChannels "4"
 237             ProcessType "secondary"
 238             FilePrefix "rte"
 239         </EAL>
 240         <Event "link_status">
 241             SendEventsOnUpdate true
 242             EnabledPortMask 0xffff
 243             PortName "interface1"
 244             PortName "interface2"
 245             SendNotification false
 246         </Event>
 247         <Event "keep_alive">
 248             SendEventsOnUpdate true
 249             LCoreMask "0xf"
 250             KeepAliveShmName "/dpdk_keepalive_shm_name"
 251             SendNotification false
 252         </Event>
 253     </Plugin>
 254
 255 .. note:: Currently, the DPDK library doesn’t support API to de-initialize
 256  the DPDK resources allocated on the initialization. It means, the collectd
 257  plugin will not be able to release the allocated DPDK resources
 258  (locks/memory/pci bindings etc.) correctly on collectd shutdown or reinitialize
 259  the DPDK library if primary DPDK process is restarted. The only way to release
 260  those resources is to terminate the process itself. For this reason, the plugin
 261  forks off a separate collectd process. This child process becomes a secondary
 262  DPDK process which can be run on specific CPU cores configured by user through
 263  collectd configuration file (“Coremask” EAL configuration option, the
 264  hexadecimal bitmask of the cores to run on).
 265
 266 For more information on the plugin parameters, please see:
 267 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 268
 269 .. note:: dpdkstat plugin initialization time depends on read interval. It
 270  requires 5 read cycles to set up internal buffers and states. During that time
 271  no statistics are submitted. Also if plugin is running and the number of DPDK
 272  ports is increased, internal buffers are resized. That requires 3 read cycles
 273  and no port statistics are submitted in that time.
 274
 275 The Address-Space Layout Randomization (ASLR) security feature in Linux should be
 276 disabled, in order for the same hugepage memory mappings to be present in all
 277 DPDK multi-process applications.
 278
 279 To disable ASLR:
 280
 281 .. code:: bash
 282
 283     $ sudo echo 0 > /proc/sys/kernel/randomize_va_space
 284
 285 To fully enable ASLR:
 286
 287 .. code:: bash
 288
 289     $ sudo echo 2 > /proc/sys/kernel/randomize_va_space
 290
 291 .. warning:: Disabling Address-Space Layout Randomization (ASLR) may have security
 292     implications. It is recommended to be disabled only when absolutely necessary,
 293     and only when all implications of this change have been understood.
 294
 295 For more information on multi-process support, please see:
 296 http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html
 297
 298 **DPDK stats plugin limitations:**
 299
 300 1. The DPDK primary process application should use the same version of DPDK
 301    that collectd DPDK plugin is using;
 302
 303 2. L2 statistics are only supported;
 304
 305 3. The plugin has been tested on Intel NIC’s only.
 306
 307 **DPDK stats known issues:**
 308
 309 * DPDK port visibility
 310
 311   When network port controlled by Linux is bound to DPDK driver, the port
 312   will not be available in the OS. It affects the SNMP write plugin as those
 313   ports will not be present in standard IF-MIB. Thus addition work is
 314   required to be done to support DPDK ports and statistics.
 315
 316 Hugepages Plugin
 317 ^^^^^^^^^^^^^^^^^
 318 Repo: https://github.com/collectd/collectd
 319
 320 Branch: master
 321
 322 Dependencies: None, but assumes hugepages are configured.
 323
 324 To configure some hugepages:
 325
 326 .. code:: bash
 327
 328    sudo mkdir -p /mnt/huge
 329    sudo mount -t hugetlbfs nodev /mnt/huge
 330    sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
 331
 332 Building and installing collectd:
 333
 334 .. code:: bash
 335
 336     $ git clone https://github.com/collectd/collectd.git
 337     $ cd collectd
 338     $ ./build.sh
 339     $ ./configure --enable-syslog --enable-logfile --enable-hugepages --enable-debug
 340     $ make
 341     $ sudo make install
 342
 343 This will install collectd to /opt/collectd
 344 The collectd configuration file can be found at /opt/collectd/etc
 345 To configure the hugepages plugin you need to modify the configuration file to
 346 include:
 347
 348 .. code:: bash
 349
 350     LoadPlugin hugepages
 351     <Plugin hugepages>
 352         ReportPerNodeHP  true
 353         ReportRootHP     true
 354         ValuesPages      true
 355         ValuesBytes      false
 356         ValuesPercentage false
 357     </Plugin>
 358
 359 For more information on the plugin parameters, please see:
 360 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 361
 362 Intel RDT Plugin
 363 ^^^^^^^^^^^^^^^^
 364 Repo: https://github.com/collectd/collectd
 365
 366 Branch: master
 367
 368 Dependencies:
 369
 370   * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git
 371   * msr kernel module
 372
 373 Building and installing PQoS/Intel RDT library:
 374
 375 .. code:: bash
 376
 377     $ git clone https://github.com/01org/intel-cmt-cat.git
 378     $ cd intel-cmt-cat
 379     $ make
 380     $ make install PREFIX=/usr
 381
 382 You will need to insert the msr kernel module:
 383
 384 .. code:: bash
 385
 386     $ modprobe msr
 387
 388 Building and installing collectd:
 389
 390 .. code:: bash
 391
 392     $ git clone https://github.com/collectd/collectd.git
 393     $ cd collectd
 394     $ ./build.sh
 395     $ ./configure --enable-syslog --enable-logfile --with-libpqos=/usr/ --enable-debug
 396     $ make
 397     $ sudo make install
 398
 399 This will install collectd to /opt/collectd
 400 The collectd configuration file can be found at /opt/collectd/etc
 401 To configure the RDT plugin you need to modify the configuration file to
 402 include:
 403
 404 .. code:: bash
 405
 406     <LoadPlugin intel_rdt>
 407       Interval 1
 408     </LoadPlugin>
 409     <Plugin "intel_rdt">
 410       Cores ""
 411     </Plugin>
 412
 413 For more information on the plugin parameters, please see:
 414 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 415
 416 IPMI Plugin
 417 ^^^^^^^^^^^^
 418 Repo: https://github.com/maryamtahhan/collectd
 419
 420 Branch: feat_ipmi_events, feat_ipmi_analog
 421
 422 Dependencies: OpenIPMI library (http://openipmi.sourceforge.net/)
 423
 424 The IPMI plugin is already implemented in the latest collectd and sensors
 425 like temperature, voltage, fanspeed, current are already supported there.
 426 The list of supported IPMI sensors has been extended and sensors like flow,
 427 power are supported now. Also, a System Event Log (SEL) notification feature
 428 has been introduced.
 429
 430 * The feat_ipmi_events branch includes new SEL feature support in collectd
 431   IPMI plugin. If this feature is enabled, the collectd IPMI plugin will
 432   dispatch notifications about new events in System Event Log.
 433
 434 * The feat_ipmi_analog branch includes the support of extended IPMI sensors in
 435   collectd IPMI plugin.
 436
 437 **Install dependencies**
 438
 439 On Ubuntu, the OpenIPMI library can be installed via apt package manager:
 440
 441 .. code:: bash
 442
 443     $ sudo apt-get install libopenipmi-dev
 444
 445 Anyway, it's recommended to use the latest version of the OpenIPMI library as
 446 it includes fixes of known issues which aren't included in standard OpenIPMI
 447 library package. The latest version of the library can be found at
 448 https://sourceforge.net/p/openipmi/code/ci/master/tree/. Steps to install the
 449 library from sources are described below.
 450
 451 Remove old version of OpenIPMI library:
 452
 453 .. code:: bash
 454
 455     $ sudo apt-get remove libopenipmi-dev
 456
 457 Download OpenIPMI library sources:
 458
 459 .. code:: bash
 460
 461     $ git clone https://git.code.sf.net/p/openipmi/code openipmi-code
 462     $ cd openipmi-code
 463
 464 Patch the OpenIPMI pkg-config file to provide correct compilation flags
 465 for collectd IPMI plugin:
 466
 467 .. code:: diff
 468
 469     diff --git a/OpenIPMIpthread.pc.in b/OpenIPMIpthread.pc.in
 470     index 59b52e5..fffa0d0 100644
 471     --- a/OpenIPMIpthread.pc.in
 472     +++ b/OpenIPMIpthread.pc.in
 473     @@ -6,6 +6,6 @@ includedir=@includedir@
 474      Name: OpenIPMIpthread
 475      Description: Pthread OS handler for OpenIPMI
 476      Version: @VERSION@
 477     -Requires: OpenIPMI pthread
 478     +Requires: OpenIPMI
 479      Libs: -L${libdir} -lOpenIPMIutils -lOpenIPMIpthread
 480     -Cflags: -I${includedir}
 481     +Cflags: -I${includedir} -pthread
 482
 483 Build and install OpenIPMI library:
 484
 485 .. code:: bash
 486
 487     $ autoreconf --install
 488     $ ./configure --prefix=/usr
 489     $ make
 490     $ sudo make install
 491
 492 Enable IPMI support in the kernel:
 493
 494 .. code:: bash
 495
 496     $ sudo modprobe ipmi_devintf
 497     $ sudo modprobe ipmi_si
 498
 499 .. note::
 500   If HW supports IPMI, the ``/dev/ipmi0`` character device will be
 501   created.
 502
 503 Clone and install the collectd IPMI plugin:
 504
 505 .. code:: bash
 506
 507     $ git clone  https://github.com/maryamtahhan/collectd
 508     $ cd collectd
 509     $ git checkout $BRANCH
 510     $ ./build.sh
 511     $ ./configure --enable-syslog --enable-logfile --enable-debug
 512     $ make
 513     $ sudo make install
 514
 515 Where $BRANCH is feat_ipmi_events or feat_ipmi_analog.
 516
 517 This will install collectd to default folder ``/opt/collectd``. The collectd
 518 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To
 519 configure the IPMI plugin you need to modify the file to include:
 520
 521 .. code:: bash
 522
 523     LoadPlugin ipmi
 524     <Plugin ipmi>
 525        SELEnabled true # only feat_ipmi_events branch supports this
 526     </Plugin>
 527
 528 .. note::
 529   By default, IPMI plugin will read all available analog sensor values,
 530   dispatch the values to collectd and send SEL notifications.
 531
 532 For more information on the IPMI plugin parameters and SEL feature configuration,
 533 please see:
 534 https://github.com/maryamtahhan/collectd/blob/feat_ipmi_events/src/collectd.conf.pod
 535
 536 Extended analog sensors support doesn't require additional configuration. The usual
 537 collectd IPMI documentation can be used:
 538
 539 - https://collectd.org/wiki/index.php/Plugin:IPMI
 540 - https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_ipmi
 541
 542 IPMI documentation:
 543
 544 - https://www.kernel.org/doc/Documentation/IPMI.txt
 545 - http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
 546
 547 Mcelog Plugin
 548 ^^^^^^^^^^^^^^
 549 Repo: https://github.com/collectd/collectd
 550
 551 Branch: master
 552
 553 Dependencies: mcelog
 554
 555 Start by installing mcelog.
 556
 557 .. note::
 558   The kernel has to have CONFIG_X86_MCE enabled. For 32bit kernels you
 559   need at least a 2.6,30 kernel.
 560
 561 On ubuntu:
 562
 563 .. code:: bash
 564
 565     $ apt-get update && apt-get install mcelog
 566
 567 Or build from source
 568
 569 .. code:: bash
 570
 571     $ git clone git://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git
 572     $ cd mcelog
 573     $ make
 574     ... become root ...
 575     $ make install
 576     $ cp mcelog.service /etc/systemd/system/
 577     $ systemctl enable mcelog.service
 578     $ systemctl start mcelog.service
 579
 580
 581 Verify you got a /dev/mcelog. You can verify the daemon is running completely
 582 by running:
 583
 584 .. code:: bash
 585
 586      $ mcelog --client
 587
 588 This should query the information in the running daemon. If it prints nothing
 589 that is fine (no errors logged yet). More info @
 590 http://www.mcelog.org/installation.html
 591
 592 Modify the mcelog configuration file "/etc/mcelog/mcelog.conf" to include or
 593 enable:
 594
 595 .. code:: bash
 596
 597     socket-path = /var/run/mcelog-client
 598
 599 Clone and install the collectd mcelog plugin:
 600
 601 .. code:: bash
 602
 603     $ git clone  https://github.com/maryamtahhan/collectd
 604     $ cd collectd
 605     $ git checkout feat_ras
 606     $ ./build.sh
 607     $ ./configure --enable-syslog --enable-logfile --enable-debug
 608     $ make
 609     $ sudo make install
 610
 611 This will install collectd to /opt/collectd
 612 The collectd configuration file can be found at /opt/collectd/etc
 613 To configure the mcelog plugin you need to modify the configuration file to
 614 include:
 615
 616 .. code:: bash
 617
 618     <LoadPlugin mcelog>
 619       Interval 1
 620     </LoadPlugin>
 621     <Plugin "mcelog">
 622        McelogClientSocket "/var/run/mcelog-client"
 623     </Plugin>
 624
 625 For more information on the plugin parameters, please see:
 626 https://github.com/maryamtahhan/collectd/blob/feat_ras/src/collectd.conf.pod
 627
 628 Simulating a Machine Check Exception can be done in one of 3 ways:
 629
 630 * Running $make test in the mcelog cloned directory - mcelog test suite
 631 * using mce-inject
 632 * using mce-test
 633
 634 **mcelog test suite:**
 635
 636 It is always a good idea to test an error handling mechanism before it is
 637 really needed. mcelog includes a test suite. The test suite relies on
 638 mce-inject which needs to be installed and in $PATH.
 639
 640 You also need the mce-inject kernel module configured (with
 641 CONFIG_X86_MCE_INJECT=y), compiled, installed and loaded:
 642
 643 .. code:: bash
 644
 645     $ modprobe mce-inject
 646
 647 Then you can run the mcelog test suite with
 648
 649 .. code:: bash
 650
 651     $ make test
 652
 653 This will inject different classes of errors and check that the mcelog triggers
 654 runs. There will be some kernel messages about page offlining attempts. The
 655 test will also lose a few pages of memory in your system (not significant)
 656 .. note::
 657   This test will kill any running mcelog, which needs to be restarted
 658   manually afterwards.
 659
 660 **mce-inject:**
 661
 662 A utility to inject corrected, uncorrected and fatal machine check exceptions
 663
 664 .. code:: bash
 665
 666     $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
 667     $ cd mce-inject
 668     $ make
 669     $ modprobe mce-inject
 670
 671 Modify the test/corrected script to include the following:
 672
 673 .. code:: bash
 674
 675     CPU 0 BANK 0
 676     STATUS 0xcc00008000010090
 677     ADDR 0x0010FFFFFFF
 678
 679 Inject the error:
 680 .. code:: bash
 681
 682     $ ./mce-inject < test/corrected
 683
 684 .. note::
 685   The uncorrected and fatal scripts under test will cause a platform reset.
 686   Only the fatal script generates the memory errors**. In order to  quickly
 687   emulate uncorrected memory errors and avoid host reboot following test errors
 688   from mce-test  suite can be injected:
 689
 690 .. code:: bash
 691
 692        $ mce-inject  mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub
 693
 694 **mce-test:**
 695
 696 In addition an more in-depth test of the Linux kernel machine check facilities
 697 can be done with the mce-test test suite. mce-test supports testing uncorrected
 698 error handling, real error injection, handling of different soft offlining
 699 cases, and other tests.
 700
 701 **Corrected memory error injection:**
 702
 703 To inject corrected memory errors:
 704
 705 * Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core
 706 * Insert einj module: modprobe einj param_extension=1
 707 * Inject an error by specifying details (last command should be repeated at least two times):
 708
 709 .. code:: bash
 710
 711     $ APEI_IF=/sys/kernel/debug/apei/einj
 712     $ echo 0x8 > $APEI_IF/error_type
 713     $ echo 0x01f5591000 > $APEI_IF/param1
 714     $ echo 0xfffffffffffff000 > $APEI_IF/param2
 715     $ echo 1 > $APEI_IF/notrigger
 716     $ echo 1 > $APEI_IF/error_inject
 717
 718 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 719
 720 Open vSwitch Plugins
 721 ^^^^^^^^^^^^^^^^^^^^^
 722 OvS Plugins Repo: https://github.com/collectd/collectd
 723
 724 OvS Plugins Branch: master
 725
 726 OvS Events MIBs: The SNMP OVS interface link status is provided by standard
 727 IF-MIB (http://www.net-snmp.org/docs/mibs/IF-MIB.txt)
 728
 729 Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl)
 730
 731 On Ubuntu, install the dependencies:
 732
 733 .. code:: bash
 734
 735     $ sudo apt-get install libyajl-dev openvswitch-switch
 736
 737 Start the Open vSwitch service:
 738
 739 .. code:: bash
 740
 741     $ sudo service openvswitch-switch start
 742
 743 configure the ovsdb-server manager:
 744
 745 .. code:: bash
 746
 747     $ sudo ovs-vsctl set-manager ptcp:6640
 748
 749 Clone and install the collectd ovs plugin:
 750
 751 .. code:: bash
 752
 753     $ git clone $REPO
 754     $ cd collectd
 755     $ git checkout master
 756     $ ./build.sh
 757     $ ./configure --enable-syslog --enable-logfile --enable-debug
 758     $ make
 759     $ sudo make install
 760
 761 This will install collectd to /opt/collectd. The collectd configuration file
 762 can be found at /opt/collectd/etc. To configure the OVS events plugin you
 763 need to modify the configuration file to include:
 764
 765 .. code:: bash
 766
 767     <LoadPlugin ovs_events>
 768        Interval 1
 769     </LoadPlugin>
 770     <Plugin "ovs_events">
 771        Port 6640
 772        Socket "/var/run/openvswitch/db.sock"
 773        Interfaces "br0" "veth0"
 774        SendNotification false
 775        DispatchValues true
 776     </Plugin>
 777
 778 To configure the OVS stats plugin you need to modify the configuration file
 779 to include:
 780
 781 .. code:: bash
 782
 783     <LoadPlugin ovs_stats>
 784        Interval 1
 785     </LoadPlugin>
 786     <Plugin ovs_stats>
 787        Port "6640"
 788        Address "127.0.0.1"
 789        Socket "/var/run/openvswitch/db.sock"
 790        Bridges "br0" "br_ext"
 791     </Plugin>
 792
 793 For more information on the plugin parameters, please see:
 794 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 795
 796 OVS PMD stats
 797 ^^^^^^^^^^^^^^
 798 Repo: https://gerrit.opnfv.org/gerrit/barometer
 799
 800 Prequistes:
 801 1. Open vSwitch dependencies are installed.
 802 2. Open vSwitch service is running.
 803 3. Ovsdb-server manager is configured.
 804 You can refer `Open vSwitch Plugins`_ section above for each one of them.
 805
 806 OVS PMD stats application is run through the exec plugin.
 807
 808 To configure the OVS PMD stats application you need to modify the exec plugin configuration
 809 to include:
 810
 811 .. code:: bash
 812
 813     <LoadPlugin exec>
 814        Interval 1
 815     </LoadPlugin
 816     <Plugin exec>
 817         Exec "user:group" "<path to ovs_pmd_stat.sh>"
 818         #NotificationExec "nobody" "/usr/lib/collectd/notify.sh"
 819     </Plugin>
 820
 821 .. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service.
 822
 823 ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument:
 824
 825 .. code:: bash
 826
 827      sudo python /usr/local/src/ovs_pmd_stats.py" "--socket-pid-file"
 828      "/var/run/openvswitch/ovs-vswitchd.pid"
 829
 830 SNMP Agent Plugin
 831 ^^^^^^^^^^^^^^^^^
 832 Repo: https://github.com/maryamtahhan/collectd/
 833
 834 Branch: feat_snmp
 835
 836 Dependencies: NET-SNMP library
 837
 838 Start by installing net-snmp and dependencies.
 839
 840 On ubuntu:
 841
 842 .. code:: bash
 843
 844     $ apt-get install snmp snmp-mibs-downloader snmpd libsnmp-dev
 845     $ systemctl start snmpd.service
 846
 847 Or build from source
 848
 849 Become root to install net-snmp dependencies
 850
 851 .. code:: bash
 852
 853     $ apt-get install libperl-dev
 854
 855 Clone and build net-snmp
 856
 857 .. code:: bash
 858
 859     $ git clone https://github.com/haad/net-snmp.git
 860     $ cd net-snmp
 861     $ ./configure --with-persistent-directory="/var/net-snmp" --with-systemd --enable-shared --prefix=/usr
 862     $ make
 863
 864 Become root
 865
 866 .. code:: bash
 867
 868     $ make install
 869
 870 Copy default configuration to persistent folder
 871
 872 .. code:: bash
 873
 874     $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf
 875
 876 Set library path and default MIB configuration
 877
 878 .. code:: bash
 879
 880     $ cd ~/
 881     $ echo export LD_LIBRARY_PATH=/usr/lib >> .bashrc
 882     $ net-snmp-config --default-mibdirs
 883     $ net-snmp-config --snmpconfpath
 884
 885 Configure snmpd as a service
 886
 887 .. code:: bash
 888
 889     $ cd net-snmp
 890     $ cp ./dist/snmpd.service /etc/systemd/system/
 891     $ systemctl enable snmpd.service
 892     $ systemctl start snmpd.service
 893
 894 Add the following line to snmpd.conf configuration file
 895 "/usr/share/snmp/snmpd.conf" to make all OID tree visible for SNMP clients:
 896
 897 .. code:: bash
 898
 899     view   systemonly  included   .1
 900
 901 To verify that SNMP is working you can get IF-MIB table using SNMP client
 902 to view the list of Linux interfaces:
 903
 904 .. code:: bash
 905
 906     $ snmpwalk -v 2c -c public localhost IF-MIB::interfaces
 907
 908 Clone and install the collectd snmp_agent plugin:
 909
 910 .. code:: bash
 911
 912     $ git clone  https://github.com/maryamtahhan/collectd
 913     $ cd collectd
 914     $ git checkout feat_snmp
 915     $ ./build.sh
 916     $ ./configure --enable-syslog --enable-logfile --enable-debug --enable-snmp --with-libnetsnmp
 917     $ make
 918     $ sudo make install
 919
 920 This will install collectd to /opt/collectd
 921 The collectd configuration file can be found at /opt/collectd/etc
 922 **SNMP Agent plugin is a generic plugin and cannot work without configuration**.
 923 To configure the snmp_agent plugin you need to modify the configuration file to
 924 include OIDs mapped to collectd types. The following example maps scalar
 925 memAvailReal OID to value represented as free memory type of memory plugin:
 926
 927 .. code:: bash
 928
 929     LoadPlugin snmp_agent
 930     <Plugin "snmp_agent">
 931       <Data "memAvailReal">
 932         Plugin "memory"
 933         Type "memory"
 934         TypeInstance "free"
 935         OIDs "1.3.6.1.4.1.2021.4.6.0"
 936       </Data>
 937     </Plugin>
 938
 939 **Limitations**
 940
 941 * Object instance with Counter64 type is not supported in SNMPv1. When GetNext
 942   request is received, Counter64 type objects will be skipped. When Get
 943   request is received for Counter64 type object, the error will be returned.
 944 * Interfaces that are not visible to Linux like DPDK interfaces cannot be
 945   retreived using standard IF-MIB tables.
 946
 947 For more information on the plugin parameters, please see:
 948 https://github.com/maryamtahhan/collectd/blob/feat_snmp/src/collectd.conf.pod
 949
 950 For more details on AgentX subagent, please see:
 951 http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/
 952
 953 virt plugin
 954 ^^^^^^^^^^^^
 955 Repo: https://github.com/maryamtahhan/collectd
 956
 957 Branch: feat_libvirt_upstream
 958
 959 Dependencies: libvirt (https://libvirt.org/), libxml2
 960
 961 On Ubuntu, install the dependencies:
 962
 963 .. code:: bash
 964
 965     $ sudo apt-get install libxml2-dev
 966
 967 Install libvirt:
 968
 969 libvirt version in package manager might be quite old and offer only limited
 970 functionality. Hence, building and installing libvirt from sources is recommended.
 971 Detailed instructions can bet found at:
 972 https://libvirt.org/compiling.html
 973
 974 Certain metrics provided by the plugin have a requirement on a minimal version of
 975 the libvirt API. *File system information* statistics require a *Guest Agent (GA)*
 976 to be installed and configured in a VM. User must make sure that installed GA
 977 version supports retrieving file system information. Number of *Performance monitoring events*
 978 metrics depends on running libvirt daemon version.
 979
 980 .. note:: Please keep in mind that RDT metrics (part of *Performance monitoring
 981     events*) have to be supported by hardware. For more details on hardware support,
 982     please see:
 983     https://github.com/01org/intel-cmt-cat
 984
 985     Additionally perf metrics **cannot** be collected if *Intel RDT* plugin is enabled.
 986
 987 libvirt version can be checked with following commands:
 988
 989 .. code:: bash
 990
 991     $ virsh --version
 992     $ libvirtd --version
 993
 994 .. table:: Extended statistics requirements
 995
 996     +-------------------------------+--------------------------+-------------+
 997     | Statistic                     | Min. libvirt API version | Requires GA |
 998     +===============================+==========================+=============+
 999     | Domain reason                 | 0.9.2                    | No          |
1000     +-------------------------------+--------------------------+-------------+
1001     | Disk errors                   | 0.9.10                   | No          |
1002     +-------------------------------+--------------------------+-------------+
1003     | Job statistics                | 1.2.9                    | No          |
1004     +-------------------------------+--------------------------+-------------+
1005     | File system information       | 1.2.11                   | Yes         |
1006     +-------------------------------+--------------------------+-------------+
1007     | Performance monitoring events | 1.3.3                    | No          |
1008     +-------------------------------+--------------------------+-------------+
1009
1010 Start libvirt daemon:
1011
1012 .. code:: bash
1013
1014     $ systemctl start libvirtd
1015
1016 Create domain (VM) XML configuration file. For more information on domain XML
1017 format and examples, please see:
1018 https://libvirt.org/formatdomain.html
1019
1020 .. note:: Installing additional hypervisor dependencies might be required before
1021     deploying virtual machine.
1022
1023 Create domain, based on created XML file:
1024
1025 .. code:: bash
1026
1027     $ virsh define DOMAIN_CFG_FILE.xml
1028
1029 Start domain:
1030
1031 .. code:: bash
1032
1033     $ virsh start DOMAIN_NAME
1034
1035 Check if domain is running:
1036
1037 .. code:: bash
1038
1039     $ virsh list
1040
1041 Check list of available *Performance monitoring events* and their settings:
1042
1043 .. code:: bash
1044
1045     $ virsh perf DOMAIN_NAME
1046
1047 Enable or disable *Performance monitoring events* for domain:
1048
1049 .. code:: bash
1050
1051     $ virsh perf DOMAIN_NAME [--enable | --disable] EVENT_NAME --live
1052
1053 Clone and install the collectd virt plugin:
1054
1055 .. code:: bash
1056
1057     $ git clone $REPO
1058     $ cd collectd
1059     $ git checkout $BRANCH
1060     $ ./build.sh
1061     $ ./configure --enable-syslog --enable-logfile --enable-debug
1062     $ make
1063     $ sudo make install
1064
1065 Where ``$REPO`` and ``$BRANCH`` are equal to information provided above.
1066
1067 This will install collectd to ``/opt/collectd``. The collectd configuration file
1068 ``collectd.conf`` can be found at ``/opt/collectd/etc``. To load the virt plugin
1069 user needs to modify the configuration file to include:
1070
1071 .. code:: bash
1072
1073     LoadPlugin virt
1074
1075 Additionally, user can specify plugin configuration parameters in this file,
1076 such as connection URI, domain name and much more. By default extended virt plugin
1077 statistics are disabled. They can be enabled with ``ExtraStats`` option.
1078
1079 .. code:: bash
1080
1081     <Plugin virt>
1082        RefreshInterval 60
1083        ExtraStats "cpu_util disk disk_err domain_state fs_info job_stats_background pcpu perf vcpupin"
1084     </Plugin>
1085
1086 For more information on the plugin parameters, please see:
1087 https://github.com/maryamtahhan/collectd/blob/feat_libvirt_upstream/src/collectd.conf.pod
1088
1089 Installing collectd as a service
1090 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1091 **NOTE**: In an OPNFV installation, collectd is installed and configured as a
1092 service.
1093
1094 Collectd service scripts are available in the collectd/contrib directory.
1095 To install collectd as a service:
1096
1097 .. code:: bash
1098
1099     $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
1100     $ cd /etc/systemd/system/
1101     $ sudo mv systemd.collectd.service collectd.service
1102     $ sudo chmod +x collectd.service
1103
1104 Modify collectd.service
1105
1106 .. code:: bash
1107
1108     [Service]
1109     ExecStart=/opt/collectd/sbin/collectd
1110     EnvironmentFile=-/opt/collectd/etc/
1111     EnvironmentFile=-/opt/collectd/etc/
1112     CapabilityBoundingSet=CAP_SETUID CAP_SETGID
1113
1114 Reload
1115
1116 .. code:: bash
1117
1118     $ sudo systemctl daemon-reload
1119     $ sudo systemctl start collectd.service
1120     $ sudo systemctl status collectd.service should show success
1121
1122 Additional useful plugins
1123 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1124
1125 * **Exec Plugin** : Can be used to show you when notifications are being
1126  generated by calling a bash script that dumps notifications to file. (handy
1127  for debug). Modify /opt/collectd/etc/collectd.conf:
1128
1129 .. code:: bash
1130
1131    LoadPlugin exec
1132    <Plugin exec>
1133    #   Exec "user:group" "/path/to/exec"
1134       NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
1135    </Plugin>
1136
1137 write_notification.sh (just writes the notification passed from exec through
1138 STDIN to a file (/tmp/notifications)):
1139
1140 .. code:: bash
1141
1142    #!/bin/bash
1143    rm -f /tmp/notifications
1144    while read x y
1145    do
1146      echo $x$y >> /tmp/notifications
1147    done
1148
1149 output to /tmp/notifications should look like:
1150
1151 .. code:: bash
1152
1153     Severity:WARNING
1154     Time:1479991318.806
1155     Host:localhost
1156     Plugin:ovs_events
1157     PluginInstance:br-ex
1158     Type:gauge
1159     TypeInstance:link_status
1160     uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
1161
1162     linkstate of "br-ex" interface has been changed to "DOWN"
1163
1164 * **logfile plugin**: Can be used to log collectd activity. Modify
1165   /opt/collectd/etc/collectd.conf to include:
1166
1167 .. code:: bash
1168
1169     LoadPlugin logfile
1170     <Plugin logfile>
1171         LogLevel info
1172         File "/var/log/collectd.log"
1173         Timestamp true
1174         PrintSeverity false
1175     </Plugin>
1176
1177
1178 Monitoring Interfaces and Openstack Support
1179 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1180 .. Figure:: monitoring_interfaces.png
1181
1182    Monitoring Interfaces and Openstack Support
1183
1184 The figure above shows the DPDK L2 forwarding application running on a compute
1185 node, sending and receiving traffic. collectd is also running on this compute
1186 node retrieving the stats periodically from DPDK through the dpdkstat plugin
1187 and publishing the retrieved stats to OpenStack through the
1188 collectd-ceilometer-plugin.
1189
1190 To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
1191
1192 For more information on configuring and installing OpenStack plugins for
1193 collectd, check out the `collectd-ceilometer-plugin GSG`_.
1194
1195 References
1196 ^^^^^^^^^^^
1197 .. [1] https://collectd.org/wiki/index.php/Naming_schema
1198 .. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
1199 .. [3] https://collectd.org/wiki/index.php/Value_list_t
1200 .. [4] https://collectd.org/wiki/index.php/Data_set
1201 .. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
1202 .. [6] https://collectd.org/wiki/index.php/Data_source
1203 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
1204
1205 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
1206 .. _gnocchi plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1207 .. _aodh plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1208 .. _collectd-ceilometer-plugin GSG: https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/GSG.rst
1209 .. _grafana guide: https://wiki.opnfv.org/display/fastpath/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd