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