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