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
 716 .. note::
 717   This test will kill any running mcelog, which needs to be restarted
 718   manually afterwards.
 719
 720 **mce-inject:**
 721
 722 A utility to inject corrected, uncorrected and fatal machine check exceptions
 723
 724 .. code:: bash
 725
 726     $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
 727     $ cd mce-inject
 728     $ make
 729     $ modprobe mce-inject
 730
 731 Modify the test/corrected script to include the following:
 732
 733 .. code:: bash
 734
 735     CPU 0 BANK 0
 736     STATUS 0xcc00008000010090
 737     ADDR 0x0010FFFFFFF
 738
 739 Inject the error:
 740 .. code:: bash
 741
 742     $ ./mce-inject < test/corrected
 743
 744 .. note::
 745   The uncorrected and fatal scripts under test will cause a platform reset.
 746   Only the fatal script generates the memory errors**. In order to  quickly
 747   emulate uncorrected memory errors and avoid host reboot following test errors
 748   from mce-test suite can be injected:
 749
 750 .. code:: bash
 751
 752        $ mce-inject  mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub
 753
 754 **mce-test:**
 755
 756 In addition a more in-depth test of the Linux kernel machine check facilities
 757 can be done with the mce-test test suite. mce-test supports testing uncorrected
 758 error handling, real error injection, handling of different soft offlining
 759 cases, and other tests.
 760
 761 **Corrected memory error injection:**
 762
 763 To inject corrected memory errors:
 764
 765 * Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core
 766 * Insert einj module: modprobe einj param_extension=1
 767 * Inject an error by specifying details (last command should be repeated at least two times):
 768
 769 .. code:: bash
 770
 771     $ APEI_IF=/sys/kernel/debug/apei/einj
 772     $ echo 0x8 > $APEI_IF/error_type
 773     $ echo 0x01f5591000 > $APEI_IF/param1
 774     $ echo 0xfffffffffffff000 > $APEI_IF/param2
 775     $ echo 1 > $APEI_IF/notrigger
 776     $ echo 1 > $APEI_IF/error_inject
 777
 778 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 779
 780 Open vSwitch Plugins
 781 ^^^^^^^^^^^^^^^^^^^^^
 782 OvS Plugins Repo: https://github.com/collectd/collectd
 783
 784 OvS Plugins Branch: master
 785
 786 OvS Events MIBs: The SNMP OVS interface link status is provided by standard
 787 IF-MIB (http://www.net-snmp.org/docs/mibs/IF-MIB.txt)
 788
 789 Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl)
 790
 791 On Centos, install the dependencies and Open vSwitch:
 792
 793 .. code:: bash
 794
 795     $ sudo yum install yajl-devel
 796
 797 Steps to install Open vSwtich can be found at
 798 http://docs.openvswitch.org/en/latest/intro/install/fedora/
 799
 800 Start the Open vSwitch service:
 801
 802 .. code:: bash
 803
 804     $ sudo service openvswitch-switch start
 805
 806 Configure the ovsdb-server manager:
 807
 808 .. code:: bash
 809
 810     $ sudo ovs-vsctl set-manager ptcp:6640
 811
 812 Clone and install the collectd ovs plugin:
 813
 814 .. code:: bash
 815
 816     $ git clone $REPO
 817     $ cd collectd
 818     $ git checkout master
 819     $ ./build.sh
 820     $ ./configure --enable-syslog --enable-logfile --enable-debug
 821     $ make
 822     $ sudo make install
 823
 824 This will install collectd to default folder ``/opt/collectd``. The collectd
 825 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
 826 To configure the OVS events plugin you need to modify the configuration file to include:
 827
 828 .. code:: bash
 829
 830     <LoadPlugin ovs_events>
 831        Interval 1
 832     </LoadPlugin>
 833     <Plugin ovs_events>
 834        Port "6640"
 835        Address "127.0.0.1"
 836        Socket "/var/run/openvswitch/db.sock"
 837        Interfaces "br0" "veth0"
 838        SendNotification true
 839     </Plugin>
 840
 841 To configure the OVS stats plugin you need to modify the configuration file
 842 to include:
 843
 844 .. code:: bash
 845
 846     <LoadPlugin ovs_stats>
 847        Interval 1
 848     </LoadPlugin>
 849     <Plugin ovs_stats>
 850        Port "6640"
 851        Address "127.0.0.1"
 852        Socket "/var/run/openvswitch/db.sock"
 853        Bridges "br0"
 854     </Plugin>
 855
 856 For more information on the plugin parameters, please see:
 857 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 858
 859 OVS PMD stats
 860 ^^^^^^^^^^^^^^
 861 Repo: https://gerrit.opnfv.org/gerrit/barometer
 862
 863 Prequistes:
 864 1. Open vSwitch dependencies are installed.
 865 2. Open vSwitch service is running.
 866 3. Ovsdb-server manager is configured.
 867 You can refer `Open vSwitch Plugins`_ section above for each one of them.
 868
 869 OVS PMD stats application is run through the exec plugin.
 870
 871 To configure the OVS PMD stats application you need to modify the exec plugin configuration
 872 to include:
 873
 874 .. code:: bash
 875
 876     <LoadPlugin exec>
 877        Interval 1
 878     </LoadPlugin
 879     <Plugin exec>
 880         Exec "user:group" "<path to ovs_pmd_stat.sh>"
 881     </Plugin>
 882
 883 .. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service.
 884
 885 ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument:
 886
 887 .. code:: bash
 888
 889      sudo python /usr/local/src/ovs_pmd_stats.py" "--socket-pid-file"
 890      "/var/run/openvswitch/ovs-vswitchd.pid"
 891
 892 SNMP Agent Plugin
 893 ^^^^^^^^^^^^^^^^^
 894 Repo: https://github.com/maryamtahhan/collectd/
 895
 896 Branch: master
 897
 898 Dependencies: NET-SNMP library
 899
 900 Start by installing net-snmp and dependencies.
 901
 902 On Centos 7:
 903
 904 .. code:: bash
 905
 906     $ sudo yum install net-snmp net-snmp-libs net-snmp-utils net-snmp-devel
 907     $ sudo systemctl start snmpd.service
 908
 909 go to the `snmp configuration`_ steps.
 910
 911 From source:
 912
 913 Clone and build net-snmp:
 914
 915 .. code:: bash
 916
 917     $ git clone https://github.com/haad/net-snmp.git
 918     $ cd net-snmp
 919     $ ./configure --with-persistent-directory="/var/net-snmp" --with-systemd --enable-shared --prefix=/usr
 920     $ make
 921
 922 Become root
 923
 924 .. code:: bash
 925
 926     $ make install
 927
 928 Copy default configuration to persistent folder:
 929
 930 .. code:: bash
 931
 932     $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf
 933
 934 Set library path and default MIB configuration:
 935
 936 .. code:: bash
 937
 938     $ cd ~/
 939     $ echo export LD_LIBRARY_PATH=/usr/lib >> .bashrc
 940     $ net-snmp-config --default-mibdirs
 941     $ net-snmp-config --snmpconfpath
 942
 943 Configure snmpd as a service:
 944
 945 .. code:: bash
 946
 947     $ cd net-snmp
 948     $ cp ./dist/snmpd.service /etc/systemd/system/
 949     $ systemctl enable snmpd.service
 950     $ systemctl start snmpd.service
 951
 952 .. _`snmp configuration`:
 953
 954 Add the following line to snmpd.conf configuration file
 955 ``/etc/snmp/snmpd.conf`` to make all OID tree visible for SNMP clients:
 956
 957 .. code:: bash
 958
 959     view    systemview    included   .1
 960
 961 To verify that SNMP is working you can get IF-MIB table using SNMP client
 962 to view the list of Linux interfaces:
 963
 964 .. code:: bash
 965
 966     $ snmpwalk -v 2c -c public localhost IF-MIB::interfaces
 967
 968 Get the default MIB location:
 969
 970 .. code:: bash
 971
 972     $ net-snmp-config --default-mibdirs
 973     /opt/stack/.snmp/mibs:/usr/share/snmp/mibs
 974
 975 Install Intel specific MIBs (if needed) into location received by
 976 ``net-snmp-config`` command (e.g. ``/usr/share/snmp/mibs``).
 977
 978 .. code:: bash
 979
 980     $ git clone https://gerrit.opnfv.org/gerrit/barometer.git
 981     $ sudo cp -f barometer/mibs/*.txt /usr/share/snmp/mibs/
 982     $ sudo systemctl restart snmpd.service
 983
 984 Clone and install the collectd snmp_agent plugin:
 985
 986 .. code:: bash
 987
 988     $ cd ~
 989     $ git clone https://github.com/maryamtahhan/collectd
 990     $ cd collectd
 991     $ git checkout feat_snmp
 992     $ ./build.sh
 993     $ ./configure --enable-syslog --enable-logfile --enable-debug --enable-snmp --with-libnetsnmp
 994     $ make
 995     $ sudo make install
 996
 997 This will install collectd to default folder ``/opt/collectd``. The collectd
 998 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
 999
1000 **SNMP Agent plugin is a generic plugin and cannot work without configuration**.
1001 To configure the snmp_agent plugin you need to modify the configuration file to
1002 include OIDs mapped to collectd types. The following example maps scalar
1003 memAvailReal OID to value represented as free memory type of memory plugin:
1004
1005 .. code:: bash
1006
1007     LoadPlugin snmp_agent
1008     <Plugin "snmp_agent">
1009       <Data "memAvailReal">
1010         Plugin "memory"
1011         Type "memory"
1012         TypeInstance "free"
1013         OIDs "1.3.6.1.4.1.2021.4.6.0"
1014       </Data>
1015     </Plugin>
1016
1017
1018 The ``snmpwalk`` command can be used to validate the collectd configuration:
1019
1020 .. code:: bash
1021
1022     $ snmpwalk -v 2c -c public localhost 1.3.6.1.4.1.2021.4.6.0
1023     UCD-SNMP-MIB::memAvailReal.0 = INTEGER: 135237632 kB
1024
1025
1026 **Limitations**
1027
1028 * Object instance with Counter64 type is not supported in SNMPv1. When GetNext
1029   request is received, Counter64 type objects will be skipped. When Get
1030   request is received for Counter64 type object, the error will be returned.
1031 * Interfaces that are not visible to Linux like DPDK interfaces cannot be
1032   retreived using standard IF-MIB tables.
1033
1034 For more information on the plugin parameters, please see:
1035 https://github.com/maryamtahhan/collectd/blob/feat_snmp/src/collectd.conf.pod
1036
1037 For more details on AgentX subagent, please see:
1038 http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/
1039
1040 .. _virt-plugin:
1041
1042 virt plugin
1043 ^^^^^^^^^^^^
1044 Repo: https://github.com/maryamtahhan/collectd
1045
1046 Branch: master
1047
1048 Dependencies: libvirt (https://libvirt.org/), libxml2
1049
1050 On Centos, install the dependencies:
1051
1052 .. code:: bash
1053
1054     $ sudo yum install libxml2-dev libpciaccess-devel yajl-devel device-mapper-devel
1055
1056 Install libvirt:
1057
1058 libvirt version in package manager might be quite old and offer only limited
1059 functionality. Hence, building and installing libvirt from sources is recommended.
1060 Detailed instructions can bet found at:
1061 https://libvirt.org/compiling.html
1062
1063 Certain metrics provided by the plugin have a requirement on a minimal version of
1064 the libvirt API. *File system information* statistics require a *Guest Agent (GA)*
1065 to be installed and configured in a VM. User must make sure that installed GA
1066 version supports retrieving file system information. Number of *Performance monitoring events*
1067 metrics depends on running libvirt daemon version.
1068
1069 .. note:: Please keep in mind that RDT metrics (part of *Performance monitoring
1070     events*) have to be supported by hardware. For more details on hardware support,
1071     please see:
1072     https://github.com/01org/intel-cmt-cat
1073
1074     Additionally perf metrics **cannot** be collected if *Intel RDT* plugin is enabled.
1075
1076 libvirt version can be checked with following commands:
1077
1078 .. code:: bash
1079
1080     $ virsh --version
1081     $ libvirtd --version
1082
1083 .. table:: Extended statistics requirements
1084
1085     +-------------------------------+--------------------------+-------------+
1086     | Statistic                     | Min. libvirt API version | Requires GA |
1087     +===============================+==========================+=============+
1088     | Domain reason                 | 0.9.2                    | No          |
1089     +-------------------------------+--------------------------+-------------+
1090     | Disk errors                   | 0.9.10                   | No          |
1091     +-------------------------------+--------------------------+-------------+
1092     | Job statistics                | 1.2.9                    | No          |
1093     +-------------------------------+--------------------------+-------------+
1094     | File system information       | 1.2.11                   | Yes         |
1095     +-------------------------------+--------------------------+-------------+
1096     | Performance monitoring events | 1.3.3                    | No          |
1097     +-------------------------------+--------------------------+-------------+
1098
1099 Start libvirt daemon:
1100
1101 .. code:: bash
1102
1103     $ systemctl start libvirtd
1104
1105 Create domain (VM) XML configuration file. For more information on domain XML
1106 format and examples, please see:
1107 https://libvirt.org/formatdomain.html
1108
1109 .. note:: Installing additional hypervisor dependencies might be required before
1110     deploying virtual machine.
1111
1112 Create domain, based on created XML file:
1113
1114 .. code:: bash
1115
1116     $ virsh define DOMAIN_CFG_FILE.xml
1117
1118 Start domain:
1119
1120 .. code:: bash
1121
1122     $ virsh start DOMAIN_NAME
1123
1124 Check if domain is running:
1125
1126 .. code:: bash
1127
1128     $ virsh list
1129
1130 Check list of available *Performance monitoring events* and their settings:
1131
1132 .. code:: bash
1133
1134     $ virsh perf DOMAIN_NAME
1135
1136 Enable or disable *Performance monitoring events* for domain:
1137
1138 .. code:: bash
1139
1140     $ virsh perf DOMAIN_NAME [--enable | --disable] EVENT_NAME --live
1141
1142 Clone and install the collectd virt plugin:
1143
1144 .. code:: bash
1145
1146     $ git clone $REPO
1147     $ cd collectd
1148     $ ./build.sh
1149     $ ./configure --enable-syslog --enable-logfile --enable-debug
1150     $ make
1151     $ sudo make install
1152
1153 Where ``$REPO`` is equal to information provided above.
1154
1155 This will install collectd to ``/opt/collectd``. The collectd configuration file
1156 ``collectd.conf`` can be found at ``/opt/collectd/etc``.
1157 To load the virt plugin user needs to modify the configuration file to include:
1158
1159 .. code:: bash
1160
1161     LoadPlugin virt
1162
1163 Additionally, user can specify plugin configuration parameters in this file,
1164 such as connection URL, domain name and much more. By default extended virt plugin
1165 statistics are disabled. They can be enabled with ``ExtraStats`` option.
1166
1167 .. code:: bash
1168
1169     <Plugin virt>
1170        RefreshInterval 60
1171        ExtraStats "cpu_util disk disk_err domain_state fs_info job_stats_background pcpu perf vcpupin"
1172     </Plugin>
1173
1174 For more information on the plugin parameters, please see:
1175 https://github.com/maryamtahhan/collectd/blob/feat_libvirt_upstream/src/collectd.conf.pod
1176
1177 .. _install-collectd-as-a-service:
1178
1179 Installing collectd as a service
1180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1181 **NOTE**: In an OPNFV installation, collectd is installed and configured as a
1182 service.
1183
1184 Collectd service scripts are available in the collectd/contrib directory.
1185 To install collectd as a service:
1186
1187 .. code:: bash
1188
1189     $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
1190     $ cd /etc/systemd/system/
1191     $ sudo mv systemd.collectd.service collectd.service
1192     $ sudo chmod +x collectd.service
1193
1194 Modify collectd.service
1195
1196 .. code:: bash
1197
1198     [Service]
1199     ExecStart=/opt/collectd/sbin/collectd
1200     EnvironmentFile=-/opt/collectd/etc/
1201     EnvironmentFile=-/opt/collectd/etc/
1202     CapabilityBoundingSet=CAP_SETUID CAP_SETGID
1203
1204 Reload
1205
1206 .. code:: bash
1207
1208     $ sudo systemctl daemon-reload
1209     $ sudo systemctl start collectd.service
1210     $ sudo systemctl status collectd.service should show success
1211
1212 Additional useful plugins
1213 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1214
1215 **Exec Plugin** : Can be used to show you when notifications are being
1216 generated by calling a bash script that dumps notifications to file. (handy
1217 for debug). Modify /opt/collectd/etc/collectd.conf:
1218
1219 .. code:: bash
1220
1221    LoadPlugin exec
1222    <Plugin exec>
1223    #   Exec "user:group" "/path/to/exec"
1224       NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
1225    </Plugin>
1226
1227 write_notification.sh (just writes the notification passed from exec through
1228 STDIN to a file (/tmp/notifications)):
1229
1230 .. code:: bash
1231
1232    #!/bin/bash
1233    rm -f /tmp/notifications
1234    while read x y
1235    do
1236      echo $x$y >> /tmp/notifications
1237    done
1238
1239 output to /tmp/notifications should look like:
1240
1241 .. code:: bash
1242
1243     Severity:WARNING
1244     Time:1479991318.806
1245     Host:localhost
1246     Plugin:ovs_events
1247     PluginInstance:br-ex
1248     Type:gauge
1249     TypeInstance:link_status
1250     uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
1251
1252     linkstate of "br-ex" interface has been changed to "DOWN"
1253
1254 * **logfile plugin**: Can be used to log collectd activity. Modify
1255   /opt/collectd/etc/collectd.conf to include:
1256
1257 .. code:: bash
1258
1259     LoadPlugin logfile
1260     <Plugin logfile>
1261         LogLevel info
1262         File "/var/log/collectd.log"
1263         Timestamp true
1264         PrintSeverity false
1265     </Plugin>
1266
1267
1268 Monitoring Interfaces and Openstack Support
1269 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1270 .. Figure:: monitoring_interfaces.png
1271
1272    Monitoring Interfaces and Openstack Support
1273
1274 The figure above shows the DPDK L2 forwarding application running on a compute
1275 node, sending and receiving traffic. Collectd is also running on this compute
1276 node retrieving the stats periodically from DPDK through the dpdkstat plugin
1277 and publishing the retrieved stats to OpenStack through the
1278 collectd-ceilometer-plugin.
1279
1280 To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
1281
1282 For more information on configuring and installing OpenStack plugins for
1283 collectd, check out the `collectd-ceilometer-plugin GSG`_.
1284
1285 References
1286 ^^^^^^^^^^^
1287 .. [1] https://collectd.org/wiki/index.php/Naming_schema
1288 .. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
1289 .. [3] https://collectd.org/wiki/index.php/Value_list_t
1290 .. [4] https://collectd.org/wiki/index.php/Data_set
1291 .. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
1292 .. [6] https://collectd.org/wiki/index.php/Data_source
1293 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
1294
1295 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
1296 .. _gnocchi plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1297 .. _aodh plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1298 .. _collectd-ceilometer-plugin GSG: https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/GSG.rst
1299 .. _grafana guide: https://wiki.opnfv.org/display/fastpath/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd