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