docs/release/userguide/feature.userguide.rst

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