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/collectd/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/collectd/collectd
 547     $ cd collectd
 548     $ ./build.sh
 549     $ ./configure --enable-syslog --enable-logfile --enable-debug
 550     $ make
 551     $ sudo make install
 552
 553 This will install collectd to default folder ``/opt/collectd``. The collectd
 554 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
 555 To configure the IPMI plugin you need to modify the file to include:
 556
 557 .. code:: bash
 558
 559     LoadPlugin ipmi
 560     <Plugin ipmi>
 561        <Instance "local">
 562          SELEnabled true # only feat_ipmi_events branch supports this
 563        </Instance>
 564     </Plugin>
 565
 566 .. note::
 567   By default, IPMI plugin will read all available analog sensor values,
 568   dispatch the values to collectd and send SEL notifications.
 569
 570 For more information on the IPMI plugin parameters and SEL feature configuration,
 571 please see: https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 572
 573 Extended analog sensors support doesn't require additional configuration. The usual
 574 collectd IPMI documentation can be used:
 575
 576 - https://collectd.org/wiki/index.php/Plugin:IPMI
 577 - https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_ipmi
 578
 579 IPMI documentation:
 580
 581 - https://www.kernel.org/doc/Documentation/IPMI.txt
 582 - http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
 583
 584 Mcelog Plugin
 585 ^^^^^^^^^^^^^^
 586 Repo: https://github.com/collectd/collectd
 587
 588 Branch: master
 589
 590 Dependencies: mcelog
 591
 592 Start by installing mcelog.
 593
 594 .. note::
 595   The kernel has to have CONFIG_X86_MCE enabled. For 32bit kernels you
 596   need atleast a 2.6,30 kernel.
 597
 598 On Centos:
 599
 600 .. code:: bash
 601
 602     $ sudo yum install mcelog
 603
 604 Or build from source
 605
 606 .. code:: bash
 607
 608     $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git
 609     $ cd mcelog
 610     $ make
 611     ... become root ...
 612     $ make install
 613     $ cp mcelog.service /etc/systemd/system/
 614     $ systemctl enable mcelog.service
 615     $ systemctl start mcelog.service
 616
 617
 618 Verify you got a /dev/mcelog. You can verify the daemon is running completely
 619 by running:
 620
 621 .. code:: bash
 622
 623      $ mcelog --client
 624
 625 This should query the information in the running daemon. If it prints nothing
 626 that is fine (no errors logged yet). More info @
 627 http://www.mcelog.org/installation.html
 628
 629 Modify the mcelog configuration file "/etc/mcelog/mcelog.conf" to include or
 630 enable:
 631
 632 .. code:: bash
 633
 634     socket-path = /var/run/mcelog-client
 635     [dimm]
 636     dimm-tracking-enabled = yes
 637     dmi-prepopulate = yes
 638     uc-error-threshold = 1 / 24h
 639     ce-error-threshold = 10 / 24h
 640
 641     [socket]
 642     socket-tracking-enabled = yes
 643     mem-uc-error-threshold = 100 / 24h
 644     mem-ce-error-threshold = 100 / 24h
 645     mem-ce-error-log = yes
 646
 647     [page]
 648     memory-ce-threshold = 10 / 24h
 649     memory-ce-log = yes
 650     memory-ce-action = soft
 651
 652     [trigger]
 653     children-max = 2
 654     directory = /etc/mcelog
 655
 656
 657 Clone and install the collectd mcelog plugin:
 658
 659 .. code:: bash
 660
 661     $ git clone https://github.com/collectd/collectd
 662     $ cd collectd
 663     $ ./build.sh
 664     $ ./configure --enable-syslog --enable-logfile --enable-debug
 665     $ make
 666     $ sudo make install
 667
 668 This will install collectd to default folder ``/opt/collectd``. The collectd
 669 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
 670 To configure the mcelog plugin you need to modify the configuration file to
 671 include:
 672
 673 .. code:: bash
 674
 675     <LoadPlugin mcelog>
 676       Interval 1
 677     </LoadPlugin>
 678     <Plugin mcelog>
 679       <Memory>
 680         McelogClientSocket "/var/run/mcelog-client"
 681         PersistentNotification false
 682       </Memory>
 683       #McelogLogfile "/var/log/mcelog"
 684     </Plugin>
 685
 686 For more information on the plugin parameters, please see:
 687 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 688
 689 Simulating a Machine Check Exception can be done in one of 3 ways:
 690
 691 * Running $make test in the mcelog cloned directory - mcelog test suite
 692 * using mce-inject
 693 * using mce-test
 694
 695 **mcelog test suite:**
 696
 697 It is always a good idea to test an error handling mechanism before it is
 698 really needed. mcelog includes a test suite. The test suite relies on
 699 mce-inject which needs to be installed and in $PATH.
 700
 701 You also need the mce-inject kernel module configured (with
 702 CONFIG_X86_MCE_INJECT=y), compiled, installed and loaded:
 703
 704 .. code:: bash
 705
 706     $ modprobe mce-inject
 707
 708 Then you can run the mcelog test suite with
 709
 710 .. code:: bash
 711
 712     $ make test
 713
 714 This will inject different classes of errors and check that the mcelog triggers
 715 runs. There will be some kernel messages about page offlining attempts. The
 716 test will also lose a few pages of memory in your system (not significant).
 717 .. note::
 718   This test will kill any running mcelog, which needs to be restarted
 719   manually afterwards.
 720
 721 **mce-inject:**
 722
 723 A utility to inject corrected, uncorrected and fatal machine check exceptions
 724
 725 .. code:: bash
 726
 727     $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git
 728     $ cd mce-inject
 729     $ make
 730     $ modprobe mce-inject
 731
 732 Modify the test/corrected script to include the following:
 733
 734 .. code:: bash
 735
 736     CPU 0 BANK 0
 737     STATUS 0xcc00008000010090
 738     ADDR 0x0010FFFFFFF
 739
 740 Inject the error:
 741 .. code:: bash
 742
 743     $ ./mce-inject < test/corrected
 744
 745 .. note::
 746   The uncorrected and fatal scripts under test will cause a platform reset.
 747   Only the fatal script generates the memory errors**. In order to  quickly
 748   emulate uncorrected memory errors and avoid host reboot following test errors
 749   from mce-test suite can be injected:
 750
 751 .. code:: bash
 752
 753        $ mce-inject  mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub
 754
 755 **mce-test:**
 756
 757 In addition a more in-depth test of the Linux kernel machine check facilities
 758 can be done with the mce-test test suite. mce-test supports testing uncorrected
 759 error handling, real error injection, handling of different soft offlining
 760 cases, and other tests.
 761
 762 **Corrected memory error injection:**
 763
 764 To inject corrected memory errors:
 765
 766 * Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core
 767 * Insert einj module: modprobe einj param_extension=1
 768 * Inject an error by specifying details (last command should be repeated at least two times):
 769
 770 .. code:: bash
 771
 772     $ APEI_IF=/sys/kernel/debug/apei/einj
 773     $ echo 0x8 > $APEI_IF/error_type
 774     $ echo 0x01f5591000 > $APEI_IF/param1
 775     $ echo 0xfffffffffffff000 > $APEI_IF/param2
 776     $ echo 1 > $APEI_IF/notrigger
 777     $ echo 1 > $APEI_IF/error_inject
 778
 779 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 780
 781 Open vSwitch Plugins
 782 ^^^^^^^^^^^^^^^^^^^^^
 783 OvS Plugins Repo: https://github.com/collectd/collectd
 784
 785 OvS Plugins Branch: master
 786
 787 OvS Events MIBs: The SNMP OVS interface link status is provided by standard
 788 IF-MIB (http://www.net-snmp.org/docs/mibs/IF-MIB.txt)
 789
 790 Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl)
 791
 792 On Centos, install the dependencies and Open vSwitch:
 793
 794 .. code:: bash
 795
 796     $ sudo yum install yajl-devel
 797
 798 Steps to install Open vSwtich can be found at
 799 http://docs.openvswitch.org/en/latest/intro/install/fedora/
 800
 801 Start the Open vSwitch service:
 802
 803 .. code:: bash
 804
 805     $ sudo service openvswitch-switch start
 806
 807 Configure the ovsdb-server manager:
 808
 809 .. code:: bash
 810
 811     $ sudo ovs-vsctl set-manager ptcp:6640
 812
 813 Clone and install the collectd ovs plugin:
 814
 815 .. code:: bash
 816
 817     $ git clone $REPO
 818     $ cd collectd
 819     $ git checkout master
 820     $ ./build.sh
 821     $ ./configure --enable-syslog --enable-logfile --enable-debug
 822     $ make
 823     $ sudo make install
 824
 825 This will install collectd to default folder ``/opt/collectd``. The collectd
 826 configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
 827 To configure the OVS events plugin you need to modify the configuration file to include:
 828
 829 .. code:: bash
 830
 831     <LoadPlugin ovs_events>
 832        Interval 1
 833     </LoadPlugin>
 834     <Plugin ovs_events>
 835        Port "6640"
 836        Address "127.0.0.1"
 837        Socket "/var/run/openvswitch/db.sock"
 838        Interfaces "br0" "veth0"
 839        SendNotification true
 840     </Plugin>
 841
 842 To configure the OVS stats plugin you need to modify the configuration file
 843 to include:
 844
 845 .. code:: bash
 846
 847     <LoadPlugin ovs_stats>
 848        Interval 1
 849     </LoadPlugin>
 850     <Plugin ovs_stats>
 851        Port "6640"
 852        Address "127.0.0.1"
 853        Socket "/var/run/openvswitch/db.sock"
 854        Bridges "br0"
 855     </Plugin>
 856
 857 For more information on the plugin parameters, please see:
 858 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
 859
 860 OVS PMD stats
 861 ^^^^^^^^^^^^^^
 862 Repo: https://gerrit.opnfv.org/gerrit/barometer
 863
 864 Prequistes:
 865 1. Open vSwitch dependencies are installed.
 866 2. Open vSwitch service is running.
 867 3. Ovsdb-server manager is configured.
 868 You can refer `Open vSwitch Plugins`_ section above for each one of them.
 869
 870 OVS PMD stats application is run through the exec plugin.
 871
 872 To configure the OVS PMD stats application you need to modify the exec plugin configuration
 873 to include:
 874
 875 .. code:: bash
 876
 877     <LoadPlugin exec>
 878        Interval 1
 879     </LoadPlugin
 880     <Plugin exec>
 881         Exec "user:group" "<path to ovs_pmd_stat.sh>"
 882     </Plugin>
 883
 884 .. note:: Exec plugin configuration has to be changed to use appropriate user before starting collectd service.
 885
 886 ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument:
 887
 888 .. code:: bash
 889
 890      sudo python /usr/local/src/ovs_pmd_stats.py" "--socket-pid-file"
 891      "/var/run/openvswitch/ovs-vswitchd.pid"
 892
 893 SNMP Agent Plugin
 894 ^^^^^^^^^^^^^^^^^
 895 Repo: https://github.com/collectd/collectd
 896
 897 Branch: master
 898
 899 Dependencies: NET-SNMP library
 900
 901 Start by installing net-snmp and dependencies.
 902
 903 On Centos 7:
 904
 905 .. code:: bash
 906
 907     $ sudo yum install net-snmp net-snmp-libs net-snmp-utils net-snmp-devel
 908     $ sudo systemctl start snmpd.service
 909
 910 go to the `snmp configuration`_ steps.
 911
 912 From source:
 913
 914 Clone and build net-snmp:
 915
 916 .. code:: bash
 917
 918     $ git clone https://github.com/haad/net-snmp.git
 919     $ cd net-snmp
 920     $ ./configure --with-persistent-directory="/var/net-snmp" --with-systemd --enable-shared --prefix=/usr
 921     $ make
 922
 923 Become root
 924
 925 .. code:: bash
 926
 927     $ make install
 928
 929 Copy default configuration to persistent folder:
 930
 931 .. code:: bash
 932
 933     $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf
 934
 935 Set library path and default MIB configuration:
 936
 937 .. code:: bash
 938
 939     $ cd ~/
 940     $ echo export LD_LIBRARY_PATH=/usr/lib >> .bashrc
 941     $ net-snmp-config --default-mibdirs
 942     $ net-snmp-config --snmpconfpath
 943
 944 Configure snmpd as a service:
 945
 946 .. code:: bash
 947
 948     $ cd net-snmp
 949     $ cp ./dist/snmpd.service /etc/systemd/system/
 950     $ systemctl enable snmpd.service
 951     $ systemctl start snmpd.service
 952
 953 .. _`snmp configuration`:
 954
 955 Add the following line to snmpd.conf configuration file
 956 ``/etc/snmp/snmpd.conf`` to make all OID tree visible for SNMP clients:
 957
 958 .. code:: bash
 959
 960     view    systemview    included   .1
 961
 962 To verify that SNMP is working you can get IF-MIB table using SNMP client
 963 to view the list of Linux interfaces:
 964
 965 .. code:: bash
 966
 967     $ snmpwalk -v 2c -c public localhost IF-MIB::interfaces
 968
 969 Get the default MIB location:
 970
 971 .. code:: bash
 972
 973     $ net-snmp-config --default-mibdirs
 974     /opt/stack/.snmp/mibs:/usr/share/snmp/mibs
 975
 976 Install Intel specific MIBs (if needed) into location received by
 977 ``net-snmp-config`` command (e.g. ``/usr/share/snmp/mibs``).
 978
 979 .. code:: bash
 980
 981     $ git clone https://gerrit.opnfv.org/gerrit/barometer.git
 982     $ sudo cp -f barometer/mibs/*.txt /usr/share/snmp/mibs/
 983     $ sudo systemctl restart snmpd.service
 984
 985 Clone and install the collectd snmp_agent plugin:
 986
 987 .. code:: bash
 988
 989     $ cd ~
 990     $ git clone https://github.com/collectd/collectd
 991     $ cd collectd
 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/collectd/collectd/blob/master/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 Repo: https://github.com/collectd/collectd
1043
1044 Branch: master
1045
1046 Dependencies: libvirt (https://libvirt.org/), libxml2
1047
1048 On Centos, install the dependencies:
1049
1050 .. code:: bash
1051
1052     $ sudo yum install libxml2-dev libpciaccess-devel yajl-devel device-mapper-devel
1053
1054 Install libvirt:
1055
1056 libvirt version in package manager might be quite old and offer only limited
1057 functionality. Hence, building and installing libvirt from sources is recommended.
1058 Detailed instructions can bet found at:
1059 https://libvirt.org/compiling.html
1060
1061 Certain metrics provided by the plugin have a requirement on a minimal version of
1062 the libvirt API. *File system information* statistics require a *Guest Agent (GA)*
1063 to be installed and configured in a VM. User must make sure that installed GA
1064 version supports retrieving file system information. Number of *Performance monitoring events*
1065 metrics depends on running libvirt daemon version.
1066
1067 .. note:: Please keep in mind that RDT metrics (part of *Performance monitoring
1068     events*) have to be supported by hardware. For more details on hardware support,
1069     please see:
1070     https://github.com/01org/intel-cmt-cat
1071
1072     Additionally perf metrics **cannot** be collected if *Intel RDT* plugin is enabled.
1073
1074 libvirt version can be checked with following commands:
1075
1076 .. code:: bash
1077
1078     $ virsh --version
1079     $ libvirtd --version
1080
1081 .. table:: Extended statistics requirements
1082
1083     +-------------------------------+--------------------------+-------------+
1084     | Statistic                     | Min. libvirt API version | Requires GA |
1085     +===============================+==========================+=============+
1086     | Domain reason                 | 0.9.2                    | No          |
1087     +-------------------------------+--------------------------+-------------+
1088     | Disk errors                   | 0.9.10                   | No          |
1089     +-------------------------------+--------------------------+-------------+
1090     | Job statistics                | 1.2.9                    | No          |
1091     +-------------------------------+--------------------------+-------------+
1092     | File system information       | 1.2.11                   | Yes         |
1093     +-------------------------------+--------------------------+-------------+
1094     | Performance monitoring events | 1.3.3                    | No          |
1095     +-------------------------------+--------------------------+-------------+
1096
1097 Start libvirt daemon:
1098
1099 .. code:: bash
1100
1101     $ systemctl start libvirtd
1102
1103 Create domain (VM) XML configuration file. For more information on domain XML
1104 format and examples, please see:
1105 https://libvirt.org/formatdomain.html
1106
1107 .. note:: Installing additional hypervisor dependencies might be required before
1108     deploying virtual machine.
1109
1110 Create domain, based on created XML file:
1111
1112 .. code:: bash
1113
1114     $ virsh define DOMAIN_CFG_FILE.xml
1115
1116 Start domain:
1117
1118 .. code:: bash
1119
1120     $ virsh start DOMAIN_NAME
1121
1122 Check if domain is running:
1123
1124 .. code:: bash
1125
1126     $ virsh list
1127
1128 Check list of available *Performance monitoring events* and their settings:
1129
1130 .. code:: bash
1131
1132     $ virsh perf DOMAIN_NAME
1133
1134 Enable or disable *Performance monitoring events* for domain:
1135
1136 .. code:: bash
1137
1138     $ virsh perf DOMAIN_NAME [--enable | --disable] EVENT_NAME --live
1139
1140 Clone and install the collectd virt plugin:
1141
1142 .. code:: bash
1143
1144     $ git clone $REPO
1145     $ cd collectd
1146     $ ./build.sh
1147     $ ./configure --enable-syslog --enable-logfile --enable-debug
1148     $ make
1149     $ sudo make install
1150
1151 Where ``$REPO`` is equal to information provided above.
1152
1153 This will install collectd to ``/opt/collectd``. The collectd configuration file
1154 ``collectd.conf`` can be found at ``/opt/collectd/etc``.
1155 To load the virt plugin user needs to modify the configuration file to include:
1156
1157 .. code:: bash
1158
1159     LoadPlugin virt
1160
1161 Additionally, user can specify plugin configuration parameters in this file,
1162 such as connection URL, domain name and much more. By default extended virt plugin
1163 statistics are disabled. They can be enabled with ``ExtraStats`` option.
1164
1165 .. code:: bash
1166
1167     <Plugin virt>
1168        RefreshInterval 60
1169        ExtraStats "cpu_util disk disk_err domain_state fs_info job_stats_background pcpu perf vcpupin"
1170     </Plugin>
1171
1172 For more information on the plugin parameters, please see:
1173 https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
1174
1175 Installing collectd as a service
1176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1177 **NOTE**: In an OPNFV installation, collectd is installed and configured as a
1178 service.
1179
1180 Collectd service scripts are available in the collectd/contrib directory.
1181 To install collectd as a service:
1182
1183 .. code:: bash
1184
1185     $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/
1186     $ cd /etc/systemd/system/
1187     $ sudo mv systemd.collectd.service collectd.service
1188     $ sudo chmod +x collectd.service
1189
1190 Modify collectd.service
1191
1192 .. code:: bash
1193
1194     [Service]
1195     ExecStart=/opt/collectd/sbin/collectd
1196     EnvironmentFile=-/opt/collectd/etc/
1197     EnvironmentFile=-/opt/collectd/etc/
1198     CapabilityBoundingSet=CAP_SETUID CAP_SETGID
1199
1200 Reload
1201
1202 .. code:: bash
1203
1204     $ sudo systemctl daemon-reload
1205     $ sudo systemctl start collectd.service
1206     $ sudo systemctl status collectd.service should show success
1207
1208 Additional useful plugins
1209 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1210
1211 * **Exec Plugin** : Can be used to show you when notifications are being
1212  generated by calling a bash script that dumps notifications to file. (handy
1213  for debug). Modify /opt/collectd/etc/collectd.conf:
1214
1215 .. code:: bash
1216
1217    LoadPlugin exec
1218    <Plugin exec>
1219    #   Exec "user:group" "/path/to/exec"
1220       NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh"
1221    </Plugin>
1222
1223 write_notification.sh (just writes the notification passed from exec through
1224 STDIN to a file (/tmp/notifications)):
1225
1226 .. code:: bash
1227
1228    #!/bin/bash
1229    rm -f /tmp/notifications
1230    while read x y
1231    do
1232      echo $x$y >> /tmp/notifications
1233    done
1234
1235 output to /tmp/notifications should look like:
1236
1237 .. code:: bash
1238
1239     Severity:WARNING
1240     Time:1479991318.806
1241     Host:localhost
1242     Plugin:ovs_events
1243     PluginInstance:br-ex
1244     Type:gauge
1245     TypeInstance:link_status
1246     uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589
1247
1248     linkstate of "br-ex" interface has been changed to "DOWN"
1249
1250 * **logfile plugin**: Can be used to log collectd activity. Modify
1251   /opt/collectd/etc/collectd.conf to include:
1252
1253 .. code:: bash
1254
1255     LoadPlugin logfile
1256     <Plugin logfile>
1257         LogLevel info
1258         File "/var/log/collectd.log"
1259         Timestamp true
1260         PrintSeverity false
1261     </Plugin>
1262
1263
1264 Monitoring Interfaces and Openstack Support
1265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1266 .. Figure:: monitoring_interfaces.png
1267
1268    Monitoring Interfaces and Openstack Support
1269
1270 The figure above shows the DPDK L2 forwarding application running on a compute
1271 node, sending and receiving traffic. Collectd is also running on this compute
1272 node retrieving the stats periodically from DPDK through the dpdkstat plugin
1273 and publishing the retrieved stats to OpenStack through the
1274 collectd-ceilometer-plugin.
1275
1276 To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
1277
1278 For more information on configuring and installing OpenStack plugins for
1279 collectd, check out the `collectd-ceilometer-plugin GSG`_.
1280
1281 References
1282 ^^^^^^^^^^^
1283 .. [1] https://collectd.org/wiki/index.php/Naming_schema
1284 .. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
1285 .. [3] https://collectd.org/wiki/index.php/Value_list_t
1286 .. [4] https://collectd.org/wiki/index.php/Data_set
1287 .. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
1288 .. [6] https://collectd.org/wiki/index.php/Data_source
1289 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
1290
1291 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
1292 .. _gnocchi plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1293 .. _aodh plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
1294 .. _collectd-ceilometer-plugin GSG: https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/GSG.rst
1295 .. _grafana guide: https://wiki.opnfv.org/display/fastpath/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd